SCons/Tool/textfile.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 __COPYRIGHT__
   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 <tool name="textfile">
  27 <summary>
  28 <para>
  29 Set &consvars; for the &b-Textfile; and &b-Substfile; builders.
  30 </para>
  31 </summary>
  32 <sets>
  33 <item>LINESEPARATOR</item>
  34 <item>SUBSTFILEPREFIX</item>
  35 <item>SUBSTFILESUFFIX</item>
  36 <item>TEXTFILEPREFIX</item>
  37 <item>TEXTFILESUFFIX</item>
  38 </sets>
  39 <uses>
  40 <item>SUBST_DICT</item>
  41 </uses>
  42 </tool>
  43
  44 <builder name="Textfile">
  45 <summary>
  46 <para>
  47 The &b-Textfile; builder generates a single text file from
  48 a template consisting of a list of strings, replacing text
  49 using the &cv-link-SUBST_DICT; &consvar; (if set) -
  50 see &b-link-Substfile; for a description of replacement.
  51 The strings will be separated in the target file using the
  52 value of the
  53 &cv-link-LINESEPARATOR; &consvar;;
  54 the line separator is not emitted after the last string.
  55 Nested lists of source strings
  56 are flattened.
  57 Source strings need not literally be Python strings:
  58 they can be Nodes or Python objects that convert cleanly
  59 to &f-link-Value; nodes
  60 </para>
  61
  62 <para>
  63 The prefix and suffix specified by the &cv-link-TEXTFILEPREFIX;
  64 and &cv-link-TEXTFILESUFFIX; &consvars;
  65 (by default an empty string and <filename>.txt</filename>, respectively)
  66 are automatically added to the target if they are not already present.
  67 Examples:
  68 </para>
  69
  70 <example_commands>
  71 # builds/writes foo.txt
  72 env.Textfile(target='foo.txt', source=['Goethe', 42, 'Schiller'])
  73
  74 # builds/writes bar.txt
  75 env.Textfile(target='bar', source=['lalala', 'tanteratei'], LINESEPARATOR='|*')
  76
  77 # nested lists are flattened automatically
  78 env.Textfile(target='blob', source=['lalala', ['Goethe', 42, 'Schiller'], 'tanteratei'])
  79
  80 # files may be used as input by wraping them in File()
  81 env.Textfile(
  82     target='concat',  # concatenate files with a marker between
  83     source=[File('concat1'), File('concat2')],
  84     LINESEPARATOR='====================\n',
  85 )
  86 </example_commands>
  87
  88 <para>Results:</para>
  89
  90 <para><filename>foo.txt</filename></para>
  91 <screen>
  92   Goethe
  93   42
  94   Schiller
  95 </screen>
  96
  97 <para><filename>bar.txt</filename></para>
  98 <screen>
  99   lalala|*tanteratei
 100 </screen>
 101
 102 <para><filename>blob.txt</filename></para>
 103 <screen>
 104   lalala
 105   Goethe
 106   42
 107   Schiller
 108   tanteratei
 109 </screen>
 110
 111 </summary>
 112 </builder>
 113
 114 <builder name="Substfile">
 115 <summary>
 116 <para>
 117 The &b-Substfile; builder creates a single text file from
 118 a template consisting of a file or set of files (or nodes),
 119 replacing text using the &cv-link-SUBST_DICT; &consvar; (if set).
 120 If a set, they are concatenated into the target file
 121 using the value of the
 122 &cv-link-LINESEPARATOR; &consvar; as a separator between contents;
 123 the separator is not emitted after the contents of the last  file.
 124 Nested lists of source files
 125 are flattened. See also &b-link-Textfile;.
 126 </para>
 127
 128 <para>
 129 If a single source file name is specified and has a <filename>.in</filename> suffix,
 130 the suffix is stripped and the remainder of the name is used as the default target name.
 131 </para>
 132
 133 <para>
 134 The prefix and suffix specified by the &cv-link-SUBSTFILEPREFIX;
 135 and &cv-link-SUBSTFILESUFFIX; &consvars;
 136 (an empty string by default in both cases)
 137 are automatically added to the target if they are not already present.
 138 </para>
 139
 140 <para>
 141 If a construction variable named &cv-link-SUBST_DICT; is present,
 142 it may be either a Python dictionary or a sequence of
 143 (<replaceable>key</replaceable>, <replaceable>value</replaceable>) tuples.
 144 If it is a dictionary it is converted into a list of tuples
 145 with unspecified order,
 146 so if one key is a prefix of another key
 147 or if one substitution could be further expanded by another subsitition,
 148 it is unpredictable whether the expansion will occur.
 149 </para>
 150
 151 <para>
 152 Any occurrences of a key in the source
 153 are replaced by the corresponding value,
 154 which may be a Python callable function or a string.
 155 If the value is a callable, it is called with no arguments to get a string.
 156 Strings are <emphasis>subst</emphasis>-expanded
 157 and the result replaces the key.
 158 </para>
 159
 160 <example_commands>
 161 env = Environment(tools=['default'])
 162
 163 env['prefix'] = '/usr/bin'
 164 script_dict = {'@prefix@': '/bin', '@exec_prefix@': '$prefix'}
 165 env.Substfile('script.in', SUBST_DICT=script_dict)
 166
 167 conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'}
 168 env.Substfile('config.h.in', conf_dict, SUBST_DICT=conf_dict)
 169
 170 # UNPREDICTABLE - one key is a prefix of another
 171 bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
 172 env.Substfile('foo.in', SUBST_DICT=bad_foo)
 173
 174 # PREDICTABLE - keys are applied longest first
 175 good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')]
 176 env.Substfile('foo.in', SUBST_DICT=good_foo)
 177
 178 # UNPREDICTABLE - one substitution could be futher expanded
 179 bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
 180 env.Substfile('bar.in', SUBST_DICT=bad_bar)
 181
 182 # PREDICTABLE - substitutions are expanded in order
 183 good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye'))
 184 env.Substfile('bar.in', SUBST_DICT=good_bar)
 185
 186 # the SUBST_DICT may be in common (and not an override)
 187 substutions = {}
 188 subst = Environment(tools=['textfile'], SUBST_DICT=substitutions)
 189 substitutions['@foo@'] = 'foo'
 190 subst['SUBST_DICT']['@bar@'] = 'bar'
 191 subst.Substfile(
 192     'pgm1.c',
 193     [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm1.in"],
 194 )
 195 subst.Substfile(
 196     'pgm2.c',
 197     [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm2.in"],
 198 )
 199
 200 </example_commands>
 201 </summary>
 202 </builder>
 203
 204 <cvar name="LINESEPARATOR">
 205 <summary>
 206 <para>
 207 The separator used by the &b-link-Substfile; and &b-link-Textfile; builders.
 208 This value is used between sources when constructing the target.
 209 It defaults to the current system line separator.
 210 </para>
 211 </summary>
 212 </cvar>
 213
 214 <cvar name="SUBST_DICT">
 215 <summary>
 216 <para>
 217 The dictionary used by the &b-link-Substfile; or &b-link-Textfile; builders
 218 for substitution values.
 219 It can be anything acceptable to the <function>dict()</function> constructor,
 220 so in addition to a dictionary,
 221 lists of tuples are also acceptable.
 222 </para>
 223 </summary>
 224 </cvar>
 225
 226 <cvar name="SUBSTFILEPREFIX">
 227 <summary>
 228 <para>
 229 The prefix used for &b-link-Substfile; file names,
 230 an empty string by default.
 231 </para>
 232 </summary>
 233 </cvar>
 234
 235 <cvar name="SUBSTFILESUFFIX">
 236 <summary>
 237 <para>
 238 The suffix used for &b-link-Substfile; file names,
 239 an empty string by default.
 240 </para>
 241 </summary>
 242 </cvar>
 243
 244 <cvar name="TEXTFILEPREFIX">
 245 <summary>
 246 <para>
 247 The prefix used for &b-link-Textfile; file names,
 248 an empty string by default.
 249 </para>
 250 </summary>
 251 </cvar>
 252
 253 <cvar name="TEXTFILESUFFIX">
 254 <summary>
 255 <para>
 256 The suffix used for &b-link-Textfile; file names;
 257 <filename>.txt</filename> by default.
 258 </para>
 259 </summary>
 260 </cvar>
 261
 262 </sconsdoc>