Missed the documentation for Textfile and Substfile

1 files changed, 204 insertions, 0 deletions

diff --git a/src/engine/SCons/Tool/textfile.xml b/src/engine/SCons/Tool/textfile.xml
new file mode 100644
index 0000000..d1026ec
--- /dev/null
+++ b/src/engine/SCons/Tool/textfile.xml
@@ -0,0 +1,204 @@
+<!--
+__COPYRIGHT__
+
+This file is processed by the bin/SConsDoc.py module.
+See its __doc__ string for a discussion of the format.
+-->
+<tool name="textfile">
+<summary>
+Set construction variables for the &b-Textfile; and &b-Substfile; builders.
+</summary>
+<sets>
+LINESEPARATOR
+SUBSTFILEPREFIX
+SUBSTFILESUFFIX
+TEXTFILEPREFIX
+TEXTFILESUFFIX
+</sets>
+<uses>
+SUBST_DICT
+</uses>
+</tool>
+
+<builder name="Textfile">
+<summary>
+The &b-Textfile; builder generates a single text file.
+The source strings constitute the lines;
+nested lists of sources are flattened. 
+&cv-LINESEPARATOR; is used to separate the strings.
+
+If present, the &cv-SUBST_DICT; construction variable
+is used to modify the strings before they are written;
+see the &b-Substfile; description for details.
+
+The prefix and suffix specified by the &cv-TEXTFILEPREFIX;
+and &cv-TEXTFILESUFFIX; construction variables
+(the null string and <filename>.txt</filename> by default, respectively)
+are automatically added to the target if they are not already present.
+Examples:
+<example>
+# builds/writes foo.txt
+env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller'])
+
+# builds/writes bar.txt
+env.Textfile(target = 'bar',
+             source = ['lalala', 'tanteratei'],
+             LINESEPARATOR='|*')
+
+# nested lists are flattened automatically
+env.Textfile(target = 'blob', 
+             source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei'])
+
+# files may be used as input by wraping them in File()
+env.Textfile(target = 'concat',  # concatenate files with a marker between
+             source = [File('concat1'), File('concat2')],
+             LINESEPARATOR = '====================\n')
+
+Results are:
+foo.txt
+  ....8<----
+  Goethe
+  42
+  Schiller
+  ....8<---- (no linefeed at the end)
+
+bar.txt:
+  ....8<----
+  lalala|*tanteratei
+  ....8<---- (no linefeed at the end)
+
+blog.txt
+  ....8<----
+  lalala
+  Goethe
+  42
+  Schiller
+  tanteratei
+  ....8<---- (no linefeed at the end)
+</example>
+</summary>
+</builder>
+
+<builder name="Substfile">
+<summary>
+The &b-Substfile; builder generates a single text file
+by concatenating the source files.
+Nested lists of sources are flattened. 
+&cv-LINESEPARATOR; is used to separate the source files;
+see the description of &b-Textfile; for details.
+
+If a single source file is present with an <filename>.in</filename> suffix,
+the suffix is stripped and the remainder is used as the default target name.
+
+The prefix and suffix specified by the &cv-SUBSTFILEPREFIX;
+and &cv-SUBSTFILESUFFIX; construction variables
+(the null string by default in both cases)
+are automatically added to the target if they are not already present.
+
+If a construction variable named &cv-SUBST_DICT; is present,
+it may be either a Python dictionary or a sequence of (key,value) tuples.
+If the former,
+the dictionary is converted into a list of tuples in an arbitrary order,
+so if one key is a prefix of another key
+or if one substitution could be further expanded by another subsitition,
+it is unpredictible whether the expansion will occur.
+
+Any occurences in the source of a key
+are replaced by the corresponding value,
+which may be a Python callable function or a string.
+If a value is a function,
+it is first called (with no arguments) to produce a string.
+The string is &subst;-expanded and the result is substituted.
+
+<example>
+env = Environment(tools = ['default', 'textfile'])
+
+env['prefix'] = '/usr/bin'
+script_dict = {'@prefix@': '/bin', @exec_prefix@: '$prefix'}
+env.Substfile('script.in', SUBST_DICT = script_dict)
+
+conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'}
+env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict)
+
+# UNPREDICTABLE - one key is a prefix of another
+bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
+env.Substfile('foo.in', SUBST_DICT = bad_foo)
+
+# PREDICTABLE - keys are applied longest first
+good_foo = ['$foobar': '$foobar', '$foo': '$foo']
+env.Substfile('foo.in', SUBST_DICT = good_foo)
+
+# UNPREDICTABLE - one substitution could be futher expanded
+bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
+env.Substfile('bar.in', SUBST_DICT = bad_bar)
+
+# PREDICTABLE - substitutions are expanded in order
+good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye'))
+env.Substfile('bar.in', SUBST_DICT = good_bar)
+
+# the SUBST_DICT may be in common (and not an override)
+substutions = {}
+subst = Environment(tools = ['textfile', SUBST_DICT = substitutions)
+substitutions['@foo@'] = 'foo'
+subst['SUBST_DICT']['@bar@'] = 'bar'
+subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'),
+                           Value('#include "@bar@.h"'),
+                           "common.in",
+                           "pgm1.in"
+                          ])
+subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'),
+                           Value('#include "@bar@.h"'),
+                           "common.in",
+                           "pgm2.in"
+                          ])
+
+</example>
+</summary>
+</builder>
+
+<cvar name="LINESEPARATOR">
+<summary>
+The separator used by the &b-Substfile; and &b-Textfile; builders.
+This value is used between sources when constructing the target.
+It defaults to the current system line separator.
+</summary>
+</cvar>
+
+<cvar name="SUBST_DICT">
+<summary>
+The dictionary used by the &b-Substfile; or &b-Textfile; builders
+for substitution values.
+It can be anything acceptable to the dict() constructor,
+so in addition to a dictionary,
+lists of tuples are also acceptable.
+</summary>
+</cvar>
+
+<cvar name="SUBSTFILEPREFIX">
+<summary>
+The prefix used for &b-Substfile; file names,
+the null string by default.
+</summary>
+</cvar>
+
+<cvar name="SUBSTFILESUFFIX">
+<summary>
+The suffix used for &b-Substfile; file names,
+the null string by default.
+</example>
+</summary>
+</cvar>
+
+<cvar name="TEXTFILEPREFIX">
+<summary>
+The prefix used for &b-Textfile; file names,
+the null string by default.
+</summary>
+</cvar>
+
+<cvar name="TEXTFILESUFFIX">
+<summary>
+The suffix used for &b-Textfile; file names;
+<filename>.txt</filename> by default.
+</summary>
+</cvar>