Name
exists — The exists command evaluates an expression and return 1 if true, zero if false. It serves roughly the same purpose for objects in a BRL-CAD database that the UNIX test command serves for files on a file system, with additional features specific to geometry and minus some of the filesystem specific options of test.
DESCRIPTION
exists works in a fashion similar to Unix-style test commands (internally it is based on NetBSD's test code) but tests objects in the current open database rather than files in a file system. If an object matching a valid expression or expressions is found 1 is returned, otherwise 0 is returned. Expressions are formed using PRIMARIES and OPERATORS. A simple object name with no primaries or operators will return true if db_lookup succeeds and the object is non-null (TODO).
PRIMARIES:
- -c object
Returns TRUE if the object is a combination
- -e object
Returns TRUE if the object exists. This reports only the results of db_lookup without doing any further testing to check for null objects, and constitutes the most basic existence test available for a database object.
- -n object
Returns TRUE if the object exists and is a NULL database object. **TODO**
- -p object
Returns TRUE if the object exists and is a geometric primitive. (Empty geometric primitives and 2D primitives like sketch will pass.)
- -v object
Returns TRUE if the object exists and has a bounding box with non-zero volume. (A sketch primitive would not pass this test.)
- object1 = object2
Returns TRUE if the objects exist and their serialized binary contents are equal.
- object1 != object2
Returns TRUE if the objects exist and their serialized binary contents are not equal.
- object1 < object2
Returns TRUE if the objects exist and the size of the serialized binary representation of object1 is less than the size of the serialized binary representation of object 2.
- object1 > object2
Returns TRUE if the objects exist and the size of the serialized binary representation of object1 is greater than the size of the serialized binary representation of object 2.
- object1 beq object2
Returns TRUE if the objects exist and their bounding box volumes are equal. *TODO* - eventually, when the right APIs become available, an "-req" option will be added for a more-expensive-but-more-accurate raytrace based volumetric comparison as well.
- object1 bne object2
Returns TRUE if the objects exist and their bounding box volumes are not equal. *TODO* - eventually, when the right APIs become available, a "-rne" option will be added for a more-expensive-but-more-accurate raytrace based volumetric comparison as well.
- object1 bgt object2
Returns TRUE if the objects exist and the volume of the bounding box of object1 is greater than the volume of the bounding box for object2. *TODO* - eventually, when the right APIs become available, an "-rgt" option will be added for a more-expensive-but-more-accurate raytrace based volumetric comparison as well.
- object1 bge object2
Returns TRUE if the objects exist and the volume of the bounding box of object1 is greater than or equal to the volume of the bounding box for object2. *TODO* - eventually, when the right APIs become available, an "-rge" option will be added for a more-expensive-but-more-accurate raytrace based volumetric comparison as well.
- object1 blt object2
Returns TRUE if the objects exist and the volume of the bounding box of object1 is less than the volume of the bounding box for object2. *TODO* - eventually, when the right APIs become available, an "-rlt" option will be added for a more-expensive-but-more-accurate raytrace based volumetric comparison as well.
- object1 ble object2
Returns TRUE if the objects exist and the volume of the bounding box of object1 is less than or equal to the volume of the bounding box for object2. *TODO* - eventually, when the right APIs become available, an "-rle" option will be added for a more-expensive-but-more-accurate raytrace based volumetric comparison as well.
OPERATORS:
primaries can be combined with the following operators:
- ! expression
True if expression is false.
- expression -a expression
The and operator operates like the logical AND operator - TRUE only if both expressions are true.
- expression -o expression
The logical OR operator - true if either expression is true.
- ( expression )
Evaluates to true if the expression inside the parentheses evaluates to true. Used to establish order of operations.
The -a operator has higher precedence than the -o operator.
A Note on Expressions
All primaries and operands must be expressed as separate arguments to exists. In practice, this means that there must be a space between each element in a exists expression. E.g. !(-c object1.s -a (object1.s -beq object2.s)) must be written as:
! ( -c object1.s -a ( object1.s -beq object2.s ) )
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 test type commands.
DIAGNOSTICS
Errors will be returned if parsing of the arguments fails, or one of the primaries' evaluation functions returns an error.
COPYRIGHT
This software is Copyright (c) 2008-2016 United States Government as represented by the U.S. Army Research Laboratory. 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 exists.c and exists.h .