From 738149c9bfb9965d013d01ef99f9bb1c2819e7e8 Mon Sep 17 00:00:00 2001
From: Luca Falavigna <dktrkranz@debian.org>
Date: Tue, 15 Jun 2010 14:28:22 +0000
Subject: Imported Upstream version 2.0.0

---
 doc/user/environments.in | 88 +++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 80 insertions(+), 8 deletions(-)

(limited to 'doc/user/environments.in')

diff --git a/doc/user/environments.in b/doc/user/environments.in
index dfe98f2..9ce5568 100644
--- a/doc/user/environments.in
+++ b/doc/user/environments.in
@@ -672,11 +672,8 @@ environment, of directory names, suffixes, etc.
 
       <sconstruct>
          env = Environment()
-         dict = env.Dictionary()
-         keys = dict.keys()
-         keys.sort()
-         for key in keys:
-             print "construction variable = '%s', value = '%s'" % (key, dict[key])
+         for item in sorted(env.Dictionary().items()):
+             print "construction variable = '%s', value = '%s'" % item
       </sconstruct>
 
     </section>
@@ -774,6 +771,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 &AllowSubstExceptions; 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>
 
@@ -1556,11 +1629,10 @@ environment, of directory names, suffixes, etc.
       #!/usr/bin/env python
       import os
       import sys
-      if len(sys.argv) > 1:
+      if len(sys.argv) &gt; 1:
           keys = sys.argv[1:]
       else:
-          keys = os.environ.keys()
-          keys.sort()
+          keys = sorted(os.environ.keys())
       for key in keys:
           print "    " + key + "=" + os.environ[key]
       </file>
-- 
cgit v1.2.3