search works in a fashion similar to Unix-style find commands (internally it is based on OpenBSD's and NetBSD's find code) but searches objects in the current open database in MGED rather than files in a file system. By default, the output is a list of matches printed in the MGED command window, but other output options are available. Matching of objects is done according to boolean expressions formed using the PRIMITIVES and OPERATORS described below.
Returns TRUE if the object has attribute attrib. If a specific value is also supplied for the attribute, TRUE is returned if the object both has the attribute and the attribute is set to value val. Both attrib and val are treated as patterns under shell pattern matching rules.
Returns TRUE if the object is a combination and has no tree below it.
Like name except the match is case insensitive.
Like regex except the match is case insensitive.
True if the depth of the object in the tree is less than or equal to n.
True if the depth of the object in the gree is greater than or equal to n.
True if the object name (not the full path, just the name) matches pattern. The evaluation is done according to shell pattern matching rules.
True if the object path matches pattern. The evaluation is done according to shell pattern matching rules.
Evaluates to TRUE - used to print out the path and name of the object.
Evaluates to TRUE - prints the pathname of the object to standard output, followed by an ASCII NUL character.
True if the object path matches pattern. Pattern evaluation is done using Regular Expression matching.
Returns TRUE if an object has ONLY standard attributes associated with it. Standard attributes in BRL-CAD are:
Returns TRUE if the type of the object matches pattern. Pattern evaluation is done using shell pattern matching. Types recognized include:
Table 2. Primitives
| arb4 | arb5 | arb6 | arb7 | arb8 | arbn |
| ars | bot | cline | dsp | ebm | ehy |
| ell | epa | eto | extrude | grip | half |
| hf | joint | nmg | part | pipe | poly |
| rec | rhc | rpc | sketch | sph | spline |
| submodel | tgc | tor | vol |
Table 3. Combinations
| Type | Abbreviations Recognized |
|---|---|
| combination | c, comb, combination |
| region | r, reg, region |
Evaluates to true if the expression inside the parenthesies evaluates to true. Used to establish order of operations.
The above operator applies the expression to every object above the current object in the full path to that object, and returns TRUE if one or more of them satisfies the expression - e.g -above -name s\* applied to /component/region.r/start_comb.c/prim1.s would return TRUE for /component and /component/region.r as both being "above" start_comb.c, but would return FALSE the deeper objects.
The and operator operates like the logical AND operator - TRUE only if both expressions are true. AND is the default operator assumed if two expressions are present with no operator explicitly defined.
The below operator applies the expression to every object below the current object in the tree hierarchy - in effect it does a "mini-search" of the tree using the current object path as a starting point and returns TRUE if the expression is satisfied by one or more objects in the sub-tree.
The logical NOT operator - returns the opposite of the evaluation result of expression.
The logical OR operator - true if either expression is true.
All primaries and operands must be expressed as separate arguments to search. In practice, this means that there must be a space between each element in a search expression. E.g. !(-name [a-z] -or -name [0-9]) must be written as:
! ( -name [a-z] -or -name [0-9] )
While this may seem like a rather verbose way of writing the expression, it greatly simplifies the parsing of the expression and is standard for virtually all find type commands. Because [a-z] and [0-9] are atomic arguments as far as search is concerned, they should NOT be expanded in a similar fashion.
The following are run from the MGED command prompt:
Example 1. Shell Globbing Based Pattern Match of Object Name
search -name *.s
Find all instances of objects in the database with names ending in ".s".
Example 2. Name Pattern Matching at Depth >= 3
search -name *.s -mindepth 3
Find all instances of objects in the database with names ending in ".s" that are 3 or more levels deep in their tree.
Example 3. Searching by Type
search . -type eto
Find all objects in the database that are elliptical tori. Notice the use of "." for the path, which means to find the objects themselves in a flat search rather than all instances in the tree hierarchy.
Example 4. Finding all Combinations below Regions
search -type comb -not ( -type region -or -type assem )
Find all instances of combinations that are not regions and do not contain regions.
Example 5. Finding all Nested Regions
search -below -type region -type region
Find all instances of objects of type region that contain a region in the subtree. This searches for regions being used "below" other regions, which is considered bad practice in BRL-CAD
Example 6. Finding all Assemblies
search -below -type region -type combination ! -type region
Find all instances of objects of type combination that contain regions but are not themselves regions. These are regarded as "assemblies" in BRL-CAD.
Errors will be returned if parsing of the arguments fails, or one of the primaries's evaluation functions returns an error.
This software is Copyright (c) 2008 United States Government as represented by the U.S. Army Research Laboratory. All rights reserved. Portions Copyright 1990, 1993, 1994 The Regents of the University of California, per copyright and license information from OpenBSD and NetBSD. For more details see the copyright statements in search.c and search.h.