1# $NetBSD: directive-for.mk,v 1.10 2020/12/27 09:58:35 rillig Exp $
2#
3# Tests for the .for directive.
4#
5# TODO: Describe naming conventions for the loop variables.
6#	.for f in values
7#	.for file in values
8#	.for _FILE_ in values
9#	.for .FILE. in values
10#	.for _f_ in values
11
12# Using the .for loop, lists of values can be produced.
13# In simple cases, the :@var@${var}@ variable modifier can be used to
14# reach the same effects.
15#
16.undef NUMBERS
17.for num in 1 2 3
18NUMBERS+=	${num}
19.endfor
20.if ${NUMBERS} != "1 2 3"
21.  error
22.endif
23
24# The .for loop also works for multiple iteration variables.
25# This is something that the variable modifier :@ cannot do.
26.for name value in VARNAME value NAME2 value2
27${name}=	${value}
28.endfor
29.if ${VARNAME} != "value" || ${NAME2} != "value2"
30.  error
31.endif
32
33# The .for loop splits the items at whitespace, taking quotes into account,
34# just like the :M or :S variable modifiers.
35#
36# Until 2012-06-03, it had split the items exactly at whitespace, without
37# taking the quotes into account.  This had resulted in 10 words.
38#
39.undef WORDS
40.for var in one t\ w\ o "three three" 'four four' `five six`
41WORDS+=	counted
42.endfor
43.if ${WORDS:[#]} != 6
44.  error
45.endif
46
47# In the body of the .for loop, the iteration variables can be accessed
48# like normal variables, even though they are not really variables.
49#
50# Instead, the expression ${var} is transformed into ${:U1}, ${:U2} and so
51# on, before the loop body is evaluated.
52#
53# A notable effect of this implementation technique is that the .for
54# iteration variables and the normal global variables live in separate
55# namespaces and do not influence each other.
56#
57var=	value before
58var2=	value before
59.for var var2 in 1 2 3 4
60.endfor
61.if ${var} != "value before"
62.  warning After the .for loop, var must still have its original value.
63.endif
64.if ${var2} != "value before"
65.  warning After the .for loop, var2 must still have its original value.
66.endif
67
68# Everything from the paragraph above also applies if the loop body is
69# empty, even if there is no actual iteration since the loop items are
70# also empty.
71#
72var=	value before
73var2=	value before
74.for var var2 in ${:U}
75.endfor
76.if ${var} != "value before"
77.  warning After the .for loop, var must still have its original value.
78.endif
79.if ${var2} != "value before"
80.  warning After the .for loop, var2 must still have its original value.
81.endif
82
83# Until 2008-12-21, the values of the iteration variables were simply
84# inserted as plain text and then parsed as usual, which made it possible
85# to achieve all kinds of strange effects.
86#
87# Before that date, the .for loop expanded to:
88#	EXPANSION+= value
89# Since that date, the .for loop expands to:
90#	EXPANSION${:U+}= value
91#
92EXPANSION=		before
93EXPANSION+ =		before
94.for plus in +
95EXPANSION${plus}=	value
96.endfor
97.if ${EXPANSION} != "before"
98.  error This must be a make from before 2009.
99.endif
100.if ${EXPANSION+} != "value"
101.  error This must be a make from before 2009.
102.endif
103
104# When the outer .for loop is expanded, it sees the expression ${i} and
105# expands it.  The inner loop then has nothing more to expand.
106.for i in outer
107.  for i in inner
108.    info ${i}
109.  endfor
110.endfor
111
112# From https://gnats.netbsd.org/29985.
113#
114# Until 2008-12-21, the .for loop was expanded by replacing the variable
115# value literally in the body.  This could lead to situations where the
116# characters from the variable value were interpreted as markup rather than
117# plain text.
118#
119# Until 2012-06-03, the .for loop had split the words at whitespace, without
120# taking quotes into account.  This made it possible to have variable values
121# like "a:\ a:\file.txt" that ended in a single backslash.  Since then, the
122# variable values have been replaced with expressions of the form ${:U...},
123# which are not interpreted as code anymore.
124#
125# As of 2020-09-22, a comment in for.c says that it may be possible to
126# produce an "unwanted substitution", but there is no demonstration code yet.
127#
128# The above changes prevent a backslash at the end of a word from being
129# interpreted as part of the code.  Because of this, the trailingBackslash
130# hack in Var_Subst is no longer needed and as of 2020-09-22, has been
131# removed.
132.for path in a:\ a:\file.txt d:\\ d:\\file.txt
133.  info ${path}
134.endfor
135
136# Ensure that braces and parentheses are properly escaped by the .for loop.
137# Each line must print the same word 3 times.
138# See GetEscapes.
139.for v in ( [ { ) ] } (()) [[]] {{}} )( ][ }{
140.  info $v ${v} $(v)
141.endfor
142
143# As of 2020-10-25, the variable names may contain arbitrary characters,
144# except for whitespace.  This allows for creative side effects. Hopefully
145# nobody is misusing this "feature".
146var=	outer
147.for var:Q in value "quoted"
148.  info ${var} ${var:Q} ${var:Q:Q}
149.endfor
150
151
152# XXX: A parse error or evaluation error in the items of the .for loop
153# should skip the whole loop.  As of 2020-12-27, the loop is expanded twice.
154.for var in word1 ${:Uword2:Z} word3
155.  info XXX: Not reached ${var}
156.endfor
157
158all:
159	@:;
160