diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/man/scons.xml | 56 |
1 files changed, 33 insertions, 23 deletions
diff --git a/doc/man/scons.xml b/doc/man/scons.xml index fc2e24d..eb91d88 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -6414,18 +6414,25 @@ env.Command('marker', 'input_file', action=[MyBuildAction, Touch('$TARGET')]) &scons; performs variable substitution on the string that makes up the action part of the builder. -Variables to be interpolated are indicated in the -string with a leading -<literal>$</literal>, to distinguish them from plain text +Variables or other text to be substituted are indicated in the +string by a leading <emphasis role="bold">$</emphasis>, +to distinguish them from plain text which is not to be substituted. -The name may be surrounded by curly braces -(<literal>${}</literal>) -to separate the name from surrounding characters if necessary. -Curly braces are required when you use +The substitutable text may be surrounded by curly braces +to separate it from surrounding characters if necessary +(for example <literal>${FOO}BAR</literal>). +To avoid substituting a substring that looks like a variable name, +escape it with an additional <emphasis role="bold">$</emphasis>, +(for example, <literal>$$FOO</literal> will be left in the +final string as <literal>$FOO</literal>). +</para> +<para> +The curly brace notation is required when you use Python list subscripting/slicing notation on a variable to select one or more items from a list, or access a variable's special attributes, -or use Python expression substitution. +or when you use Python expression substitution +(see below for descriptions of these). </para> <para> @@ -6670,9 +6677,10 @@ echo Last build occurred . > $TARGET <para>While &consvars; are normally directly substituted, if a variable refers to a &consvar; -whose value is a &Python; function, -that function is called during substitution. -Such a function must accept four arguments: +whose value is a callable &Python; object (a function +or a class with a <literal>__call__</literal> method), +that object is called during substitution. +The callable must accept four arguments: <parameter>target</parameter>, <parameter>source</parameter>, <parameter>env</parameter> and @@ -6681,19 +6689,21 @@ Such a function must accept four arguments: <parameter>target</parameter> is a list of target nodes, <parameter>env</parameter> is the &consenv; to use for context, and <parameter>for_signature</parameter> is -a Boolean value that tells the function +a boolean value that tells the callable if it is being called for the purpose of generating a build signature. Since the build signature is used for rebuild determination, -the function should omit variable elements -that do not affect whether a rebuild should be triggered -(see <emphasis role="bold">$(</emphasis> -and <emphasis role="bold">$)</emphasis> -above) if <parameter>for_signature</parameter> is true. +variable elements that do not affect whether +a rebuild should be triggered +should be omitted from the returned string +if <parameter>for_signature</parameter> is true. +See <emphasis role="bold">$(</emphasis> +and <emphasis role="bold">$)</emphasis> above +for the syntax. </para> <para> &SCons; will insert whatever -the called function returns +the callable returns into the expanded string: </para> @@ -6712,11 +6722,11 @@ will be exactly as it was set: <literal>"$FOO baz"</literal>. </para> <para>You can use this feature to pass arguments to a -Python function by creating a callable class -that stores one or more arguments in an object, -and then uses them when the -<methodname>__call__()</methodname> -method is called. +callable variable by creating a callable class +that stores passed arguments in the instance, +and then uses them +(in the <methodname>__call__</methodname> method) +when the instance is called. Note that in this case, the entire variable expansion must be enclosed by curly braces |