From 87bd27f06c0e23fedb66c4c5a46b564c1ce88ce7 Mon Sep 17 00:00:00 2001 From: Steven Knight Date: Fri, 4 Jun 2010 23:55:28 +0000 Subject: Issue 1975: Add documentation of the AllowSubstExceptions() function to the User's Guide. (Jim Randall) --- bin/scons-doc.py | 2 +- doc/scons.mod | 5 ++- doc/user/environments.in | 76 ++++++++++++++++++++++++++++++++++++++++++++++ doc/user/environments.xml | 77 +++++++++++++++++++++++++++++++++++++++++++++++ src/CHANGES.txt | 4 +++ 5 files changed, 162 insertions(+), 2 deletions(-) diff --git a/bin/scons-doc.py b/bin/scons-doc.py index df35393..14e862c 100644 --- a/bin/scons-doc.py +++ b/bin/scons-doc.py @@ -818,7 +818,7 @@ def process(filename): try: f = open(filename, 'r') except EnvironmentError, e: - sys.stderr.write('%s: %s\n' % (filename, msg)) + sys.stderr.write('%s: %s\n' % (filename, e)) return 1 data = f.read() 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 @@ AddVariables"> Alias"> Aliases"> +AllowSubstExceptions"> AlwaysBuild"> Append"> AppendENVPath"> @@ -281,7 +282,9 @@ TryRun"> - + +IndexError"> +NameError"> str"> zipfile"> 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.
+ Handling Problems With Value Expansion + + + + If a problem occurs when expanding a construction variable, + by default it is expanded to '' + (a null string), and will not cause scons to fail. + + + + env = Environment() + print "value is:", env.subst( '->$MISSING<-' ) + + + + + scons -Q + + + 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 + '' + 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. + + + + + AllowSubstExceptions() + env = Environment() + print "value is:", env.subst( '->$MISSING<-' ) + + + + + scons -Q + + + + This can also be used to allow other exceptions that might occur, + most usefully with the ${...} construction + variable syntax. For example, this would allow zero-division to + occur in a variable expansion in addition to the default exceptions + allowed + + + + + AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) + env = Environment() + print "value is:", env.subst( '->${1 / 0}<-' ) + + + + + scons -Q + + + + + + If &AllowSubstExceptions; is called multiple times, each call + completely overwrites the previous list of allowed exceptions. + + +
+ +
Controlling the Default &ConsEnv;: the &DefaultEnvironment; Function 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.
+ Handling Problems With Value Expansion + + + + If a problem occurs when expanding a construction variable, + by default it is expanded to '' + (a null string), and will not cause scons to fail. + + + env = Environment() + print "value is:", env.subst( '->$MISSING<-' ) + + + + % scons -Q + value is: -><- + scons: `.' is up to date. + + + 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 + '' + 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. + + + + AllowSubstExceptions() + env = Environment() + print "value is:", env.subst( '->$MISSING<-' ) + + + + % scons -Q + value is: + scons: *** NameError `MISSING' trying to evaluate `$MISSING' + File "/home/my/project/SConstruct", line 3, in <module> + + + + This can also be used to allow other exceptions that might occur, + most usefully with the ${...} construction + variable syntax. For example, this would allow zero-division to + occur in a variable expansion in addition to the default exceptions + allowed + + + + AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) + env = Environment() + print "value is:", env.subst( '->${1 / 0}<-' ) + + + + % scons -Q + value is: -><- + scons: `.' is up to date. + + + + + + If &AllowSubstExceptions; is called multiple times, each call + completely overwrites the previous list of allowed exceptions. + + +
+ +
Controlling the Default &ConsEnv;: the &DefaultEnvironment; Function diff --git a/src/CHANGES.txt b/src/CHANGES.txt index d207279..6f74566 100644 --- a/src/CHANGES.txt +++ b/src/CHANGES.txt @@ -80,6 +80,10 @@ RELEASE 2.0.0.beta.20100531 - Mon, 31 May 2010 22:15:00 -0700 - Start deprecation cycle for SourceCode() and related factories + From Jim Randall: + + - Document the AllowSubstExceptions() function in the User's Guide. + RELEASE 1.3.0 - Tue, 23 Mar 2010 21:44:19 -0400 -- cgit v0.12