SCons/Subst.xml

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