[src/trunk]: src/usr.bin/make/unit-tests tests/make: document the modifier ':...

[rillig <rillig%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/fb35af8ee060
branches:  trunk
changeset: 373570:fb35af8ee060
user:      rillig <rillig%NetBSD.org@localhost>
date:      Sat Feb 18 11:55:20 2023 +0000

description:
tests/make: document the modifier ':@var@body@'

diffstat:

 usr.bin/make/unit-tests/varmod-loop.exp |   6 +++---
 usr.bin/make/unit-tests/varmod-loop.mk  |  19 ++++++++++++++++---
 2 files changed, 19 insertions(+), 6 deletions(-)

diffs (51 lines):

diff -r 36d6db11009c -r fb35af8ee060 usr.bin/make/unit-tests/varmod-loop.exp
--- a/usr.bin/make/unit-tests/varmod-loop.exp   Sat Feb 18 11:16:09 2023 +0000
+++ b/usr.bin/make/unit-tests/varmod-loop.exp   Sat Feb 18 11:55:20 2023 +0000
@@ -1,10 +1,10 @@
-Parsing line 78: USE_8_DOLLARS=        ${:U1:@var@${8_DOLLARS}@} ${8_DOLLARS} $$$$$$$$
+Parsing line 91: USE_8_DOLLARS=        ${:U1:@var@${8_DOLLARS}@} ${8_DOLLARS} $$$$$$$$
 CondParser_Eval: ${USE_8_DOLLARS} != "\$\$\$\$ \$\$\$\$ \$\$\$\$"
 Comparing "$$$$ $$$$ $$$$" != "$$$$ $$$$ $$$$"
-Parsing line 83: SUBST_CONTAINING_LOOP:= ${USE_8_DOLLARS}
+Parsing line 96: SUBST_CONTAINING_LOOP:= ${USE_8_DOLLARS}
 CondParser_Eval: ${SUBST_CONTAINING_LOOP} != "\$\$ \$\$\$\$ \$\$\$\$"
 Comparing "$$ $$$$ $$$$" != "$$ $$$$ $$$$"
-Parsing line 108: .MAKEFLAGS: -d0
+Parsing line 121: .MAKEFLAGS: -d0
 ParseDependency(.MAKEFLAGS: -d0)
 :varname-overwriting-target: :x1y x2y x3y: ::
 mod-loop-dollar:1:
diff -r 36d6db11009c -r fb35af8ee060 usr.bin/make/unit-tests/varmod-loop.mk
--- a/usr.bin/make/unit-tests/varmod-loop.mk    Sat Feb 18 11:16:09 2023 +0000
+++ b/usr.bin/make/unit-tests/varmod-loop.mk    Sat Feb 18 11:55:20 2023 +0000
@@ -1,6 +1,20 @@
-# $NetBSD: varmod-loop.mk,v 1.22 2023/02/18 11:16:09 rillig Exp $
+# $NetBSD: varmod-loop.mk,v 1.23 2023/02/18 11:55:20 rillig Exp $
+#
+# Tests for the expression modifier ':@var@body@', which replaces each word of
+# the expression with the expanded body, which may contain references to the
+# variable 'var'.  For example, '${1 2 3:L:@word@<${word}>@}' encloses each
+# word in angle quotes, resulting in '<1> <2> <3>'.
 #
-# Tests for the :@var@...${var}...@ variable modifier.
+# The variable name can be chosen freely, except that it must not contain a
+# '$'.  For simplicity and readability, variable names should only use the
+# characters 'A-Za-z0-9'.
+#
+# The body may contain subexpressions in the form '${...}' or '$(...)'.  These
+# subexpressions differ from everywhere else in makefiles in that the parser
+# only scans '${...}' for balanced '{' and '}', likewise for '$(...)'.  Any
+# other '$' is left as-is during parsing.  Later, when the body is expanded
+# for each word, each '$$' is interpreted as a single '$', and the remaining
+# '$' are interpreted as expressions, like when evaluating a regular variable.
 
 # Force the test results to be independent of the default value of this
 # setting, which is 'yes' for NetBSD's usr.bin/make but 'no' for the bmake
@@ -19,7 +33,6 @@
        @echo :$@: :${:U1 2 3:@\@@x${@}y@}: :$@:
 
 
-
 # Demonstrate that it is possible to generate dollar signs using the
 # :@ modifier.
 #