macro conditional expressions (no tests yet)

[pspp] / doc / flow-control.texi

diff --git a/doc/flow-control.texi b/doc/flow-control.texi
index 056ffb31310753dddafabbebf29ad12fe165f4f0..3b52205ef337430db413ae26bdbe8d9cd29cb05a 100644 (file)
--- a/doc/flow-control.texi
+++ b/doc/flow-control.texi
@@ -71,6 +71,11 @@ The following functions may be used within the body:
   !TAIL(arg)
   !UNQUOTE(arg)
   !UPCASE(arg)
+
+The body may also include the following constructs:
+
+!IF (condition) !THEN true-expansion !ENDIF
+!IF (condition) !THEN true-expansion !ELSE false-expansion !ENDIF
 @end display
 
 The DEFINE command defines a macro that can later be called any number
@@ -87,15 +92,6 @@ character not normally allowed in identifiers.  These identifiers are
 reserved only for use with macros, which helps keep them from being
 confused with other kinds of identifiers.
 
-@menu
-* Macro Basics::
-* Macro Arguments::
-* Controlling Macro Expansion::
-* Macro Functions::
-* Macro Settings::
-* Macro Notes::
-@end menu
-
 @node Macro Basics
 @subsection Macro Basics
 
@@ -530,6 +526,50 @@ to uppercase.
 @end example
 @end deffn
 
+@node Macro Conditional Expansion
+@subsection Macro Conditional Expansion
+
+The @code{!IF} construct may be used inside a macro body to allow for
+conditional expansion.  It takes the following forms:
+
+@example
+!IF (condition) !THEN true-expansion !ENDIF
+!IF (condition) !THEN true-expansion !ELSE false-expansion !ENDIF
+@end example
+
+When the @var{condition} evaluates to true, @var{true-expansion} is
+expanded.  When it evaluates to false, @var{false-expansion} is
+expanded, if it is present.  The unquoted value @samp{0} is considered
+false, and all other values are considered true.
+
+Within @var{condition}, macros, macro arguments, and macro functions
+are expanded.  After expansion, the condition is evaluated as a macro
+expression that may use only the following operators, in descending
+order of operator precedence:
+
+@example
+()
+!EQ !NE !GT !LT !GE !LE = ~= <> > < >= <=
+!NOT ~
+!AND &
+!OR |
+@end example
+
+All of these operators yield a Boolean result, either @samp{0} for
+false or @samp{1} for true.
+
+If an operand is a quoted string, then the operator considers the
+contents of the quoted string; otherwise, it must be a single token.
+Thus, @code{1 = '1'} is true, and @code{'a b' = a b} is in error
+because the right-hand operand is two tokens.
+
+Comparisons in macro expressions are always string comparisons.  This
+can be surprising when the operands are numbers: e.g.@: @code{1 < 1.0}
+and @code{10 < 2} both evaluate to @samp{1} (true).
+
+Macro expression comparisons are case sensitive, so that @code{a = A}
+evaluates to @samp{0} (false).
+
 @node Macro Settings
 @subsection Macro Settings
 
@@ -551,7 +591,9 @@ of each macro in the input.  This feature can be useful for debugging
 macro definitions.
 
 MNEST (@pxref{SET MNEST}) limits the depth of expansion of macro
-calls, that is, the nesting level of macro expansion.
+calls, that is, the nesting level of macro expansion.  The default is
+50.  This is mainly useful to avoid infinite expansion in the case of
+a macro that calls itself.
 
 MITERATE