<ulclass="crumbs"><li><ahref="../webs.html">Source</a></li><li><ahref="index.html">foundation</a></li><li><ahref="index.html#1">Chapter 1: Setting Up</a></li><li><b>Foundation</b></li></ul><pclass="purpose">Starting up and shutting down.</p>
<ulclass="toc"><li><ahref="#SP1">§1. Introduction</a></li><li><ahref="#SP2">§2. Basic definitions</a></li><li><ahref="#SP8">§8. The beginning and the end</a></li></ul><hrclass="tocbar">
<pclass="inwebparagraph"><aid="SP1"></a><b>§1. Introduction. </b>The Foundation module supplies some of the conveniences of more modern
programming languages to ANSI C. It offers the usual stuff of standard
and file system accesss, regular-expression matching and so on. At one
time the higher-level material formed a second module called "Foundation
and Empire", but now it's all consolidated into a single everything-you-need
module. Almost all functionality is optional and can be ignored if not
wanted. With a few provisos, the code is thread-safe, sturdy and well
tested, since it forms the support code for the Inform programming
language's compiler and outlying tools, including Inweb itself. If you
need to write a command-line utility in ANSI C with no dependencies on
other tools or libraries to speak of, you could do worse.
</p>
<pclass="inwebparagraph">To use <codeclass="display"><spanclass="extract">foundation</span></code>, the Contents section of a web should include:
</p>
<preclass="display">
<spanclass="plain">Import: foundation</span>
</pre>
<pclass="inwebparagraph">before beginning the chapter rundown. There are then a few conventions
which must be followed. The <codeclass="display"><spanclass="extract">main</span></code> routine for the client should, as one
of its very first acts, call <codeclass="display"><spanclass="extract">Foundation::start()</span></code>, and should similarly, just
before it exits, call <codeclass="display"><spanclass="extract">Foundation::end()</span></code>. Any other module used should be
started after Foundation starts, and ended before Foundation ends.
</p>
<pclass="inwebparagraph">In addition, the client's source code needs to define a few symbols to indicate
what it needs in the way of memory allocation. For an example, see the code
for Inweb itself.
</p>
<pclass="inwebparagraph"><aid="SP2"></a><b>§2. Basic definitions. </b>These are all from the ANSI C standard library (or the pthread POSIX standard),
which means that Inweb will tangle them up to the top of the C source code.
Because pthread is not normally available on Windows, a special header is
<spanclass="reserved">text_stream</span><spanclass="plain"> *</span><spanclass="identifier">DL</span><spanclass="plain"> = </span><spanclass="identifier">NULL</span><spanclass="plain">; </span><spanclass="comment"> Current destination of debugging text: kept <codeclass="display"><spanclass="extract">NULL</span></code> until opened</span>
<pclass="inwebparagraph"><aid="SP5"></a><b>§5. </b>And we recognise two different encodings for narrow (i.e., <codeclass="display"><spanclass="extract">char *</span></code>) C strings.
<spanclass="definitionkeyword">define</span><spanclass="constant">UTF8_ENC</span><spanclass="plain"></span><spanclass="constant">1</span><spanclass="plain"></span><spanclass="comment"> Write as UTF-8 without BOM</span>
<spanclass="definitionkeyword">define</span><spanclass="constant">ISO_ENC</span><spanclass="plain"></span><spanclass="constant">2</span><spanclass="plain"></span><spanclass="comment"> Write as ISO Latin-1 (i.e., no conversion needed)</span>
<pclass="inwebparagraph"><aid="SP8"></a><b>§8. The beginning and the end. </b>As noted above, the client needs to call these when starting up and when
shutting down.
</p>
<pclass="inwebparagraph">The Inweb notation <codeclass="display"><spanclass="extract">[[textliterals]]</span></code> inserts declarations of I-literals,
that is, literal <codeclass="display"><spanclass="extract">text_stream *</span></code> values written as <codeclass="display"><spanclass="extract">I"strings"</span></code>.
<<spanclass="cwebmacro">Register the default debugging log aspects</span><spanclass="cwebmacronumber">8.2</span>><spanclass="plain">;</span>
<<spanclass="cwebmacro">Register the default debugging log writers</span><spanclass="cwebmacronumber">8.3</span>><spanclass="plain">;</span>
<<spanclass="cwebmacro">Register the default command line switches</span><spanclass="cwebmacronumber">8.5</span>><spanclass="plain">;</span>
<spanclass="plain">}</span>
</pre>
<pclass="inwebparagraph"></p>
<pclass="endnote">The function Foundation::start appears nowhere else.</p>
<pclass="inwebparagraph"><aid="SP8_1"></a><b>§8.1. </b>After calling <codeclass="display"><spanclass="extract">Foundation::start()</span></code>, the client can register further stream
writing routines, following these models: they define the meaning of escape
characters in <codeclass="display"><spanclass="extract">WRITE</span></code>, our version of formatted printing. <codeclass="display"><spanclass="extract">%f</span></code>, for example,
prints a filename by calling <codeclass="display"><spanclass="extract">Filenames::writer</span></code>.
</p>
<pclass="macrodefinition"><codeclass="display">
<<spanclass="cwebmacrodefn">Register the default stream writers</span><spanclass="cwebmacronumber">8.1</span>> =
<pclass="endnote">This code is used in <ahref="#SP8">§8</a>.</p>
<pclass="inwebparagraph"><aid="SP8_3"></a><b>§8.3. </b>Debugging log writers are similar to stream writers, but implement the <codeclass="display"><spanclass="extract">$</span></code>
escapes only available to the debugging log. For example, <codeclass="display"><spanclass="extract">$S</span></code> calls the
<codeclass="display"><spanclass="extract">Streams::log</span></code> function to print a textual representation of the current
state of a stream.
</p>
<pclass="macrodefinition"><codeclass="display">
<<spanclass="cwebmacrodefn">Register the default debugging log writers</span><spanclass="cwebmacronumber">8.3</span>> =
<pclass="endnote">This code is used in <ahref="#SP8">§8</a>.</p>
<pclass="inwebparagraph"><aid="SP8_4"></a><b>§8.4. </b>We provide an optional service for parsing the command line. By default,
the <codeclass="display"><spanclass="extract">-log A</span></code> switch makes that aspect active, though it's hyphenated, so
for example <codeclass="display"><spanclass="extract">-log memory-usage</span></code> or <codeclass="display"><spanclass="extract">-log no-memory-usage</span></code>. <codeclass="display"><spanclass="extract">-fixtime</span></code> is
used to ease automated testing: we don't want to reject the output from
some tool just because it contains today's date and not the date when the
test was set up. <codeclass="display"><spanclass="extract">-crash</span></code> tells the tool to crash on a fatal error, rather
than to exit cleanly, to make it easier to diagnose in a debugger.
<spanclass="definitionkeyword">enum</span><spanclass="constant">LOG_CLSW</span><spanclass="definitionkeyword"> from </span><spanclass="constant">0</span>
<spanclass="identifier">L</span><spanclass="string">"intentionally crash on internal errors, for backtracing"</span><spanclass="plain">, </span><spanclass="constant">FALSE</span><spanclass="plain">);</span>
<spanclass="identifier">L</span><spanclass="string">"pretend the time is 11 a.m. on 28 March 2016 for testing"</span><spanclass="plain">, </span><spanclass="constant">FALSE</span><spanclass="plain">);</span>
