pintos-os.org Git - pspp/blob - doc/flow-control.texi

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