1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-07-08 18:14:21 +03:00
inform7/docs/inter/M-ti.html
Graham Nelson 1268a0f40e Colonised
2020-04-14 17:56:54 +01:00

387 lines
24 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Textual Inter</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>Compiler Webs</h2><ul>
<li><a href="../inbuild/index.html">inbuild</a></li>
<li><a href="../inform7/index.html">inform7</a></li>
<li><a href="index.html"><span class="selectedlink">inter</span></a></li>
</ul><h2>Inbuild Modules</h2><ul>
<li><a href="../supervisor-module/index.html">supervisor</a></li>
</ul><h2>Inform7 Modules</h2><ul>
<li><a href="../core-module/index.html">core</a></li>
<li><a href="../inflections-module/index.html">inflections</a></li>
<li><a href="../linguistics-module/index.html">linguistics</a></li>
<li><a href="../kinds-module/index.html">kinds</a></li>
<li><a href="../if-module/index.html">if</a></li>
<li><a href="../multimedia-module/index.html">multimedia</a></li>
<li><a href="../problems-module/index.html">problems</a></li>
<li><a href="../index-module/index.html">index</a></li>
</ul><h2>Inter Modules</h2><ul>
<li><a href="../bytecode-module/index.html">bytecode</a></li>
<li><a href="../building-module/index.html">building</a></li>
<li><a href="../codegen-module/index.html">codegen</a></li>
</ul><h2>Shared Modules</h2><ul>
<li><a href="../arch-module/index.html">arch</a></li>
<li><a href="../syntax-module/index.html">syntax</a></li>
<li><a href="../words-module/index.html">words</a></li>
<li><a href="../html-module/index.html">html</a></li>
<li><a href="../../../inweb/docs/foundation-module/index.html">foundation</a></li>
</ul>
</nav>
<main role="main">
<!--Weave of 'Textual Inter' generated by 7-->
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../compiler.html">Compiler Tools</a></li><li><a href="index.html">inter</a></li><li><a href="index.html#M">Manual</a></li><li><b>Textual Inter</b></li></ul><p class="purpose">A specification of the inter language, as written out in text file form.</p>
<ul class="toc"><li><a href="#SP1">&#167;1. Textual, Binary, Memory</a></li><li><a href="#SP2">&#167;2. Global statements</a></li><li><a href="#SP7">&#167;7. Package declarations</a></li><li><a href="#SP11">&#167;11. Symbol annotations</a></li><li><a href="#SP12">&#167;12. Splats</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Textual, Binary, Memory. </b>Inter code has three representations: as a binary file, as a textual file,
and in memory &mdash; a sort of cross-referenced form of binary. For speed, the
Inform compiler generates memory inter directly, and code-generates from
that, so that the inter is normally never written out to disc. When Inter
performs a conversion, it loads (say) textual inter into memory inter, then
writes that out as binary inter.
</p>
<p class="inwebparagraph">The following specification covers the inter language in its textual form:
a UTF-8 encoded text file which conventionally takes the file extension
".intert".
</p>
<p class="inwebparagraph">It should be stressed that inter is designed for inspection &mdash; that is, for
people to be able to read. It's not intended as a programming language for
humans to write: the code is verbose and low-level. The idea is that inter
code will be written by programs (such as Inform), but that this code will
be possible for humans to check.
</p>
<p class="inwebparagraph">Like assembly language, inter code is line-based: each line is a "statement".
Lines can be of arbitrary length. A line beginning with a <code class="display"><span class="extract">#</span></code> (in column 1) is
a comment, and blank lines are ignored.
</p>
<p class="inwebparagraph">The term "name" below means a string of one or more English upper or lower
case letters, underscores, or digits, except that it must not begin with
a digit.
</p>
<p class="inwebparagraph">As in Python, indentation from the left margin is highly significant, and
should be in the form of tab characters.
</p>
<p class="inwebparagraph">Inform follows certain conventions in the inter that it writes, but these
conventions are not part of the specification, and may change. Any paragraph
below which begins with "Convention" records the current practice.
</p>
<p class="inwebparagraph">There are three forms of statement: global statements, data statements, and
code statements. We will take these in turn.
</p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. Global statements. </b>These statements must appear first in the file, and must be unindented.
There are only four of these:
</p>
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b><code class="display"><span class="extract">version NUMBER</span></code> indicates that the file was written in that version of
the inter language. At present there has only ever been one version, but
that may not always be true. A <code class="display"><span class="extract">version</span></code> statement number must come before
anything else, even other global statements; in particular, there cannot be
two such statements in the same file.
</p>
<p class="inwebparagraph">Convention. Inform always opens with the statement: <code class="display"><span class="extract">version 1</span></code>
</p>
<p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b><code class="display"><span class="extract">packagetype NAME</span></code> declares that <code class="display"><span class="extract">NAME</span></code> is the name of a type of package.
Packages are the main hierarchical organisation for inter files, as we
will see below. Each package has a type as well as a name, and the type
must be one of those declared like this.
</p>
<p class="inwebparagraph">For example, <code class="display"><span class="extract">packagetype _adjective</span></code> creates <code class="display"><span class="extract">_adjective</span></code> as a possible type
for packages in this file.
</p>
<p class="inwebparagraph">The first two package types must be <code class="display"><span class="extract">_plain</span></code> and <code class="display"><span class="extract">_code</span></code>, in that order.
</p>
<p class="inwebparagraph">Convention. All of Inform's package type names begin similarly with an
underscore, to prevent name clashes. Inform uses package types semantically,
to show what kind of thing is being defined in the content of a particular
package. This makes it easier to search a large inter repository for all of
the adjective defimitions, for example: we just need to look for packages of
type <code class="display"><span class="extract">_adjective</span></code>.
</p>
<p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b><code class="display"><span class="extract">pragma TARGET "WHATEVER"</span></code> does not change the meaning of the inter file;
it simply provides pragmatic advice to the eventual compiler of code
generated from this file. <code class="display"><span class="extract">TARGET</span></code> indicates the context for which this
is intended; at present, the only possible choice is <code class="display"><span class="extract">target_I6</span></code>, meaning,
"if you are compiling me to Inform 6".
</p>
<p class="inwebparagraph">Convention. Inform uses this to pass on ICL (Inform Command Language)
commands to Inform 6, such as memory settings or command-line switches.
For example,
</p>
<pre class="display">
<span class="reserved">pragma</span><span class="plain"> target_I6 </span><span class="string">"$MAX_LABELS=200000"</span>
</pre>
<p class="inwebparagraph">(This would be meaningless if we were compiling to some other format.)
</p>
<p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b><code class="display"><span class="extract">primitive PRIMITIVE IN -&gt; OUT</span></code> defines a new code statement &mdash; if inter
were an assembly language, these would be the opcodes. For example,
</p>
<pre class="display">
<span class="reserved">primitive</span><span class="plain"> </span><span class="functiontext">!move</span><span class="plain"> </span><span class="reserved">val</span><span class="plain"> </span><span class="reserved">val</span><span class="plain"> -&gt; </span><span class="reserved">void</span>
</pre>
<p class="inwebparagraph">defines the primitive <code class="display"><span class="extract">!move</span></code> as something which consumes two values and
produces none. (Further details on this will appear in the section on code
packages.)
</p>
<p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. Package declarations. </b>After the global area, an inter file should declare a package called <code class="display"><span class="extract">main</span></code>,
which must have the package type <code class="display"><span class="extract">_plain</span></code>.
</p>
<p class="inwebparagraph">The statement <code class="display"><span class="extract">package NAME TYPE</span></code> declares a new package, and the <code class="display"><span class="extract">TYPE</span></code>
must be one of those declared by <code class="display"><span class="extract">packagetype</span></code> statements in the global area.
</p>
<p class="inwebparagraph">The declaration line for a package begins at the level of indentation of
the package's owner. For <code class="display"><span class="extract">main</span></code>, it should be unindented, and this is the
only package allowed to appear at the top level: all other packages should
be inside <code class="display"><span class="extract">main</span></code> in some way.
</p>
<p class="inwebparagraph">The contents of the package are then one tab stop in from the declaration. Thus:
</p>
<pre class="display">
<span class="reserved">package</span><span class="plain"> main _plain</span>
<span class="plain">...</span>
<span class="reserved">package</span><span class="plain"> m1_RBLK1 _code</span>
<span class="plain">...</span>
<span class="reserved">package</span><span class="plain"> m1_RBLK2 _code</span>
<span class="plain">...</span>
</pre>
<p class="inwebparagraph">Here, <code class="display"><span class="extract">main</span></code> contains two sub-packages, <code class="display"><span class="extract">m1_RBLK1</span></code> and <code class="display"><span class="extract">m1_RBLK2</span></code>, and
indentation is used to show which package a statement belongs to.
</p>
<p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>After the declaration line, a package definition continues with a set
of symbols definitions. In effect, this is the symbols table for the
package written out explicitly. Each definition is a <code class="display"><span class="extract">symbol</span></code> line, in
one of these three forms:
</p>
<pre class="display">
<span class="reserved">symbol</span><span class="plain"> </span><span class="reserved">private</span><span class="plain"> TYPE NAME</span>
<span class="reserved">symbol</span><span class="plain"> </span><span class="reserved">public</span><span class="plain"> TYPE NAME</span>
<span class="reserved">symbol</span><span class="plain"> </span><span class="reserved">external</span><span class="plain"> TYPE NAME </span><span class="reserved">--&gt;</span><span class="plain"> SYMBOL</span>
</pre>
<p class="inwebparagraph">For example,
</p>
<pre class="display">
<span class="reserved">symbol</span><span class="plain"> </span><span class="reserved">public</span><span class="plain"> </span><span class="reserved">misc</span><span class="plain"> MEMORY_HEAP_SIZE</span>
<span class="reserved">symbol</span><span class="plain"> </span><span class="reserved">external</span><span class="plain"> </span><span class="reserved">misc</span><span class="plain"> AllowInShowme </span><span class="reserved">--&gt;</span><span class="plain"> /main/resources/template/AllowInShowme</span>
</pre>
<p class="inwebparagraph"><code class="display"><span class="extract">private</span></code> means that the meaning and existence of <code class="display"><span class="extract">NAME</span></code> are invisible
from outside the current package; <code class="display"><span class="extract">public</span></code> means that other packages are
allowed to refer to <code class="display"><span class="extract">NAME</span></code>; and <code class="display"><span class="extract">external</span></code> means that this package is
making just such a reference, and that <code class="display"><span class="extract">NAME</span></code> in this package is equivalent
to <code class="display"><span class="extract">SYMBOL</span></code>, defined elsewhere. It is possible that <code class="display"><span class="extract">SYMBOL</span></code> points only to
another symbol which is also <code class="display"><span class="extract">external</span></code>, so that we then have to follow
another link to find the original non-external definition. However, it is
a requirement that this process must eventually end. It would be illegal
to write
</p>
<pre class="display">
<span class="reserved">package</span><span class="plain"> main _plain</span>
<span class="reserved">package</span><span class="plain"> A _plain</span>
<span class="reserved">symbol</span><span class="plain"> </span><span class="reserved">external</span><span class="plain"> </span><span class="reserved">misc</span><span class="plain"> S </span><span class="reserved">--&gt;</span><span class="plain"> /main/B/T</span>
<span class="reserved">package</span><span class="plain"> B _plain</span>
<span class="reserved">symbol</span><span class="plain"> </span><span class="reserved">external</span><span class="plain"> </span><span class="reserved">misc</span><span class="plain"> T </span><span class="reserved">--&gt;</span><span class="plain"> /main/B/S</span>
</pre>
<p class="inwebparagraph">The symbol <code class="display"><span class="extract">TYPE</span></code> must be one of four possibilities:
</p>
<ul class="items"><li>(a) <code class="display"><span class="extract">label</span></code>, used to mark execution positions in code packages;
</li><li>(b) <code class="display"><span class="extract">package</span></code>, meaning that this is the name of a package;
</li><li>(c) <code class="display"><span class="extract">packagetype</span></code>, meaning that this is a package type;
</li><li>(d) <code class="display"><span class="extract">misc</span></code>, meaning "anything else" &mdash; most symbols have this type.
</li></ul>
<p class="inwebparagraph">The run of <code class="display"><span class="extract">symbol</span></code> declarations at the top of a module can become quite
long, since it has to give a complete description of all symbols used inside
the module, whether they're defined internally or externally. As a
convenience for people writing test cases by hand, it's in fact optional
to predeclare a symbol in textual inter provided that this symbol is
declared earlier in the file than its first use. However, when Inter
writes out a textual inter file, it always writes the symbols table out
in full, and never exercises this option.
</p>
<p class="inwebparagraph">Convention. A conspicuous feature of inter code generated by Inform is that
many symbols have the form <code class="display"><span class="extract">P_Name</span></code>, where <code class="display"><span class="extract">P</span></code> is some prefix letter showing
what sort of thing is referred to: for example, symbols for kinds all begin
with the prefix <code class="display"><span class="extract">K</span></code> (<code class="display"><span class="extract">K_number</span></code>, <code class="display"><span class="extract">K_text</span></code>, and so on), while variables
begin with <code class="display"><span class="extract">V</span></code>, instances with <code class="display"><span class="extract">I</span></code>, properties with <code class="display"><span class="extract">P</span></code>, and so on. This
is all simply a convention used by Inform for clarity and to reduce the
risk of accidental name clashes; it is not required by inter.
</p>
<p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b>Where a local symbol is being equated with an external one, the <code class="display"><span class="extract">SYMBOL</span></code>
given is a sort of URL showing the package to look inside. Thus
</p>
<pre class="display">
<span class="plain">/main/resources/template/AllowInShowme</span>
</pre>
<p class="inwebparagraph">means "the symbol <code class="display"><span class="extract">AllowInShowme</span></code> in package <code class="display"><span class="extract">template</span></code> inside package
<code class="display"><span class="extract">resources</span></code> inside package <code class="display"><span class="extract">main</span></code>".
</p>
<p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. </b>Optionally, a <code class="display"><span class="extract">private</span></code> or <code class="display"><span class="extract">public</span></code> symbol can also specify a name it
wishes to be given when the Inter is translated into some other language
(i.e., Inform 6 or similar). This is written like so:
</p>
<pre class="display">
<span class="reserved">symbol</span><span class="plain"> </span><span class="reserved">private</span><span class="plain"> TYPE NAME </span><span class="element">`TRANSLATION</span><span class="plain">`</span>
</pre>
<p class="inwebparagraph">So, for example,
</p>
<pre class="display">
<span class="reserved">symbol</span><span class="plain"> </span><span class="reserved">public</span><span class="plain"> </span><span class="reserved">misc</span><span class="plain"> launcher </span><span class="element">`launcher_U32</span><span class="plain">`</span>
</pre>
<p class="inwebparagraph">Symbols tabulated as <code class="display"><span class="extract">external</span></code> cannot be marked in this way, but of course
the original definition (to which the external link eventually leads) can be.
For example,
</p>
<pre class="display">
<span class="reserved">package</span><span class="plain"> main _plain</span>
<span class="reserved">package</span><span class="plain"> A _plain</span>
<span class="reserved">symbol</span><span class="plain"> </span><span class="reserved">external</span><span class="plain"> </span><span class="reserved">misc</span><span class="plain"> S </span><span class="reserved">--&gt;</span><span class="plain"> /main/B/T</span>
<span class="reserved">package</span><span class="plain"> B _plain</span>
<span class="reserved">symbol</span><span class="plain"> </span><span class="reserved">public</span><span class="plain"> </span><span class="reserved">misc</span><span class="plain"> T </span><span class="element">`FancyName</span><span class="plain">`</span>
</pre>
<p class="inwebparagraph">would result in the names <code class="display"><span class="extract">S</span></code> and <code class="display"><span class="extract">T</span></code> both being compiled to the name
<code class="display"><span class="extract">FancyName</span></code> in the final code.
</p>
<p class="inwebparagraph">Convention. Inform mostly makes use of this feature of inter late in code
generation, essentially to avoid namespace clashes in the final output code,
but it also needs to use it to implement low-level features of the Inform
language such as:
</p>
<blockquote>
<p>The marked for listing property translates into I6 as "workflag".</p>
</blockquote>
<p class="inwebparagraph"><a id="SP11"></a><b>&#167;11. Symbol annotations. </b>A useful feature of inter is that short-term or inessential metadata can
be attached to symbols; inter is flexible abput what this data might mean.
These annotations can also be represented in text form, which is useful
for looking at the output from different code-generation stages.
</p>
<p class="inwebparagraph">Annotations are written on the line where the symbol is created, not where
it is declared in the symbols table. For example, here is a creation of
a symbol for a constant:
</p>
<pre class="display">
<span class="reserved">constant</span><span class="plain"> WORD_NEXTTOHIGHBIT </span><span class="identifier">K_typeless_int</span><span class="plain"> = </span><span class="constant">0</span><span class="plain">x4000</span>
</pre>
<p class="inwebparagraph">And here it is with an annotation:
</p>
<pre class="display">
<span class="reserved">constant</span><span class="plain"> WORD_NEXTTOHIGHBIT </span><span class="identifier">K_typeless_int</span><span class="plain"> = </span><span class="constant">0</span><span class="plain">x4000 </span><span class="identifier">__hex</span>
</pre>
<p class="inwebparagraph">The annotation, <code class="display"><span class="extract">__hex</span></code>, simply means that the natural way to print the
value of this constant would be hexadecimal; it doesn't change the meaning
of the program, and this is typical of annotations.
</p>
<p class="inwebparagraph">All annotations begin with a double underscore, and some can take a number
or text literal:
</p>
<pre class="display">
<span class="identifier">__binary</span>
<span class="identifier">__table_array</span><span class="plain">=1</span>
<span class="identifier">__name</span><span class="plain">=</span><span class="string">"matching key"</span>
</pre>
<p class="inwebparagraph">There is no built-in set of annotations, and their use does not need to be
predeclared anywhere: simply writing
</p>
<pre class="display">
<span class="reserved">constant</span><span class="plain"> MY_CONSTANT </span><span class="identifier">K_typeless_int</span><span class="plain"> = </span><span class="constant">27</span><span class="plain"> </span><span class="identifier">__plugh</span>
</pre>
<p class="inwebparagraph">would create the annotation <code class="display"><span class="extract">__plugh</span></code> as a possibility, if it didn't already
exist. However, Inform has a conventional set of annotations which it uses
for symbols with various meanings, and that set will be covered later.
</p>
<p class="inwebparagraph"><a id="SP12"></a><b>&#167;12. Splats. </b>The special statement <code class="display"><span class="extract">splat "TEXT"</span></code> or <code class="display"><span class="extract">splat ANNOTATION "TEXT"</span></code> allows
raw Inform 6 code (or potentially raw code for any language) to be included
verbatim in inter. Splat is not a respectful term, and nor does it deserve
one. The annotation can be any of: <code class="display"><span class="extract">IFDEF_PLM</span></code>, <code class="display"><span class="extract">IFNDEF_PLM</span></code>, <code class="display"><span class="extract">IFNOT_PLM</span></code>,
<code class="display"><span class="extract">ENDIF_PLM</span></code>, <code class="display"><span class="extract">IFTRUE_PLM</span></code>, <code class="display"><span class="extract">CONSTANT_PLM</span></code>, <code class="display"><span class="extract">ARRAY_PLM</span></code>, <code class="display"><span class="extract">GLOBAL_PLM</span></code>,
<code class="display"><span class="extract">STUB_PLM</span></code>, <code class="display"><span class="extract">ROUTINE_PLM</span></code>, <code class="display"><span class="extract">ATTRIBUTE_PLM</span></code>, <code class="display"><span class="extract">PROPERTY_PLM</span></code>, <code class="display"><span class="extract">VERB_PLM</span></code>,
<code class="display"><span class="extract">FAKEACTION_PLM</span></code>, <code class="display"><span class="extract">OBJECT_PLM</span></code>, <code class="display"><span class="extract">DEFAULT_PLM</span></code>, <code class="display"><span class="extract">MYSTERY_PLM</span></code>.
</p>
<p class="inwebparagraph">Convention. Inform creates no splats, except as needed to convert
Inform 6 template code into inter, in the code-generator.
</p>
<hr class="tocbar">
<ul class="toc"><li><a href="M-ui.html">Back to 'Using Inter'</a></li><li><a href="M-dpiti.html">Continue with 'Data Packages in Textual Inter'</a></li></ul><hr class="tocbar">
<!--End of weave-->
</main>
</body>
</html>