[src/trunk]: src/usr.bin/make/unit-tests tests/make: document how variable ev...

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

details:   https://anonhg.NetBSD.org/src/rev/01c9f204116d
branches:  trunk
changeset: 370735:01c9f204116d
user:      rillig <rillig%NetBSD.org@localhost>
date:      Sun Sep 25 21:26:23 2022 +0000

description:
tests/make: document how variable evaluation needs to be tested

It's about 100_000 combinations to cover the basic edge cases.

diffstat:

 usr.bin/make/unit-tests/parse-var.exp |   2 +-
 usr.bin/make/unit-tests/parse-var.mk  |  75 ++++++++++++++++++++++++++++++++++-
 2 files changed, 75 insertions(+), 2 deletions(-)

diffs (94 lines):

diff -r 05b3e17c2922 -r 01c9f204116d usr.bin/make/unit-tests/parse-var.exp
--- a/usr.bin/make/unit-tests/parse-var.exp     Sun Sep 25 21:26:22 2022 +0000
+++ b/usr.bin/make/unit-tests/parse-var.exp     Sun Sep 25 21:26:23 2022 +0000
@@ -1,5 +1,5 @@
 make: Unfinished modifier for "BRACE_GROUP" (',' missing)
-make: "parse-var.mk" line 57: Malformed conditional (0 && ${BRACE_GROUP:S,${BRACE_PAIR:S,{,{{,},<lbraces>,})
+make: "parse-var.mk" line 130: Malformed conditional (0 && ${BRACE_GROUP:S,${BRACE_PAIR:S,{,{{,},<lbraces>,})
 make: Fatal errors encountered -- cannot continue
 make: stopped in unit-tests
 exit status 1
diff -r 05b3e17c2922 -r 01c9f204116d usr.bin/make/unit-tests/parse-var.mk
--- a/usr.bin/make/unit-tests/parse-var.mk      Sun Sep 25 21:26:22 2022 +0000
+++ b/usr.bin/make/unit-tests/parse-var.mk      Sun Sep 25 21:26:23 2022 +0000
@@ -1,6 +1,79 @@
-# $NetBSD: parse-var.mk,v 1.5 2022/08/23 19:22:01 rillig Exp $
+# $NetBSD: parse-var.mk,v 1.6 2022/09/25 21:26:23 rillig Exp $
 #
 # Tests for parsing variable expressions.
+#
+# TODO: Add systematic tests for all of the below combinations.
+#
+# Written form:
+#      short form
+#      long form with braces           endc == '}'
+#      long form with parentheses      endc == ')'
+#      indirect modifiers              endc == '\0'
+#
+# Based on:
+#      undefined variable
+#      global variable
+#      command-line variable
+#      environment variable
+#      target-local variable
+#      legacy variable '@F'
+#
+# VarEvalMode:
+#      parse
+#      eval
+#      eval-undeferr
+#      eval-keep-dollar
+#      eval-keep-undef
+#      eval-keep-dollar-undef
+#
+# Global mode:
+#      without -dL
+#      with -dL
+#
+# Modifiers:
+#      no
+#      yes, stay undefined
+#      convert to defined
+#      indirect modifiers, involving changes to VarEvalMode
+#
+# Error conditions:
+#      for the short form, EOF after the '$'
+#      for the short form, each character
+#      for the long forms, EOF right after '${'
+#      for the long forms, EOF after the variable name
+#      for the long forms, EOF after the ':'
+#      for the long forms, EOF after parsing a modifier
+#      for the long forms, ':}'
+#      for each modifier: syntactic error
+#      for each modifier: evaluation error
+#
+# Context:
+#      in a condition, only operand, unquoted
+#      in a condition, only operand, quoted
+#      in a condition, left-hand side, unquoted
+#      in a condition, left-hand side, quoted
+#      in a condition, right-hand side, unquoted
+#      in a condition, right-hand side, quoted
+#      left-hand side of a variable assignment
+#      right-hand side of a ':=' variable assignment
+#      right-hand side of a '!=' variable assignment
+#      shell command in a target
+#      .info directive
+#      dependency line
+#      items in a .for loop
+#      everywhere else Var_Parse is called
+#
+# Further influences:
+#      multi-level evaluations like 'other=${OTHER}' with OTHER='$$ ${THIRD}'
+#
+# Effects:
+#      How much does the parsing position advance (pp)?
+#      What's the value of the expression (out_val)?
+#      What's the status after parsing the expression (VarParseResult)?
+#      What error messages are printed (Parse_Error)?
+#      What no-effect error messages are printed (Error)?
+#      What error messages should be printed but aren't?
+#      What other side effects are there?
 
 .MAKEFLAGS: -dL