doc/flow-control.texi

   1 @node Conditionals and Looping, Statistics, Data Selection, Top
   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, DO IF, Conditionals and Looping, Conditionals and Looping
  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, DO REPEAT, BREAK, Conditionals and Looping
  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, LOOP, DO IF, Conditionals and Looping
  63 @section DO REPEAT
  64 @vindex DO REPEAT
  65
  66 @display
  67 DO REPEAT repvar_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
  76 num_or_range takes one of the following forms:
  77         number
  78         num1 TO num2
  79 @end display
  80
  81 @cmd{DO REPEAT} repeats a block of code, textually substituting
  82 different variables, numbers, or strings into the block with each
  83 repetition.
  84
  85 Specify a repeat variable name followed by an equals sign (@samp{=}) and
  86 the list of replacements.  Replacements can be a list of variables
  87 (which may be existing variables or new variables or a combination
  88 thereof), of numbers, or of strings.  When new variable names are
  89 specified, @cmd{DO REPEAT} creates them as numeric variables.  When numbers
  90 are specified, runs of integers may be indicated with TO notation, for
  91 instance @samp{1 TO 5} and @samp{1 2 3 4 5} would be equivalent.  There
  92 is no equivalent notation for string values.
  93
  94 Multiple repeat variables can be specified.  When this is done, each
  95 variable must have the same number of replacements.
  96
  97 The code within @cmd{DO REPEAT} is repeated as many times as there are
  98 replacements for each variable.  The first time, the first value for
  99 each repeat variable is substituted; the second time, the second value
 100 for each repeat variable is substituted; and so on.
 101
 102 Repeat variable substitutions work like macros.  They take place
 103 anywhere in a line that the repeat variable name occurs as a token,
 104 including command and subcommand names.  For this reason it is not a
 105 good idea to select words commonly used in command and subcommand names
 106 as repeat variable identifiers.
 107
 108 If PRINT is specified on @cmd{END REPEAT}, the commands after substitutions
 109 are made are printed to the listing file, prefixed by a plus sign
 110 (@samp{+}).
 111
 112 @node LOOP,  , DO REPEAT, Conditionals and Looping
 113 @section LOOP
 114 @vindex LOOP
 115
 116 @display
 117 LOOP [index_var=start TO end [BY incr]] [IF condition].
 118         @dots{}
 119 END LOOP [IF condition].
 120 @end display
 121
 122 @cmd{LOOP} iterates a group of commands.  A number of
 123 termination options are offered.
 124
 125 Specify index_var to make that variable count from one value to
 126 another by a particular increment.  index_var must be a pre-existing
 127 numeric variable.  start, end, and incr are numeric expressions
 128 (@pxref{Expressions}.)
 129
 130 During the first iteration, index_var is set to the value of start.
 131 During each successive iteration, index_var is increased by the value of
 132 incr.  If end > start, then the loop terminates when index_var > end;
 133 otherwise it terminates when index_var < end.  If incr is not specified
 134 then it defaults to +1 or -1 as appropriate.
 135
 136 If end > start and incr < 0, or if end < start and incr > 0, then the
 137 loop is never executed.  index_var is nevertheless set to the value of
 138 start.
 139
 140 Modifying index_var within the loop is allowed, but it has no effect on
 141 the value of index_var in the next iteration.
 142
 143 Specify a boolean expression for the condition on @cmd{LOOP} to
 144 cause the loop to be executed only if the condition is true.  If the
 145 condition is false or missing before the loop contents are executed the
 146 first time, the loop contents are not executed at all.
 147
 148 If index and condition clauses are both present on @cmd{LOOP}, the index
 149 clause is always evaluated first.
 150
 151 Specify a boolean expression for the condition on @cmd{END LOOP} to cause
 152 the loop to terminate if the condition is not true after the enclosed
 153 code block is executed.  The condition is evaluated at the end of the
 154 loop, not at the beginning.
 155
 156 If the index clause and both condition clauses are not present, then the
 157 loop is executed MXLOOPS (@pxref{SET}) times.
 158
 159 @cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).
 160
 161 Loop index variables are by default reset to system-missing from one
 162 case to another, not left, unless a scratch variable is used as index.
 163 When loops are nested, this is usually undesired behavior, which can
 164 be corrected with @cmd{LEAVE} (@pxref{LEAVE}) or by using a scratch
 165 variable as the loop index.
 166
 167 When @cmd{LOOP} or @cmd{END LOOP} is specified following @cmd{TEMPORARY}
 168 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
 169 (@pxref{LAG}).
 170 @setfilename ignored