[src/trunk]: src/usr.bin/make/unit-tests tests/make: document parsing behavio...

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

details:   https://anonhg.NetBSD.org/src/rev/85c98c4316b6
branches:  trunk
changeset: 368798:85c98c4316b6
user:      rillig <rillig%NetBSD.org@localhost>
date:      Sat Aug 06 07:06:58 2022 +0000

description:
tests/make: document parsing behavior of modifiers

The table was created by manually inspecting the code of the various
ApplyModifier functions in var.c.

The modifiers are listed in alphabetical order, except for the SysV
modifier, which is listed at the end since it is used as a fallback
modifier for many other modifiers and because it does not have a fixed
prefix.

diffstat:

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

diffs (80 lines):

diff -r e0867bd1b89a -r 85c98c4316b6 usr.bin/make/unit-tests/varmod.exp
--- a/usr.bin/make/unit-tests/varmod.exp        Sat Aug 06 05:55:37 2022 +0000
+++ b/usr.bin/make/unit-tests/varmod.exp        Sat Aug 06 07:06:58 2022 +0000
@@ -1,8 +1,8 @@
-make: "varmod.mk" line 42: To escape a dollar, use \$, not $$, at "$$:L} != """
-make: "varmod.mk" line 42: Invalid variable name ':', at "$:L} != """
-make: "varmod.mk" line 47: Dollar followed by nothing
-make: "varmod.mk" line 56: Missing delimiter ':' after modifier "P"
-make: "varmod.mk" line 57: Missing argument for ".error"
+make: "varmod.mk" line 93: To escape a dollar, use \$, not $$, at "$$:L} != """
+make: "varmod.mk" line 93: Invalid variable name ':', at "$:L} != """
+make: "varmod.mk" line 98: Dollar followed by nothing
+make: "varmod.mk" line 107: Missing delimiter ':' after modifier "P"
+make: "varmod.mk" line 108: Missing argument for ".error"
 make: Fatal errors encountered -- cannot continue
 make: stopped in unit-tests
 exit status 1
diff -r e0867bd1b89a -r 85c98c4316b6 usr.bin/make/unit-tests/varmod.mk
--- a/usr.bin/make/unit-tests/varmod.mk Sat Aug 06 05:55:37 2022 +0000
+++ b/usr.bin/make/unit-tests/varmod.mk Sat Aug 06 07:06:58 2022 +0000
@@ -1,7 +1,58 @@
-# $NetBSD: varmod.mk,v 1.5 2020/12/19 22:33:11 rillig Exp $
+# $NetBSD: varmod.mk,v 1.6 2022/08/06 07:06:58 rillig Exp $
 #
 # Tests for variable modifiers, such as :Q, :S,from,to or :Ufallback.
 
+# As of 2022-08-06, the possible behaviors during parsing are:
+#
+# * `strict`: the parsing style used by most modifiers:
+#   * either uses `ParseModifierPart` or parses the modifier literal
+#   * other modifiers may follow, separated by a ':'
+#
+# * `greedy`: calls `ParseModifierPart` with `ch->endc`; this means
+#   that no further modifiers are parsed in that expression.
+#
+# * `no-colon`: after parsing this modifier, the following modifier
+#   does not need to be separated by a colon.
+#   Omitting this colon is bad style.
+#
+# * `individual`: parsing this modifier does not follow the common
+#   pattern of calling `ParseModifierPart`.
+#
+# The SysV column says whether a parse error in the modifier falls back
+# trying the `:from=to` System V modifier.
+#
+# | **Operator** | **Behavior** | **Remarks**        | **SysV** |
+# |--------------|--------------|--------------------|----------|
+# | `!`          | no-colon     |                    | no       |
+# | `:=`         | greedy       |                    | yes      |
+# | `?:`         | greedy       |                    | no       |
+# | `@`          | no-colon     |                    | no       |
+# | `C`          | no-colon     |                    | no       |
+# | `D`          | individual   | custom parser      | N/A      |
+# | `E`          | strict       |                    | yes      |
+# | `H`          | strict       |                    | yes      |
+# | `L`          | no-colon     |                    | N/A      |
+# | `M`          | individual   | custom parser      | N/A      |
+# | `N`          | individual   | custom parser      | N/A      |
+# | `O`          | strict       | only literal value | no       |
+# | `P`          | no-colon     |                    | N/A      |
+# | `Q`          | strict       |                    | yes      |
+# | `R`          | strict       |                    | yes      |
+# | `S`          | no-colon     |                    | N/A      |
+# | `T`          | strict       |                    | N/A      |
+# | `U`          | individual   | custom parser      | N/A      |
+# | `[`          | strict       |                    | no       |
+# | `_`          | individual   | strcspn            | yes      |
+# | `gmtime`     | strict       | only literal value | yes      |
+# | `hash`       | strict       |                    | N/A      |
+# | `localtime`  | strict       | only literal value | yes      |
+# | `q`          | strict       |                    | yes      |
+# | `range`      | strict       |                    | N/A      |
+# | `sh`         | strict       |                    | N/A      |
+# | `t`          | strict       |                    | no       |
+# | `u`          | strict       |                    | yes      |
+# | `from=to`    | greedy       | SysV, fallback     | N/A      |
+
 DOLLAR1=       $$
 DOLLAR2=       ${:U\$}