ifhub/inform7
1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-07-08 10:04:21 +03:00
Code Issues Projects Releases Wiki Activity
inform7/docs/inblorb/3-plc.html
Graham Nelson 1268a0f40e Colonised
2020-04-14 17:56:54 +01:00

299 lines
47 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>Placeholders</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="../index.html">
<img src="../docs-src/Figures/Inform.png" height=72">
</a></h1>
<ul><li><a href="../compiler.html">compiler tools</a></li>
<li><a href="../other.html">other tools</a></li>
<li><a href="../extensions.html">extensions and kits</a></li>
<li><a href="../units.html">unit test tools</a></li>
</ul><h2>Other Tools</h2><ul>
<li><a href="index.html"><span class="selectedlink">inblorb</span></a></li>
<li><a href="../indoc/index.html">indoc</a></li>
<li><a href="../inpolicy/index.html">inpolicy</a></li>
<li><a href="../inrtps/index.html">inrtps</a></li>
</ul><h2>Foundation</h2><ul>
<li><a href="../../../inweb/docs/foundation-module/index.html">foundation</a></li>
</ul>
</nav>
<main role="main">
<!--Weave of 'Placeholders' generated by 7-->
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../other.html">Other Tools</a></li><li><a href="index.html">inblorb</a></li><li><a href="index.html#3">Chapter 3: Other Material</a></li><li><b>Placeholders</b></li></ul><p class="purpose">To manage placeholder variables.</p>
<ul class="toc"><li><a href="#SP1">&#167;1. Placeholders</a></li><li><a href="#SP2">&#167;2. Initial values</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Placeholders. </b>Placeholders are markers such as "[AUTHOR]", found in the template
files for making web pages. ("AUTHOR" would be the name of this one; the use
of capital letters is customary but not required.) Most of these can be set
to arbitrary texts by use of the <code class="display"><span class="extract">placeholder</span></code> command in the blurb file, but
a few are "reserved":
</p>
<pre class="definitions">
<span class="definitionkeyword">define</span> <span class="constant">SOURCE_RPL</span><span class="plain"> </span><span class="constant">1</span>
<span class="definitionkeyword">define</span> <span class="constant">SOURCENOTES_RPL</span><span class="plain"> </span><span class="constant">2</span>
<span class="definitionkeyword">define</span> <span class="constant">SOURCELINKS_RPL</span><span class="plain"> </span><span class="constant">3</span>
<span class="definitionkeyword">define</span> <span class="constant">COVER_RPL</span><span class="plain"> </span><span class="constant">4</span>
<span class="definitionkeyword">define</span> <span class="constant">DOWNLOAD_RPL</span><span class="plain"> </span><span class="constant">5</span>
<span class="definitionkeyword">define</span> <span class="constant">AUXILIARY_RPL</span><span class="plain"> </span><span class="constant">6</span>
<span class="definitionkeyword">define</span> <span class="constant">PAGENUMBER_RPL</span><span class="plain"> </span><span class="constant">7</span>
<span class="definitionkeyword">define</span> <span class="constant">PAGEEXTENT_RPL</span><span class="plain"> </span><span class="constant">8</span>
</pre>
<pre class="display">
<span class="reserved">typedef</span><span class="plain"> </span><span class="reserved">struct</span><span class="plain"> </span><span class="reserved">placeholder</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">pl_name</span><span class="plain">; </span><span class="comment"> such as "[AUTHOR]"</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">pl_contents</span><span class="plain">; </span><span class="comment"> current value</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">reservation</span><span class="plain">; </span><span class="comment"> one of the <code class="display"><span class="extract">*_RPL</span></code> values above, or 0 for unreserved</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">locked</span><span class="plain">; </span><span class="comment"> currently being expanded: locked to prevent mise-en-abyme</span>
<span class="constant">MEMORY_MANAGEMENT</span>
<span class="plain">} </span><span class="reserved">placeholder</span><span class="plain">;</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The structure placeholder is private to this section.</p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. Initial values. </b>The <code class="display"><span class="extract">BLURB</span></code> refers here to back-cover-style text, and not to the "blurb"
file which we are acting on.
</p>
<pre class="display">
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Placeholders::initialise<button class="popup" onclick="togglePopup('usagePopup82')">...<span class="popuptext" id="usagePopup82">Usage of <b>Placeholders::initialise</b>:<br>Main - <a href="1-mn.html#SP3">&#167;3</a></span></button></span><span class="plain">(</span><span class="reserved">void</span><span class="plain">) {</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"SOURCE"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">""</span><span class="plain">, </span><span class="constant">SOURCE_RPL</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"SOURCENOTES"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">""</span><span class="plain">, </span><span class="constant">SOURCENOTES_RPL</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"SOURCELINKS"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">""</span><span class="plain">, </span><span class="constant">SOURCELINKS_RPL</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"COVER"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">""</span><span class="plain">, </span><span class="constant">COVER_RPL</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"DOWNLOAD"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">""</span><span class="plain">, </span><span class="constant">DOWNLOAD_RPL</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"AUXILIARY"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">""</span><span class="plain">, </span><span class="constant">AUXILIARY_RPL</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"PAGENUMBER"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">""</span><span class="plain">, </span><span class="constant">PAGENUMBER_RPL</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"PAGEEXTENT"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">""</span><span class="plain">, </span><span class="constant">PAGEEXTENT_RPL</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"CBLORBERRORS"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">""</span><span class="plain">, </span><span class="constant">0</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"INBROWSERPLAY"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">""</span><span class="plain">, </span><span class="constant">0</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"INTERPRETERSCRIPTS"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">""</span><span class="plain">, </span><span class="constant">0</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"OTHERCREDITS"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">""</span><span class="plain">, </span><span class="constant">0</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"BLURB"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">""</span><span class="plain">, </span><span class="constant">0</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"TEMPLATE"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"Standard"</span><span class="plain">, </span><span class="constant">0</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"GENERATOR"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"inblorb [[Build Number]]"</span><span class="plain">, </span><span class="constant">0</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"BASE64_TOP"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">""</span><span class="plain">, </span><span class="constant">0</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"BASE64_TAIL"</span><span class="plain">, </span><span class="identifier">I</span><span class="string">""</span><span class="plain">, </span><span class="constant">0</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"JAVASCRIPTPRELUDE"</span><span class="plain">, </span><span class="functiontext"><a href="4-sm.html#SP26">Str::literal</a></span><span class="plain">(</span><span class="identifier">JAVASCRIPT_PRELUDE</span><span class="plain">), </span><span class="constant">0</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"FONTTAG"</span><span class="plain">, </span><span class="functiontext"><a href="4-sm.html#SP26">Str::literal</a></span><span class="plain">(</span><span class="identifier">FONT_TAG</span><span class="plain">), </span><span class="constant">0</span><span class="plain">);</span>
<span class="functiontext"><a href="1-mn.html#SP4">Main::initialise_time_variables</a></span><span class="plain">();</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>We don't need any very efficient system for parsing these names, as there
are typically fewer than 20 placeholders at a time.
</p>
<pre class="display">
<span class="reserved">placeholder</span><span class="plain"> *</span><span class="functiontext">Placeholders::find<button class="popup" onclick="togglePopup('usagePopup83')">...<span class="popuptext" id="usagePopup83">Usage of <b>Placeholders::find</b>:<br><a href="#SP6">&#167;6</a>, <a href="#SP7">&#167;7</a></span></button></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">placeholder</span><span class="plain"> *</span><span class="identifier">wv</span><span class="plain">;</span>
<span class="identifier">LOOP_OVER</span><span class="plain">(</span><span class="identifier">wv</span><span class="plain">, </span><span class="reserved">placeholder</span><span class="plain">)</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext"><a href="4-sm.html#SP18">Str::eq</a></span><span class="plain">(</span><span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">pl_name</span><span class="plain">, </span><span class="identifier">name</span><span class="plain">))</span>
<span class="reserved">return</span><span class="plain"> </span><span class="identifier">wv</span><span class="plain">;</span>
<span class="reserved">return</span><span class="plain"> </span><span class="identifier">NULL</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">text_stream</span><span class="plain"> *</span><span class="functiontext">Placeholders::read<button class="popup" onclick="togglePopup('usagePopup84')">...<span class="popuptext" id="usagePopup84">Usage of <b>Placeholders::read</b>:<br>Main - <a href="1-mn.html#SP5">&#167;5</a><br>Blurb Parser - <a href="1-bp.html#SP8">&#167;8</a><br>Releaser - <a href="3-rls.html#SP5">&#167;5</a>, <a href="3-rls.html#SP6_5">&#167;6.5</a>, <a href="3-rls.html#SP6_8">&#167;6.8</a>, <a href="3-rls.html#SP6_9">&#167;6.9</a>, <a href="3-rls.html#SP7">&#167;7</a>, <a href="3-rls.html#SP8_1">&#167;8.1</a>, <a href="3-rls.html#SP8_2">&#167;8.2</a>, <a href="3-rls.html#SP8_2_1">&#167;8.2.1</a>, <a href="3-rls.html#SP11">&#167;11</a><br>Links and Auxiliary Files - <a href="3-laaf.html#SP5">&#167;5</a><br>Website Maker - <a href="3-wm.html#SP11">&#167;11</a>, <a href="3-wm.html#SP15">&#167;15</a>, <a href="3-wm.html#SP15_1">&#167;15.1</a>, <a href="3-wm.html#SP18">&#167;18</a></span></button></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">placeholder</span><span class="plain"> *</span><span class="identifier">wv</span><span class="plain"> = </span><span class="functiontext"><a href="#SP3">Placeholders::find</a></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">wv</span><span class="plain">) </span><span class="reserved">return</span><span class="plain"> </span><span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">pl_contents</span><span class="plain">;</span>
<span class="reserved">return</span><span class="plain"> </span><span class="identifier">NULL</span><span class="plain">;</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>There are no "types" of these placeholders. When they hold numbers, it's only
as the text of a number written out in decimal, so:
</p>
<pre class="display">
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Placeholders::set_to_number<button class="popup" onclick="togglePopup('usagePopup85')">...<span class="popuptext" id="usagePopup85">Usage of <b>Placeholders::set_to_number</b>:<br>Main - <a href="1-mn.html#SP4">&#167;4</a>, <a href="1-mn.html#SP6_1">&#167;6.1</a><br>Blurb Parser - <a href="1-bp.html#SP7_2">&#167;7.2</a></span></button></span><span class="plain">(</span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">var</span><span class="plain">, </span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">v</span><span class="plain">) {</span>
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">temp_digits</span><span class="plain">);</span>
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">temp_digits</span><span class="plain">, </span><span class="string">"%d"</span><span class="plain">, </span><span class="identifier">v</span><span class="plain">);</span>
<span class="functiontext"><a href="#SP5">Placeholders::set_to</a></span><span class="plain">(</span><span class="identifier">var</span><span class="plain">, </span><span class="identifier">temp_digits</span><span class="plain">, </span><span class="constant">0</span><span class="plain">);</span>
<span class="identifier">DISCARD_TEXT</span><span class="plain">(</span><span class="identifier">temp_digits</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>And here we set a given placeholder to a given text value. If it doesn't
already exist, it will be created. A reserved placeholder can then never again
be set, and since it will have been set at creation time (above), it follows
that a reserved placeholder cannot be set with the <code class="display"><span class="extract">placeholder</span></code> command of a
blurb file.
</p>
<pre class="display">
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Placeholders::set_to<button class="popup" onclick="togglePopup('usagePopup86')">...<span class="popuptext" id="usagePopup86">Usage of <b>Placeholders::set_to</b>:<br><a href="#SP2">&#167;2</a>, <a href="#SP4">&#167;4</a>, Main - <a href="1-mn.html#SP4">&#167;4</a>, <a href="1-mn.html#SP6_1">&#167;6.1</a><br>Blurb Parser - <a href="1-bp.html#SP7_2">&#167;7.2</a>, <a href="1-bp.html#SP7_2_1">&#167;7.2.1</a>, <a href="1-bp.html#SP7_2_2">&#167;7.2.2</a><br>Releaser - <a href="3-rls.html#SP6_7">&#167;6.7</a>, <a href="3-rls.html#SP6_8">&#167;6.8</a>, <a href="3-rls.html#SP6_9">&#167;6.9</a>, <a href="3-rls.html#SP9_1">&#167;9.1</a></span></button></span><span class="plain">(</span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">var</span><span class="plain">, </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">text</span><span class="plain">, </span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">reservation</span><span class="plain">) {</span>
<span class="functiontext"><a href="#SP6">Placeholders::set_to_inner</a></span><span class="plain">(</span><span class="identifier">var</span><span class="plain">, </span><span class="identifier">text</span><span class="plain">, </span><span class="identifier">reservation</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Placeholders::append_to<button class="popup" onclick="togglePopup('usagePopup87')">...<span class="popuptext" id="usagePopup87">Usage of <b>Placeholders::append_to</b>:<br>Blorb Errors - <a href="1-be.html#SP4">&#167;4</a><br>Releaser - <a href="3-rls.html#SP8_2">&#167;8.2</a>, <a href="3-rls.html#SP12">&#167;12</a>, <a href="3-rls.html#SP12_1">&#167;12.1</a>, <a href="3-rls.html#SP12_2">&#167;12.2</a>, <a href="3-rls.html#SP12_3">&#167;12.3</a>, <a href="3-rls.html#SP12_4">&#167;12.4</a>, <a href="3-rls.html#SP12_5">&#167;12.5</a>, <a href="3-rls.html#SP12_6">&#167;12.6</a>, <a href="3-rls.html#SP12_7">&#167;12.7</a>, <a href="3-rls.html#SP12_8">&#167;12.8</a>, <a href="3-rls.html#SP12_9">&#167;12.9</a>, <a href="3-rls.html#SP12_10">&#167;12.10</a></span></button></span><span class="plain">(</span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">var</span><span class="plain">, </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">text</span><span class="plain">) {</span>
<span class="functiontext"><a href="#SP6">Placeholders::set_to_inner</a></span><span class="plain">(</span><span class="identifier">var</span><span class="plain">, </span><span class="identifier">text</span><span class="plain">, </span><span class="constant">0</span><span class="plain">, </span><span class="constant">TRUE</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>Where:
</p>
<pre class="display">
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Placeholders::set_to_inner<button class="popup" onclick="togglePopup('usagePopup88')">...<span class="popuptext" id="usagePopup88">Usage of <b>Placeholders::set_to_inner</b>:<br><a href="#SP5">&#167;5</a></span></button></span><span class="plain">(</span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">var</span><span class="plain">, </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">text</span><span class="plain">, </span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">reservation</span><span class="plain">, </span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">extend</span><span class="plain">) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">verbose_mode</span><span class="plain">) </span><span class="identifier">PRINT</span><span class="plain">(</span><span class="string">"! [%S] &lt;-- \"%S\"\n"</span><span class="plain">, </span><span class="identifier">var</span><span class="plain">, </span><span class="identifier">text</span><span class="plain">);</span>
<span class="reserved">placeholder</span><span class="plain"> *</span><span class="identifier">wv</span><span class="plain"> = </span><span class="functiontext"><a href="#SP3">Placeholders::find</a></span><span class="plain">(</span><span class="identifier">var</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">wv</span><span class="plain">) &amp;&amp; (</span><span class="identifier">reservation</span><span class="plain"> &gt; </span><span class="constant">0</span><span class="plain">)) { </span><span class="functiontext"><a href="1-be.html#SP3">BlorbErrors::error_1S</a></span><span class="plain">(</span><span class="string">"tried to set reserved variable %S"</span><span class="plain">, </span><span class="identifier">var</span><span class="plain">); </span><span class="reserved">return</span><span class="plain">; }</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">wv</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) {</span>
<span class="identifier">wv</span><span class="plain"> = </span><span class="identifier">CREATE</span><span class="plain">(</span><span class="reserved">placeholder</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">verbose_mode</span><span class="plain">) </span><span class="identifier">PRINT</span><span class="plain">(</span><span class="string">"! Creating [%S]\n"</span><span class="plain">, </span><span class="identifier">var</span><span class="plain">);</span>
<span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">pl_name</span><span class="plain"> = </span><span class="functiontext"><a href="4-sm.html#SP3">Str::duplicate</a></span><span class="plain">(</span><span class="identifier">var</span><span class="plain">);</span>
<span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">pl_contents</span><span class="plain"> = </span><span class="functiontext"><a href="4-sm.html#SP2">Str::new</a></span><span class="plain">();</span>
<span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">reservation</span><span class="plain"> = </span><span class="identifier">reservation</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">extend</span><span class="plain">) </span><span class="functiontext"><a href="4-sm.html#SP16">Str::concatenate</a></span><span class="plain">(</span><span class="identifier">wv</span><span class="plain">-&gt;</span><span class="identifier">pl_contents</span><span class="plain">, </span><span class="identifier">text</span><span class="plain">);</span>
<span class="reserved">else</span><span class="plain"> </span><span class="functiontext"><a href="4-sm.html#SP16">Str::copy</a></span><span class="plain">(</span><span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">pl_contents</span><span class="plain">, </span><span class="identifier">text</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b>And that just leaves writing the output of these placeholders. The scenario
here is that we're copying HTML over to make a new web page, but we've hit
text in the template like "[AUTHOR]". We output the value of this
placeholder instead of that literal text. The reserved placeholders output as
special gadgets instead of any fixed text, so those all call suitable
routines elsewhere in Inblorb.
</p>
<p class="inwebparagraph">If the placeholder name isn't known to us, we print the text back, so that the
original material will be unchanged. (This is in case the original contains
uses of square brackets which aren't for placeholding.)
</p>
<pre class="display">
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">escape_quotes_mode</span><span class="plain"> = </span><span class="constant">0</span><span class="plain">;</span>
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Placeholders::write<button class="popup" onclick="togglePopup('usagePopup89')">...<span class="popuptext" id="usagePopup89">Usage of <b>Placeholders::write</b>:<br><a href="#SP7_1">&#167;7.1</a>, Solution Deviser - <a href="3-sd.html#SP12">&#167;12</a><br>Website Maker - <a href="3-wm.html#SP10">&#167;10</a></span></button></span><span class="plain">(</span><span class="constant">OUTPUT_STREAM</span><span class="plain">, </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">var</span><span class="plain">) {</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">multiparagraph_mode</span><span class="plain"> = </span><span class="constant">FALSE</span><span class="plain">, </span><span class="identifier">eqm</span><span class="plain"> = </span><span class="identifier">escape_quotes_mode</span><span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext"><a href="4-sm.html#SP13">Str::get_first_char</a></span><span class="plain">(</span><span class="identifier">var</span><span class="plain">) == </span><span class="character">'*'</span><span class="plain">) { </span><span class="functiontext"><a href="4-sm.html#SP24">Str::delete_first_character</a></span><span class="plain">(</span><span class="identifier">var</span><span class="plain">); </span><span class="identifier">escape_quotes_mode</span><span class="plain"> = </span><span class="constant">1</span><span class="plain">; }</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext"><a href="4-sm.html#SP13">Str::get_first_char</a></span><span class="plain">(</span><span class="identifier">var</span><span class="plain">) == </span><span class="character">'*'</span><span class="plain">) { </span><span class="functiontext"><a href="4-sm.html#SP24">Str::delete_first_character</a></span><span class="plain">(</span><span class="identifier">var</span><span class="plain">); </span><span class="identifier">escape_quotes_mode</span><span class="plain"> = </span><span class="constant">2</span><span class="plain">; }</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext"><a href="4-sm.html#SP18">Str::eq</a></span><span class="plain">(</span><span class="identifier">var</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"BLURB"</span><span class="plain">)) </span><span class="identifier">multiparagraph_mode</span><span class="plain"> = </span><span class="constant">TRUE</span><span class="plain">;</span>
<span class="reserved">placeholder</span><span class="plain"> *</span><span class="identifier">wv</span><span class="plain"> = </span><span class="functiontext"><a href="#SP3">Placeholders::find</a></span><span class="plain">(</span><span class="identifier">var</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">wv</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) || (</span><span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">locked</span><span class="plain">)) {</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"[%S]"</span><span class="plain">, </span><span class="identifier">var</span><span class="plain">);</span>
<span class="plain">} </span><span class="reserved">else</span><span class="plain"> {</span>
<span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">locked</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">multiparagraph_mode</span><span class="plain">) </span><span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"&lt;p&gt;"</span><span class="plain">);</span>
<span class="reserved">switch</span><span class="plain"> (</span><span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">reservation</span><span class="plain">) {</span>
<span class="reserved">case</span><span class="plain"> </span><span class="constant">0</span><span class="plain">: </span>&lt;<span class="cwebmacro">Copy an ordinary unreserved placeholder</span> <span class="cwebmacronumber">7.1</span>&gt;<span class="plain">; </span><span class="reserved">break</span><span class="plain">;</span>
<span class="reserved">case</span><span class="plain"> </span><span class="identifier">SOURCE_RPL:</span><span class="plain"> </span><span class="functiontext"><a href="3-wm.html#SP20">Websites::expand_SOURCE_or_SOURCENOTES_variable</a></span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">); </span><span class="reserved">break</span><span class="plain">;</span>
<span class="reserved">case</span><span class="plain"> </span><span class="identifier">SOURCENOTES_RPL:</span><span class="plain"> </span><span class="functiontext"><a href="3-wm.html#SP20">Websites::expand_SOURCE_or_SOURCENOTES_variable</a></span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="constant">TRUE</span><span class="plain">); </span><span class="reserved">break</span><span class="plain">;</span>
<span class="reserved">case</span><span class="plain"> </span><span class="identifier">SOURCELINKS_RPL:</span><span class="plain"> </span><span class="functiontext"><a href="3-wm.html#SP18">Websites::expand_SOURCELINKS_variable</a></span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">); </span><span class="reserved">break</span><span class="plain">;</span>
<span class="reserved">case</span><span class="plain"> </span><span class="identifier">COVER_RPL:</span><span class="plain"> </span><span class="functiontext"><a href="3-laaf.html#SP7">Links::expand_COVER_variable</a></span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">); </span><span class="reserved">break</span><span class="plain">;</span>
<span class="reserved">case</span><span class="plain"> </span><span class="identifier">DOWNLOAD_RPL:</span><span class="plain"> </span><span class="functiontext"><a href="3-laaf.html#SP5">Links::expand_DOWNLOAD_variable</a></span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">); </span><span class="reserved">break</span><span class="plain">;</span>
<span class="reserved">case</span><span class="plain"> </span><span class="identifier">AUXILIARY_RPL:</span><span class="plain"> </span><span class="functiontext"><a href="3-laaf.html#SP4">Links::expand_AUXILIARY_variable</a></span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">); </span><span class="reserved">break</span><span class="plain">;</span>
<span class="reserved">case</span><span class="plain"> </span><span class="identifier">PAGENUMBER_RPL:</span><span class="plain"> </span><span class="functiontext"><a href="3-wm.html#SP16">Websites::expand_PAGENUMBER_variable</a></span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">); </span><span class="reserved">break</span><span class="plain">;</span>
<span class="reserved">case</span><span class="plain"> </span><span class="identifier">PAGEEXTENT_RPL:</span><span class="plain"> </span><span class="functiontext"><a href="3-wm.html#SP17">Websites::expand_PAGEEXTENT_variable</a></span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">); </span><span class="reserved">break</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">multiparagraph_mode</span><span class="plain">) </span><span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"&lt;/p&gt;"</span><span class="plain">);</span>
<span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">locked</span><span class="plain"> = </span><span class="constant">FALSE</span><span class="plain">;</span>
<span class="identifier">escape_quotes_mode</span><span class="plain"> = </span><span class="identifier">eqm</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP7_1"></a><b>&#167;7.1. </b>Note that the [BLURB] placeholder &mdash; which holds the story description, and is
like a back cover blurb for a book; the name is not related to the release
instructions format &mdash; may consist of multiple paragraphs. If so, then they
will be divided by <code class="display"><span class="extract">&lt;br/&gt;</span></code>, since that's the XML convention. But we want to
translate those breaks to <code class="display"><span class="extract">&lt;/p&gt;&lt;p&gt;</span></code>, closing an old paragraph and opening
a new one, because that will make the blurb text much easier to style
with a CSS file. It follows that [BLURB] should always appear in templates
within an HTML paragraph.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Copy an ordinary unreserved placeholder</span> <span class="cwebmacronumber">7.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">L</span><span class="plain"> = </span><span class="functiontext"><a href="4-sm.html#SP8">Str::len</a></span><span class="plain">(</span><span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">pl_contents</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">L</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">c</span><span class="plain"> = </span><span class="functiontext"><a href="4-sm.html#SP13">Str::get_at</a></span><span class="plain">(</span><span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">pl_contents</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">c</span><span class="plain"> == </span><span class="character">'&lt;'</span><span class="plain">) &amp;&amp;</span>
<span class="plain">(</span><span class="functiontext"><a href="4-sm.html#SP13">Str::get_at</a></span><span class="plain">(</span><span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">pl_contents</span><span class="plain">, </span><span class="identifier">i</span><span class="plain">+1) == </span><span class="character">'b'</span><span class="plain">) &amp;&amp;</span>
<span class="plain">(</span><span class="functiontext"><a href="4-sm.html#SP13">Str::get_at</a></span><span class="plain">(</span><span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">pl_contents</span><span class="plain">, </span><span class="identifier">i</span><span class="plain">+2) == </span><span class="character">'r'</span><span class="plain">) &amp;&amp;</span>
<span class="plain">(</span><span class="functiontext"><a href="4-sm.html#SP13">Str::get_at</a></span><span class="plain">(</span><span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">pl_contents</span><span class="plain">, </span><span class="identifier">i</span><span class="plain">+3) == </span><span class="character">'/'</span><span class="plain">) &amp;&amp;</span>
<span class="plain">(</span><span class="functiontext"><a href="4-sm.html#SP13">Str::get_at</a></span><span class="plain">(</span><span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">pl_contents</span><span class="plain">, </span><span class="identifier">i</span><span class="plain">+4) == </span><span class="character">'&gt;'</span><span class="plain">) &amp;&amp; (</span><span class="identifier">multiparagraph_mode</span><span class="plain">)) {</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"&lt;/p&gt;&lt;p&gt;"</span><span class="plain">); </span><span class="identifier">i</span><span class="plain"> += </span><span class="constant">4</span><span class="plain">; </span><span class="reserved">continue</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="character">'['</span><span class="plain">) {</span>
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">inner_name</span><span class="plain">);</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">expanded</span><span class="plain"> = </span><span class="constant">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">j</span><span class="plain"> = </span><span class="identifier">i</span><span class="plain">+1; </span><span class="identifier">j</span><span class="plain">&lt;</span><span class="identifier">L</span><span class="plain">; </span><span class="identifier">j</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="functiontext"><a href="4-sm.html#SP13">Str::get_at</a></span><span class="plain">(</span><span class="identifier">wv</span><span class="plain">-&gt;</span><span class="element">pl_contents</span><span class="plain">, </span><span class="identifier">j</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="character">'['</span><span class="plain">) || (</span><span class="identifier">c</span><span class="plain"> == </span><span class="character">' '</span><span class="plain">)) </span><span class="reserved">break</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="character">']'</span><span class="plain">) {</span>
<span class="identifier">i</span><span class="plain"> = </span><span class="identifier">j</span><span class="plain">;</span>
<span class="functiontext"><a href="#SP7">Placeholders::write</a></span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">inner_name</span><span class="plain">);</span>
<span class="identifier">expanded</span><span class="plain"> = </span><span class="constant">TRUE</span><span class="plain">;</span>
<span class="reserved">break</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="identifier">PUT_TO</span><span class="plain">(</span><span class="identifier">inner_name</span><span class="plain">, </span><span class="identifier">c</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="identifier">DISCARD_TEXT</span><span class="plain">(</span><span class="identifier">inner_name</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">expanded</span><span class="plain">) </span><span class="reserved">continue</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="character">'\x0a'</span><span class="plain">) || (</span><span class="identifier">c</span><span class="plain"> == </span><span class="character">'\x0d'</span><span class="plain">) || (</span><span class="identifier">c</span><span class="plain"> == </span><span class="character">'\x7f'</span><span class="plain">)) &amp;&amp; (</span><span class="identifier">multiparagraph_mode</span><span class="plain">)) {</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"&lt;p&gt;"</span><span class="plain">); </span><span class="reserved">continue</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">escape_quotes_mode</span><span class="plain"> == </span><span class="constant">1</span><span class="plain">) &amp;&amp; (</span><span class="identifier">c</span><span class="plain"> == </span><span class="character">'\''</span><span class="plain">)) </span><span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"&amp;#39;"</span><span class="plain">);</span>
<span class="reserved">else</span><span class="plain"> </span><span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">escape_quotes_mode</span><span class="plain"> == </span><span class="constant">2</span><span class="plain">) &amp;&amp; (</span><span class="identifier">c</span><span class="plain"> == </span><span class="character">'\''</span><span class="plain">)) </span><span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"%%2527"</span><span class="plain">);</span>
<span class="reserved">else</span><span class="plain"> </span><span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"%c"</span><span class="plain">, </span><span class="identifier">c</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP7">&#167;7</a>.</p>
<hr class="tocbar">
<ul class="toc"><li><a href="3-laaf.html">Back to 'Links and Auxiliary Files'</a></li><li><a href="3-tmp.html">Continue with 'Templates'</a></li></ul><hr class="tocbar">
<!--End of weave-->
<script>
function togglePopup(material_id) {
var popup = document.getElementById(material_id);
popup.classList.toggle("show");
}
</script>
<link href="Popups.css" rel="stylesheet" rev="stylesheet" type="text/css">
</main>
</body>
</html>
Reference in a new issue View git blame Copy permalink