Allow a Variable to not be substituted

New parameter do_subst added to the variables Add method,
if false indicates the variable value should not be substituted
by the Variables logic. The default is True.

Fixes #4241.

Signed-off-by: Mats Wichmann <mats@linux.com>

2 files changed, 18 insertions, 3 deletions

diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen
index 8c89616..fad7d5d 100644
--- a/doc/generated/variables.gen
+++ b/doc/generated/variables.gen
@@ -10668,7 +10668,7 @@ Various yacc tools have emitted various formats
 at different times.
 Set this to match what your parser generator produces.
 </para>
-<para><emphasis>New in version 4.X.Y</emphasis>. </para>
+<para><emphasis>New in version 4.6.0</emphasis>. </para>
 </listitem>
   </varlistentry>
   <varlistentry id="cv-YACC_HEADER_FILE">
@@ -10826,7 +10826,7 @@ The value is used only if &cv-YACC_GRAPH_FILE_SUFFIX; is not set.
 The default value is <filename>.gv</filename>.
 </para>
 <para>
-<emphasis>Changed in version 4.X.Y</emphasis>: deprecated. The default value
+<emphasis>Changed in version 4.6.0</emphasis>: deprecated. The default value
 changed from <filename>.vcg</filename> (&bison; stopped generating
 <filename>.vcg</filename> output with version 2.4, in 2006).
 </para>
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index cdaaa44..eb02a23 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -4835,7 +4835,7 @@ not to any stored-values files.
 
 <variablelist>
   <varlistentry id="v-Add">
-  <term><replaceable>vars</replaceable>.<function>Add</function>(<parameter>key, [help, default, validator, converter]</parameter>)</term>
+  <term><replaceable>vars</replaceable>.<function>Add</function>(<parameter>key, [help, default, validator, converter, do_subst]</parameter>)</term>
   <listitem>
 <para>Add a customizable &consvar; to the &Variables; object.
 <parameter>key</parameter>
@@ -4888,6 +4888,16 @@ it can raise a <exceptionname>ValueError</exceptionname>.
 </para>
 
 <para>
+Substitution will be performed on the variable value
+as it is added, before the converter and validator are called,
+unless the optional <parameter>do_subst</parameter> parameter
+is false (default <literal>True</literal>).
+Suppressing substitution may be useful if the variable value
+looks like a &consvar; reference (<literal>$VAR</literal>)
+to be expanded later.
+</para>
+
+<para>
 As a special case, if <parameter>key</parameter>
 is a sequence and is the <emphasis>only</emphasis>
 argument to &Add;, it is unpacked into the five parameters
@@ -4919,6 +4929,11 @@ def valid_color(key, val, env):
 
 vars.Add('COLOR', validator=valid_color)
 </programlisting>
+
+<para>
+<emphasis>Changed in version 4.8.0:</emphasis>
+added the <parameter>do_subst</parameter> parameter.
+</para>
   </listitem>
   </varlistentry>