Documented new semantics for existential conditionals to check boolean state.
1 parent 4873d58 commit a2603e7654cf9456fc55e56e207ed14875f12f54
@tundra tundra authored on 20 Jan 2005
Showing 1 changed file
View
118
tconfpy.3
 
.fi
.ft \" revert
 
As a practical matter, unless you actually need to do comparisons involving
\fC"True"\fP and \fC"False"\fP strings, it is best to use the Existential Conditionals
to test the
.B state
of a boolean variable. See the section entitled,
.B Existential Conditionals And Booleans
below, for the details.
 
 
.SS The \fC.include\fP Directive
 
At any point in a configuration file, you can "include" another configuration file
This will test to see if a variable called \fCvt100\fP exists in the
symbol table. This is a handy way to see if you have a local variable
defined appropriate for the currently defined terminal, for instance.
 
.SS Existential Conditionals And Booleans
 
As we've just seen, \fC.ifall/any/none\fP check to see if the
variables named on the Right Hand Side "exist". This is true
for all kinds of variables, regardless of their type. For instance:
 
.ft C \" Courier
.nf
.ifall Boolean1 Boolean2
...
.endif
 
Foo = Boolean3
.ifall [Foo]
...
.endif
.fi
.ft \" revert
 
The first conditional will be \fCTrue\fP only if both variables,
\fCBoolean1\fP and \fCBoolean2\fP exist. Similarly, the second
conditional will be \fCTrue\fP only if \fCBoolean3\fP exists.
 
However, when using indirection on a boolean variable (i.e. A variable
that has been pre-defined to be a boolean type by the calling program),
.B the state of the boolean is returned.
For example:
 
.ft C \" Courier
.nf
.ifall [Boolean1] [Boolean2]
...
.endif
.fi
.ft \" revert
 
In this case, the \fC[Boolean..]\fP indirection is understood to mean,
"Return the logical state of the boolean variable in question". This
allows the existential conditionals to act like
.B logical
operators when their targets are boolean. In the example above,
the test will only be True if both booleans are logically True.
 
You can even mix and match:
 
.ft C \" Courier
.nf
.ifall Boolean1 [Boolean2]
...
.endif
.fi
.ft \" revert
 
 
This conditional will be \fCTrue\fP only if \fCBoolean1\fP
.B exists
and \fCBoolean2\fP is \fCTrue\fP.
 
It's worth mentioning just
.B why
the semantics of indirect boolean references are different than for
other variable types. If booleans were treated the same as other
variables, then \fC[Boolean]\fP would return a string representation
of the boolean variable's state - i.e., It would return \fC"True"\fP
or \fC"False"\fP. In effect, we would be doing this:
 
.ft C \" Courier
.nf
.ifall/any/none True False True True False ...
.fi
.ft \" revert
 
This more-or-less makes no sense, since we're checking to see if
variables named "True" and "False" exist. What
.B does
make a lot of sense is to use the state of a boolean variable to drive
the conditional logic.
 
There is one other reason this feature is provided. Earlier versions
of \fCtconfpy\fP did not have this feature - booleans were treated
like any other variable. This meant that doing logical tests on the state
of the boolean required a kind of tortuous construct using the Comparsion
Conditionals (described in the next section):
 
.ft C \" Courier
.nf
# Example of AND logic using Comparison Conditional
 
.if [Bool1][Bool2][Bool3] == TrueTrueTrue
...
.endif
.fi
.ft \" revert
 
This is ugly, hard to read, and hard to maintain. By contrast, the
method just described allows booleans to be used in their intended
manner - to make logical choices. \fC.ifall\fP becomes a logical
"AND" function. \fC.ifany\fP becomes a logical "OR" function, and
\fC.ifnone\fP becomes a logical "NOR" function when these tests are
applied to indirect boolean references.
 
Both methods of testing boolean state remain supported, so you can use
the style most appropriate for your application.
 
 
.SS Comparison Conditional Directives
 
There are two Comparison Conditionals:
.fi
.ft \" revert
 
.SH DOCUMENT REVISION INFORMATION
$Id: tconfpy.3,v 1.158 2005/01/20 08:42:34 tundra Exp $
$Id: tconfpy.3,v 1.159 2005/01/20 09:32:57 tundra Exp $