mirror of
https://github.com/ganelson/inform.git
synced 2024-07-05 08:34:22 +03:00
214 lines
16 KiB
HTML
214 lines
16 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Inform Annotations</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">
|
|
<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/Inform.png" height=72">
|
|
</a></h1>
|
|
<ul><li><a href="../index.html">home</a></li>
|
|
</ul><h2>Compiler</h2><ul>
|
|
<li><a href="../structure.html">structure</a></li>
|
|
<li><a href="../inbuildn.html">inbuild</a></li>
|
|
<li><a href="../inform7n.html">inform7</a></li>
|
|
<li><a href="../intern.html">inter</a></li>
|
|
<li><a href="../services.html">services</a></li>
|
|
<li><a href="../secrets.html">secrets</a></li>
|
|
</ul><h2>Other Tools</h2><ul>
|
|
<li><a href="../inblorbn.html">inblorb</a></li>
|
|
<li><a href="../indocn.html">indoc</a></li>
|
|
<li><a href="../inform6.html">inform6</a></li>
|
|
<li><a href="../inpolicyn.html">inpolicy</a></li>
|
|
<li><a href="../inrtpsn.html">inrtps</a></li>
|
|
</ul><h2>Resources</h2><ul>
|
|
<li><a href="../extensions.html">extensions</a></li>
|
|
<li><a href="../kits.html">kits</a></li>
|
|
</ul><h2>Repository</h2><ul>
|
|
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=18> github</a></li>
|
|
</ul><h2>Related Projects</h2><ul>
|
|
<li><a href="../../../inweb/index.html">inweb</a></li>
|
|
<li><a href="../../../intest/index.html">intest</a></li>
|
|
|
|
</ul>
|
|
</nav>
|
|
<main role="main">
|
|
<!--Weave of 'Inform Annotations' generated by Inweb-->
|
|
<div class="breadcrumbs">
|
|
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inter</a></li><li><a href="index.html#M">Manual</a></li><li><b>Inform Annotations</b></li></ul></div>
|
|
<p class="purpose">The standard set of symbol annotations used within Inform.</p>
|
|
|
|
<ul class="toc"><li><a href="M-ia.html#SP1">§1. Status</a></li><li><a href="M-ia.html#SP2">§2. Translation</a></li><li><a href="M-ia.html#SP3">§3. Append</a></li><li><a href="M-ia.html#SP4">§4. Assimilation markers</a></li><li><a href="M-ia.html#SP5">§5. Miscellaneous code-generation storage</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>§1. Status. </b>The Inter specification allows for any number of annotations to be used;
|
|
none are required. The ones listed below are those used in the Inform toolchain
|
|
at present.
|
|
</p>
|
|
|
|
<p class="commentary">As a general guideline, annotations are best used for temporary storage during
|
|
complex operations (optimisation, code generation, and so on), rather than for
|
|
information which changes the functionality of a program. But this is only a
|
|
guideline, and several of the cases below could be argued to break it.
|
|
</p>
|
|
|
|
<p class="commentary">What is certainly true is that we want to avoid annotations if there are better
|
|
ways to achieve the same thing. At one time there were over 30 in use, but the
|
|
figure is now below 10.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>§2. Translation. </b>The final code we generate is itself (probably) the source code of a program
|
|
in some other language — C, for example. That means that most of the symbols
|
|
in our Inter program will be "translated" into identifiers in that final
|
|
program. For example, the Inter declaration:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> BakersDozen = </span><span class="constant-syntax">13</span>
|
|
</pre>
|
|
<p class="commentary">might ultimately be compiled to:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> #</span><span class="identifier-syntax">define</span><span class="plain-syntax"> </span><span class="identifier-syntax">CON_019900_BKRSDZN</span><span class="plain-syntax"> </span><span class="constant-syntax">13</span>
|
|
</pre>
|
|
<p class="commentary">An exaggerated example, perhaps, but the point is that it's normally none of
|
|
our business what identifiers the final code-generator chooses to use.
|
|
</p>
|
|
|
|
<p class="commentary">However, we can override its choice like so:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> BakersDozen = </span><span class="constant-syntax">13</span><span class="plain-syntax"> </span><span class="identifier-syntax">__translation</span><span class="plain-syntax">=</span><span class="string-syntax">"BAKERS_DOZEN"</span>
|
|
</pre>
|
|
<p class="commentary">And now it would come out as:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> #</span><span class="identifier-syntax">define</span><span class="plain-syntax"> </span><span class="identifier-syntax">BAKERS_DOZEN</span><span class="plain-syntax"> </span><span class="constant-syntax">13</span>
|
|
</pre>
|
|
<p class="commentary">The <span class="extract"><span class="extract-syntax">__translation</span></span> annotation is sometimes added by the final code-generator
|
|
itself, to keep track of its translation decisions, but can also be added by
|
|
the Inform 7 front-end compiler. Ideally it wouldn't ever do so, but this is
|
|
the only sensible way to implement the low-level language feature:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="identifier-syntax">The</span><span class="plain-syntax"> </span><span class="identifier-syntax">tally</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">a</span><span class="plain-syntax"> </span><span class="identifier-syntax">number</span><span class="plain-syntax"> </span><span class="identifier-syntax">that</span><span class="plain-syntax"> </span><span class="identifier-syntax">varies</span><span class="plain-syntax">. </span><span class="identifier-syntax">The</span><span class="plain-syntax"> </span><span class="identifier-syntax">tally</span><span class="plain-syntax"> </span><span class="identifier-syntax">translates</span><span class="plain-syntax"> </span><span class="identifier-syntax">into</span><span class="plain-syntax"> </span><span class="identifier-syntax">Inter</span><span class="plain-syntax"> </span><span class="identifier-syntax">as</span><span class="plain-syntax"> </span><span class="string-syntax">"SHAZAM"</span><span class="plain-syntax">.</span>
|
|
</pre>
|
|
<p class="commentary">And this is in turn is a feature we can't simply abolish, or not without
|
|
inventing some similar bodge, because it's needed in order to reconcile the
|
|
natural-language names for certain standard properties (e.g., "lighted")
|
|
with their kit-source equivalents (e.g. <span class="extract"><span class="extract-syntax">lit</span></span>).
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>§3. Append. </b>Like the <span class="extract"><span class="extract-syntax">insert</span></span> instruction (see <a href="M-dpiti.html" class="internal">Data Packages in Textual Inter</a>), the
|
|
<span class="extract"><span class="extract-syntax">__append</span></span> annotation subverts Inter by writing some code in raw Inform 6
|
|
syntax. This can be added to any definition of an instance of an object type,
|
|
or to the type itself.
|
|
</p>
|
|
|
|
<p class="commentary">For example, the I7 source text:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="identifier-syntax">Include</span><span class="plain-syntax"> (- </span><span class="identifier-syntax">has</span><span class="plain-syntax"> </span><span class="identifier-syntax">door</span><span class="plain-syntax">, -) </span><span class="identifier-syntax">when</span><span class="plain-syntax"> </span><span class="identifier-syntax">defining</span><span class="plain-syntax"> </span><span class="identifier-syntax">a</span><span class="plain-syntax"> </span><span class="identifier-syntax">door</span><span class="plain-syntax">.</span>
|
|
</pre>
|
|
<p class="commentary">leads to:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">kind</span><span class="plain-syntax"> K4_door <= K1_thing </span><span class="identifier-syntax">__append</span><span class="plain-syntax">=</span><span class="string-syntax">" has door, "</span>
|
|
</pre>
|
|
<p class="commentary">Whereas to some extent <span class="extract"><span class="extract-syntax">insert</span></span> can work even if the target is not I6, the
|
|
<span class="extract"><span class="extract-syntax">__append</span></span> annotation ties the program to I6 only. At some point we may
|
|
simply abolish the "Include... when defining..." feature from I7, and then
|
|
we'll gladly remove <span class="extract"><span class="extract-syntax">__append</span></span>. Consider it deprecated already.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>§4. Assimilation markers. </b>Every symbol (other than a function name) whose definition was assimilated from
|
|
Inform 6-syntax code in the source of a kit is given the boolean annotation
|
|
<span class="extract"><span class="extract-syntax">__assimilated</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">In addition, if the definition is of a fake action or an object, the annotation
|
|
<span class="extract"><span class="extract-syntax">__fake_action</span></span> or <span class="extract"><span class="extract-syntax">__object</span></span> will be applied. For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="reserved-syntax">Constant</span><span class="plain-syntax"> </span><span class="identifier-syntax">Dozen</span><span class="plain-syntax"> = </span><span class="constant-syntax">12</span><span class="plain-syntax">;</span>
|
|
<span class="identifier-syntax">Fake_action</span><span class="plain-syntax"> </span><span class="identifier-syntax">PluralFound</span><span class="plain-syntax">;</span>
|
|
<span class="identifier-syntax">Object</span><span class="plain-syntax"> </span><span class="identifier-syntax">thedark</span><span class="plain-syntax"> </span><span class="string-syntax">"(darkness object)"</span><span class="plain-syntax">;</span>
|
|
</pre>
|
|
<p class="commentary">assimilates to:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">package</span><span class="plain-syntax"> Dozen_con _plain</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> Dozen = </span><span class="constant-syntax">12</span><span class="plain-syntax"> </span><span class="identifier-syntax">__assimilated</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">package</span><span class="plain-syntax"> ##PluralFound_con _plain</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> ##PluralFound = </span><span class="constant-syntax">0</span><span class="plain-syntax"> </span><span class="identifier-syntax">__assimilated</span><span class="plain-syntax"> </span><span class="identifier-syntax">__fake_action</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">package</span><span class="plain-syntax"> thedark_con _plain</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> thedark = </span><span class="constant-syntax">0</span><span class="plain-syntax"> </span><span class="identifier-syntax">__assimilated</span><span class="plain-syntax"> </span><span class="identifier-syntax">__object</span>
|
|
</pre>
|
|
<p class="commentary">See the Inter test case <span class="extract"><span class="extract-syntax">Assim</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">These three markers are applied only during assimilation, and thus only by Inter.
|
|
The main Inform 7 compiler never applies them.
|
|
</p>
|
|
|
|
<p class="commentary">It would be feasible to combine these three annotations into a single one, say
|
|
<span class="extract"><span class="extract-syntax">__assimilated_from="DIRECTIVE"</span></span>, marking everything with the I6 directive it
|
|
came from. But while that would be elegant it would cost storage and time.
|
|
Boolean annotations are cheaper, and <span class="extract"><span class="extract-syntax">__assimilated</span></span> occurs a lot.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>§5. Miscellaneous code-generation storage. </b>As noted above, the main use case intended for annotations is as a way for
|
|
optimisation or code-generation pipeline steps to attach notes to the tree.
|
|
These are of no significance once those steps are complete, and do not change
|
|
the meaning of the program.
|
|
</p>
|
|
|
|
<p class="commentary">They can also come or go without notice; they are not really part of the Inter
|
|
specification at all. But briefly, the current set used is:
|
|
</p>
|
|
|
|
<p class="commentary"><span class="extract"><span class="extract-syntax">__inner_property_name="NAME"</span></span> is used by <a href="../final-module/2-vo.html" class="internal">Vanilla Objects (in final)</a> to mark
|
|
which property name belongs to which two-word property array.
|
|
</p>
|
|
|
|
<p class="commentary"><span class="extract"><span class="extract-syntax">__object_kind_counter=NUMBER</span></span> is used by <a href="../pipeline-module/5-knd.html" class="internal">Kinds (in pipeline)</a> to number off
|
|
the kinds of object found in the program.
|
|
</p>
|
|
|
|
<p class="commentary"><span class="extract"><span class="extract-syntax">__array_address=NUMBER</span></span> is used by <a href="../final-module/5-cmm.html" class="internal">C Memory Model (in final)</a> to mark the
|
|
address in process memory of each array.
|
|
</p>
|
|
|
|
<p class="commentary"><span class="extract"><span class="extract-syntax">__global_offset=NUMBER</span></span> is used by <a href="../final-module/4-i6gv.html" class="internal">Inform 6 Global Variables (in final)</a> to
|
|
mark where in its array of global variables a given variable lives.
|
|
</p>
|
|
|
|
<nav role="progress"><div class="progresscontainer">
|
|
<ul class="progressbar"><li class="progressprev"><a href="M-ip.html">❮</a></li><li class="progresscurrentchapter">M</li><li class="progresssection"><a href="M-ui.html">ui</a></li><li class="progresssection"><a href="M-ti.html">ti</a></li><li class="progresssection"><a href="M-dpiti.html">dpiti</a></li><li class="progresssection"><a href="M-cpiti.html">cpiti</a></li><li class="progresssection"><a href="M-ip.html">ip</a></li><li class="progresscurrent">ia</li><li class="progresssection"><a href="M-io.html">io</a></li><li class="progresssection"><a href="M-pas.html">pas</a></li><li class="progresssection"><a href="M-rc.html">rc</a></li><li class="progresschapter"><a href="1-mn.html">1</a></li><li class="progressnext"><a href="M-io.html">❯</a></li></ul></div>
|
|
</nav><!--End of weave-->
|
|
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|