Conditional and Looping Constructs
**********************************

This chapter documents pspp commands used for conditional execution, looping, and flow of control.

BREAK
=====

     BREAK.

BREAK terminates execution of the innermost currently executing LOOP construct.

BREAK is allowed only inside LOOP...END LOOP. See LOOP, for more details.

DEFINE
======

     DEFINE macro_name([argument[/argument]...])
     ...body...
     !ENDDEFINE.

     Each argument takes the following form:
       {!arg_name =,!POSITIONAL} [!DEFAULT(default)] [!NOEXPAND]
       {!TOKENS(count),!CHAREND('token'),!ENCLOSE('start','end'),!CMDEND}

     The following directives may be used within the body:
       !OFFEXPAND
       !ONEXPAND

     The following functions may be used within the body:
       !BLANKS(count)
       !CONCAT(arg...)
       !EVAL(arg)
       !HEAD(arg)
       !INDEX(haystack, needle)
       !LENGTH(arg)
       !NULL
       !QUOTE(arg)
       !SUBSTR(arg, start[, count])
       !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

The DEFINE command defines a macro that can later be called any number of times within a syntax file.  Each time it is called, the macro's body is expanded, that is, substituted, as if the body had been written instead of the macro call.  A macro may accept arguments, whose values are specified at the point of invocation and expanded in the body where they are referenced.  Macro bodies may also use various directives and functions, which are also expanded when the macro is called.

Many identifiers associated with macros begin with !, a 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.

Macro Basics
------------

The simplest macros have no arguments.  The following defines a macro named !vars that expands to the variable names v1 v2 v3, along with a few example uses.  The macro's name begins with !, which is optional for macro names.  The () following the macro name are required:

     DEFINE !vars()
     v1 v2 v3
     !ENDDEFINE.

     DESCRIPTIVES !vars.
     FREQUENCIES /VARIABLES=!vars.

Macros can also expand to entire commands.  For example, the following example performs the same analyses as the last one:

     DEFINE !commands()
     DESCRIPTIVES v1 v2 v3.
     FREQUENCIES /VARIABLES=v1 v2 v3.
     !ENDDEFINE.

     !commands

The body of a macro can call another macro.  For example, we could combine the two preceding examples, with !commands calling !vars to obtain the variables to analyze.  The following shows one way that could work:

     DEFINE !commands()
     DESCRIPTIVES !vars.
     FREQUENCIES /VARIABLES=!vars.
     !ENDDEFINE.

     DEFINE !vars() v1 v2 v3 !ENDDEFINE.
     !commands

     * We can redefine the variables macro to analyze different variables:
     DEFINE !vars() v4 v5 !ENDDEFINE.
     !commands

The !commands macro would be easier to use if it took the variables to analyze as an argument rather than through another macro. The following section shows how to do that.

Macro Arguments
---------------

