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-tmp.html
Graham Nelson ae621dd4d0 Catching up with Foundation function name changes
2020-04-15 23:49:59 +01:00

212 lines
23 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>Templates</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 'Templates' 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>Templates</b></li></ul><p class="purpose">To manage templates for website generation.</p>
<ul class="toc"><li><a href="3-tmp.html#SP1">&#167;1. Templates and their paths</a></li><li><a href="3-tmp.html#SP3">&#167;3. Defining template paths</a></li><li><a href="3-tmp.html#SP6">&#167;6. Searching for template files</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Templates and their paths. </b>Template paths define, in order of priority, where to look for templates.
</p>
<pre class="display">
<span class="reserved">typedef</span><span class="plain"> </span><span class="reserved">struct</span><span class="plain"> </span><span class="reserved">template_path</span><span class="plain"> {</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">pathname</span><span class="plain"> *</span><span class="identifier">template_repository</span><span class="plain">; </span><span class="comment"> pathname of folder of repository</span>
<span class="constant">MEMORY_MANAGEMENT</span>
<span class="plain">} </span><span class="reserved">template_path</span><span class="plain">;</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The structure template_path is private to this section.</p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>Whereas templates are the things themselves.
</p>
<pre class="display">
<span class="reserved">typedef</span><span class="plain"> </span><span class="reserved">struct</span><span class="plain"> </span><span class="reserved">template</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">template_name</span><span class="plain">; </span><span class="comment"> e.g., "Standard"</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">template_path</span><span class="plain"> *</span><span class="identifier">template_location</span><span class="plain">;</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">filename</span><span class="plain"> *</span><span class="identifier">latest_use</span><span class="plain">; </span><span class="comment"> filename most recently sought from it</span>
<span class="constant">MEMORY_MANAGEMENT</span>
<span class="plain">} </span><span class="reserved">template</span><span class="plain">;</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The structure template is private to this section.</p>
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. Defining template paths. </b>The following implements the Blurb command "template path".
</p>
<pre class="display">
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">no_template_paths</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">Templates::new_path<button class="popup" onclick="togglePopup('usagePopup90')">...<span class="popuptext" id="usagePopup90">Usage of <b>Templates::new_path</b>:<br>Blurb Parser - <a href="1-bp.html#SP7_2">&#167;7.2</a></span></button></span><span class="plain">(</span><span class="reserved">pathname</span><span class="plain"> *</span><span class="identifier">P</span><span class="plain">) {</span>
<span class="reserved">template_path</span><span class="plain"> *</span><span class="identifier">tp</span><span class="plain"> = </span><span class="identifier">CREATE</span><span class="plain">(</span><span class="reserved">template_path</span><span class="plain">);</span>
<span class="identifier">tp</span><span class="plain">-&gt;</span><span class="element">template_repository</span><span class="plain"> = </span><span class="identifier">P</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">"! Template search path %d: &lt;%p&gt;\n"</span><span class="plain">, ++</span><span class="identifier">no_template_paths</span><span class="plain">, </span><span class="identifier">P</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>The following searches for a named file in a named template, returning
the template path which holds the template if it exists. This might look a
pretty odd thing to do &mdash; weren't we looking for the file itself? But the
answer is that <code class="display"><span class="extract">Templates::seek_file</span></code> is really used to detect
the presence of templates, not of files.
</p>
<pre class="display">
<span class="reserved">template_path</span><span class="plain"> *</span><span class="functiontext">Templates::seek_file<button class="popup" onclick="togglePopup('usagePopup91')">...<span class="popuptext" id="usagePopup91">Usage of <b>Templates::seek_file</b>:<br><a href="3-tmp.html#SP5">&#167;5</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">text_stream</span><span class="plain"> *</span><span class="identifier">leafname</span><span class="plain">) {</span>
<span class="reserved">template_path</span><span class="plain"> *</span><span class="identifier">tp</span><span class="plain">;</span>
<span class="identifier">LOOP_OVER</span><span class="plain">(</span><span class="identifier">tp</span><span class="plain">, </span><span class="reserved">template_path</span><span class="plain">) {</span>
<span class="reserved">pathname</span><span class="plain"> *</span><span class="identifier">T</span><span class="plain"> = </span><span class="functiontext"><a href="../../../inweb/docs/foundation-module/3-pth.html#SP4">Pathnames::down</a></span><span class="plain">(</span><span class="identifier">tp</span><span class="plain">-&gt;</span><span class="element">template_repository</span><span class="plain">, </span><span class="identifier">name</span><span class="plain">);</span>
<span class="reserved">filename</span><span class="plain"> *</span><span class="identifier">possible</span><span class="plain"> = </span><span class="functiontext"><a href="../../../inweb/docs/foundation-module/3-fln.html#SP2">Filenames::in</a></span><span class="plain">(</span><span class="identifier">T</span><span class="plain">, </span><span class="identifier">leafname</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext"><a href="../../../inweb/docs/foundation-module/4-tf.html#SP1">TextFiles::exists</a></span><span class="plain">(</span><span class="identifier">possible</span><span class="plain">)) </span><span class="reserved">return</span><span class="plain"> </span><span class="identifier">tp</span><span class="plain">;</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="SP5"></a><b>&#167;5. </b>And this is where that happens. Suppose we need to locate the template
"Molybdenum". We ought to do this by looking for a directory of that name
among the template paths, but searching for directories is a little tricky
to do in ANSI C in a way which will work on all platforms. So instead we
look for any of the four files which compulsorily ought to exist (or the
one which does in the case of an interpreter; those look rather like
website templates).
</p>
<pre class="display">
<span class="reserved">template</span><span class="plain"> *</span><span class="functiontext">Templates::find_file<button class="popup" onclick="togglePopup('usagePopup92')">...<span class="popuptext" id="usagePopup92">Usage of <b>Templates::find_file</b>:<br><a href="3-tmp.html#SP6">&#167;6</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">template</span><span class="plain"> *</span><span class="identifier">t</span><span class="plain">;</span>
&lt;<span class="cwebmacro">Is this a template we already know?</span> <span class="cwebmacronumber">5.1</span>&gt;<span class="plain">;</span>
<span class="reserved">template_path</span><span class="plain"> *</span><span class="identifier">tp</span><span class="plain"> = </span><span class="functiontext"><a href="3-tmp.html#SP4">Templates::seek_file</a></span><span class="plain">(</span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"index.html"</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">tp</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) </span><span class="identifier">tp</span><span class="plain"> = </span><span class="functiontext"><a href="3-tmp.html#SP4">Templates::seek_file</a></span><span class="plain">(</span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"source.html"</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">tp</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) </span><span class="identifier">tp</span><span class="plain"> = </span><span class="functiontext"><a href="3-tmp.html#SP4">Templates::seek_file</a></span><span class="plain">(</span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"style.css"</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">tp</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) </span><span class="identifier">tp</span><span class="plain"> = </span><span class="functiontext"><a href="3-tmp.html#SP4">Templates::seek_file</a></span><span class="plain">(</span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"(extras).txt"</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">tp</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) </span><span class="identifier">tp</span><span class="plain"> = </span><span class="functiontext"><a href="3-tmp.html#SP4">Templates::seek_file</a></span><span class="plain">(</span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"(manifest).txt"</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">tp</span><span class="plain">) {</span>
<span class="identifier">t</span><span class="plain"> = </span><span class="identifier">CREATE</span><span class="plain">(</span><span class="reserved">template</span><span class="plain">);</span>
<span class="identifier">t</span><span class="plain">-&gt;</span><span class="element">template_name</span><span class="plain"> = </span><span class="functiontext"><a href="../../../inweb/docs/foundation-module/4-sm.html#SP3">Str::duplicate</a></span><span class="plain">(</span><span class="identifier">name</span><span class="plain">);</span>
<span class="identifier">t</span><span class="plain">-&gt;</span><span class="element">template_location</span><span class="plain"> = </span><span class="identifier">tp</span><span class="plain">;</span>
<span class="reserved">return</span><span class="plain"> </span><span class="identifier">t</span><span class="plain">;</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="SP5_1"></a><b>&#167;5.1. </b>It reduces pointless file accesses to cache the results, so:
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Is this a template we already know?</span> <span class="cwebmacronumber">5.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">LOOP_OVER</span><span class="plain">(</span><span class="identifier">t</span><span class="plain">, </span><span class="reserved">template</span><span class="plain">)</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext"><a href="../../../inweb/docs/foundation-module/4-sm.html#SP18">Str::eq</a></span><span class="plain">(</span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">t</span><span class="plain">-&gt;</span><span class="element">template_name</span><span class="plain">))</span>
<span class="reserved">return</span><span class="plain"> </span><span class="identifier">t</span><span class="plain">;</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="3-tmp.html#SP5">&#167;5</a>.</p>
<p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. Searching for template files. </b>If we can't find the file <code class="display"><span class="extract">name</span></code> in the template specified, we try looking
inside "Standard" instead (if we can find a template of that name).
</p>
<pre class="display">
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">template_doesnt_exist</span><span class="plain"> = </span><span class="constant">FALSE</span><span class="plain">;</span>
<span class="reserved">filename</span><span class="plain"> *</span><span class="functiontext">Templates::find_file_in_specific_template<button class="popup" onclick="togglePopup('usagePopup93')">...<span class="popuptext" id="usagePopup93">Usage of <b>Templates::find_file_in_specific_template</b>:<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#SP6_9_1">&#167;6.9.1</a>, <a href="3-rls.html#SP9">&#167;9</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">text_stream</span><span class="plain"> *</span><span class="identifier">needed</span><span class="plain">) {</span>
<span class="reserved">template</span><span class="plain"> *</span><span class="identifier">t</span><span class="plain"> = </span><span class="functiontext"><a href="3-tmp.html#SP5">Templates::find_file</a></span><span class="plain">(</span><span class="identifier">name</span><span class="plain">), *</span><span class="identifier">Standard</span><span class="plain"> = </span><span class="functiontext"><a href="3-tmp.html#SP5">Templates::find_file</a></span><span class="plain">(</span><span class="identifier">I</span><span class="string">"Standard"</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">t</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">template_doesnt_exist</span><span class="plain"> == </span><span class="constant">FALSE</span><span class="plain">) {</span>
<span class="functiontext"><a href="1-be.html#SP3">BlorbErrors::errorf_1S</a></span><span class="plain">(</span>
<span class="string">"Websites and play-in-browser interpreter web pages are created "</span>
<span class="string">"using named templates. (Basic examples are built into the Inform "</span>
<span class="string">"application. You can also create your own, putting them in the "</span>
<span class="string">"'Templates' subfolder of the project's Materials folder.) Each "</span>
<span class="string">"template has a name. On this Release, I tried to use the "</span>
<span class="string">"'%S' template, but couldn't find a copy of it anywhere."</span><span class="plain">, </span><span class="identifier">name</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="identifier">template_doesnt_exist</span><span class="plain"> = </span><span class="constant">TRUE</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">filename</span><span class="plain"> *</span><span class="identifier">path</span><span class="plain"> = </span><span class="functiontext"><a href="3-tmp.html#SP7">Templates::try_single</a></span><span class="plain">(</span><span class="identifier">t</span><span class="plain">, </span><span class="identifier">needed</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">path</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) &amp;&amp; (</span><span class="identifier">Standard</span><span class="plain">)) </span><span class="identifier">path</span><span class="plain"> = </span><span class="functiontext"><a href="3-tmp.html#SP7">Templates::try_single</a></span><span class="plain">(</span><span class="identifier">Standard</span><span class="plain">, </span><span class="identifier">needed</span><span class="plain">);</span>
<span class="reserved">return</span><span class="plain"> </span><span class="identifier">path</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>Where, finally:
</p>
<pre class="display">
<span class="reserved">filename</span><span class="plain"> *</span><span class="functiontext">Templates::try_single<button class="popup" onclick="togglePopup('usagePopup94')">...<span class="popuptext" id="usagePopup94">Usage of <b>Templates::try_single</b>:<br><a href="3-tmp.html#SP6">&#167;6</a></span></button></span><span class="plain">(</span><span class="reserved">template</span><span class="plain"> *</span><span class="identifier">t</span><span class="plain">, </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">needed</span><span class="plain">) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">t</span><span class="plain"> == </span><span class="identifier">NULL</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="reserved">pathname</span><span class="plain"> *</span><span class="identifier">T</span><span class="plain"> = </span><span class="functiontext"><a href="../../../inweb/docs/foundation-module/3-pth.html#SP4">Pathnames::down</a></span><span class="plain">(</span><span class="identifier">t</span><span class="plain">-&gt;</span><span class="identifier">template_location</span><span class="plain">-&gt;</span><span class="element">template_repository</span><span class="plain">, </span><span class="identifier">t</span><span class="plain">-&gt;</span><span class="element">template_name</span><span class="plain">);</span>
<span class="identifier">t</span><span class="plain">-&gt;</span><span class="element">latest_use</span><span class="plain"> = </span><span class="functiontext"><a href="../../../inweb/docs/foundation-module/3-fln.html#SP2">Filenames::in</a></span><span class="plain">(</span><span class="identifier">T</span><span class="plain">, </span><span class="identifier">needed</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">"! Trying &lt;%f&gt;\n"</span><span class="plain">, </span><span class="identifier">t</span><span class="plain">-&gt;</span><span class="element">latest_use</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext"><a href="../../../inweb/docs/foundation-module/4-tf.html#SP1">TextFiles::exists</a></span><span class="plain">(</span><span class="identifier">t</span><span class="plain">-&gt;</span><span class="element">latest_use</span><span class="plain">)) </span><span class="reserved">return</span><span class="plain"> </span><span class="identifier">t</span><span class="plain">-&gt;</span><span class="element">latest_use</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>
<hr class="tocbar">
<ul class="toc"><li><a href="3-plc.html">Back to 'Placeholders'</a></li><li><a href="3-wm.html">Continue with 'Website Maker'</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