[src/trunk]: src/usr.bin/make make(1): clean up documentation, small refactor...

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

details:   https://anonhg.NetBSD.org/src/rev/f599cf473c1a
branches:  trunk
changeset: 935492:f599cf473c1a
user:      rillig <rillig%NetBSD.org@localhost>
date:      Fri Jul 03 22:10:42 2020 +0000

description:
make(1): clean up documentation, small refactorings for variables

- document the callback for VarModify
- clearly mark the callbacks
- shorten the documentation for some callback functions
- fix the documentation of VarSYSVMatch
- remove unnecessary null check from VarLoopExpand
- add test for applying modifiers to empty strings

diffstat:

 usr.bin/make/unit-tests/modmisc.exp |    6 +
 usr.bin/make/unit-tests/modmisc.mk  |   19 ++-
 usr.bin/make/var.c                  |  263 ++++++++++-------------------------
 3 files changed, 98 insertions(+), 190 deletions(-)

diffs (truncated from 472 to 300 lines):

diff -r 94d9faad575a -r f599cf473c1a usr.bin/make/unit-tests/modmisc.exp
--- a/usr.bin/make/unit-tests/modmisc.exp       Fri Jul 03 19:37:27 2020 +0000
+++ b/usr.bin/make/unit-tests/modmisc.exp       Fri Jul 03 22:10:42 2020 +0000
@@ -11,4 +11,10 @@
 basename of 'a/b/c def a.b.c a.b/c a a.a .gitignore a a.a' is 'c def a.b.c c a a.a .gitignore a a.a'
 suffix of 'a/b/c def a.b.c a.b/c a a.a .gitignore a a.a' is 'c b/c a gitignore a'
 root of 'a/b/c def a.b.c a.b/c a a.a .gitignore a a.a' is 'a/b/c def a.b a a a  a a'
+S:
+C:
+@:
+S:empty
+C:empty
+@:
 exit status 0
diff -r 94d9faad575a -r f599cf473c1a usr.bin/make/unit-tests/modmisc.mk
--- a/usr.bin/make/unit-tests/modmisc.mk        Fri Jul 03 19:37:27 2020 +0000
+++ b/usr.bin/make/unit-tests/modmisc.mk        Fri Jul 03 22:10:42 2020 +0000
@@ -1,4 +1,4 @@
-# $Id: modmisc.mk,v 1.6 2020/07/03 18:41:50 rillig Exp $
+# $Id: modmisc.mk,v 1.7 2020/07/03 22:10:42 rillig Exp $
 #
 # miscellaneous modifier tests
 
@@ -15,7 +15,7 @@
 MOD_OPT=@d@$${exists($$d):?$$d:$${d:S,/usr,/opt,}}@
 MOD_SEP=S,:, ,g
 
-all:   modvar modvarloop modsysv mod-HTE
+all:   modvar modvarloop modsysv mod-HTE emptyvar undefvar
 
 modsysv:
        @echo "The answer is ${libfoo.a:L:libfoo.a=42}"
@@ -43,3 +43,18 @@
        @echo "basename of '"${PATHNAMES:Q}"' is '"${PATHNAMES:T:Q}"'"
        @echo "suffix of '"${PATHNAMES:Q}"' is '"${PATHNAMES:E:Q}"'"
        @echo "root of '"${PATHNAMES:Q}"' is '"${PATHNAMES:R:Q}"'"
+
+# When a modifier is applied to the "" variable, the result is discarded.
+emptyvar:
+       @echo S:${:S,^$,empty,}
+       @echo C:${:C,^$,empty,}
+       @echo @:${:@var@${var}@}
+
+# The :U modifier turns even the "" variable into something that has a value.
+# The resulting variable is empty, but is still considered to contain a
+# single empty word. This word can be accessed by the :S and :C modifiers,
+# but not by the :@ modifier since it explicitly skips empty words.
+undefvar:
+       @echo S:${:U:S,^$,empty,}
+       @echo C:${:U:C,^$,empty,}
+       @echo @:${:U:@var@empty@}
diff -r 94d9faad575a -r f599cf473c1a usr.bin/make/var.c
--- a/usr.bin/make/var.c        Fri Jul 03 19:37:27 2020 +0000
+++ b/usr.bin/make/var.c        Fri Jul 03 22:10:42 2020 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: var.c,v 1.243 2020/07/03 18:41:50 rillig Exp $ */
+/*     $NetBSD: var.c,v 1.244 2020/07/03 22:10:42 rillig Exp $ */
 
 /*
  * Copyright (c) 1988, 1989, 1990, 1993
@@ -69,14 +69,14 @@
  */
 
 #ifndef MAKE_NATIVE
