Issue 1975: Add documentation of the AllowSubstExceptions() function

to the User's Guide.  (Jim Randall)

3 files changed, 157 insertions, 1 deletions

diff --git a/doc/scons.mod b/doc/scons.mod
index 1de2807..51d2a47 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -157,6 +157,7 @@
 <!ENTITY AddVariables "<function>AddVariables</function>">
 <!ENTITY Alias "<function>Alias</function>">
 <!ENTITY Aliases "<function>Aliases</function>">
+<!ENTITY AllowSubstExceptions "<function>AllowSubstExceptions</function>">
 <!ENTITY AlwaysBuild "<function>AlwaysBuild</function>">
 <!ENTITY Append "<function>Append</function>">
 <!ENTITY AppendENVPath "<function>AppendENVPath</function>">
@@ -281,7 +282,9 @@
 <!ENTITY TryRun "<function>TryRun</function>">
 
 
-<!-- Python functions -->
+<!-- Python functions and classes -->
+<!ENTITY IndexError "<classname>IndexError</classname>">
+<!ENTITY NameError "<classname>NameError</classname>">
 <!ENTITY str "<function>str</function>">
 <!ENTITY zipfile "<function>zipfile</function>">
 
diff --git a/doc/user/environments.in b/doc/user/environments.in
index 7bb9d01..0e53363 100644
--- a/doc/user/environments.in
+++ b/doc/user/environments.in
@@ -772,6 +772,82 @@ environment, of directory names, suffixes, etc.
     </section>
 
     <section>
+    <title>Handling Problems With Value Expansion</title>
+
+      <para>
+
+      If a problem occurs when expanding a construction variable,
+      by default it is expanded to <literal>''</literal>
+      (a null string), and will not cause scons to fail. 
+      
+       <scons_example name="missing1">
+         <file name="SConstruct" printme="1">
+          env = Environment()
+          print "value is:", env.subst( '->$MISSING<-' )
+        </file>
+      </scons_example>
+
+       <scons_output example="missing1">
+          <scons_output_command>scons -Q</scons_output_command>
+       </scons_output>
+      
+      This default behaviour can be changed using the &AllowSubstExceptions;
+      function.
+      When a problem occurs with a variable expansion it generates
+      an exception, and the &AllowSubstException; function controls
+      which of these exceptions are actually fatal and which are
+      allowed to occur safely.   By default, &NameError; and &IndexError;
+      are the two exceptions that are allowed to occur: so instead of
+      causing scons to fail, these are caught, the variable expanded to
+      <literal>''</literal>
+      and scons execution continues.
+      To require that all construction variable names exist, and that
+      indexes out of range are not allowed, call &AllowSubstExceptions;
+      with no extra arguments.
+      </para>
+
+       <scons_example name="missing2">
+         <file name="SConstruct" printme="1">
+          AllowSubstExceptions()
+          env = Environment()
+          print "value is:", env.subst( '->$MISSING<-' )
+        </file>
+      </scons_example>
+
+       <scons_output example="missing2">
+          <scons_output_command>scons -Q</scons_output_command>
+       </scons_output>
+
+      <para>
+      This can also be used to allow other exceptions that might occur,
+      most usefully with the <literal>${...}</literal> construction
+      variable syntax.  For example, this would allow zero-division to
+      occur in a variable expansion in addition to the default exceptions
+      allowed
+      </para>
+
+       <scons_example name="missing3">
+         <file name="SConstruct" printme="1">
+          AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
+          env = Environment()
+          print "value is:", env.subst( '->${1 / 0}<-' )
+        </file>
+      </scons_example>
+
+       <scons_output example="missing3">
+          <scons_output_command>scons -Q</scons_output_command>
+       </scons_output>
+      <sconstruct>
+      </sconstruct>
+
+      <para>
+      If &AllowSubstExceptions; is called multiple times, each call
+      completely overwrites the previous list of allowed exceptions.
+      </para>
+
+    </section>
+
+    <section>
     <title>Controlling the Default &ConsEnv;:  the &DefaultEnvironment; Function</title>
 
       <para>
diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index 8f62b3b..2bc43f5 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -772,6 +772,83 @@ environment, of directory names, suffixes, etc.
     </section>
 
     <section>
+    <title>Handling Problems With Value Expansion</title>
+
+      <para>
+
+      If a problem occurs when expanding a construction variable,
+      by default it is expanded to <literal>''</literal>
+      (a null string), and will not cause scons to fail. 
+      
+       <programlisting>
+          env = Environment()
+          print "value is:", env.subst( '-&gt;$MISSING&lt;-' )
+      </programlisting>
+
+       <screen>
+          % <userinput>scons -Q</userinput>
+          value is: -&gt;&lt;-
+          scons: `.' is up to date.
+       </screen>
+      
+      This default behaviour can be changed using the &AllowSubstExceptions;
+      function.
+      When a problem occurs with a variable expansion it generates
+      an exception, and the &AllowSubstException; function controls
+      which of these exceptions are actually fatal and which are
+      allowed to occur safely.   By default, &NameError; and &IndexError;
+      are the two exceptions that are allowed to occur: so instead of
+      causing scons to fail, these are caught, the variable expanded to
+      <literal>''</literal>
+      and scons execution continues.
+      To require that all construction variable names exist, and that
+      indexes out of range are not allowed, call &AllowSubstExceptions;
+      with no extra arguments.
+      </para>
+
+       <programlisting>
+          AllowSubstExceptions()
+          env = Environment()
+          print "value is:", env.subst( '-&gt;$MISSING&lt;-' )
+      </programlisting>
+
+       <screen>
+          % <userinput>scons -Q</userinput>
+          value is:
+          scons: *** NameError `MISSING' trying to evaluate `$MISSING'
+          File "/home/my/project/SConstruct", line 3, in &lt;module&gt;
+       </screen>
+
+      <para>
+      This can also be used to allow other exceptions that might occur,
+      most usefully with the <literal>${...}</literal> construction
+      variable syntax.  For example, this would allow zero-division to
+      occur in a variable expansion in addition to the default exceptions
+      allowed
+      </para>
+
+       <programlisting>
+          AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
+          env = Environment()
+          print "value is:", env.subst( '-&gt;${1 / 0}&lt;-' )
+      </programlisting>
+
+       <screen>
+          % <userinput>scons -Q</userinput>
+          value is: -&gt;&lt;-
+          scons: `.' is up to date.
+       </screen>
+      <programlisting>
+      </programlisting>
+
+      <para>
+      If &AllowSubstExceptions; is called multiple times, each call
+      completely overwrites the previous list of allowed exceptions.
+      </para>
+
+    </section>
+
+    <section>
     <title>Controlling the Default &ConsEnv;:  the &DefaultEnvironment; Function</title>
 
       <para>