GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  SEARCH (n)

.ds Aq ’

NAME

search - find and list objects in a BRL-CAD database

CONTENTS

SYNOPSIS

search [path1] [path2...] [options...]

DESCRIPTION

search works in a fashion similar to Unix-style find commands (internally it is based on OpenBSDs and NetBSDs find code) but searches objects in the current open database in MGED rather than files in a file system. There are two modes of search output. The default mode returns a list of all objects found matching the criteria. A second mode returns a list of full paths containing all instances of all matching objects in the database. The mode of search is determined by each path argument - a path starting with the "/" character will produce a full path instance list, while all other paths will produce the unique object list. One search command may use paths indicating both modes - such a "mixed mode" search will return a list of full paths and objects in the order paths were supplied to search. Matching of objects is done according to boolean expressions formed using the PRIMITIVES and OPERATORS described below.

Something to bear in mind is that all search routines perform a full path tree search "under the hood." A prefix "/" character changes the way the output is reported, but does not change the underlying search method - for example, depth and patch search criteria will still match even if no "/" character is appended to the input path.

PRIMITIVES:

-attr attrib[>/</=val]

Returns TRUE if the object has attribute attrib. If a specific value is also supplied for the attribute with an equal condition, TRUE is returned if the object both has the attribute and the attribute is set to value val. In the case of >, <, >=, and <= there are two possibilities - if val is numerical a numerical comparison is performed, otherwise a string comparison is performed. Both attrib and val are treated as patterns under shell pattern matching rules when a string comparison is performed, but in numerical mode only the attribute name is pattern matched.

-iname pattern

Like name except the match is case insensitive.

-iregex pattern

Like regex except the match is case insensitive.

-maxdepth n

True if the depth of the object in the tree is less than or equal to n.

-mindepth n

True if the depth of the object in the tree is greater than or equal to n.

-name pattern

True if the object name (not the full path, just the name) matches pattern. The evaluation is done according to shell pattern matching rules.

-nnodes n

True if the object is a combination and has n nodes. This option also supports supplying <, >, <=, and >= in front of the number to support returning true for objects with node counts less than, greater than, less than or equal to, and greater than or equal to n.

-path pattern

True if the object path matches pattern. The evaluation is done according to shell pattern matching rules.

-print

Evaluates to TRUE - used to print out the path and name of the object.

-regex pattern

True if the object path matches pattern. Pattern evaluation is done using Regular Expression matching.

-stdattr

Returns TRUE if an object has ONLY standard attributes associated with it. Standard attributes in BRL-CAD are:

Table 1. Standard Attributes

GIFTmater inherit
material_id oshader
region_id rgb

-type pattern

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 brep 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

OPERATORS

( expression )

Evaluates to true if the expression inside the parentheses evaluates to true. Used to establish order of operations.

-above expression

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.

expression -and expression (a.k.a -a)

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.

-below expression

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.

-not expression (a.k.a -!)

The logical NOT operator - returns the opposite of the evaluation result of expression.

expression -or expression (a.k.a -o)

The logical OR operator - true if either expression is true.

A NOTE ON EXPRESSIONS

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.

EXAMPLES

The following are run from the MGED command prompt:

Example 1. Shell Globbing Based Pattern Match of Object Name

search -name *.s

Find all objects in the database with names ending in ".s".

Example 2. Full Path Instance Reporting of Search Results

search / -name *.s

Find all instances of objects in the database with names ending in ".s".

Example 3. 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 4. Finding all Objects in a Subtree

search group1 -name *.r

Find all objects below group1 in the database that have names ending in ".r" Note that this will return a list of objects, not the full path information associated with each instance of the objects matched.

Example 5. Finding all Instances of Objects in a Subtree

search /group1 -name *.r

Find all instances of objects below group1 in the database that have names ending in ".r" Note that, unlike the previous example, this will return the full path information associated with each instance of the objects matched.

Example 6. Searching by Type

search . -type eto

Find all objects in the database that are elliptical tori. Note that a path of "." produces the same search behavior as the default behavior for an unspecified path.

Example 7. Finding all Instances of Nested Regions

search / -type region -above -type region

Find all instances of objects of type region that contain a region. This searches for regions being used within the subtrees of other regions, which is considered bad practice in BRL-CAD.

Example 8. Finding all Assemblies

search / -below -type region ! -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.

Example 9. Finding all Combinations below Regions

search / ! ( -below -type region ) ! -type region -type comb

Find all instances of combinations that are not regions and do not contain regions.

Example 10. Finding all Empty Combinations

search -nnodes 0

Find all combinations containing zero nodes.

Example 11. Finding all Combinations With 10 or More Nodes

search -nnodes >=10

Find all combinations with 10 or more nodes.

DIAGNOSTICS

Errors will be returned if parsing of the arguments fails, or one of the primaries evaluation functions returns an error.

AUTHOR

Clifford Yapp

COPYRIGHT

This software is Copyright (c) 2008-2013 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.

BUGS

Bugs resulting from incorrect parsing of shell pattern expressions are the result of libbus fnmatch.

BUG REPORTS

Reports of bugs or problems should be submitted via electronic mail to <devs@brlcad.org>, or via the "cadbug.sh" script.

Search for    or go to Top of page |  Section n |  Main Index


BRL-CAD SEARCH (nged) 04/04/2016

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.