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