 @@ -1,14 +1,14 @@
-/*	$NetBSD: var.c,v 1.591 2020/10/27 07:16:27 rillig Exp $	*/
+/*	$NetBSD: var.c,v 1.592 2020/10/30 06:44:57 rillig Exp $	*/
 /*
  * Copyright (c) 1988, 1989, 1990, 1993
  *	The Regents of the University of California.  All rights reserved.
+ *
  * This code is derived from software contributed to Berkeley by
  * Adam de Boor.
+ *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
 @@ -58,80 +58,88 @@
  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  */
-/*-
+/*
- * var.c --
+ * Handling of variables and the expressions formed from them.
  *	Variable-handling functions
  * Variables are set using lines of the form VAR=value.  Both the variable
  * name and the value can contain references to other variables, by using
  * expressions like ${VAR}, ${VAR:Modifiers}, ${${VARNAME}} or ${VAR:${MODS}}.
+ *
  * Interface:
- *	Var_Set		Set the value of a variable in the given
+ *	Var_Init	Initialize this module.
  *			context. The variable is created if it doesn't
- *			yet exist.
+ *	Var_End		Clean up the module.
+ *
- *	Var_Append	Append more characters to an existing variable
+ *	Var_Set		Set the value of the variable, creating it if
- *			in the given context. The variable needn't
+ *			necessary.
  *			exist already -- it will be created if it doesn't.
- *			A space is placed between the old value and the
+ *	Var_Append	Append more characters to the variable, creating it if
- *			new one.
+ *			necessary. A space is placed between the old value and
  *			the new one.
+ *
  *	Var_Exists	See if a variable exists.
+ *
- *	Var_Value	Return the unexpanded value of a variable in a
+ *	Var_Value	Return the unexpanded value of a variable, or NULL if
- *			context or NULL if the variable is undefined.
+ *			the variable is undefined.
+ *
- *	Var_Subst	Substitute either a single variable or all
+ *	Var_Subst	Substitute all variable expressions in a string.
  *			variables in a string, using the given context.
+ *
- *	Var_Parse	Parse a variable expansion from a string and
+ *	Var_Parse	Parse a variable expression such as ${VAR:Mpattern}.
  *			return the result and the number of characters
  *			consumed.
+ *
- *	Var_Delete	Delete a variable in a context.
+ *	Var_Delete	Delete a variable.
+ *
- *	Var_Init	Initialize this module.
+ *	Var_ExportVars	Export some or even all variables to the environment
  *			of this process and its child processes.
+ *
  *	Var_Export	Export the variable to the environment of this process
  *			and its child processes.
+ *
  *	Var_UnExport	Don't export the variable anymore.
+ *
  * Debugging:
- *	Var_Dump	Print out all variables defined in the given
+ *	Var_Stats	Print out hashing statistics if in -dh mode.
  *			context.
  *	Var_Dump	Print out all variables defined in the given context.
+ *
  * XXX: There's a lot of duplication in these functions.
  */
 #include    <sys/stat.h>
 #ifndef NO_REGEX
 #include    <sys/types.h>
 #include    <regex.h>
 #endif
 #include    <inttypes.h>
 #include    <limits.h>
 #include    <time.h>
 #include    "make.h"
 #include    "dir.h"
 #include    "job.h"
 #include    "metachar.h"
 /*	"@(#)var.c	8.3 (Berkeley) 3/19/94" */
-MAKE_RCSID("$NetBSD: var.c,v 1.591 2020/10/27 07:16:27 rillig Exp $");
+MAKE_RCSID("$NetBSD: var.c,v 1.592 2020/10/30 06:44:57 rillig Exp $");
 #define VAR_DEBUG1(fmt, arg1) DEBUG1(VAR, fmt, arg1)
 #define VAR_DEBUG2(fmt, arg1, arg2) DEBUG2(VAR, fmt, arg1, arg2)
 #define VAR_DEBUG3(fmt, arg1, arg2, arg3) DEBUG3(VAR, fmt, arg1, arg2, arg3)
 #define VAR_DEBUG4(fmt, arg1, arg2, arg3, arg4) DEBUG4(VAR, fmt, arg1, arg2, arg3, arg4)
 ENUM_FLAGS_RTTI_3(VarEvalFlags,
 		  VARE_UNDEFERR, VARE_WANTRES, VARE_ASSIGN);
 /*
  * This lets us tell if we have replaced the original environ
  * (which we cannot free).
  */