doc/flow-control.texi

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