Macros may take any number of arguments, which are specified within the parentheses in the DEFINE command.  Arguments come in two varieties based on how their values are specified when the macro is called:

  * A positional argument has a required value that follows the macro's name.  Use the !POSITIONAL keyword to declare a positional argument.

     References to a positional argument in a macro body are numbered: !1 is the first positional argument, !2 the second, and so on.  In addition, !* expands to all of the positional argument values, separated by a space.

     The following example uses a positional argument:

          DEFINE !analyze(!POSITIONAL !CMDEND)
          DESCRIPTIVES !1.
          FREQUENCIES /VARIABLES=!1.
          !ENDDEFINE.

          !analyze v1 v2 v3.
          !analyze v4 v5.

  * A keyword argument has a name.  In the macro call, its value is specified with the syntax NAME=VALUE.  Because of the names, keyword argument values may take any order in a macro call. If one is omitted, then a default value is used: either the value specified in !DEFAULT(VALUE), or an empty value otherwise.

     In declaration and calls, a keyword argument's name may not begin with !, but references to it in the macro body do start with a leading !.

     The following example uses a keyword argument that defaults to ALL if the argument is not assigned a value:

          DEFINE !analyze_kw(vars=!DEFAULT(ALL) !CMDEND)
          DESCRIPTIVES !vars.
          FREQUENCIES /VARIABLES=!vars.
          !ENDDEFINE.

          !analyze_kw vars=v1 v2 v3.  /* Analyze specified variables.
          !analyze_kw.                /* Analyze all variables.

If a macro has both positional and keyword arguments, then the positional arguments must come first in the DEFINE command, and their values also come first in macro calls.

Each argument declaration specifies the form of its value:

!TOKENS(COUNT)
     Exactly COUNT tokens, e.g. !TOKENS(1) for a single token.  Each identifier, number, quoted string, operator, or punctuator is a token.  See Tokens, for a complete definition.

     The following variant of !analyze_kw accepts only a single variable name (or ALL) as its argument:

          DEFINE !analyze_one_var(!POSITIONAL !TOKENS(1))
          DESCRIPTIVES !1.
          FREQUENCIES /VARIABLES=!1.
          !ENDDEFINE.

          !analyze_one_var v1.

!CHAREND('TOKEN')
     Any number of tokens up to TOKEN, which should be an operator or punctuator token such as / or +.  The TOKEN does not become part of the value.

     With the following variant of !analyze_kw, the variables must be following by /:

          DEFINE !analyze_parens(vars=!CHARNED('/'))
          DESCRIPTIVES !vars.
          FREQUENCIES /VARIABLES=!vars.
          !ENDDEFINE.

          !analyze_parens vars=v1 v2 v3/.

!ENCLOSE('START','END')
     Any number of tokens enclosed between START and END, which should each be operator or punctuator tokens.  For example, use !ENCLOSE('(',')') for a value enclosed within parentheses. (Such a value could never have right parentheses inside it, even paired with left parentheses.)  The start and end tokens are not part of the value.

     With the following variant of !analyze_kw, the variables must be specified within parentheses:

          DEFINE !analyze_parens(vars=!ENCLOSE('(',')'))
          DESCRIPTIVES !vars.
          FREQUENCIES /VARIABLES=!vars.
          !ENDDEFINE.

          !analyze_parens vars=(v1 v2 v3).

!CMDEND
     Any number of tokens up to the end of the command.  This should be used only for the last positional parameter, since it consumes all of the tokens in the command calling the macro.

     The following variant of !analyze_kw takes all the variable names up to the end of the command as its argument:

          DEFINE !analyze_kw(vars=!CMDEND)
          DESCRIPTIVES !vars.
          FREQUENCIES /VARIABLES=!vars.
          !ENDDEFINE.

          !analyze_kw vars=v1 v2 v3.

By default, when an argument's value contains a macro call, the call is expanded each time the argument appears in the macro's body.  The !NOEXPAND keyword in an argument declaration suppresses this expansion.  See Controlling Macro Expansion, for details.

Controlling Macro Expansion
---------------------------

Multiple factors control whether macro calls are expanded in different situations.  At the highest level, SET MEXPAND controls whether macro calls are expanded.  By default, it is enabled.  See SET MEXPAND, for details.

A macro body may contain macro calls.  By default, these are expanded. If a macro body contains !OFFEXPAND or !ONEXPAND directives, then !OFFEXPAND disables expansion of macro calls until the following !ONEXPAND.

A macro argument's value may contain a macro call.  By default, these macro calls are expanded.  If the argument was declared with the !NOEXPAND keyword, they are not expanded.

The argument to a macro function is a special context that does not expand macro calls.  For example, if !vars is the name of a macro, then !LENGTH(!vars) expands to 5, as does !LENGTH(!1) if positional argument 1 has value !vars. In these cases, use the !EVAL macro function to expand macros, e.g. !LENGTH(!EVAL(!vars)) or !LENGTH(!EVAL(!1)). See Macro Functions, for details.

These rules apply to macro calls.  Uses of macro functions and macro arguments within a macro body are always expanded.

Macro Functions
---------------

Macro bodies may manipulate syntax using macro functions.  Macro functions accept tokens as arguments and expand to sequences of characters.

The arguments to macro functions have a restricted form.  They may only be a single token (such as an identifier or a string), a macro argument, or a call to a macro function.  Thus, x, 5.0, x, !1, "5 + 6", and !CONCAT(x,y) are valid macro arguments, but x y and 5 + 6 are not.

Macro functions expand to sequences of characters.  When these character strings are processed further as character strings, e.g. with !LENGTH, any character string is valid.  When they are interpreted as PSPP syntax, e.g. when the expansion becomes part of a command, they need to be valid for that purpose.  For example, !UNQUOTE("It's") will yield an error if the expansion It's becomes part of a PSPP command, because it contains unbalanced single quotes, but !LENGTH(!UNQUOTE("It's")) expands to 4.

The following macro functions are available.  Each function's documentation includes examples in the form CALL ==> EXPANSION.

 -- Macro Function: !BLANKS (count)
     Expands to COUNT unquoted spaces, where COUNT is a nonnegative integer.  Outside quotes, any positive number of spaces are equivalent; for a quoted string of spaces, use !QUOTE(!BLANKS(COUNT)).

     In the examples below, _ stands in for a space to make the results visible.

          !BLANKS(0)                  ==> empty
          !BLANKS(1)                  ==> _
          !BLANKS(2)                  ==> __
          !QUOTE(!BLANKS(5))          ==> '_____'

 -- Macro Function: !CONCAT (arg...)
     Expands to the concatenation of all of the arguments.  Before concatenation, each quoted string argument is unquoted, as if !UNQUOTE were applied.  This allows for ``token pasting'', combining two (or more) tokens into a single one:

          !CONCAT(x, y)                ==> xy
          !CONCAT('x', 'y')            ==> xy
          !CONCAT(12, 34)              ==> 1234
          !CONCAT(!NULL, 123)          ==> 123

     !CONCAT is often used for constructing a series of similar variable names from a prefix followed by a number and perhaps a suffix.  For example:

          !CONCAT(x, 0)                ==> x0
          !CONCAT(x, 0, y)             ==> x0y

     An identifier token must begin with a letter (or # or @), which means that attempting to use a number as the first part of an identifier will produce a pair of distinct tokens rather than a single one.  For example:

          !CONCAT(0, x)                ==> 0 x
          !CONCAT(0, x, y)             ==> 0 xy

 -- Macro Function: !EVAL (arg)
     Expands macro calls in ARG.  This is especially useful if ARG is the name of a macro or a macro argument that expands to one, because arguments to macro functions are not expanded by default.

     The following examples assume that !vars is a macro that expands to a b c:

          !vars                        ==> a b c
          !QUOTE(!vars)                ==> '!vars'
          !EVAL(!vars)                 ==> a b c
          !QUOTE(!EVAL(!vars))         ==> 'a b c'

     These examples additionally assume that argument !1 has value !vars:

          !1                           ==> a b c
          !QUOTE(!1)                   ==> '!vars'
          !EVAL(!1)                    ==> a b c
          !QUOTE(!EVAL(!1))            ==> 'a b c'

 -- Macro Function: !HEAD (arg)
 -- Macro Function: !TAIL (arg)
     !HEAD expands to just the first token in an unquoted version of ARG, and !TAIL to all the tokens after the first.

          !HEAD('a b c')               ==> a
          !HEAD('a')                   ==> a
          !HEAD(!NULL)                 ==> empty
          !HEAD('')                    ==> empty

          !TAIL('a b c')               ==> b c
          !TAIL('a')                   ==> empty
          !TAIL(!NULL)                 ==> empty
          !TAIL('')                    ==> empty

 -- Macro Function: !INDEX (haystack, needle)
     Looks for NEEDLE in HAYSTACK.  If it is present, expands to the 1-based index of its first occurrence; if not, expands to 0.

          !INDEX(banana, an)           ==> 2
          !INDEX(banana, nan)          ==> 3
          !INDEX(banana, apple)        ==> 0
          !INDEX("banana", nan)        ==> 4
          !INDEX("banana", "nan")      ==> 0
          !INDEX(!UNQUOTE("banana"), !UNQUOTE("nan")) ==> 3

 -- Macro Function: !LENGTH (arg)
     Expands to a number token representing the number of characters in ARG.

          !LENGTH(123)                 ==> 3
          !LENGTH(123.00)              ==> 6
          !LENGTH( 123 )               ==> 3
          !LENGTH("123")               ==> 5
          !LENGTH(xyzzy)               ==> 5
          !LENGTH("xyzzy")             ==> 7
          !LENGTH("xy""zzy")           ==> 9
          !LENGTH(!UNQUOTE("xyzzy"))   ==> 5
          !LENGTH(!UNQUOTE("xy""zzy")) ==> 6
          !LENGTH(!1)                  ==> 5 if !1 is a b c
          !LENGTH(!1)                  ==> 0 if !1 is empty
          !LENGTH(!NULL)               ==> 0

 -- Macro Function: !NULL
     Expands to an empty character sequence.

          !NULL                        ==> empty
          !QUOTE(!NULL)                ==> ''

 -- Macro Function: !QUOTE (arg)
 -- Macro Function: !UNQUOTE (arg)
     The !QUOTE function expands to its argument surrounded by apostrophes, doubling any apostrophes inside the argument to make sure that it is valid PSPP syntax for a string.  If the argument was already a quoted string, !QUOTE expands to it unchanged.

     Given a quoted string argument, the !UNQUOTED function expands to the string's contents, with the quotes removed and any doubled quote marks reduced to singletons.  If the argument was not a quoted string, !UNQUOTE expands to the argument unchanged.

          !QUOTE(123.0)                ==> '123.0'
          !QUOTE( 123 )                ==> '123'
          !QUOTE('a b c')              ==> 'a b c'
          !QUOTE("a b c")              ==> "a b c"
          !QUOTE(!1)                   ==> 'a ''b'' c' if !1 is a 'b' c

          !UNQUOTE(123.0)              ==> 123.0
          !UNQUOTE( 123 )              ==> 123
          !UNQUOTE('a b c')            ==> a b c
          !UNQUOTE("a b c")            ==> a b c
          !UNQUOTE(!1)                 ==> a 'b' c if !1 is a 'b' c

          !QUOTE(!UNQUOTE(123.0))      ==> '123.0'
          !QUOTE(!UNQUOTE( 123 ))      ==> '123'
          !QUOTE(!UNQUOTE('a b c'))    ==> 'a b c'
          !QUOTE(!UNQUOTE("a b c"))    ==> 'a b c'
          !QUOTE(!UNQUOTE(!1))         ==> 'a ''b'' c' if !1 is a 'b' c

 -- Macro Function: !SUBSTR (arg, start[, count])
     Expands to a substring of ARG starting from 1-based position START.  If COUNT is given, it limits the number of characters in the expansion; if it is omitted, then the expansion extends to the end of ARG.

          !SUBSTR(banana, 3)           ==> nana
          !SUBSTR(banana, 3, 3)        ==> nan
          !SUBSTR("banana", 3)         ==> error (anana" is not a valid token)
          !SUBSTR(!UNQUOTE("banana"), 3) ==> nana
          !SUBSTR("banana", 3, 3)      ==> ana

          !SUBSTR(banana, 3, 0)        ==> empty
          !SUBSTR(banana, 3, 10)       ==> nana
          !SUBSTR(banana, 10, 3)       ==> empty

 -- Macro Function: !UPCASE (arg)
     Expands to an unquoted version of ARG with all letters converted to uppercase.

          !UPCASE(freckle)             ==> FRECKLE
          !UPCASE('freckle')           ==> FRECKLE
          !UPCASE('a b c')             ==> A B C
          !UPCASE('A B C')             ==> A B C

Macro Conditional Expansion
---------------------------

The !IF construct may be used inside a macro body to allow for conditional expansion.  It takes the following forms:

     !IF (condition) !THEN true-expansion !IFEND
     !IF (condition) !THEN true-expansion !ELSE false-expansion !IFEND

When the CONDITION evaluates to true, TRUE-EXPANSION is expanded.  When it evaluates to false, FALSE-EXPANSION is expanded, if it is present.  The unquoted value 0 is considered false, and all other values are considered true.

Within 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:

     ()
     !EQ !NE !GT !LT !GE !LE = ~= <> > < >= <=
     !NOT ~
     !AND &
     !OR |

All of these operators yield a Boolean result, either 0 for false or 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, 1 = '1' is true, and '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. 1 < 1.0 and 10 < 2 both evaluate to 1 (true).

Macro expression comparisons are case sensitive, so that a = A evaluates to 0 (false).

Macro Settings
--------------

Some macro behavior is controlled through the SET command (see SET).  This section describes these settings.

Any SET command that changes these settings within a macro body only takes effect following the macro.  This is because PSPP expands a macro's entire body at once, so that the SET command inside the body only executes afterwards.

The MEXPAND setting (see SET MEXPAND) controls whether macros will be expanded at all.  By default, macro expansion is on.  To avoid expansion of macros called within a macro body, use !OFFEXPAND and !ONEXPAND (see Controlling Macro Expansion).

When MPRINT (see SET MPRINT) is turned on, PSPP logs an expansion of each macro in the input.  This feature can be useful for debugging macro definitions.

MNEST (see SET MNEST) limits the depth of expansion of macro 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

PRESERVE...RESTORE

SET MEXPAND, etc. doesn't work inside macro bodies.

Extra Notes
-----------

!* expands to all the positional arguments.

Macros in comments.

Macros in titles.

DO IF
=====

     DO IF condition.
             ...
     [ELSE IF condition.
             ...
     ]...
     [ELSE.
             ...]
     END IF.

DO IF allows one of several sets of transformations to be executed, depending on user-specified conditions.

If the specified boolean expression evaluates as true, then the block of code following DO IF is executed.  If it evaluates as missing, then none of the code blocks is executed.  If it is false, then the boolean expression on the first ELSE IF, if present, is tested in turn, with the same rules applied.  If all expressions evaluate to false, then the ELSE code block is executed, if it is present.

When DO IF or ELSE IF is specified following TEMPORARY (see TEMPORARY), the LAG function may not be used (see LAG).

DO REPEAT
=========

     DO REPEAT dummy_name=expansion....
             ...
     END REPEAT [PRINT].

     expansion takes one of the following forms:
             var_list
             num_or_range...
             'string'...
             ALL

     num_or_range takes one of the following forms:
             number
             num1 TO num2

DO REPEAT repeats a block of code, textually substituting different variables, numbers, or strings into the block with each repetition.

Specify a dummy variable name followed by an equals sign (=) and the list of replacements.  Replacements can be a list of existing or new variables, numbers, strings, or ALL to specify all existing variables.  When numbers are specified, runs of increasing integers may be indicated as NUM1 TO NUM2, so that 1 TO 5 is short for 1 2 3 4 5.

Multiple dummy variables can be specified.  Each variable must have the same number of replacements.

The code within DO REPEAT is repeated as many times as there are replacements for each variable.  The first time, the first value for each dummy variable is substituted; the second time, the second value for each dummy variable is substituted; and so on.

Dummy variable substitutions work like macros.  They take place anywhere in a line that the dummy variable name occurs.  This includes command and subcommand names, so command and subcommand names that appear in the code block should not be used as dummy variable identifiers.  Dummy variable substitutions do not occur inside quoted strings, comments, unquoted strings (such as the text on the TITLE or DOCUMENT command), or inside BEGIN DATA...END DATA.

Substitution occurs only on whole words, so that, for example, a dummy variable PRINT would not be substituted into the word PRINTOUT.

New variable names used as replacements are not automatically created as variables, but only if used in the code block in a context that would create them, e.g. on a NUMERIC or STRING command or on the left side of a COMPUTE assignment.

Any command may appear within DO REPEAT, including nested DO REPEAT commands.  If INCLUDE or INSERT appears within DO REPEAT, the substitutions do not apply to the included file.

If PRINT is specified on END REPEAT, the commands after substitutions are made should be printed to the listing file, prefixed by a plus sign (+).  This feature is not yet implemented.

LOOP
====

     LOOP [INDEX_VAR=START TO END [BY INCR]] [IF CONDITION].
             ...
     END LOOP [IF CONDITION].

LOOP iterates a group of commands.  A number of termination options are offered.

Specify index_var to make that variable count from one value to another by a particular increment.  INDEX_VAR must be a pre-existing numeric variable.  START, END, and INCR are numeric expressions (see Expressions.)

During the first iteration, INDEX_VAR is set to the value of START. During each successive iteration, INDEX_VAR is increased by the value of INCR.  If END > START, then the loop terminates when INDEX_VAR > END; otherwise it terminates when INDEX_VAR < END.  If INCR is not specified then it defaults to +1 or -1 as appropriate.

If END > START and INCR < 0, or if END < START and INCR > 0, then the loop is never executed.  INDEX_VAR is nevertheless set to the value of start.

Modifying INDEX_VAR within the loop is allowed, but it has no effect on the value of INDEX_VAR in the next iteration.

Specify a boolean expression for the condition on LOOP to cause the loop to be executed only if the condition is true.  If the condition is false or missing before the loop contents are executed the first time, the loop contents are not executed at all.

If index and condition clauses are both present on LOOP, the index variable is always set before the condition is evaluated.  Thus, a condition that makes use of the index variable will always see the index value to be used in the next execution of the body.

Specify a boolean expression for the condition on END LOOP to cause the loop to terminate if the condition is true after the enclosed code block is executed.  The condition is evaluated at the end of the loop, not at the beginning, so that the body of a loop with only a condition on END LOOP will always execute at least once.

If the index clause is not present, then the loop is executed at most MAX_LOOPS (see SET) times (but possibly fewer, if a condition clause evaluates to false or if BREAK executes). The default value of MAX_LOOPS is 40.

BREAK also terminates LOOP execution (see BREAK).

Loop index variables are by default reset to system-missing from one case to another, not left, unless a scratch variable is used as index. When loops are nested, this is usually undesired behavior, which can be corrected with LEAVE (see LEAVE) or by using a scratch variable as the loop index.

When LOOP or END LOOP is specified following TEMPORARY (see TEMPORARY), the LAG function may not be used (see LAG).