-static char rcsid[] = "$NetBSD: var.c,v 1.243 2020/07/03 18:41:50 rillig Exp $";
+static char rcsid[] = "$NetBSD: var.c,v 1.244 2020/07/03 22:10:42 rillig Exp $";
 #else
 #include <sys/cdefs.h>
 #ifndef lint
 #if 0
 static char sccsid[] = "@(#)var.c      8.3 (Berkeley) 3/19/94";
 #else
-__RCSID("$NetBSD: var.c,v 1.243 2020/07/03 18:41:50 rillig Exp $");
+__RCSID("$NetBSD: var.c,v 1.244 2020/07/03 22:10:42 rillig Exp $");
 #endif
 #endif /* not lint */
 #endif
@@ -1168,7 +1168,22 @@
     return p;
 }
 
-/* Add the dirname of the given word to the buffer. */
+
+/* This callback for VarModify gets a single word from an expression and
+ * typically adds a modification of this word to the buffer. It may also do
+ * nothing or add several words.
+ *
+ * If addSpaces is TRUE, it must add a space before adding anything else to
+ * the buffer.
+ *
+ * It returns the addSpace value for the next call of this callback. Typical
+ * return values are the current addSpaces or TRUE. */
+typedef Boolean (*VarModifyCallback)(GNode *ctxt, Var_Parse_State *vpstate,
+    char *word, Boolean addSpace, Buffer *buf, void *data);
+
+
+/* Callback function for VarModify to implement the :H modifier.
+ * Add the dirname of the given word to the buffer. */
 static Boolean
 VarHead(GNode *ctx MAKE_ATTR_UNUSED, Var_Parse_State *vpstate,
        char *word, Boolean addSpace, Buffer *buf,
@@ -1186,7 +1201,8 @@
     return TRUE;
 }
 
-/* Add the basename of the given word to the buffer. */
+/* Callback function for VarModify to implement the :T modifier.
+ * Add the basename of the given word to the buffer. */
 static Boolean
 VarTail(GNode *ctx MAKE_ATTR_UNUSED, Var_Parse_State *vpstate,
        char *word, Boolean addSpace, Buffer *buf,
@@ -1198,11 +1214,11 @@
     if (addSpace && vpstate->varSpace)
        Buf_AddByte(buf, vpstate->varSpace);
     Buf_AddBytes(buf, strlen(base), base);
-
     return TRUE;
 }
 
-/* Add the filename suffix of the given word to the buffer, if it exists. */
+/* Callback function for VarModify to implement the :E modifier.
+ * Add the filename suffix of the given word to the buffer, if it exists. */
 static Boolean
 VarSuffix(GNode *ctx MAKE_ATTR_UNUSED, Var_Parse_State *vpstate,
          char *word, Boolean addSpace, Buffer *buf,
@@ -1218,7 +1234,8 @@
     return TRUE;
 }
 
-/* Add the filename basename of the given word to the buffer. */
+/* Callback function for VarModify to implement the :R modifier.
+ * Add the filename basename of the given word to the buffer. */
 static Boolean
 VarRoot(GNode *ctx MAKE_ATTR_UNUSED, Var_Parse_State *vpstate,
        char *word, Boolean addSpace, Buffer *buf,
@@ -1233,167 +1250,78 @@
     return TRUE;
 }
 
-/*-
- *-----------------------------------------------------------------------
- * VarMatch --
- *     Place the word in the buffer if it matches the given pattern.
- *     Callback function for VarModify to implement the :M modifier.
- *
- * Input:
- *     word            Word to examine
- *     addSpace        TRUE if need to add a space to the buffer
- *                     before adding the word, if it matches
- *     buf             Buffer in which to store it
- *     pattern         Pattern the word must match
- *
- * Results:
- *     TRUE if a space should be placed in the buffer before the next
- *     word.
- *
- * Side Effects:
- *     The word may be copied to the buffer.
- *
- *-----------------------------------------------------------------------
- */
+/* Callback function for VarModify to implement the :M modifier.
+ * Place the word in the buffer if it matches the given pattern. */
 static Boolean
 VarMatch(GNode *ctx MAKE_ATTR_UNUSED, Var_Parse_State *vpstate,
         char *word, Boolean addSpace, Buffer *buf,
-        void *pattern)
+        void *data)
 {
+    const char *pattern = data;
     if (DEBUG(VAR))
-       fprintf(debug_file, "VarMatch [%s] [%s]\n", word, (char *)pattern);
-    if (Str_Match(word, (char *)pattern)) {
-       if (addSpace && vpstate->varSpace) {
-           Buf_AddByte(buf, vpstate->varSpace);
-       }
-       addSpace = TRUE;
-       Buf_AddBytes(buf, strlen(word), word);
-    }
-    return addSpace;
+       fprintf(debug_file, "VarMatch [%s] [%s]\n", word, pattern);
+    if (!Str_Match(word, pattern))
+       return addSpace;
+    if (addSpace && vpstate->varSpace)
+       Buf_AddByte(buf, vpstate->varSpace);
+    Buf_AddBytes(buf, strlen(word), word);
+    return TRUE;
 }
 
 #ifdef SYSVVARSUB
