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 New variable names used as replacements are not automatically created
 112 as variables, but only if used in the code block in a context that
 113 would create them, e.g.@: on a @cmd{NUMERIC} or @cmd{STRING} command
 114 or on the left side of a @cmd{COMPUTE} assignment.
 115
 116 Any command may appear within @subcmd{DO REPEAT}, including nested @subcmd{DO REPEAT}
 117 commands.  If @cmd{INCLUDE} or @cmd{INSERT} appears within @subcmd{DO REPEAT},
 118 the substitutions do not apply to the included file.
 119
 120 If @subcmd{PRINT} is specified on @cmd{END REPEAT}, the commands after substitutions
 121 are made are printed to the listing file, prefixed by a plus sign
 122 (@samp{+}).
 123
 124 @node LOOP
 125 @section LOOP
 126 @vindex LOOP
 127
 128 @display
 129 LOOP [@var{index_var}=@var{start} TO @var{end} [BY @var{incr}]] [IF @var{condition}].
 130         @dots{}
 131 END LOOP [IF @var{condition}].
 132 @end display
 133
 134 @cmd{LOOP} iterates a group of commands.  A number of
 135 termination options are offered.
 136
 137 Specify index_var to make that variable count from one value to
 138 another by a particular increment.  @var{index_var} must be a pre-existing
 139 numeric variable.  @var{start}, @var{end}, and @var{incr} are numeric expressions
 140 (@pxref{Expressions}.)
 141
 142 During the first iteration, @var{index_var} is set to the value of @var{start}.
 143 During each successive iteration, @var{index_var} is increased by the value of
 144 @var{incr}.  If @var{end} > @var{start}, then the loop terminates
 145 when @var{index_var} > @var{end};
 146 otherwise it terminates when @var{index_var} < @var{end}.  If @var{incr} is not specified
 147 then it defaults to +1 or -1 as appropriate.
 148
 149 If @var{end} > @var{start} and @var{incr} < 0, or if @var{end} < @var{start} and
 150  @var{incr} > 0, then the
 151 loop is never executed.  @var{index_var} is nevertheless set to the value of
 152 start.
 153
 154 Modifying @var{index_var} within the loop is allowed, but it has no effect on
 155 the value of @var{index_var} in the next iteration.
 156
 157 Specify a boolean expression for the condition on @cmd{LOOP} to
 158 cause the loop to be executed only if the condition is true.  If the
 159 condition is false or missing before the loop contents are executed the
 160 first time, the loop contents are not executed at all.
 161
 162 If index and condition clauses are both present on @cmd{LOOP}, the
 163 index variable is always set before the condition is evaluated.  Thus,
 164 a condition that makes use of the index variable will always see the
 165 index value to be used in the next execution of the body.
 166
 167 Specify a boolean expression for the condition on @cmd{END LOOP} to cause
 168 the loop to terminate if the condition is true after the enclosed
 169 code block is executed.  The condition is evaluated at the end of the
 170 loop, not at the beginning, so that the body of a loop with only a
 171 condition on @cmd{END LOOP} will always execute at least once.
 172
 173 If neither the index clause nor either condition clause is
 174 present, then the loop is executed @var{max_loops} (@pxref{SET}) times.
 175 The default value of @var{max_loops} is 40.
 176
 177 @cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).
 178
 179 Loop index variables are by default reset to system-missing from one
 180 case to another, not left, unless a scratch variable is used as index.
 181 When loops are nested, this is usually undesired behavior, which can
 182 be corrected with @cmd{LEAVE} (@pxref{LEAVE}) or by using a scratch
 183 variable as the loop index.
 184
 185 When @cmd{LOOP} or @cmd{END LOOP} is specified following @cmd{TEMPORARY}
 186 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
 187 (@pxref{LAG}).