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.

SYNOPSIS

exists {expression} [expression...]

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.

EXAMPLES

The following are run from the MGED command prompt:

Example 1. Example1

exists object1.s

DIAGNOSTICS

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

AUTHOR

BRL-CAD Team

COPYRIGHT

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

BUGS

TODO.

BUG REPORTS

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org