1 # $NetBSD: directive-for.mk,v 1.22 2023/06/01 20:56:35 rillig Exp $
3 # Tests for the .for directive.
5 # TODO: Describe naming conventions for the loop variables.
8 # .for _FILE_ in values
9 # .for .FILE. in values
13 # varmod-loop.mk The ':@var@...@' modifier
15 # A typical use case for a .for loop is to populate a variable with a list of
16 # values depending on other variables. In simple cases, the same effect can
17 # be achieved using the ':@var@${var}@' modifier.
22 .if ${NUMBERS} != "1 2 3"
27 # The .for loop also works for multiple iteration variables.
28 # This is something that the modifier :@ cannot do.
29 .for name value in VARNAME value NAME2 value2
32 .if ${VARNAME} != "value" || ${NAME2} != "value2"
37 # The .for loop splits the items at whitespace, taking quotes into account,
38 # just like the :M or :S modifiers.
40 # Until 2012-06-03, the .for loop had split the items exactly at whitespace,
41 # without taking the quotes into account. This had resulted in 10 words.
43 .for var in one t\ w\ o "three three" 'four four' `five six`
51 # In the body of the .for loop, the iteration variables can be accessed
52 # like normal variables, even though they are not really variables.
54 # Instead, before interpreting the body of the .for loop, the body is
55 # generated by replacing each expression ${var} with ${:U1}, ${:U2} and so
58 # A noticeable effect of this implementation technique is that the .for
59 # iteration variables and the normal global variables live in separate
60 # namespaces and do not influence each other. The "scope" of the .for loop
61 # variables is restricted to the current makefile, it does not reach over to
62 # any included makefiles.
65 .for var var2 in 1 2 3 4
67 .if ${var} != "value before"
68 . warning After the .for loop, var must still have its original value.
70 .if ${var2} != "value before"
71 . warning After the .for loop, var2 must still have its original value.
74 # Everything from the paragraph above also applies if the loop body is
75 # empty. In this particular example, the items to be iterated are empty as
79 .for var var2 in ${:U}
81 .if ${var} != "value before"
82 . warning After the .for loop, var must still have its original value.
84 .if ${var2} != "value before"
85 . warning After the .for loop, var2 must still have its original value.
88 # Before for.c 1.39 from 2008-12-21, the values of the iteration variables
89 # were simply inserted as plain text and then parsed as usual, which made it
90 # possible to achieve all kinds of strange effects, such as generating '.if'
91 # directives or inserting '$' characters in random places, thereby changing
92 # how following '$' are interpreted.
94 # Before that date, the .for loop below expanded to:
96 # Since that date, the .for loop below expands to:
97 # EXPANSION${:U+}= value
102 EXPANSION${plus}= value
104 .if ${EXPANSION} != "before"
105 . error This must be a make from before 2009.
107 .if ${EXPANSION+} != "value"
108 . error This must be a make from before 2009.
111 # When the outer .for loop is expanded, it sees the expression ${i} and
112 # expands it. The inner loop then only sees the expression ${:Uouter} and
113 # has nothing more to expand.
122 # From https://gnats.netbsd.org/29985.
124 # Until 2008-12-21, the .for loop was expanded by replacing the variable
125 # value literally in the body. This could lead to situations where the
126 # characters from the variable value were interpreted as markup rather than
129 # Until 2012-06-03, the .for loop had split the words at whitespace, without
130 # taking quotes into account. This made it possible to have variable values
131 # like "a:\ a:\file.txt" that ended in a single backslash. Since then, the
132 # variable values have been replaced with expressions of the form ${:U...},
133 # which are not interpreted as code anymore.
134 .for path in a:\ a:\file.txt d:\\ d:\\file.txt
137 # expect-2: a:\ a:\file.txt
139 # expect-4: d:\\file.txt
142 # Ensure that braces and parentheses are properly escaped by the .for loop.
143 # Each line must print the same word 3 times.
144 # See ForLoop_SubstBody.
145 .for v in ( [ { ) ] } (()) [[]] {{}} )( ][ }{
154 # expect-08: (()) (()) (())
155 # expect-09: [[]] [[]] [[]]
156 # expect-10: {{}} {{}} {{}}
157 # expect-11: )( )( )(
158 # expect-12: ][ ][ ][
159 # expect-13: }{ }{ }{
161 # Before 2023-05-09, the variable names could contain arbitrary characters,
162 # except for whitespace, allowing for creative side effects, as usual for
163 # arbitrary code injection.
165 # expect+1: invalid character ':' in .for loop variable name
166 .for var:Q in value "quoted"
167 . info <${var}> <${var:Q}> <${var:Q:Q}>
170 # Before 2023-05-09, when variable names could contain '$', the short
171 # expression '$$' was preserved, the long expressions were substituted.
172 # expect+1: invalid character '$' in .for loop variable name
174 . info <$$> <${$}> <$($)>
178 # https://gnats.netbsd.org/53146 mentions the idea of using a dynamic
179 # variable name in .for loops, based on some other variable. The .for loops
180 # are already tricky enough to understand in detail, even without this
181 # possibility, therefore the variable names are restricted to using harmless
184 # expect+1: invalid character '$' in .for loop variable name
185 .for $(INDIRECT) in value
186 # If the variable name could be chosen dynamically, the iteration variable
187 # might have been 'direct', thereby expanding the expression '${direct}'.
188 . info <$(INDIRECT)> <$(direct)> <$($(INDIRECT))>
192 # XXX: A parse error or evaluation error in the items of the .for loop
193 # should skip the whole loop. As of 2023-05-09, the loop is expanded as
195 # expect+1: Unknown modifier "Z"
196 .for var in word1 ${:Uword2:Z} word3
197 . info XXX: Not reached ${var}
199 # expect-2: XXX: Not reached word1
200 # expect-3: XXX: Not reached word3
203 # An empty list of variables to the left of the 'in' is a parse error.
204 .for in value # expect+0: no iteration variables in for
208 # An empty list of iteration values to the right of the 'in' is accepted.
209 # Unlike in the shell, it is not a parse error.
214 # If the iteration values become empty after expanding the expressions, the
215 # body of the loop is not evaluated. It is not a parse error.
221 # The loop body can be empty.
226 # A mismatched .if inside a .for loop is detected each time when the loop body
230 .endfor # expect+0: 1 open conditional
232 # If there are no iteration values, the loop body is not processed, and the
233 # check for mismatched conditionals is not performed.
239 # When a .for without the corresponding .endfor occurs in an inactive branch
240 # of an .if, the .for directive is just skipped, it does not even need a
241 # corresponding .endfor. In other words, the behavior of the parser depends
242 # on the actual values of the conditions in the .if clauses.
244 . for var in value # does not need a corresponding .endfor
246 .endfor # expect+0: for-less endfor
247 .endif # expect+0: if-less endif
250 # When a .for without the corresponding .endfor occurs in an active branch of
251 # an .if, the parser just counts the number of .for and .endfor directives,
252 # without looking at any other directives.
255 . endif # expect+0: if-less endif
256 . endfor # no 'for-less endfor'
257 .endif # no 'if-less endif'
260 # Before for.c 1.172 from 2023-05-08, when make parsed a .for loop, it
261 # assumed that there was no line continuation between the '.' and the 'for'
262 # or 'endfor', as there is no practical reason to break the line at this
265 # When make scanned the outer .for loop, it did not recognize the inner .for
266 # loop as such and instead treated it as an unknown directive. The body of
267 # the outer .for loop thus ended above the '.endfor'.
269 # When make scanned the inner .for loop, it did not recognize the inner
270 # .endfor as such, which led to a parse error 'Unexpected end of file in .for
271 # loop' from the '.endfor' line, followed by a second parse error 'for-less
272 # .endfor' from the '.\\n endfor' line.
283 # When there is a variable definition 'scope=cmdline' from the command line
284 # (which has higher precedence than global variables) and a .for loop iterates
285 # over a variable of the same name, the expression '${scope}' expands to the
286 # value from the .for loop. This is because when the body of the .for loop is
287 # expanded, the expression '${scope}' is textually replaced with ${:Uloop}',
288 # without resolving any other variable names (ForLoop_SubstBody). Later, when
289 # the body of the .for loop is actually interpreted, the body text doesn't
290 # contain the word 'scope' anymore.
291 .MAKEFLAGS: scope=cmdline
293 . if ${scope} != "loop"
299 # Since at least 1993, iteration stops at the first newline.
300 # Back then, the .newline variable didn't exist, therefore it was unlikely
301 # that a newline ever occurred.
302 .for var in a${.newline}b${.newline}c
303 . info newline-item=(${var})
305 # expect-2: newline-item=(a)