'\" t
.\"     Title: EXISTS
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 04/13/2022
.\"    Manual: BRL-CAD User Commands
.\"    Source: BRL-CAD
.\"  Language: English
.\"
.TH "EXISTS" "nged" "04/13/2022" "BRL\-CAD" "BRL\-CAD User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
exists \- The \fBexists\fR 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\&.
.SH "SYNOPSIS"
.HP \w'\fBexists\fR\ 'u
\fBexists\fR {expression} [\fIexpression\fR...]
.SH "DESCRIPTION"
.PP

\fBexists\fR
works in a fashion similar to Unix\-style test commands (internally it is based on NetBSD\*(Aqs test code) but tests
\fIobjects\fR
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)\&.
.SH "PRIMARIES:"
.PP
\fB\-c\fR \fIobject\fR
.RS 4
Returns TRUE if the object is a combination
.RE
.PP
\fB\-e\fR \fIobject\fR
.RS 4
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\&.
.RE
.PP
\fB\-n\fR \fIobject\fR
.RS 4
Returns TRUE if the object exists and is a NULL database object\&. **TODO**
.RE
.PP
\fB\-p\fR \fIobject\fR
.RS 4
Returns TRUE if the object exists and is a geometric primitive\&. (Empty geometric primitives and 2D primitives like sketch will pass\&.)
.RE
.PP
\fB\-v\fR \fIobject\fR
.RS 4
Returns TRUE if the object exists and has a bounding box with non\-zero volume\&. (A sketch primitive would not pass this test\&.)
.RE
.PP
\fIobject1\fR \fB=\fR \fIobject2\fR
.RS 4
Returns TRUE if the objects exist and their serialized binary contents are equal\&.
.RE
.PP
\fIobject1\fR \fB!=\fR \fIobject2\fR
.RS 4
Returns TRUE if the objects exist and their serialized binary contents are not equal\&.
.RE
.PP
\fIobject1\fR \fB<\fR \fIobject2\fR
.RS 4
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\&.
.RE
.PP
\fIobject1\fR \fB>\fR \fIobject2\fR
.RS 4
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\&.
.RE
.PP
\fIobject1\fR \fBbeq\fR \fIobject2\fR
.RS 4
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\&.
.RE
.PP
\fIobject1\fR \fBbne\fR \fIobject2\fR
.RS 4
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\&.
.RE
.PP
\fIobject1\fR \fBbgt\fR \fIobject2\fR
.RS 4
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\&.
.RE
.PP
\fIobject1\fR \fBbge\fR \fIobject2\fR
.RS 4
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\&.
.RE
.PP
\fIobject1\fR \fBblt\fR \fIobject2\fR
.RS 4
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\&.
.RE
.PP
\fIobject1\fR \fBble\fR \fIobject2\fR
.RS 4
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\&.
.RE
.SH "OPERATORS:"
.PP
primaries can be combined with the following operators:
.PP
\fB!\fR \fIexpression\fR
.RS 4
True if
\fIexpression\fR
is false\&.
.RE
.PP
\fIexpression\fR \fB\-a\fR \fIexpression\fR
.RS 4
The and operator operates like the logical AND operator \- TRUE only if both expressions are true\&.
.RE
.PP
\fIexpression\fR \fB\-o\fR \fIexpression\fR
.RS 4
The logical OR operator \- true if either expression is true\&.
.RE
.PP
\fB(\fR \fIexpression\fR \fB)\fR
.RS 4
Evaluates to true if the expression inside the parentheses evaluates to true\&. Used to establish order of operations\&.
.RE
.PP
The
\fB\-a\fR
operator has higher precedence than the
\fB\-o\fR
operator\&.
.SH "A NOTE ON EXPRESSIONS"
.PP
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:
.PP
! ( \-c object1\&.s \-a ( object1\&.s \-beq object2\&.s ) )
.PP
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
\fBtest\fR
type commands\&.
.SH "EXAMPLES"
.PP
The following are run from the MGED command prompt:
.PP
\fBExample\ \&1.\ \&Example1\fR
.PP

\fBexists object1\&.s\fR
.PP

.SH "DIAGNOSTICS"
.PP
Errors will be returned if parsing of the arguments fails, or one of the primaries\*(Aq evaluation functions returns an error\&.
.SH "AUTHOR"
.PP
BRL\-CAD Team
.SH "COPYRIGHT"
.PP
This software is Copyright (c) 2008\-2021 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 \&.
.SH "BUGS"
.PP
TODO\&.
.SH "BUG REPORTS"
.PP
Reports of bugs or problems should be submitted via electronic mail to
devs@brlcad\&.org
