SCons/Subst.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 Copyright The SCons Foundation
   4
   5 This file is processed by the bin/SConsDoc.py module.
   6 See its __doc__ string for a discussion of the format.
   7 -->
   8
   9 <!DOCTYPE sconsdoc [
  10 <!ENTITY % scons SYSTEM '../doc/scons.mod'>
  11 %scons;
  12 <!ENTITY % builders-mod SYSTEM '../doc/generated/builders.mod'>
  13 %builders-mod;
  14 <!ENTITY % functions-mod SYSTEM '../doc/generated/functions.mod'>
  15 %functions-mod;
  16 <!ENTITY % tools-mod SYSTEM '../doc/generated/tools.mod'>
  17 %tools-mod;
  18 <!ENTITY % variables-mod SYSTEM '../doc/generated/variables.mod'>
  19 %variables-mod;
  20 ]>
  21
  22 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  23           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  24           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  25
  26
  27 <scons_function name="AllowSubstExceptions">
  28 <arguments signature="global">
  29 ([exception, ...])
  30 </arguments>
  31 <summary>
  32 <para>
  33 Specifies the exceptions that will be allowed
  34 when expanding construction variables.
  35 By default,
  36 any construction variable expansions that generate a
  37 <literal>NameError</literal>
  38 or
  39 <literal>IndexError</literal>
  40 exception will expand to a
  41 <literal>''</literal>
  42 (an empty string) and not cause scons to fail.
  43 All exceptions not in the specified list
  44 will generate an error message
  45 and terminate processing.
  46 </para>
  47
  48 <para>
  49 If
  50 &f-AllowSubstExceptions;
  51 is called multiple times,
  52 each call completely overwrites the previous list
  53 of allowed exceptions.
  54 </para>
  55
  56 <para>
  57 Example:
  58 </para>
  59
  60 <example_commands>
  61 # Requires that all construction variable names exist.
  62 # (You may wish to do this if you want to enforce strictly
  63 # that all construction variables must be defined before use.)
  64 AllowSubstExceptions()
  65
  66 # Also allow a string containing a zero-division expansion
  67 # like '${1 / 0}' to evalute to ''.
  68 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
  69 </example_commands>
  70 </summary>
  71 </scons_function>
  72
  73 </sconsdoc>