Merge commit 'origin/master' into charset
[pspp-builds.git] / 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
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 dummy 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 some combination),
88 numbers, or strings.  When new variable names are
89 specified, @cmd{DO REPEAT} creates them as numeric variables.  When numbers
90 are specified, runs of increasing integers may be indicated as
91 @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 as a token,
104 including command and subcommand names.  For this reason,
105 words commonly used in command and subcommand names should not be used
106 as dummy 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
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
149 index variable is always set before the condition is evaluated.  Thus,
150 a condition that makes use of the index variable will always see the
151 index value to be used in the next execution of the body.
152
153 Specify a boolean expression for the condition on @cmd{END LOOP} to cause
154 the loop to terminate if the condition is true after the enclosed
155 code block is executed.  The condition is evaluated at the end of the
156 loop, not at the beginning, so that the body of a loop with only a
157 condition on @cmd{END LOOP} will always execute at least once.
158
159 If neither the index clause nor either condition clause is
160 present, then the loop is executed MXLOOPS (@pxref{SET}) times.
161
162 @cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).
163
164 Loop index variables are by default reset to system-missing from one
165 case to another, not left, unless a scratch variable is used as index.
166 When loops are nested, this is usually undesired behavior, which can
167 be corrected with @cmd{LEAVE} (@pxref{LEAVE}) or by using a scratch
168 variable as the loop index.
169
170 When @cmd{LOOP} or @cmd{END LOOP} is specified following @cmd{TEMPORARY}
171 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
172 (@pxref{LAG}).