AwesomeAdam54321/inweb-bootstrap
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
inweb-bootstrap/docs/foundation-module/2-dl.html
Graham Nelson db41a57f65 And equations
2020-04-10 21:29:28 +01:00

412 lines
46 KiB
HTML
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Debugging Log</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 'Debugging Log' 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#2">Chapter 2: Memory, Streams and Collections</a></li><li><b>Debugging Log</b></li></ul><p class="purpose">To write to the debugging log, a plain text file which traces what we're doing, in order to assist those lost souls debugging it.</p>
<ul class="toc"><li><a href="#SP1">&#167;1. The DL stream</a></li><li><a href="#SP2">&#167;2. Macros</a></li><li><a href="#SP3">&#167;3. Debugging aspects</a></li><li><a href="#SP6">&#167;6. Subheadings</a></li><li><a href="#SP7">&#167;7. Aspects</a></li><li><a href="#SP10">&#167;10. The starred trace</a></li><li><a href="#SP11">&#167;11. Wrapping up</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. The DL stream. </b>The debugging log file occupies the following stream:
</p>
<pre class="display">
<span class="reserved">text_stream</span><span class="plain"> </span><span class="identifier">debug_log_file_struct</span><span class="plain">; </span><span class="comment"> The actual debugging log file</span>
<span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">debug_log_file</span><span class="plain"> = &amp;</span><span class="identifier">debug_log_file_struct</span><span class="plain">; </span><span class="comment"> The actual debugging log file</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. Macros. </b>"The most effective debugging tool is still careful thought, coupled with
judiciously placed print statements" (Brian Kernighan).
</p>
<p class="inwebparagraph">To write to the debugging log, we must in principle write to a stream called
<code class="display"><span class="extract">DL</span></code>. In practice we more often use a pair of pseudo-functions called <code class="display"><span class="extract">LOG</span></code>
and <code class="display"><span class="extract">LOGIF</span></code>, which are macros defined in the section on Streams. For
instance, the pseudo-function-call
</p>
<pre class="display">
<span class="plain">LOGIF(WHATEVER, "Heading %d skipped\n", n);</span>
</pre>
<p class="inwebparagraph">prints the line in question to the debugging log only if the aspect <code class="display"><span class="extract">WHATEVER</span></code>
is currently switched on. Plain <code class="display"><span class="extract">LOG</span></code> does the same, but unconditionally.
</p>
<pre class="definitions">
<span class="definitionkeyword">define</span> <span class="constant">LOG_INDENT</span><span class="plain"> </span><span class="identifier">STREAM_INDENT</span><span class="plain">(</span><span class="identifier">DL</span><span class="plain">)</span>
<span class="definitionkeyword">define</span> <span class="constant">LOG_OUTDENT</span><span class="plain"> </span><span class="identifier">STREAM_OUTDENT</span><span class="plain">(</span><span class="identifier">DL</span><span class="plain">)</span>
</pre>
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. Debugging aspects. </b>There are many different things which can go into the debugging file, or
need not: for Inform even a simple half-page source can result in a
debugging log 5MB in size, so we generally don't want everything included
unless we ask for it.
</p>
<p class="inwebparagraph">A "debugging aspect" is a category of information that can be included, or
not, as we please. Each has a unique number and a name of up to three words in
length.
</p>
<pre class="display">
<span class="reserved">typedef</span><span class="plain"> </span><span class="reserved">struct</span><span class="plain"> </span><span class="reserved">debugging_aspect</span><span class="plain"> {</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">hyphenated_name</span><span class="plain">; </span><span class="comment"> e.g., "memory-usage"</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">negated_name</span><span class="plain">; </span><span class="comment"> e.g., "no-memory-usage"</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">unhyphenated_name</span><span class="plain">; </span><span class="comment"> e.g., "memory usage"</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">on_or_off</span><span class="plain">; </span><span class="comment"> whether or not active when writing to debugging log</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">alternate</span><span class="plain">; </span><span class="comment"> whether or not active when writing in trace mode</span>
<span class="constant">MEMORY_MANAGEMENT</span>
<span class="plain">} </span><span class="reserved">debugging_aspect</span><span class="plain">;</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The structure debugging_aspect is accessed in 8/bdfw and here.</p>
<p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>And now we must define all those constants and names. Note that the
<code class="display"><span class="extract">TRUE</span></code> or <code class="display"><span class="extract">FALSE</span></code> settings below are the defaults, and apply unless the
source says otherwise. The <code class="display"><span class="extract">alternate</span></code> settings are those used in
trace-sentences mode, that is, between asterisk sentences.
</p>
<pre class="definitions">
<span class="definitionkeyword">enum</span> <span class="constant">DEBUGGING_LOG_INCLUSIONS_DA</span><span class="definitionkeyword"> from </span><span class="constant">0</span>
<span class="definitionkeyword">enum</span> <span class="constant">SHELL_USAGE_DA</span>
<span class="definitionkeyword">enum</span> <span class="constant">MEMORY_USAGE_DA</span>
<span class="definitionkeyword">enum</span> <span class="constant">TEXT_FILES_DA</span>
</pre>
<pre class="display">
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">das_created</span><span class="plain"> = </span><span class="constant">FALSE</span><span class="plain">;</span>
<span class="reserved">debugging_aspect</span><span class="plain"> </span><span class="identifier">the_debugging_aspects</span><span class="plain">[</span><span class="identifier">NO_DEFINED_DA_VALUES</span><span class="plain">];</span>
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Log::declare_aspect</span><span class="plain">(</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">a</span><span class="plain">, </span><span class="identifier">wchar_t</span><span class="plain"> *</span><span class="identifier">name</span><span class="plain">, </span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">def</span><span class="plain">, </span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">alt</span><span class="plain">) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">das_created</span><span class="plain"> == </span><span class="constant">FALSE</span><span class="plain">) {</span>
<span class="identifier">das_created</span><span class="plain"> = </span><span class="constant">TRUE</span><span class="plain">;</span>
&lt;<span class="cwebmacro">Empty the aspects table</span> <span class="cwebmacronumber">4.1</span>&gt;<span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">a</span><span class="plain"> &lt; </span><span class="constant">0</span><span class="plain">) || (</span><span class="identifier">a</span><span class="plain"> &gt;= </span><span class="identifier">NO_DEFINED_DA_VALUES</span><span class="plain">)) </span><span class="identifier">internal_error</span><span class="plain">(</span><span class="string">"aspect out of range"</span><span class="plain">);</span>
<span class="reserved">debugging_aspect</span><span class="plain"> *</span><span class="identifier">da</span><span class="plain"> = &amp;(</span><span class="identifier">the_debugging_aspects</span><span class="plain">[</span><span class="identifier">a</span><span class="plain">]);</span>
&lt;<span class="cwebmacro">Set up the new aspect</span> <span class="cwebmacronumber">4.2</span>&gt;<span class="plain">;</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Log::declare_aspect is used in 1/fm (<a href="1-fm.html#SP8_2">&#167;8.2</a>).</p>
<p class="inwebparagraph"><a id="SP4_1"></a><b>&#167;4.1. </b><code class="display">
&lt;<span class="cwebmacrodefn">Empty the aspects table</span> <span class="cwebmacronumber">4.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">for</span><span class="plain"> (</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">a</span><span class="plain">=0; </span><span class="identifier">a</span><span class="plain">&lt;</span><span class="identifier">NO_DEFINED_DA_VALUES</span><span class="plain">; </span><span class="identifier">a</span><span class="plain">++) {</span>
<span class="reserved">debugging_aspect</span><span class="plain"> *</span><span class="identifier">da</span><span class="plain"> = &amp;(</span><span class="identifier">the_debugging_aspects</span><span class="plain">[</span><span class="identifier">a</span><span class="plain">]);</span>
<span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">hyphenated_name</span><span class="plain"> = </span><span class="functiontext">Str::new</span><span class="plain">();</span>
<span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">unhyphenated_name</span><span class="plain"> = </span><span class="functiontext">Str::new</span><span class="plain">();</span>
<span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">negated_name</span><span class="plain"> = </span><span class="functiontext">Str::new</span><span class="plain">();</span>
<span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">on_or_off</span><span class="plain"> = </span><span class="constant">FALSE</span><span class="plain">;</span>
<span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">alternate</span><span class="plain"> = </span><span class="constant">FALSE</span><span class="plain">;</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP4">&#167;4</a>.</p>
<p class="inwebparagraph"><a id="SP4_2"></a><b>&#167;4.2. </b><code class="display">
&lt;<span class="cwebmacrodefn">Set up the new aspect</span> <span class="cwebmacronumber">4.2</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">negated_name</span><span class="plain">, </span><span class="string">"no-"</span><span class="plain">);</span>
<span class="reserved">for</span><span class="plain"> (</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">i</span><span class="plain">=0; </span><span class="identifier">name</span><span class="plain">[</span><span class="identifier">i</span><span class="plain">]; </span><span class="identifier">i</span><span class="plain">++) {</span>
<span class="identifier">wchar_t</span><span class="plain"> </span><span class="identifier">c</span><span class="plain"> = </span><span class="identifier">name</span><span class="plain">[</span><span class="identifier">i</span><span class="plain">];</span>
<span class="identifier">PUT_TO</span><span class="plain">(</span><span class="identifier">da</span><span class="plain">-&gt;</span><span class="identifier">unhyphenated_name</span><span class="plain">, </span><span class="identifier">c</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Characters::is_space_or_tab</span><span class="plain">(</span><span class="identifier">c</span><span class="plain">)) </span><span class="identifier">c</span><span class="plain"> = </span><span class="character">'-'</span><span class="plain">;</span>
<span class="identifier">PUT_TO</span><span class="plain">(</span><span class="identifier">da</span><span class="plain">-&gt;</span><span class="identifier">hyphenated_name</span><span class="plain">, </span><span class="identifier">c</span><span class="plain">);</span>
<span class="identifier">PUT_TO</span><span class="plain">(</span><span class="identifier">da</span><span class="plain">-&gt;</span><span class="identifier">negated_name</span><span class="plain">, </span><span class="identifier">c</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">on_or_off</span><span class="plain"> = </span><span class="identifier">def</span><span class="plain">;</span>
<span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">alternate</span><span class="plain"> = </span><span class="identifier">alt</span><span class="plain">;</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP4">&#167;4</a>.</p>
<p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>The debugging log provides an opportunity to see what has been happening
behind the scenes; but such a log file is often buffered by the filing system,
so that a sudden crash of NI may result in the loss of recent data written to
the log. Which is a pity, since this is exactly the most useful evidence as to
the cause of the crash in the first place. Accordingly, we fairly often
<code class="display"><span class="extract">fflush</span></code> the debug log file, forcing any buffered output to be written.
</p>
<p class="inwebparagraph">In this rest of this section, we always assume that <code class="display"><span class="extract">DL</span></code> is open. Note that it
is possible this has been switched to be <code class="display"><span class="extract">stdout</span></code>, or even that it is
temporarily the sentence tracing file: but we don't care.
</p>
<pre class="display">
<span class="reserved">filename</span><span class="plain"> *</span><span class="identifier">debug_log_filename</span><span class="plain"> = </span><span class="identifier">NULL</span><span class="plain">;</span>
<span class="reserved">filename</span><span class="plain"> *</span><span class="functiontext">Log::get_debug_log_filename</span><span class="plain">(</span><span class="reserved">void</span><span class="plain">) {</span>
<span class="reserved">return</span><span class="plain"> </span><span class="identifier">debug_log_filename</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Log::set_debug_log_filename</span><span class="plain">(</span><span class="reserved">filename</span><span class="plain"> *</span><span class="identifier">F</span><span class="plain">) {</span>
<span class="identifier">debug_log_filename</span><span class="plain"> = </span><span class="identifier">F</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">int</span><span class="plain"> </span><span class="functiontext">Log::open</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="identifier">debug_log_filename</span><span class="plain">) &amp;&amp; (</span><span class="identifier">DL</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">)) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">STREAM_OPEN_TO_FILE</span><span class="plain">(</span><span class="identifier">debug_log_file</span><span class="plain">, </span><span class="identifier">debug_log_filename</span><span class="plain">, </span><span class="constant">ISO_ENC</span><span class="plain">) == </span><span class="constant">FALSE</span><span class="plain">)</span>
<span class="reserved">return</span><span class="plain"> </span><span class="constant">FALSE</span><span class="plain">;</span>
<span class="identifier">DL</span><span class="plain"> = </span><span class="identifier">debug_log_file</span><span class="plain">;</span>
<span class="functiontext">Streams::enable_debugging</span><span class="plain">(</span><span class="identifier">DL</span><span class="plain">);</span>
<span class="identifier">LOG</span><span class="plain">(</span><span class="string">"Debugging log of %s\n"</span><span class="plain">, </span><span class="identifier">INTOOL_NAME</span><span class="plain">);</span>
<span class="reserved">return</span><span class="plain"> </span><span class="constant">TRUE</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">return</span><span class="plain"> </span><span class="constant">FALSE</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">int</span><span class="plain"> </span><span class="functiontext">Log::open_alternative</span><span class="plain">(</span><span class="reserved">filename</span><span class="plain"> *</span><span class="identifier">F</span><span class="plain">, </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">at</span><span class="plain">) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">STREAM_OPEN_TO_FILE</span><span class="plain">(</span><span class="identifier">at</span><span class="plain">, </span><span class="identifier">F</span><span class="plain">, </span><span class="constant">ISO_ENC</span><span class="plain">) == </span><span class="constant">FALSE</span><span class="plain">)</span>
<span class="reserved">return</span><span class="plain"> </span><span class="constant">FALSE</span><span class="plain">;</span>
<span class="identifier">DL</span><span class="plain"> = </span><span class="identifier">at</span><span class="plain">;</span>
<span class="functiontext">Streams::enable_debugging</span><span class="plain">(</span><span class="identifier">DL</span><span class="plain">);</span>
<span class="identifier">LOG</span><span class="plain">(</span><span class="string">"Debugging log of %s\n"</span><span class="plain">, </span><span class="identifier">INTOOL_NAME</span><span class="plain">);</span>
<span class="reserved">return</span><span class="plain"> </span><span class="constant">TRUE</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Log::close</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="identifier">DL</span><span class="plain">) {</span>
<span class="functiontext">Log::show_debugging_contents</span><span class="plain">();</span>
<span class="identifier">STREAM_CLOSE</span><span class="plain">(</span><span class="identifier">DL</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="plain">}</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Log::get_debug_log_filename is used in 3/cla (<a href="3-cla.html#SP13_1_1">&#167;13.1.1</a>).</p>
<p class="endnote">The function Log::set_debug_log_filename is used in 3/cla (<a href="3-cla.html#SP13_1_1">&#167;13.1.1</a>).</p>
<p class="endnote">The function Log::open is used in 3/cla (<a href="3-cla.html#SP13_1_1">&#167;13.1.1</a>).</p>
<p class="endnote">The function Log::open_alternative appears nowhere else.</p>
<p class="endnote">The function Log::close is used in 1/fm (<a href="1-fm.html#SP9">&#167;9</a>).</p>
<p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. Subheadings. </b>To provide signposts in what is otherwise a huge amorphous pile of text,
the debugging log can be divided into "phases", subdivided into "stages".
This is how.
</p>
<pre class="display">
<span class="reserved">char</span><span class="plain"> </span><span class="identifier">debug_log_phase</span><span class="plain">[32];</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">debug_log_subheading</span><span class="plain"> = </span><span class="constant">1</span><span class="plain">;</span>
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Log::new_phase</span><span class="plain">(</span><span class="reserved">char</span><span class="plain"> *</span><span class="identifier">p</span><span class="plain">, </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">q</span><span class="plain">) {</span>
<span class="functiontext">CStrings::truncated_strcpy</span><span class="plain">(</span><span class="identifier">debug_log_phase</span><span class="plain">, </span><span class="identifier">p</span><span class="plain">, </span><span class="constant">32</span><span class="plain">);</span>
<span class="identifier">LOG</span><span class="plain">(</span><span class="string">"\n\n-----------------------------------------------------\n"</span><span class="plain">);</span>
<span class="identifier">LOG</span><span class="plain">(</span><span class="string">"Phase %s ... %S"</span><span class="plain">, </span><span class="identifier">p</span><span class="plain">, </span><span class="identifier">q</span><span class="plain">);</span>
<span class="identifier">LOG</span><span class="plain">(</span><span class="string">"\n-----------------------------------------------------\n\n"</span><span class="plain">);</span>
<span class="identifier">STREAM_FLUSH</span><span class="plain">(</span><span class="identifier">DL</span><span class="plain">);</span>
<span class="identifier">debug_log_subheading</span><span class="plain"> = </span><span class="constant">1</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Log::new_stage</span><span class="plain">(</span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">p</span><span class="plain">) {</span>
<span class="identifier">LOG</span><span class="plain">(</span><span class="string">"\n\n==== Phase %s.%d ... %S ====\n\n"</span><span class="plain">, </span><span class="identifier">debug_log_phase</span><span class="plain">, </span><span class="identifier">debug_log_subheading</span><span class="plain">, </span><span class="identifier">p</span><span class="plain">);</span>
<span class="identifier">debug_log_subheading</span><span class="plain">++;</span>
<span class="identifier">STREAM_FLUSH</span><span class="plain">(</span><span class="identifier">DL</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Log::new_phase appears nowhere else.</p>
<p class="endnote">The function Log::new_stage appears nowhere else.</p>
<p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. Aspects. </b>As mentioned above, a wide range of activities can be logged to the debugging
log: these are called "aspects" and we can switch logging of them off or on
independently. The following routine tests whether a given aspect is currently
being logged, and is used by our main macros. Aspect 0 mandates writing to the
debug log, and is used when errors occur.
</p>
<pre class="display">
<span class="reserved">int</span><span class="plain"> </span><span class="functiontext">Log::aspect_switched_on</span><span class="plain">(</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">aspect</span><span class="plain">) {</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">decision</span><span class="plain"> = </span><span class="identifier">the_debugging_aspects</span><span class="plain">[</span><span class="identifier">aspect</span><span class="plain">].</span><span class="element">on_or_off</span><span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">aspect</span><span class="plain"> == </span><span class="constant">DEBUGGING_LOG_INCLUSIONS_DA</span><span class="plain">) </span><span class="identifier">decision</span><span class="plain"> = </span><span class="constant">TRUE</span><span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">decision</span><span class="plain">) </span><span class="identifier">STREAM_FLUSH</span><span class="plain">(</span><span class="identifier">DL</span><span class="plain">);</span>
<span class="reserved">return</span><span class="plain"> </span><span class="identifier">decision</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Log::set_aspect</span><span class="plain">(</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">aspect</span><span class="plain">, </span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">state</span><span class="plain">) {</span>
<span class="identifier">the_debugging_aspects</span><span class="plain">[</span><span class="identifier">aspect</span><span class="plain">].</span><span class="element">on_or_off</span><span class="plain"> = </span><span class="identifier">state</span><span class="plain">;</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Log::aspect_switched_on is used in <a href="#SP11">&#167;11</a>, 1/fm (<a href="1-fm.html#SP9">&#167;9</a>), 2/str (<a href="2-str.html#SP3">&#167;3</a>).</p>
<p class="endnote">The function Log::set_aspect appears nowhere else.</p>
<p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>We sometimes want to switch everything on, or switch everything off:
</p>
<pre class="display">
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Log::set_all_aspects</span><span class="plain">(</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">new_state</span><span class="plain">) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">DL</span><span class="plain">) </span><span class="identifier">LOGIF</span><span class="plain">(</span><span class="identifier">DEBUGGING_LOG_INCLUSIONS</span><span class="plain">, </span><span class="string">"Set debugging aspect: everything -&gt; %s\n"</span><span class="plain">,</span>
<span class="identifier">new_state</span><span class="plain">?</span><span class="string">"TRUE"</span><span class="plain">:</span><span class="string">"FALSE"</span><span class="plain">);</span>
<span class="reserved">for</span><span class="plain"> (</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">a</span><span class="plain">=0; </span><span class="identifier">a</span><span class="plain">&lt;</span><span class="identifier">NO_DEFINED_DA_VALUES</span><span class="plain">; </span><span class="identifier">a</span><span class="plain">++) {</span>
<span class="reserved">debugging_aspect</span><span class="plain"> *</span><span class="identifier">da</span><span class="plain"> = &amp;(</span><span class="identifier">the_debugging_aspects</span><span class="plain">[</span><span class="identifier">a</span><span class="plain">]);</span>
<span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">on_or_off</span><span class="plain"> = </span><span class="identifier">new_state</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Log::set_all_aspects is used in <a href="#SP9">&#167;9</a>.</p>
<p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b>We also want the ability to change debugging log settings from the command
line; the command line form is derived from the textual form by replacing
every space with a hyphen: for instance, <code class="display"><span class="extract">property-provision</span></code>.
</p>
<p class="inwebparagraph">We also recognise <code class="display"><span class="extract">no-property-provision</span></code> to switch this off again,
<code class="display"><span class="extract">everything</span></code> and <code class="display"><span class="extract">nothing</span></code> with the obvious meanings, and <code class="display"><span class="extract">list</span></code> to
print out a list of debugging aspects to <code class="display"><span class="extract">STDOUT</span></code>.
</p>
<pre class="display">
<span class="reserved">int</span><span class="plain"> </span><span class="functiontext">Log::set_aspect_from_command_line</span><span class="plain">(</span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">name</span><span class="plain">, </span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">give_error</span><span class="plain">) {</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">list_mode</span><span class="plain"> = </span><span class="constant">FALSE</span><span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Str::eq_wide_string</span><span class="plain">(</span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"everything"</span><span class="plain">)) { </span><span class="functiontext">Log::set_all_aspects</span><span class="plain">(</span><span class="constant">TRUE</span><span class="plain">); </span><span class="reserved">return</span><span class="plain"> </span><span class="constant">TRUE</span><span class="plain">; }</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Str::eq_wide_string</span><span class="plain">(</span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"nothing"</span><span class="plain">)) { </span><span class="functiontext">Log::set_all_aspects</span><span class="plain">(</span><span class="constant">FALSE</span><span class="plain">); </span><span class="reserved">return</span><span class="plain"> </span><span class="constant">TRUE</span><span class="plain">; }</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Str::eq_wide_string</span><span class="plain">(</span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"list"</span><span class="plain">)) </span><span class="identifier">list_mode</span><span class="plain"> = </span><span class="constant">TRUE</span><span class="plain">;</span>
<span class="reserved">for</span><span class="plain"> (</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">i</span><span class="plain">=0; </span><span class="identifier">i</span><span class="plain">&lt;</span><span class="identifier">NO_DEFINED_DA_VALUES</span><span class="plain">; </span><span class="identifier">i</span><span class="plain">++) {</span>
<span class="reserved">debugging_aspect</span><span class="plain"> *</span><span class="identifier">da</span><span class="plain"> = &amp;(</span><span class="identifier">the_debugging_aspects</span><span class="plain">[</span><span class="identifier">i</span><span class="plain">]);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Str::eq</span><span class="plain">(</span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">negated_name</span><span class="plain">)) {</span>
<span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">on_or_off</span><span class="plain"> = </span><span class="constant">FALSE</span><span class="plain">; </span><span class="reserved">return</span><span class="plain"> </span><span class="constant">TRUE</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="functiontext">Str::eq</span><span class="plain">(</span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">hyphenated_name</span><span class="plain">)) ||</span>
<span class="plain">(</span><span class="functiontext">Str::eq</span><span class="plain">(</span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">unhyphenated_name</span><span class="plain">))) {</span>
<span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">on_or_off</span><span class="plain"> = </span><span class="constant">TRUE</span><span class="plain">; </span><span class="reserved">return</span><span class="plain"> </span><span class="constant">TRUE</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">list_mode</span><span class="plain">) &amp;&amp; (</span><span class="functiontext">Str::len</span><span class="plain">(</span><span class="identifier">da</span><span class="plain">-&gt;</span><span class="identifier">hyphenated_name</span><span class="plain">) &gt; </span><span class="constant">0</span><span class="plain">)) {</span>
<span class="identifier">PRINT</span><span class="plain">(</span><span class="string">"--log %S (%s)\n"</span><span class="plain">, </span><span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">hyphenated_name</span><span class="plain">, (</span><span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">on_or_off</span><span class="plain">)?</span><span class="string">"on"</span><span class="plain">:</span><span class="string">"off"</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">list_mode</span><span class="plain"> == </span><span class="constant">FALSE</span><span class="plain">) &amp;&amp; (</span><span class="identifier">give_error</span><span class="plain">))</span>
<span class="identifier">PRINT</span><span class="plain">(</span><span class="string">"No such debugging log aspect as '%S'.\n"</span>
<span class="string">"(Try running -log list for a list of the valid aspects.)\n"</span><span class="plain">, </span><span class="identifier">name</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">list_mode</span><span class="plain"> == </span><span class="constant">TRUE</span><span class="plain">) </span><span class="reserved">return</span><span class="plain"> </span><span class="constant">TRUE</span><span class="plain">;</span>
<span class="reserved">return</span><span class="plain"> </span><span class="constant">FALSE</span><span class="plain">;</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Log::set_aspect_from_command_line is used in 3/cla (<a href="3-cla.html#SP13_1_1">&#167;13.1.1</a>).</p>
<p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. The starred trace. </b>This is a useful way to switch into a more detailed view, and then switch
out again without having lost our earlier settings.
</p>
<pre class="display">
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Log::tracing_on</span><span class="plain">(</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">starred</span><span class="plain">, </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">heading</span><span class="plain">) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">starred</span><span class="plain">) {</span>
<span class="identifier">LOG</span><span class="plain">(</span><span class="string">"\n*** Entering sentence trace mode: %S ***\n"</span><span class="plain">, </span><span class="identifier">heading</span><span class="plain">);</span>
<span class="plain">} </span><span class="reserved">else</span><span class="plain"> {</span>
<span class="identifier">LOG</span><span class="plain">(</span><span class="string">"\n*** Leaving sentence trace mode: %S ***\n\n"</span><span class="plain">, </span><span class="identifier">heading</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="reserved">for</span><span class="plain"> (</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">i</span><span class="plain">=0; </span><span class="identifier">i</span><span class="plain">&lt;</span><span class="identifier">NO_DEFINED_DA_VALUES</span><span class="plain">; </span><span class="identifier">i</span><span class="plain">++) {</span>
<span class="reserved">debugging_aspect</span><span class="plain"> *</span><span class="identifier">da</span><span class="plain"> = &amp;(</span><span class="identifier">the_debugging_aspects</span><span class="plain">[</span><span class="identifier">i</span><span class="plain">]);</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">j</span><span class="plain"> = </span><span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">on_or_off</span><span class="plain">;</span>
<span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">on_or_off</span><span class="plain"> = </span><span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">alternate</span><span class="plain">;</span>
<span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">alternate</span><span class="plain"> = </span><span class="identifier">j</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Log::tracing_on appears nowhere else.</p>
<p class="inwebparagraph"><a id="SP11"></a><b>&#167;11. Wrapping up. </b>At the end of the debugging log we list what was in it, mostly to provide
the reader with a list of other things which could have been put into it,
but weren't.
</p>
<pre class="display">
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Log::show_debugging_settings_with_state</span><span class="plain">(</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">state</span><span class="plain">) {</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">c</span><span class="plain"> = </span><span class="constant">0</span><span class="plain">;</span>
<span class="reserved">for</span><span class="plain"> (</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">i</span><span class="plain">=0; </span><span class="identifier">i</span><span class="plain">&lt;</span><span class="identifier">NO_DEFINED_DA_VALUES</span><span class="plain">; </span><span class="identifier">i</span><span class="plain">++) {</span>
<span class="reserved">debugging_aspect</span><span class="plain"> *</span><span class="identifier">da</span><span class="plain"> = &amp;(</span><span class="identifier">the_debugging_aspects</span><span class="plain">[</span><span class="identifier">i</span><span class="plain">]);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">on_or_off</span><span class="plain"> == </span><span class="identifier">state</span><span class="plain">) {</span>
<span class="identifier">c</span><span class="plain">++;</span>
<span class="identifier">LOG</span><span class="plain">(</span><span class="string">" %S"</span><span class="plain">, </span><span class="identifier">da</span><span class="plain">-&gt;</span><span class="element">hyphenated_name</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">c</span><span class="plain"> % </span><span class="constant">6</span><span class="plain"> == </span><span class="constant">0</span><span class="plain">) </span><span class="identifier">LOG</span><span class="plain">(</span><span class="string">"\n"</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">c</span><span class="plain"> == </span><span class="constant">0</span><span class="plain">) { </span><span class="identifier">LOG</span><span class="plain">(</span><span class="string">" (nothing)\n"</span><span class="plain">); } </span><span class="reserved">else</span><span class="plain"> { </span><span class="identifier">LOG</span><span class="plain">(</span><span class="string">"\n"</span><span class="plain">); }</span>
<span class="plain">}</span>
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Log::show_debugging_contents</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">DEBUGGING_LOG_INCLUSIONS_DA</span><span class="plain">) == </span><span class="constant">FALSE</span><span class="plain">) </span><span class="reserved">return</span><span class="plain">;</span>
<span class="identifier">LOG</span><span class="plain">(</span><span class="string">"\n\nThat concludes the debugging log from this run.\n"</span>
<span class="string">"Its contents were as follows -\n\n"</span><span class="plain">);</span>
<span class="identifier">LOG</span><span class="plain">(</span><span class="string">"Included:\n"</span><span class="plain">); </span><span class="functiontext">Log::show_debugging_settings_with_state</span><span class="plain">(</span><span class="constant">TRUE</span><span class="plain">);</span>
<span class="identifier">LOG</span><span class="plain">(</span><span class="string">"Omitted:\n"</span><span class="plain">); </span><span class="functiontext">Log::show_debugging_settings_with_state</span><span class="plain">(</span><span class="constant">FALSE</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Log::show_debugging_settings_with_state appears nowhere else.</p>
<p class="endnote">The function Log::show_debugging_contents is used in <a href="#SP5">&#167;5</a>.</p>
<hr class="tocbar">
<ul class="toc"><li><i>(This section begins Chapter 2: Memory, Streams and Collections.)</i></li><li><a href="2-mmr.html">Continue with 'Memory'</a></li></ul><hr class="tocbar">
<!--End of weave-->
</main>
</body>
</html>
Reference in a new issue View git blame Copy permalink