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 f06ec6100d Improved collation language and thence index pages
2020-05-02 23:50:23 +01:00

357 lines
61 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>
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
<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="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
<script>
function togglePopup(material_id) {
var popup = document.getElementById(material_id);
popup.classList.toggle("show");
}
</script>
<link href="../docs-assets/Popups.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
</head>
<body class="commentary-font">
<nav role="navigation">
<h1><a href="../index.html">
<img src="../docs-assets/Octagram.png" width=72 height=72">
</a></h1>
<ul><li><a href="../inweb/index.html">inweb</a></li>
</ul><h2>Foundation Module</h2><ul>
<li><a href="index.html"><span class="selectedlink">foundation</span></a></li>
<li><a href="../foundation-test/index.html">foundation-test</a></li>
</ul><h2>Example Webs</h2><ul>
<li><a href="../goldbach/index.html">goldbach</a></li>
<li><a href="../twinprimes/twinprimes.html">twinprimes</a></li>
<li><a href="../eastertide/index.html">eastertide</a></li>
</ul><h2>Repository</h2><ul>
<li><a href="https://github.com/ganelson/inweb"><img src="../docs-assets/github.png" height=18> github</a></li>
</ul><h2>Related Projects</h2><ul>
<li><a href="../../../inform/docs/index.html">inform</a></li>
<li><a href="../../../intest/docs/index.html">intest</a></li>
</ul>
</nav>
<main role="main">
<!--Weave of 'Debugging Log' generated by Inweb-->
<div class="breadcrumbs">
<ul class="crumbs"><li><a href="../index.html">Home</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></div>
<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="2-dl.html#SP1">&#167;1. The DL stream</a></li><li><a href="2-dl.html#SP2">&#167;2. Macros</a></li><li><a href="2-dl.html#SP3">&#167;3. Debugging aspects</a></li><li><a href="2-dl.html#SP6">&#167;6. Subheadings</a></li><li><a href="2-dl.html#SP7">&#167;7. Aspects</a></li><li><a href="2-dl.html#SP10">&#167;10. The starred trace</a></li><li><a href="2-dl.html#SP11">&#167;11. Wrapping up</a></li></ul><hr class="tocbar">
<p class="commentary firstcommentary"><a id="SP1"></a><b>&#167;1. The DL stream. </b>The debugging log file occupies the following stream:
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">text_stream</span><span class="plain-syntax"> </span><span class="identifier-syntax">debug_log_file_struct</span><span class="plain-syntax">; </span><span class="comment-syntax"> The actual debugging log file</span>
<span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">debug_log_file</span><span class="plain-syntax"> = &amp;</span><span class="identifier-syntax">debug_log_file_struct</span><span class="plain-syntax">; </span><span class="comment-syntax"> The actual debugging log file</span>
</pre>
<p class="commentary firstcommentary"><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="commentary">To write to the debugging log, we must in principle write to a stream called
<span class="extract"><span class="extract-syntax">DL</span></span>. In practice we more often use a pair of pseudo-functions called <span class="extract"><span class="extract-syntax">LOG</span></span>
and <span class="extract"><span class="extract-syntax">LOGIF</span></span>, which are macros defined in the section on Streams. For
instance, the pseudo-function-call
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> LOGIF(WHATEVER, "Heading %d skipped\n", n);</span>
</pre>
<p class="commentary">prints the line in question to the debugging log only if the aspect <span class="extract"><span class="extract-syntax">WHATEVER</span></span>
is currently switched on. Plain <span class="extract"><span class="extract-syntax">LOG</span></span> does the same, but unconditionally.
</p>
<pre class="definitions code-font"><span class="definition-keyword">define</span> <span class="constant-syntax">LOG_INDENT</span><span class="plain-syntax"> </span><span class="identifier-syntax">STREAM_INDENT</span><span class="plain-syntax">(</span><span class="identifier-syntax">DL</span><span class="plain-syntax">)</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">LOG_OUTDENT</span><span class="plain-syntax"> </span><span class="identifier-syntax">STREAM_OUTDENT</span><span class="plain-syntax">(</span><span class="identifier-syntax">DL</span><span class="plain-syntax">)</span>
</pre>
<p class="commentary firstcommentary"><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="commentary">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="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">debugging_aspect</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">hyphenated_name</span><span class="plain-syntax">; </span><span class="comment-syntax"> e.g., "memory-usage"</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">negated_name</span><span class="plain-syntax">; </span><span class="comment-syntax"> e.g., "no-memory-usage"</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">unhyphenated_name</span><span class="plain-syntax">; </span><span class="comment-syntax"> e.g., "memory usage"</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">on_or_off</span><span class="plain-syntax">; </span><span class="comment-syntax"> whether or not active when writing to debugging log</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">alternate</span><span class="plain-syntax">; </span><span class="comment-syntax"> whether or not active when writing in trace mode</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">debugging_aspect</span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>The structure debugging_aspect is accessed in 8/bdfw and here.</li></ul>
<p class="commentary firstcommentary"><a id="SP4"></a><b>&#167;4. </b>And now we must define all those constants and names. Note that the
<span class="extract"><span class="extract-syntax">TRUE</span></span> or <span class="extract"><span class="extract-syntax">FALSE</span></span> settings below are the defaults, and apply unless the
source says otherwise. The <span class="extract"><span class="extract-syntax">alternate</span></span> settings are those used in
trace-sentences mode, that is, between asterisk sentences.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">DEBUGGING_LOG_INCLUSIONS_DA</span><span class="plain-syntax"> </span><span class="identifier-syntax">from</span><span class="plain-syntax"> </span><span class="constant-syntax">0</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">SHELL_USAGE_DA</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">MEMORY_USAGE_DA</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">TEXT_FILES_DA</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">das_created</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">debugging_aspect</span><span class="plain-syntax"> </span><span class="identifier-syntax">the_debugging_aspects</span><span class="plain-syntax">[</span><span class="identifier-syntax">NO_DEFINED_DA_VALUES</span><span class="plain-syntax">];</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Log::declare_aspect</span><button class="popup" onclick="togglePopup('usagePopup1')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup1">Usage of <span class="code-font"><span class="function-syntax">Log::declare_aspect</span></span>:<br/>Foundation Module - <a href="1-fm.html#SP8_2">&#167;8.2</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">a</span><span class="plain-syntax">, </span><span class="identifier-syntax">wchar_t</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">def</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">alt</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">das_created</span><span class="plain-syntax"> == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">das_created</span><span class="plain-syntax"> = </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="2-dl.html#SP4_1" class="named-paragraph-link"><span class="named-paragraph">Empty the aspects table</span><span class="named-paragraph-number">4.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">a</span><span class="plain-syntax"> &lt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) || (</span><span class="identifier-syntax">a</span><span class="plain-syntax"> &gt;= </span><span class="identifier-syntax">NO_DEFINED_DA_VALUES</span><span class="plain-syntax">)) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"aspect out of range"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">debugging_aspect</span><span class="plain-syntax"> *</span><span class="identifier-syntax">da</span><span class="plain-syntax"> = &amp;(</span><span class="identifier-syntax">the_debugging_aspects</span><span class="plain-syntax">[</span><span class="identifier-syntax">a</span><span class="plain-syntax">]);</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="2-dl.html#SP4_2" class="named-paragraph-link"><span class="named-paragraph">Set up the new aspect</span><span class="named-paragraph-number">4.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP4_1"></a><b>&#167;4.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Empty the aspects table</span><span class="named-paragraph-number">4.1</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">a</span><span class="plain-syntax">=0; </span><span class="identifier-syntax">a</span><span class="plain-syntax">&lt;</span><span class="identifier-syntax">NO_DEFINED_DA_VALUES</span><span class="plain-syntax">; </span><span class="identifier-syntax">a</span><span class="plain-syntax">++) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">debugging_aspect</span><span class="plain-syntax"> *</span><span class="identifier-syntax">da</span><span class="plain-syntax"> = &amp;(</span><span class="identifier-syntax">the_debugging_aspects</span><span class="plain-syntax">[</span><span class="identifier-syntax">a</span><span class="plain-syntax">]);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">hyphenated_name</span><span class="plain-syntax"> = </span><a href="4-sm.html#SP2" class="function-link"><span class="function-syntax">Str::new</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">unhyphenated_name</span><span class="plain-syntax"> = </span><a href="4-sm.html#SP2" class="function-link"><span class="function-syntax">Str::new</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">negated_name</span><span class="plain-syntax"> = </span><a href="4-sm.html#SP2" class="function-link"><span class="function-syntax">Str::new</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">on_or_off</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">alternate</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="2-dl.html#SP4">&#167;4</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP4_2"></a><b>&#167;4.2. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Set up the new aspect</span><span class="named-paragraph-number">4.2</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">negated_name</span><span class="plain-syntax">, </span><span class="string-syntax">"no-"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">i</span><span class="plain-syntax">=0; </span><span class="identifier-syntax">name</span><span class="plain-syntax">[</span><span class="identifier-syntax">i</span><span class="plain-syntax">]; </span><span class="identifier-syntax">i</span><span class="plain-syntax">++) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wchar_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">c</span><span class="plain-syntax"> = </span><span class="identifier-syntax">name</span><span class="plain-syntax">[</span><span class="identifier-syntax">i</span><span class="plain-syntax">];</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PUT_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">unhyphenated_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">c</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="4-chr.html#SP2" class="function-link"><span class="function-syntax">Characters::is_space_or_tab</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">c</span><span class="plain-syntax">)) </span><span class="identifier-syntax">c</span><span class="plain-syntax"> = </span><span class="character-syntax">'-'</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PUT_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">hyphenated_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">c</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PUT_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">negated_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">c</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">on_or_off</span><span class="plain-syntax"> = </span><span class="identifier-syntax">def</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">alternate</span><span class="plain-syntax"> = </span><span class="identifier-syntax">alt</span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="2-dl.html#SP4">&#167;4</a>.</li></ul>
<p class="commentary firstcommentary"><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 Inform 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
<span class="extract"><span class="extract-syntax">fflush</span></span> the debug log file, forcing any buffered output to be written.
</p>
<p class="commentary">In this rest of this section, we always assume that <span class="extract"><span class="extract-syntax">DL</span></span> is open. Note that it
is possible this has been switched to be <span class="extract"><span class="extract-syntax">stdout</span></span>, or even that it is
temporarily the sentence tracing file: but we don't care.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">debug_log_filename</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="function-syntax">Log::get_debug_log_filename</span><button class="popup" onclick="togglePopup('usagePopup2')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup2">Usage of <span class="code-font"><span class="function-syntax">Log::get_debug_log_filename</span></span>:<br/>Command Line Arguments - <a href="3-cla.html#SP13_1_1">&#167;13.1.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">debug_log_filename</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Log::set_debug_log_filename</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">Log::set_debug_log_filename</span></span>:<br/>Command Line Arguments - <a href="3-cla.html#SP13_1_1">&#167;13.1.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">debug_log_filename</span><span class="plain-syntax"> = </span><span class="identifier-syntax">F</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Log::open</span><button class="popup" onclick="togglePopup('usagePopup4')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup4">Usage of <span class="code-font"><span class="function-syntax">Log::open</span></span>:<br/>Command Line Arguments - <a href="3-cla.html#SP13_1_1">&#167;13.1.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">debug_log_filename</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">DL</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">STREAM_OPEN_TO_FILE</span><span class="plain-syntax">(</span><span class="identifier-syntax">debug_log_file</span><span class="plain-syntax">, </span><span class="identifier-syntax">debug_log_filename</span><span class="plain-syntax">, </span><span class="constant-syntax">ISO_ENC</span><span class="plain-syntax">) == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DL</span><span class="plain-syntax"> = </span><span class="identifier-syntax">debug_log_file</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="2-str.html#SP20" class="function-link"><span class="function-syntax">Streams::enable_debugging</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">DL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"Debugging log of %s\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">PROGRAM_NAME</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Log::open_alternative</span><span class="plain-syntax">(</span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">at</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">STREAM_OPEN_TO_FILE</span><span class="plain-syntax">(</span><span class="identifier-syntax">at</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="constant-syntax">ISO_ENC</span><span class="plain-syntax">) == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DL</span><span class="plain-syntax"> = </span><span class="identifier-syntax">at</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="2-str.html#SP20" class="function-link"><span class="function-syntax">Streams::enable_debugging</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">DL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"Debugging log of %s\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">PROGRAM_NAME</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Log::close</span><button class="popup" onclick="togglePopup('usagePopup5')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup5">Usage of <span class="code-font"><span class="function-syntax">Log::close</span></span>:<br/>Foundation Module - <a href="1-fm.html#SP9">&#167;9</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">DL</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="2-dl.html#SP11" class="function-link"><span class="function-syntax">Log::show_debugging_contents</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">STREAM_CLOSE</span><span class="plain-syntax">(</span><span class="identifier-syntax">DL</span><span class="plain-syntax">); </span><span class="identifier-syntax">DL</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><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="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">char</span><span class="plain-syntax"> </span><span class="identifier-syntax">debug_log_phase</span><span class="plain-syntax">[32];</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">debug_log_subheading</span><span class="plain-syntax"> = </span><span class="constant-syntax">1</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Log::new_phase</span><span class="plain-syntax">(</span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">p</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">q</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="4-cst.html#SP9" class="function-link"><span class="function-syntax">CStrings::truncated_strcpy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">debug_log_phase</span><span class="plain-syntax">, </span><span class="identifier-syntax">p</span><span class="plain-syntax">, </span><span class="constant-syntax">32</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"\n\n-----------------------------------------------------\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"Phase %s ... %S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">p</span><span class="plain-syntax">, </span><span class="identifier-syntax">q</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"\n-----------------------------------------------------\n\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">STREAM_FLUSH</span><span class="plain-syntax">(</span><span class="identifier-syntax">DL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">debug_log_subheading</span><span class="plain-syntax"> = </span><span class="constant-syntax">1</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Log::new_stage</span><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">p</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"\n\n==== Phase %s.%d ... %S ====\n\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">debug_log_phase</span><span class="plain-syntax">, </span><span class="identifier-syntax">debug_log_subheading</span><span class="plain-syntax">, </span><span class="identifier-syntax">p</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">debug_log_subheading</span><span class="plain-syntax">++;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">STREAM_FLUSH</span><span class="plain-syntax">(</span><span class="identifier-syntax">DL</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><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="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Log::aspect_switched_on</span><button class="popup" onclick="togglePopup('usagePopup6')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup6">Usage of <span class="code-font"><span class="function-syntax">Log::aspect_switched_on</span></span>:<br/><a href="2-dl.html#SP11">&#167;11</a><br/>Foundation Module - <a href="1-fm.html#SP9">&#167;9</a><br/>Streams - <a href="2-str.html#SP3">&#167;3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">aspect</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">decision</span><span class="plain-syntax"> = </span><span class="identifier-syntax">the_debugging_aspects</span><span class="plain-syntax">[</span><span class="identifier-syntax">aspect</span><span class="plain-syntax">].</span><span class="element-syntax">on_or_off</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">aspect</span><span class="plain-syntax"> == </span><span class="constant-syntax">DEBUGGING_LOG_INCLUSIONS_DA</span><span class="plain-syntax">) </span><span class="identifier-syntax">decision</span><span class="plain-syntax"> = </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">decision</span><span class="plain-syntax">) </span><span class="identifier-syntax">STREAM_FLUSH</span><span class="plain-syntax">(</span><span class="identifier-syntax">DL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">decision</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Log::set_aspect</span><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">aspect</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">state</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">the_debugging_aspects</span><span class="plain-syntax">[</span><span class="identifier-syntax">aspect</span><span class="plain-syntax">].</span><span class="element-syntax">on_or_off</span><span class="plain-syntax"> = </span><span class="identifier-syntax">state</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP8"></a><b>&#167;8. </b>We sometimes want to switch everything on, or switch everything off:
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Log::set_all_aspects</span><button class="popup" onclick="togglePopup('usagePopup7')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup7">Usage of <span class="code-font"><span class="function-syntax">Log::set_all_aspects</span></span>:<br/><a href="2-dl.html#SP9">&#167;9</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">new_state</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">DL</span><span class="plain-syntax">) </span><span class="identifier-syntax">LOGIF</span><span class="plain-syntax">(</span><span class="identifier-syntax">DEBUGGING_LOG_INCLUSIONS</span><span class="plain-syntax">, </span><span class="string-syntax">"Set debugging aspect: everything -&gt; %s\n"</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">new_state</span><span class="plain-syntax">?</span><span class="string-syntax">"TRUE"</span><span class="plain-syntax">:</span><span class="string-syntax">"FALSE"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">a</span><span class="plain-syntax">=0; </span><span class="identifier-syntax">a</span><span class="plain-syntax">&lt;</span><span class="identifier-syntax">NO_DEFINED_DA_VALUES</span><span class="plain-syntax">; </span><span class="identifier-syntax">a</span><span class="plain-syntax">++) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">debugging_aspect</span><span class="plain-syntax"> *</span><span class="identifier-syntax">da</span><span class="plain-syntax"> = &amp;(</span><span class="identifier-syntax">the_debugging_aspects</span><span class="plain-syntax">[</span><span class="identifier-syntax">a</span><span class="plain-syntax">]);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">on_or_off</span><span class="plain-syntax"> = </span><span class="identifier-syntax">new_state</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><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, <span class="extract"><span class="extract-syntax">property-provision</span></span>.
</p>
<p class="commentary">We also recognise <span class="extract"><span class="extract-syntax">no-property-provision</span></span> to switch this off again,
<span class="extract"><span class="extract-syntax">everything</span></span> and <span class="extract"><span class="extract-syntax">nothing</span></span> with the obvious meanings, and <span class="extract"><span class="extract-syntax">list</span></span> to
print out a list of debugging aspects to <span class="extract"><span class="extract-syntax">STDOUT</span></span>.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Log::set_aspect_from_command_line</span><button class="popup" onclick="togglePopup('usagePopup8')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup8">Usage of <span class="code-font"><span class="function-syntax">Log::set_aspect_from_command_line</span></span>:<br/>Command Line Arguments - <a href="3-cla.html#SP13_1_1">&#167;13.1.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">give_error</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">list_mode</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="4-sm.html#SP22" class="function-link"><span class="function-syntax">Str::eq_wide_string</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"everything"</span><span class="plain-syntax">)) { </span><a href="2-dl.html#SP8" class="function-link"><span class="function-syntax">Log::set_all_aspects</span></a><span class="plain-syntax">(</span><span class="constant-syntax">TRUE</span><span class="plain-syntax">); </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">; }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="4-sm.html#SP22" class="function-link"><span class="function-syntax">Str::eq_wide_string</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"nothing"</span><span class="plain-syntax">)) { </span><a href="2-dl.html#SP8" class="function-link"><span class="function-syntax">Log::set_all_aspects</span></a><span class="plain-syntax">(</span><span class="constant-syntax">FALSE</span><span class="plain-syntax">); </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">; }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="4-sm.html#SP22" class="function-link"><span class="function-syntax">Str::eq_wide_string</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"list"</span><span class="plain-syntax">)) </span><span class="identifier-syntax">list_mode</span><span class="plain-syntax"> = </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">i</span><span class="plain-syntax">=0; </span><span class="identifier-syntax">i</span><span class="plain-syntax">&lt;</span><span class="identifier-syntax">NO_DEFINED_DA_VALUES</span><span class="plain-syntax">; </span><span class="identifier-syntax">i</span><span class="plain-syntax">++) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">debugging_aspect</span><span class="plain-syntax"> *</span><span class="identifier-syntax">da</span><span class="plain-syntax"> = &amp;(</span><span class="identifier-syntax">the_debugging_aspects</span><span class="plain-syntax">[</span><span class="identifier-syntax">i</span><span class="plain-syntax">]);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">, </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">negated_name</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">on_or_off</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><a href="4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">, </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">hyphenated_name</span><span class="plain-syntax">)) ||</span>
<span class="plain-syntax"> (</span><a href="4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">, </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">unhyphenated_name</span><span class="plain-syntax">))) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">on_or_off</span><span class="plain-syntax"> = </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">; </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">list_mode</span><span class="plain-syntax">) &amp;&amp; (</span><a href="4-sm.html#SP8" class="function-link"><span class="function-syntax">Str::len</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">hyphenated_name</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PRINT</span><span class="plain-syntax">(</span><span class="string-syntax">"--log %S (%s)\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">hyphenated_name</span><span class="plain-syntax">, (</span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">on_or_off</span><span class="plain-syntax">)?</span><span class="string-syntax">"on"</span><span class="plain-syntax">:</span><span class="string-syntax">"off"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">list_mode</span><span class="plain-syntax"> == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">give_error</span><span class="plain-syntax">))</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PRINT</span><span class="plain-syntax">(</span><span class="string-syntax">"No such debugging log aspect as '%S'.\n"</span>
<span class="plain-syntax"> </span><span class="string-syntax">"(Try running -log list for a list of the valid aspects.)\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">list_mode</span><span class="plain-syntax"> == </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><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="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Log::tracing_on</span><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">starred</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">heading</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">starred</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"\n*** Entering sentence trace mode: %S ***\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">heading</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"\n*** Leaving sentence trace mode: %S ***\n\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">heading</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">i</span><span class="plain-syntax">=0; </span><span class="identifier-syntax">i</span><span class="plain-syntax">&lt;</span><span class="identifier-syntax">NO_DEFINED_DA_VALUES</span><span class="plain-syntax">; </span><span class="identifier-syntax">i</span><span class="plain-syntax">++) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">debugging_aspect</span><span class="plain-syntax"> *</span><span class="identifier-syntax">da</span><span class="plain-syntax"> = &amp;(</span><span class="identifier-syntax">the_debugging_aspects</span><span class="plain-syntax">[</span><span class="identifier-syntax">i</span><span class="plain-syntax">]);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">j</span><span class="plain-syntax"> = </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">on_or_off</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">on_or_off</span><span class="plain-syntax"> = </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">alternate</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">alternate</span><span class="plain-syntax"> = </span><span class="identifier-syntax">j</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><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="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Log::show_debugging_settings_with_state</span><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">state</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">c</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">i</span><span class="plain-syntax">=0; </span><span class="identifier-syntax">i</span><span class="plain-syntax">&lt;</span><span class="identifier-syntax">NO_DEFINED_DA_VALUES</span><span class="plain-syntax">; </span><span class="identifier-syntax">i</span><span class="plain-syntax">++) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">debugging_aspect</span><span class="plain-syntax"> *</span><span class="identifier-syntax">da</span><span class="plain-syntax"> = &amp;(</span><span class="identifier-syntax">the_debugging_aspects</span><span class="plain-syntax">[</span><span class="identifier-syntax">i</span><span class="plain-syntax">]);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">on_or_off</span><span class="plain-syntax"> == </span><span class="identifier-syntax">state</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">c</span><span class="plain-syntax">++;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">" %S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">da</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">hyphenated_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">c</span><span class="plain-syntax"> % </span><span class="constant-syntax">6</span><span class="plain-syntax"> == </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">c</span><span class="plain-syntax"> == </span><span class="constant-syntax">0</span><span class="plain-syntax">) { </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">" (nothing)\n"</span><span class="plain-syntax">); } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> { </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"\n"</span><span class="plain-syntax">); }</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Log::show_debugging_contents</span><button class="popup" onclick="togglePopup('usagePopup9')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup9">Usage of <span class="code-font"><span class="function-syntax">Log::show_debugging_contents</span></span>:<br/><a href="2-dl.html#SP5">&#167;5</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="2-dl.html#SP7" class="function-link"><span class="function-syntax">Log::aspect_switched_on</span></a><span class="plain-syntax">(</span><span class="constant-syntax">DEBUGGING_LOG_INCLUSIONS_DA</span><span class="plain-syntax">) == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"\n\nThat concludes the debugging log from this run.\n"</span>
<span class="plain-syntax"> </span><span class="string-syntax">"Its contents were as follows -\n\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"Included:\n"</span><span class="plain-syntax">); </span><a href="2-dl.html#SP11" class="function-link"><span class="function-syntax">Log::show_debugging_settings_with_state</span></a><span class="plain-syntax">(</span><span class="constant-syntax">TRUE</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"Omitted:\n"</span><span class="plain-syntax">); </span><a href="2-dl.html#SP11" class="function-link"><span class="function-syntax">Log::show_debugging_settings_with_state</span></a><span class="plain-syntax">(</span><span class="constant-syntax">FALSE</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<nav role="progress"><div class="progresscontainer">
<ul class="progressbar"><li class="progressprev"><a href="1-wp.html">&#10094;</a></li><li class="progresschapter"><a href="P-abgtf.html">P</a></li><li class="progresschapter"><a href="1-fm.html">1</a></li><li class="progresscurrentchapter">2</li><li class="progresscurrent">dl</li><li class="progresssection"><a href="2-mmr.html">mmr</a></li><li class="progresssection"><a href="2-str.html">str</a></li><li class="progresssection"><a href="2-wal.html">wal</a></li><li class="progresssection"><a href="2-mth.html">mth</a></li><li class="progresssection"><a href="2-llas.html">llas</a></li><li class="progresssection"><a href="2-dct.html">dct</a></li><li class="progresssection"><a href="2-trs.html">trs</a></li><li class="progresschapter"><a href="3-em.html">3</a></li><li class="progresschapter"><a href="4-chr.html">4</a></li><li class="progresschapter"><a href="5-htm.html">5</a></li><li class="progresschapter"><a href="6-bf.html">6</a></li><li class="progresschapter"><a href="7-vn.html">7</a></li><li class="progresschapter"><a href="8-ws.html">8</a></li><li class="progressnext"><a href="2-mmr.html">&#10095;</a></li></ul></div>
</nav><!--End of weave-->
</main>
</body>
</html>
Reference in a new issue View git blame Copy permalink