#set TITLE = "conditional expressions"
#include top

.SH DESCRIPTION
Ploticus uses conditional expressions in script \fB#if\fR statements, and
in data \fCselect\fR attributes (for example, proc bars
has a \fCselect\fR attribute).  

.SH EXAMPLES
Some examples of conditional expressions as used with the #if operator...
.LP
\fC#if @MODE = red\fR
.LP
\fC#if @MODE in red,green,blue\fR
.LP
\fC#if @COUNT > 2\fR
.LP
\fC#if @COUNT > 2 || @MODE = A\fR
.LP
\fC#if @COUNT > 2 && @MODE = A\fR

.LP
Some examples of conditional expressions as used with the \fCselect\fR attribute.
Note that data field references have a preceding double at-sign (\fB@@@@\fR):
.LP
\fCselect: all\fR  (select all records)
.LP
\fCselect: @@@@4 = red\fR  (select all records where field 4 is equal to \fCred\fR)
.LP
\fCselect: @@@@color = red\fR  (select all records where the field named 'color' 
is equal to \fCred\fR.
This works only when fieldnames have been defined in proc getdata.)
.LP
\fCselect: @@@@4 in A,B,C\fR  ( '' where field 4 is one of A, B, or C)
.LP
\fCselect: $inrange(@@@@2,X) = 1\fR  ( '' where field 2 is in plottable range of X axis)
.LP
\fCselect: $inrange(@@@@1,X,-5,5) = 1\fR  ( '' where field 1 is in the range of -5 to +5 on the X axis)
.LP
A gallery example having a conditional select is 
.ig >>
<a href="../gallery/timeline1a.htm">
.>>
 timeline1a 
.ig >>
</a>
.>>

.SH DESCRIPTION
As can be seen in the above examples, operands may be numeric or alphanumeric.
Operands and operators are delimited by white space.
Operands may be literal, a 
.ig >>
<a href="scripts.html#variables">
.>>
 @variable 
.ig >>
</a>
.>>
 , or a 
.ig >>
<a href="scripts.html#functions">
.>>
 $function 
.ig >>
</a>
.>>
 .  In \fCselect\fR attributes operands may also
be 
.ig >>
<a href="attributetypes.html#dfield">
.>>
 dfields
.ig >>
</a>
.>>
 (a preceding at-sign (\fB@\fR) is used).
No quotes are used; an embedded space within an alphanumeric may
be represented using an underscore (\fB_\fR).  To test for a zero
length string use the $strlen function, e.g. \fC$strlen(@VAL) < 1\fR

.SH THE 'INRANGE' FUNCTION 
A common operation in \fCselect\fR attributes is to select only
data that are within plottable range.  A function called \fB$inrange\fR
is available to do that.  For example:
.nf
.ft C
	select:  $inrange(@@@@5,Y) = 1
.fi
.ft R
would select only data records where field 5 is within plottable range
with respect to the Y axis.
.LP
A number of other
.ig >>
<a href="functions.html">
.>>
 functions 
.ig >>
</a>
.>>
are also available.


.SH LOGICAL OPERATORS
Available operators are:
.nf
\fB= \fR	Equal to.  Case sensitive for strings. 
\fB!=\fR	Not equal to. 
\fB> \fR	Greater than. 
\fB>=\fR 	Greater than or equal to. 
\fB< \fR 	Less than. 
\fB<=\fR 	Less than or equal to. 
.fi
.LP
\fBWild card matching\fR:  Wild card matching may be done
using \fBlike\fP.  Wild card characters are \fB*\fR which matches
any number of any character, and \fB?\fR which matches a single
instance of any character.  This matching is case-insensitive.
.nf
\fBlike\fR	Wild card match.  Example: \fChello like h*\fR (true)
\fB!like\fR	Not a wild card match.
.LP
\fBList operators\fP:  A list is a comma-delimited
series of values with no embedded spaces, such as \fCx,y,z\fR or
\fCred,green,yellow\fR.  In all of these, the list must be given
on the right side of the operator.
.nf
\fBin\fR	Member of list.  Example: \fCz in x,y,z\fR (true)
\fB!in\fR	Not a member of list. (Alt: \fBni\fR)
\fBinlike\fR 	Same as \fBin\fP but wild card matching is used.
		(Wild cards may be used in list members.)
\fB!inlike\fR	Same as \fB!in\fP but wild card matching is used.
.fi


.SH LOGICAL CONNECTORS
Individual conditional expressions may be connected together using
logical AND (\fB&&\fR) or OR (\fB||\fR).
An entire expression may be negated by putting \fBnot:\fR at the beginning
of the expression.
Because parentheses may not be used to establish presidence, AND always
has higher presidnece than OR (ANDs are evaluated after all ORs are evaluated).


.SH MORE EXAMPLES
More examples of conditional expressions:
.LP
Example: \fC@SCORE > 70 && @SCORE <= 80\fR
.LP
Example: \fC$strlen(@INPUT) = 0\fR
.LP
Example: \fC@VAR in A,F,R,none\fR
.LP
Example: \fC@VAR like Gr*\fR
.LP
Example: \fC@VAR inlike Gr*,Gu*,Gy*\fR
.LP
Example: \fC@VAR in 02,08 || @STATUS = u\fR


.SH LIMITATIONS AND BUGS
Embedded spaces within character string operands are not allowed; underscore (_) is
often used to represent spaces.
.LP
Embedded commas within character string operands may cause problems if operand
is used on the right side of a list operator, or within a function call.
.LP
Operands which happen to be \fB&&\fR, \fB||\fR, or \fBnot:\fR will be 
misinterpreted.
.LP
Operands beginning with $ followed by an alpha character will
be misinterpreted as function calls.
.LP
There is no way to represent a 0 length string in a conditional.
Instead, $strlen() should be used to test for 0 length strings.
.LP
Evaluation order when && and || are both found in an expression cannot
be controlled by applying parentheses (see LOGICAL CONNECTORS section).

#include bottom
