doc/flow-control.texi

   1 @node Conditionals and Looping
   2 @chapter Conditional and Looping Constructs
   3 @cindex conditionals
   4 @cindex loops
   5 @cindex flow of control
   6 @cindex control flow
   7
   8 This chapter documents PSPP commands used for conditional execution,
   9 looping, and flow of control.
  10
  11 @menu
  12 * BREAK::                       Exit a loop.
  13 * DO IF::                       Conditionally execute a block of code.
  14 * DO REPEAT::                   Textually repeat a code block.
  15 * LOOP::                        Repeat a block of code.
  16 @end menu
  17
  18 @node BREAK
  19 @section BREAK
  20 @vindex BREAK
  21
  22 @display
  23 BREAK.
  24 @end display
  25
  26 @cmd{BREAK} terminates execution of the innermost currently executing
  27 @cmd{LOOP} construct.
  28
  29 @cmd{BREAK} is allowed only inside @cmd{LOOP}@dots{}@cmd{END LOOP}.
  30 @xref{LOOP}, for more details.
  31
  32 @node DO IF
  33 @section DO IF
  34 @vindex DO IF
  35
  36 @display
  37 DO IF condition.
  38         @dots{}
  39 [ELSE IF condition.
  40         @dots{}
  41 ]@dots{}
  42 [ELSE.
  43         @dots{}]
  44 END IF.
  45 @end display
  46
  47 @cmd{DO IF} allows one of several sets of transformations to be
  48 executed, depending on user-specified conditions.
  49
  50 If the specified boolean expression evaluates as true, then the block
  51 of code following @cmd{DO IF} is executed.  If it evaluates as
  52 missing, then
  53 none of the code blocks is executed.  If it is false, then
  54 the boolean expression on the first @cmd{ELSE IF}, if present, is tested in
  55 turn, with the same rules applied.  If all expressions evaluate to
  56 false, then the @cmd{ELSE} code block is executed, if it is present.
  57
  58 When @cmd{DO IF} or @cmd{ELSE IF} is specified following @cmd{TEMPORARY}
  59 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
  60 (@pxref{LAG}).
  61
  62 @node DO REPEAT
  63 @section DO REPEAT
  64 @vindex DO REPEAT
  65
  66 @display
  67 DO REPEAT dummy_name=expansion@dots{}.
  68         @dots{}
  69 END REPEAT [PRINT].
  70
  71 expansion takes one of the following forms:
  72         var_list
  73         num_or_range@dots{}
  74         'string'@dots{}
  75         ALL
  76
  77 num_or_range takes one of the following forms:
  78         number
  79         num1 TO num2
  80 @end display
  81
  82 @cmd{DO REPEAT} repeats a block of code, textually substituting
  83 different variables, numbers, or strings into the block with each
  84 repetition.
  85
  86 Specify a dummy variable name followed by an equals sign (@samp{=})
  87 and the list of replacements.  Replacements can be a list of existing
  88 or new variables, numbers, strings, or @code{ALL} to specify all
  89 existing variables.  When numbers are specified, runs of increasing
  90 integers may be indicated as @code{@var{num1} TO @var{num2}}, so that
  91 @samp{1 TO 5} is short for @samp{1 2 3 4 5}.
  92
  93 Multiple dummy variables can be specified.  Each
  94 variable must have the same number of replacements.
  95
  96 The code within @cmd{DO REPEAT} is repeated as many times as there are
  97 replacements for each variable.  The first time, the first value for
  98 each dummy variable is substituted; the second time, the second value
  99 for each dummy variable is substituted; and so on.
 100
 101 Dummy variable substitutions work like macros.  They take place
 102 anywhere in a line that the dummy variable name occurs.  This includes
 103 command and subcommand names, so command and subcommand names that
 104 appear in the code block should not be used as dummy variable
 105 identifiers.  Dummy variable substitutions do not occur inside quoted
 106 strings, comments, unquoted strings (such as the text on the
 107 @cmd{TITLE} or @cmd{DOCUMENT} command), or inside @cmd{BEGIN
 108 DATA}@dots{}@cmd{END DATA}.
 109
 110 New variable names used as replacements are not automatically created
 111 as variables, but only if used in the code block in a context that
 112 would create them, e.g.@: on a @cmd{NUMERIC} or @cmd{STRING} command
 113 or on the left side of a @cmd{COMPUTE} assignment.
 114
 115 Any command may appear within DO REPEAT, including nested DO REPEAT
 116 commands.  If @cmd{INCLUDE} or @cmd{INSERT} appears within DO REPEAT,
 117 the substitutions do not apply to the included file.
 118
 119 If PRINT is specified on @cmd{END REPEAT}, the commands after substitutions
 120 are made are printed to the listing file, prefixed by a plus sign
 121 (@samp{+}).
 122
 123 @node LOOP
 124 @section LOOP
 125 @vindex LOOP
 126
 127 @display
 128 LOOP [index_var=start TO end [BY incr]] [IF condition].
 129         @dots{}
 130 END LOOP [IF condition].
 131 @end display
 132
 133 @cmd{LOOP} iterates a group of commands.  A number of
 134 termination options are offered.
 135
 136 Specify index_var to make that variable count from one value to
 137 another by a particular increment.  index_var must be a pre-existing
 138 numeric variable.  start, end, and incr are numeric expressions
 139 (@pxref{Expressions}.)
 140
 141 During the first iteration, index_var is set to the value of start.
 142 During each successive iteration, index_var is increased by the value of
 143 incr.  If end > start, then the loop terminates when index_var > end;
 144 otherwise it terminates when index_var < end.  If incr is not specified
 145 then it defaults to +1 or -1 as appropriate.
 146
 147 If end > start and incr < 0, or if end < start and incr > 0, then the
 148 loop is never executed.  index_var is nevertheless set to the value of
 149 start.
 150
 151 Modifying index_var within the loop is allowed, but it has no effect on
 152 the value of index_var in the next iteration.
 153
 154 Specify a boolean expression for the condition on @cmd{LOOP} to
 155 cause the loop to be executed only if the condition is true.  If the
 156 condition is false or missing before the loop contents are executed the
 157 first time, the loop contents are not executed at all.
 158
 159 If index and condition clauses are both present on @cmd{LOOP}, the
 160 index variable is always set before the condition is evaluated.  Thus,
 161 a condition that makes use of the index variable will always see the
 162 index value to be used in the next execution of the body.
 163
 164 Specify a boolean expression for the condition on @cmd{END LOOP} to cause
 165 the loop to terminate if the condition is true after the enclosed
 166 code block is executed.  The condition is evaluated at the end of the
 167 loop, not at the beginning, so that the body of a loop with only a
 168 condition on @cmd{END LOOP} will always execute at least once.
 169
 170 If neither the index clause nor either condition clause is
 171 present, then the loop is executed MXLOOPS (@pxref{SET}) times.
 172
 173 @cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).
 174
 175 Loop index variables are by default reset to system-missing from one
 176 case to another, not left, unless a scratch variable is used as index.
 177 When loops are nested, this is usually undesired behavior, which can
 178 be corrected with @cmd{LEAVE} (@pxref{LEAVE}) or by using a scratch
 179 variable as the loop index.
 180
 181 When @cmd{LOOP} or @cmd{END LOOP} is specified following @cmd{TEMPORARY}
 182 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
 183 (@pxref{LAG}).