292 lines
22 KiB
HTML
292 lines
22 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Foundation Module</title>
|
|
<meta name="viewport" content="width=device-width initial-scale=1">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta http-equiv="Content-Language" content="en-gb">
|
|
<link href="../inweb.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
</head>
|
|
<body>
|
|
<nav role="navigation">
|
|
<h1><a href="../webs.html">Sources</a></h1>
|
|
<ul>
|
|
<li><a href="../inweb/index.html">inweb</a></li>
|
|
</ul>
|
|
<h2>Foundation</h2>
|
|
<ul>
|
|
<li><a href="../foundation-module/index.html">foundation-module</a></li>
|
|
<li><a href="../foundation-test/index.html">foundation-test</a></li>
|
|
</ul>
|
|
|
|
|
|
</nav>
|
|
<main role="main">
|
|
|
|
<!--Weave of 'Foundation Module' generated by 7-->
|
|
<ul class="crumbs"><li><a href="../webs.html">Source</a></li><li><a href="index.html">foundation</a></li><li><a href="index.html#1">Chapter 1: Setting Up</a></li><li><b>Foundation Module</b></li></ul><p class="purpose">Starting up and shutting down.</p>
|
|
|
|
<ul class="toc"><li><a href="#SP1">§1. Introduction</a></li><li><a href="#SP2">§2. Basic definitions</a></li><li><a href="#SP8">§8. The beginning and the end</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="inwebparagraph"><a id="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
|
|
libraries everywhere: memory management, collection classes, filename
|
|
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>
|
|
|
|
<p class="inwebparagraph">To use <code class="display"><span class="extract">foundation</span></code>, the Contents section of a web should include:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">Import: foundation</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">before beginning the chapter rundown. There are then a few conventions
|
|
which must be followed. The <code class="display"><span class="extract">main</span></code> routine for the client should, as one
|
|
of its very first acts, call <code class="display"><span class="extract">Foundation::start()</span></code>, and should similarly, just
|
|
before it exits, call <code class="display"><span class="extract">Foundation::end()</span></code>. Any other module used should be
|
|
started after Foundation starts, and ended before Foundation ends.
|
|
</p>
|
|
|
|
<p class="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>
|
|
|
|
<p class="inwebparagraph"><a id="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
|
|
supplied instead for that case.
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">#</span><span class="identifier">include</span><span class="plain"> <</span><span class="identifier">ctype</span><span class="plain">.</span><span class="identifier">h</span><span class="plain">></span>
|
|
<span class="plain">#</span><span class="identifier">include</span><span class="plain"> <</span><span class="identifier">stdarg</span><span class="plain">.</span><span class="identifier">h</span><span class="plain">></span>
|
|
<span class="plain">#</span><span class="identifier">include</span><span class="plain"> <</span><span class="identifier">stdio</span><span class="plain">.</span><span class="identifier">h</span><span class="plain">></span>
|
|
<span class="plain">#</span><span class="identifier">include</span><span class="plain"> <</span><span class="identifier">stdlib</span><span class="plain">.</span><span class="identifier">h</span><span class="plain">></span>
|
|
<span class="plain">#</span><span class="identifier">include</span><span class="plain"> <</span><span class="identifier">string</span><span class="plain">.</span><span class="identifier">h</span><span class="plain">></span>
|
|
<span class="plain">#</span><span class="identifier">include</span><span class="plain"> <</span><span class="identifier">time</span><span class="plain">.</span><span class="identifier">h</span><span class="plain">></span>
|
|
<span class="plain">#</span><span class="identifier">include</span><span class="plain"> <</span><span class="identifier">math</span><span class="plain">.</span><span class="identifier">h</span><span class="plain">></span>
|
|
<span class="plain">#</span><span class="identifier">include</span><span class="plain"> <</span><span class="identifier">wchar</span><span class="plain">.</span><span class="identifier">h</span><span class="plain">></span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP3"></a><b>§3. </b></p>
|
|
|
|
<pre class="display">
|
|
<span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">DL</span><span class="plain"> = </span><span class="identifier">NULL</span><span class="plain">; </span><span class="comment"> Current destination of debugging text: kept <code class="display"><span class="extract">NULL</span></code> until opened</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP4"></a><b>§4. </b>We'll use three truth states, the third of which can also mean "unknown".
|
|
</p>
|
|
|
|
|
|
<pre class="definitions">
|
|
<span class="definitionkeyword">define</span> <span class="constant">TRUE</span><span class="plain"> </span><span class="constant">1</span>
|
|
<span class="definitionkeyword">define</span> <span class="constant">FALSE</span><span class="plain"> </span><span class="constant">0</span>
|
|
<span class="definitionkeyword">define</span> <span class="constant">NOT_APPLICABLE</span><span class="plain"> </span><span class="constant">2</span>
|
|
</pre>
|
|
<p class="inwebparagraph"><a id="SP5"></a><b>§5. </b>And we recognise two different encodings for narrow (i.e., <code class="display"><span class="extract">char *</span></code>) C strings.
|
|
</p>
|
|
|
|
|
|
<pre class="definitions">
|
|
<span class="definitionkeyword">define</span> <span class="constant">UTF8_ENC</span><span class="plain"> </span><span class="constant">1</span><span class="plain"> </span><span class="comment"> Write as UTF-8 without BOM</span>
|
|
<span class="definitionkeyword">define</span> <span class="constant">ISO_ENC</span><span class="plain"> </span><span class="constant">2</span><span class="plain"> </span><span class="comment"> Write as ISO Latin-1 (i.e., no conversion needed)</span>
|
|
</pre>
|
|
<p class="inwebparagraph"><a id="SP6"></a><b>§6. </b>It is assumed that our host filing system can manage at least 30-character
|
|
filenames, that space is legal as a character in a filename, and that trailing
|
|
extensions can be longer than 3 characters (in particular, that <code class="display"><span class="extract">.html</span></code> is
|
|
allowed). There are no clear rules but on Windows <code class="display"><span class="extract">MAX_PATH</span></code> can be as low as
|
|
260, and on Mac OS X the equivalent limit is 1024; both systems can house
|
|
files buried more deeply, but in both cases the user interface to the
|
|
operating system fails to recognise them. Some Linux implementations raise the
|
|
equivalent <code class="display"><span class="extract">PATH_MAX</span></code> limit as high as 4096. This seems a reasonable
|
|
compromise in practice:
|
|
</p>
|
|
|
|
|
|
<pre class="definitions">
|
|
<span class="definitionkeyword">define</span> <span class="constant">MAX_FILENAME_LENGTH</span><span class="plain"> </span><span class="constant">1025</span>
|
|
</pre>
|
|
<p class="inwebparagraph"><a id="SP7"></a><b>§7. </b>Very occasionally we'll store a pointer as data:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="reserved">typedef</span><span class="plain"> </span><span class="reserved">long</span><span class="plain"> </span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">pointer_sized_int</span><span class="plain">;</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="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>
|
|
|
|
<p class="inwebparagraph">The Inweb notation <code class="display"><span class="extract">[[textliterals]]</span></code> inserts declarations of I-literals,
|
|
that is, literal <code class="display"><span class="extract">text_stream *</span></code> values written as <code class="display"><span class="extract">I"strings"</span></code>.
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Foundation::start</span><span class="plain">(</span><span class="reserved">void</span><span class="plain">) {</span>
|
|
<span class="functiontext">Memory::start</span><span class="plain">();</span>
|
|
<<span class="cwebmacro">Register the default stream writers</span> <span class="cwebmacronumber">8.1</span>><span class="plain">;</span>
|
|
<span class="plain">[[</span><span class="identifier">textliterals</span><span class="plain">]];</span>
|
|
<span class="functiontext">Time::begin</span><span class="plain">();</span>
|
|
<span class="functiontext">Pathnames::start</span><span class="plain">();</span>
|
|
<<span class="cwebmacro">Register the default debugging log aspects</span> <span class="cwebmacronumber">8.2</span>><span class="plain">;</span>
|
|
<<span class="cwebmacro">Register the default debugging log writers</span> <span class="cwebmacronumber">8.3</span>><span class="plain">;</span>
|
|
<<span class="cwebmacro">Register the default command line switches</span> <span class="cwebmacronumber">8.5</span>><span class="plain">;</span>
|
|
<span class="plain">}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="endnote">The function Foundation::start appears nowhere else.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP8_1"></a><b>§8.1. </b>After calling <code class="display"><span class="extract">Foundation::start()</span></code>, the client can register further stream
|
|
writing routines, following these models: they define the meaning of escape
|
|
characters in <code class="display"><span class="extract">WRITE</span></code>, our version of formatted printing. <code class="display"><span class="extract">%f</span></code>, for example,
|
|
prints a filename by calling <code class="display"><span class="extract">Filenames::writer</span></code>.
|
|
</p>
|
|
|
|
|
|
<p class="macrodefinition"><code class="display">
|
|
<<span class="cwebmacrodefn">Register the default stream writers</span> <span class="cwebmacronumber">8.1</span>> =
|
|
</code></p>
|
|
|
|
|
|
<pre class="displaydefn">
|
|
<span class="functiontext">Writers::register_writer</span><span class="plain">(</span><span class="character">'f'</span><span class="plain">, &</span><span class="functiontext">Filenames::writer</span><span class="plain">);</span>
|
|
<span class="functiontext">Writers::register_writer</span><span class="plain">(</span><span class="character">'p'</span><span class="plain">, &</span><span class="functiontext">Pathnames::writer</span><span class="plain">);</span>
|
|
<span class="functiontext">Writers::register_writer</span><span class="plain">(</span><span class="character">'v'</span><span class="plain">, &</span><span class="functiontext">VersionNumbers::writer</span><span class="plain">);</span>
|
|
<span class="functiontext">Writers::register_writer</span><span class="plain">(</span><span class="character">'S'</span><span class="plain">, &</span><span class="functiontext">Streams::writer</span><span class="plain">);</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="endnote">This code is used in <a href="#SP8">§8</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP8_2"></a><b>§8.2. </b>We provide a full logging service, in which different "aspects" can be
|
|
switched on or off. Each aspect represents an activity of the program about
|
|
which a narrative is printed, or not printed, to the debugging log file.
|
|
The following are always provided, but are all off by default.
|
|
</p>
|
|
|
|
|
|
<p class="macrodefinition"><code class="display">
|
|
<<span class="cwebmacrodefn">Register the default debugging log aspects</span> <span class="cwebmacronumber">8.2</span>> =
|
|
</code></p>
|
|
|
|
|
|
<pre class="displaydefn">
|
|
<span class="functiontext">Log::declare_aspect</span><span class="plain">(</span><span class="constant">DEBUGGING_LOG_INCLUSIONS_DA</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"debugging log inclusions"</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">);</span>
|
|
<span class="functiontext">Log::declare_aspect</span><span class="plain">(</span><span class="constant">SHELL_USAGE_DA</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"shell usage"</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">);</span>
|
|
<span class="functiontext">Log::declare_aspect</span><span class="plain">(</span><span class="constant">MEMORY_USAGE_DA</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"memory usage"</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">);</span>
|
|
<span class="functiontext">Log::declare_aspect</span><span class="plain">(</span><span class="constant">TEXT_FILES_DA</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"text files"</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">);</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="endnote">This code is used in <a href="#SP8">§8</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP8_3"></a><b>§8.3. </b>Debugging log writers are similar to stream writers, but implement the <code class="display"><span class="extract">$</span></code>
|
|
escapes only available to the debugging log. For example, <code class="display"><span class="extract">$S</span></code> calls the
|
|
<code class="display"><span class="extract">Streams::log</span></code> function to print a textual representation of the current
|
|
state of a stream.
|
|
</p>
|
|
|
|
|
|
<p class="macrodefinition"><code class="display">
|
|
<<span class="cwebmacrodefn">Register the default debugging log writers</span> <span class="cwebmacronumber">8.3</span>> =
|
|
</code></p>
|
|
|
|
|
|
<pre class="displaydefn">
|
|
<span class="functiontext">Writers::register_logger</span><span class="plain">(</span><span class="character">'a'</span><span class="plain">, &</span><span class="functiontext">Tries::log_avinue</span><span class="plain">);</span>
|
|
<span class="functiontext">Writers::register_logger</span><span class="plain">(</span><span class="character">'S'</span><span class="plain">, &</span><span class="functiontext">Streams::log</span><span class="plain">);</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="endnote">This code is used in <a href="#SP8">§8</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP8_4"></a><b>§8.4. </b>We provide an optional service for parsing the command line. By default,
|
|
the <code class="display"><span class="extract">-log A</span></code> switch makes that aspect active, though it's hyphenated, so
|
|
for example <code class="display"><span class="extract">-log memory-usage</span></code> or <code class="display"><span class="extract">-log no-memory-usage</span></code>. <code class="display"><span class="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. <code class="display"><span class="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.
|
|
</p>
|
|
|
|
|
|
<pre class="definitions">
|
|
<span class="definitionkeyword">enum</span> <span class="constant">LOG_CLSW</span><span class="definitionkeyword"> from </span><span class="constant">0</span>
|
|
<span class="definitionkeyword">enum</span> <span class="constant">VERSION_CLSW</span>
|
|
<span class="definitionkeyword">enum</span> <span class="constant">CRASH_CLSW</span>
|
|
<span class="definitionkeyword">enum</span> <span class="constant">HELP_CLSW</span>
|
|
<span class="definitionkeyword">enum</span> <span class="constant">FIXTIME_CLSW</span>
|
|
<span class="definitionkeyword">enum</span> <span class="constant">AT_CLSW</span>
|
|
</pre>
|
|
<p class="inwebparagraph"><a id="SP8_5"></a><b>§8.5. </b><code class="display">
|
|
<<span class="cwebmacrodefn">Register the default command line switches</span> <span class="cwebmacronumber">8.5</span>> =
|
|
</code></p>
|
|
|
|
|
|
<pre class="displaydefn">
|
|
<span class="functiontext">CommandLine::begin_group</span><span class="plain">(</span><span class="constant">FOUNDATION_CLSG</span><span class="plain">, </span><span class="identifier">NULL</span><span class="plain">);</span>
|
|
<span class="functiontext">CommandLine::declare_switch</span><span class="plain">(</span><span class="constant">LOG_CLSW</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"log"</span><span class="plain">, </span><span class="constant">2</span><span class="plain">,</span>
|
|
<span class="identifier">L</span><span class="string">"write the debugging log to include diagnostics on X"</span><span class="plain">);</span>
|
|
<span class="functiontext">CommandLine::declare_switch</span><span class="plain">(</span><span class="constant">VERSION_CLSW</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"version"</span><span class="plain">, </span><span class="constant">1</span><span class="plain">,</span>
|
|
<span class="identifier">L</span><span class="string">"print out version number"</span><span class="plain">);</span>
|
|
<span class="functiontext">CommandLine::declare_boolean_switch</span><span class="plain">(</span><span class="constant">CRASH_CLSW</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"crash"</span><span class="plain">, </span><span class="constant">1</span><span class="plain">,</span>
|
|
<span class="identifier">L</span><span class="string">"intentionally crash on internal errors, for backtracing"</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">);</span>
|
|
<span class="functiontext">CommandLine::declare_switch</span><span class="plain">(</span><span class="constant">HELP_CLSW</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"help"</span><span class="plain">, </span><span class="constant">1</span><span class="plain">,</span>
|
|
<span class="identifier">L</span><span class="string">"print this help information"</span><span class="plain">);</span>
|
|
<span class="functiontext">CommandLine::declare_boolean_switch</span><span class="plain">(</span><span class="constant">FIXTIME_CLSW</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"fixtime"</span><span class="plain">, </span><span class="constant">1</span><span class="plain">,</span>
|
|
<span class="identifier">L</span><span class="string">"pretend the time is 11 a.m. on 28 March 2016 for testing"</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">);</span>
|
|
<span class="functiontext">CommandLine::declare_switch</span><span class="plain">(</span><span class="constant">AT_CLSW</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"at"</span><span class="plain">, </span><span class="constant">2</span><span class="plain">,</span>
|
|
<span class="identifier">L</span><span class="string">"specify that this tool is installed at X"</span><span class="plain">);</span>
|
|
<span class="functiontext">CommandLine::end_group</span><span class="plain">();</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="endnote">This code is used in <a href="#SP8">§8</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9"></a><b>§9. </b>Once the following has been called, it is not safe to use any of the
|
|
<code class="display"><span class="extract">foundation</span></code> facilities. It should be called on any normal exit, but not on
|
|
an early termination due to a fatal error, as this may lead to thread
|
|
safety problems.
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Foundation::end</span><span class="plain">(</span><span class="reserved">void</span><span class="plain">) {</span>
|
|
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Log::aspect_switched_on</span><span class="plain">(</span><span class="constant">MEMORY_USAGE_DA</span><span class="plain">)) </span><span class="functiontext">Memory::log_statistics</span><span class="plain">();</span>
|
|
<span class="functiontext">Log::close</span><span class="plain">();</span>
|
|
<span class="functiontext">Memory::free</span><span class="plain">();</span>
|
|
<span class="plain">}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="endnote">The function Foundation::end appears nowhere else.</p>
|
|
|
|
<hr class="tocbar">
|
|
<ul class="toc"><li><i>(This section begins Chapter 1: Setting Up.)</i></li><li><a href="1-pp.html">Continue with 'POSIX Platforms'</a></li></ul><hr class="tocbar">
|
|
<!--End of weave-->
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|