-/*-
- *-----------------------------------------------------------------------
- * VarSYSVMatch --
- *     Place the word in the buffer if it matches the given pattern.
- *     Callback function for VarModify to implement the System V %
- *     modifiers.
- *
- * Input:
- *     word            Word to examine
- *     addSpace        TRUE if need to add a space to the buffer
- *                     before adding the word, if it matches
- *     buf             Buffer in which to store it
- *     patp            Pattern the word must match
- *
- * Results:
- *     TRUE if a space should be placed in the buffer before the next
- *     word.
- *
- * Side Effects:
- *     The word may be copied to the buffer.
- *
- *-----------------------------------------------------------------------
- */
+/* Callback function for VarModify to implement the :%.from=%.to modifier. */
 static Boolean
 VarSYSVMatch(GNode *ctx, Var_Parse_State *vpstate,
             char *word, Boolean addSpace, Buffer *buf,
-            void *patp)
+            void *data)
 {
     size_t len;
     char *ptr;
     Boolean hasPercent;
-    VarPattern           *pat = (VarPattern *)patp;
-    char *varexp;
+    VarPattern *pat = data;
 
     if (addSpace && vpstate->varSpace)
        Buf_AddByte(buf, vpstate->varSpace);
 
-    addSpace = TRUE;
-
     if ((ptr = Str_SYSVMatch(word, pat->lhs, &len, &hasPercent)) != NULL) {
-       varexp = Var_Subst(NULL, pat->rhs, ctx, VARF_WANTRES);
+       char *varexp = Var_Subst(NULL, pat->rhs, ctx, VARF_WANTRES);
        Str_SYSVSubst(buf, varexp, ptr, len, hasPercent);
        free(varexp);
     } else {
        Buf_AddBytes(buf, strlen(word), word);
     }
 
-    return addSpace;
+    return TRUE;
 }
 #endif
 
-
-/*-
- *-----------------------------------------------------------------------
- * VarNoMatch --
- *     Place the word in the buffer if it doesn't match the given pattern.
- *     Callback function for VarModify to implement the :N modifier.
- *
- * Input:
- *     word            Word to examine
- *     addSpace        TRUE if need to add a space to the buffer
- *                     before adding the word, if it matches
- *     buf             Buffer in which to store it
- *     pattern         Pattern the word must match
- *
- * Results:
- *     TRUE if a space should be placed in the buffer before the next
- *     word.
- *
- * Side Effects:
- *     The word may be copied to the buffer.
- *
- *-----------------------------------------------------------------------
- */
+/* Callback function for VarModify to implement the :N modifier.
+ * Place the word in the buffer if it doesn't match the given pattern. */
 static Boolean
 VarNoMatch(GNode *ctx MAKE_ATTR_UNUSED, Var_Parse_State *vpstate,
           char *word, Boolean addSpace, Buffer *buf,
-          void *pattern)
+          void *data)
 {
-    if (!Str_Match(word, (char *)pattern)) {
-       if (addSpace && vpstate->varSpace) {
-           Buf_AddByte(buf, vpstate->varSpace);
-       }
-       addSpace = TRUE;
-       Buf_AddBytes(buf, strlen(word), word);
-    }
-    return addSpace;
+    const char *pattern = data;
+    if (Str_Match(word, pattern))
+       return addSpace;
+    if (addSpace && vpstate->varSpace)
+       Buf_AddByte(buf, vpstate->varSpace);
+    Buf_AddBytes(buf, strlen(word), word);
+    return TRUE;
 }
 
-
-/*-
- *-----------------------------------------------------------------------
- * VarSubstitute --
- *     Perform a string-substitution on the given word, placing the
- *     result in the passed buffer.