<!-- Converted by db4-upgrade version 1.0 -->

<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="ls">

<refmeta>
  <refentrytitle>LS</refentrytitle>
  <manvolnum>nged</manvolnum>
  <refmiscinfo class="source">BRL-CAD</refmiscinfo>
  <refmiscinfo class="manual">BRL-CAD User Commands</refmiscinfo>
</refmeta>

<refnamediv xml:id="name">
  <refname>ls</refname>
  <refpurpose>The command with no <emphasis>object</emphasis> argument lists the name of every object in the
database (in alphabetical order) except for those marked as hidden with the <command>hide</command>
command.  If the object argument is supplied, only those objects are listed.
   </refpurpose>
</refnamediv>

<!-- body begins here -->
<refsynopsisdiv xml:id="synopsis">
  <cmdsynopsis sepchar=" ">
    <command>ls</command>    
      <arg choice="opt" rep="norepeat">-A -o -a -c -r -s -p -l -q</arg>
    	<arg choice="opt" rep="norepeat"><replaceable>objects</replaceable></arg>
  </cmdsynopsis>
</refsynopsisdiv>

<refsection xml:id="description"><info><title>DESCRIPTION</title></info>
  
  <para>The command with no <emphasis>object</emphasis> argument lists the name of every object in the
	database (in alphabetical order) except for those marked as hidden with the <command>hide</command>
	command.  If the <emphasis>object</emphasis> argument is supplied, only those <emphasis>objects</emphasis> 	are listed.  The <emphasis>object</emphasis> argument may include regular expressions. If the <emphasis>-A	</emphasis> option is used, then the arguments are expected to be a list of attribute name/value pairs, and 	objects having attributes that match the provided list are listed. By default, an object must match all
	the specified attributes in order to be listed; however, the <emphasis>-o</emphasis> flag indicates that an
	object matching at least one attribute name/value pair should be listed. See the <command>attr</command>
	command for information on how to set or get attributes. Regular expressions are not
	supported for attributes. The following options are also allowed:
   </para>
<itemizedlist mark="bullet">
<listitem>
 <para>a -- List all objects in the database.
 </para>
</listitem>
<listitem>
 <para>c -- List all non-hidden combinations in the database.
 </para>
</listitem>
<listitem>
 <para>r -- List all non-hidden regions in the database.
 </para>
</listitem>
<listitem>
 <para>s -- List all non-hidden primitives in the database.
 </para>
</listitem>
<listitem>
 <para>p -- List all non-hidden primitives in the database.
 </para>
</listitem>
<listitem>
 <para>l -- Use long format showing object name, object type, major type, minor type, and
   length.
 </para>
</listitem>
<listitem>
	<para>q -- Suppress informational output messages during database lookup process
	</para>
</listitem>
</itemizedlist>

<para>The <command>ls</command> command is a synonym for the <command>t</command> command.  Note that when any of 	the above options are used, the output is not formatted.
</para>
</refsection>

<refsection xml:id="examples"><info><title>EXAMPLES</title></info>
  
  <para>The examples show the use of the <command>ls</command> command and its options to list objects, primitives, regions, or combinations having a specific object. 
  </para>
  <example><info><title>List all objects beginning with a particular name.</title></info>
    
    <variablelist>
      <varlistentry>
	   <term><prompt>mged&gt;</prompt> <userinput>ls shape*</userinput></term>
	   <listitem>
	     <para>Lists all objects with names beginning with "shape" (output is formatted).
	      	     </para>
	   </listitem>
      </varlistentry>
    </variablelist>
  </example>
       
  <example><info><title>List all objects beginning with a particular name.</title></info>
    
    <para>
      <prompt>mged&gt;</prompt><userinput>ls -a shape*</userinput>
    </para>
    <para>Lists all objects with names beginning with "shape."
    </para>
  </example>
  <example><info><title>List all primitives beginning with a particular name.</title></info>
    
    <para>
      <prompt>mged&gt;</prompt><userinput>ls -p wheel*</userinput>
    </para>
    <para>Lists all primitives with names beginning with "wheel."
    </para>
  </example>
 <example><info><title>List all regions beginning with a particular name.</title></info>
    
    <para>
      <prompt>mged&gt;</prompt><userinput>ls -r wheel*</userinput>
    </para>
    <para>Lists all regions with names beginning with "wheel."
    </para>
  </example>
 <example><info><title>List all combinations beginning with a particular name.</title></info>
    
    <para>
      <prompt>mged&gt;</prompt><userinput>ls -c suspension*</userinput>
    </para>
    <para>Lists all combinations with names beginning with "suspension."
    </para>
  </example>
  <example><info><title>List all regions having particular attributes.</title></info>
    
    <para>
      <prompt>mged&gt;</prompt><userinput>ls -A -o -r Comment{First comment} Comment{Second comment}</userinput>
    </para>
    <para>Lists all regions that have a "Comment" attribute that is set to either "First comment" or "Second comment."
    </para>
  </example>

</refsection>

<info><corpauthor>BRL-CAD Team</corpauthor></info>

<refsection xml:id="bug_reports"><info><title>BUG REPORTS</title></info>
  
  <para>
    Reports of bugs or problems should be submitted via electronic
    mail to &lt;devs@brlcad.org&gt;, or via the "cadbug.sh" script.
  </para>
</refsection>
</refentry>
