zip-reader.c: Fix memory leak
[pspp] / 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}).