[src/trunk]: src/usr.bin/make/unit-tests make(1): explain the varmod-assign test

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

details:   https://anonhg.NetBSD.org/src/rev/12f0981fe322
branches:  trunk
changeset: 937754:12f0981fe322
user:      rillig <rillig%NetBSD.org@localhost>
date:      Tue Aug 25 18:59:30 2020 +0000

description:
make(1): explain the varmod-assign test

I have no idea why I added the mod-assign-nested test.  It is completely
boring and doesn't provide any insight.

diffstat:

 usr.bin/make/unit-tests/varmod-assign.mk |  26 +++++++++++++++++++++++++-
 1 files changed, 25 insertions(+), 1 deletions(-)

diffs (51 lines):

diff -r ae44898cb7c4 -r 12f0981fe322 usr.bin/make/unit-tests/varmod-assign.mk
--- a/usr.bin/make/unit-tests/varmod-assign.mk  Tue Aug 25 17:37:09 2020 +0000
+++ b/usr.bin/make/unit-tests/varmod-assign.mk  Tue Aug 25 18:59:30 2020 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: varmod-assign.mk,v 1.2 2020/08/16 12:48:55 rillig Exp $
+# $NetBSD: varmod-assign.mk,v 1.3 2020/08/25 18:59:30 rillig Exp $
 #
 # Tests for the obscure ::= variable modifiers, which perform variable
 # assignments during evaluation, just like the = operator in C.
@@ -7,17 +7,41 @@
 all:   mod-assign-nested
 
 mod-assign:
+       # The ::?= modifier applies the ?= assignment operator 3 times.
+       # The ?= operator only has an effect for the first time, therefore
+       # the variable FIRST ends up with the value 1.
        @echo $@: ${1 2 3:L:@i@${FIRST::?=$i}@} first=${FIRST}.
+
+       # The ::= modifier applies the = assignment operator 3 times.
+       # The = operator overwrites the previous value, therefore the
+       # variable LAST ends up with the value 3.
        @echo $@: ${1 2 3:L:@i@${LAST::=$i}@} last=${LAST}.
+
+       # The ::+= modifier applies the += assignment operator 3 times.
+       # The += operator appends 3 times to the variable, therefore
+       # the variable APPENDED ends up with the value "1 2 3".
        @echo $@: ${1 2 3:L:@i@${APPENDED::+=$i}@} appended=${APPENDED}.
+
+       # The ::!= modifier applies the != assignment operator 3 times.
+       # The side effects of the shell commands are visible in the output.
+       # Just as with the ::= modifier, the last value is stored in the
+       # RAN variable.
        @echo $@: ${echo.1 echo.2 echo.3:L:@i@${RAN::!=${i:C,.*,&; & 1>\&2,:S,., ,g}}@} ran:${RAN}.
+
        # The assignments happen in the global scope and thus are
        # preserved even after the shell command has been run.
        @echo $@: global: ${FIRST:Q}, ${LAST:Q}, ${APPENDED:Q}, ${RAN:Q}.
 
 mod-assign-nested:
+       # The condition "1" is true, therefore THEN1 gets assigned a value,
+       # and IT1 as well.  Nothing surprising here.
        @echo $@: ${1:?${THEN1::=then1${IT1::=t1}}:${ELSE1::=else1${IE1::=e1}}}${THEN1}${ELSE1}${IT1}${IE1}
+
+       # The condition "0" is false, therefore ELSE1 gets assigned a value,
+       # and IE1 as well.  Nothing surprising here as well.
        @echo $@: ${0:?${THEN2::=then2${IT2::=t2}}:${ELSE2::=else2${IE2::=e2}}}${THEN2}${ELSE2}${IT2}${IE2}
+
+       # The same effects happen when the variables are defined elsewhere.
        @echo $@: ${SINK3:Q}
        @echo $@: ${SINK4:Q}
 SINK3:=        ${1:?${THEN3::=then3${IT3::=t3}}:${ELSE3::=else3${IE3::=e3}}}${THEN3}${ELSE3}${IT3}${IE3}