1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-07-08 10:04:21 +03:00
inform7/docs/inter/M-ti.html

388 lines
29 KiB
HTML
Raw Normal View History

2019-03-20 14:51:06 +02:00
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
2020-04-14 19:56:54 +03:00
<title>Textual Inter</title>
2020-05-03 03:20:55 +03:00
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
2020-03-19 02:11:25 +02:00
<meta name="viewport" content="width=device-width initial-scale=1">
2019-03-20 14:51:06 +02:00
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en-gb">
2020-05-03 03:01:21 +03:00
2020-05-03 03:20:55 +03:00
<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">
2020-04-14 19:56:54 +03:00
2019-03-20 14:51:06 +02:00
</head>
2020-05-03 03:01:21 +03:00
<body class="commentary-font">
2020-03-19 02:11:25 +02:00
<nav role="navigation">
2020-04-14 19:56:54 +03:00
<h1><a href="../index.html">
2020-05-03 18:34:53 +03:00
<img src="../docs-assets/Inform.png" height=72">
2020-04-14 19:56:54 +03:00
</a></h1>
<ul><li><a href="../compiler.html">compiler tools</a></li>
2020-03-19 02:11:25 +02:00
<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>
2020-04-14 19:56:54 +03:00
</ul><h2>Compiler Webs</h2><ul>
2020-03-19 02:11:25 +02:00
<li><a href="../inbuild/index.html">inbuild</a></li>
<li><a href="../inform7/index.html">inform7</a></li>
2020-04-14 19:56:54 +03:00
<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>
2020-03-19 02:11:25 +02:00
<li><a href="../core-module/index.html">core</a></li>
2020-08-27 17:50:24 +03:00
<li><a href="../assertions-module/index.html">assertions</a></li>
<li><a href="../values-module/index.html">values</a></li>
<li><a href="../knowledge-module/index.html">knowledge</a></li>
<li><a href="../imperative-module/index.html">imperative</a></li>
<li><a href="../runtime-module/index.html">runtime</a></li>
2020-03-19 02:11:25 +02:00
<li><a href="../if-module/index.html">if</a></li>
<li><a href="../multimedia-module/index.html">multimedia</a></li>
<li><a href="../index-module/index.html">index</a></li>
2020-04-14 19:56:54 +03:00
</ul><h2>Inter Modules</h2><ul>
<li><a href="../bytecode-module/index.html">bytecode</a></li>
2020-03-19 02:11:25 +02:00
<li><a href="../building-module/index.html">building</a></li>
<li><a href="../pipeline-module/index.html">pipeline</a></li>
<li><a href="../final-module/index.html">final</a></li>
2020-05-20 02:02:28 +03:00
</ul><h2>Services</h2><ul>
2020-04-14 19:56:54 +03:00
<li><a href="../arch-module/index.html">arch</a></li>
2020-08-27 17:50:24 +03:00
<li><a href="../calculus-module/index.html">calculus</a></li>
2020-04-14 19:56:54 +03:00
<li><a href="../html-module/index.html">html</a></li>
2020-05-20 02:02:28 +03:00
<li><a href="../inflections-module/index.html">inflections</a></li>
2020-08-27 17:50:24 +03:00
<li><a href="../kinds-module/index.html">kinds</a></li>
2020-05-20 02:02:28 +03:00
<li><a href="../linguistics-module/index.html">linguistics</a></li>
<li><a href="../problems-module/index.html">problems</a></li>
2020-08-27 17:50:24 +03:00
<li><a href="../syntax-module/index.html">syntax</a></li>
<li><a href="../words-module/index.html">words</a></li>
2020-03-19 02:11:25 +02:00
<li><a href="../../../inweb/docs/foundation-module/index.html">foundation</a></li>
2020-04-14 19:56:54 +03:00
</ul>
2020-03-19 02:11:25 +02:00
</nav>
<main role="main">
2020-05-03 03:01:21 +03:00
<!--Weave of 'Textual Inter' generated by Inweb-->
<div class="breadcrumbs">
<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></div>
<p class="purpose">A specification of the inter language, as written out in text file form.</p>
2019-03-20 14:51:06 +02:00
<ul class="toc"><li><a href="M-ti.html#SP1">&#167;1. Textual, Binary, Memory</a></li><li><a href="M-ti.html#SP2">&#167;2. Global statements</a></li><li><a href="M-ti.html#SP7">&#167;7. Package declarations</a></li><li><a href="M-ti.html#SP11">&#167;11. Symbol annotations</a></li><li><a href="M-ti.html#SP12">&#167;12. Splats</a></li></ul><hr class="tocbar">
2019-03-20 14:51:06 +02:00
2020-08-27 17:50:24 +03:00
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. Textual, Binary, Memory. </b>Inter code has three representations: as a binary file, as a textual file,
2019-03-20 14:51:06 +02:00
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>
2020-05-03 03:01:21 +03:00
<p class="commentary">The following specification covers the inter language in its textual form:
2019-03-20 14:51:06 +02:00
a UTF-8 encoded text file which conventionally takes the file extension
".intert".
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">It should be stressed that inter is designed for inspection &mdash; that is, for
2019-03-20 14:51:06 +02:00
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>
2020-05-03 03:01:21 +03:00
<p class="commentary">Like assembly language, inter code is line-based: each line is a "statement".
Lines can be of arbitrary length. A line beginning with a <span class="extract"><span class="extract-syntax">#</span></span> (in column 1) is
2019-03-20 14:51:06 +02:00
a comment, and blank lines are ignored.
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">The term "name" below means a string of one or more English upper or lower
2019-03-20 14:51:06 +02:00
case letters, underscores, or digits, except that it must not begin with
a digit.
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">As in Python, indentation from the left margin is highly significant, and
2019-03-20 14:51:06 +02:00
should be in the form of tab characters.
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">Inform follows certain conventions in the inter that it writes, but these
2019-03-20 14:51:06 +02:00
conventions are not part of the specification, and may change. Any paragraph
below which begins with "Convention" records the current practice.
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">There are three forms of statement: global statements, data statements, and
2019-03-20 14:51:06 +02:00
code statements. We will take these in turn.
</p>
2020-08-27 17:50:24 +03:00
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. Global statements. </b>These statements must appear first in the file, and must be unindented.
2019-03-20 14:51:06 +02:00
There are only four of these:
</p>
2020-08-27 17:50:24 +03:00
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. </b><span class="extract"><span class="extract-syntax">version NUMBER</span></span> indicates that the file was written in that version of
2019-03-20 14:51:06 +02:00
the inter language. At present there has only ever been one version, but
2020-05-03 03:01:21 +03:00
that may not always be true. A <span class="extract"><span class="extract-syntax">version</span></span> statement number must come before
2019-03-20 14:51:06 +02:00
anything else, even other global statements; in particular, there cannot be
two such statements in the same file.
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">Convention. Inform always opens with the statement: <span class="extract"><span class="extract-syntax">version 1</span></span>
2019-03-20 14:51:06 +02:00
</p>
2020-08-27 17:50:24 +03:00
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>&#167;4. </b><span class="extract"><span class="extract-syntax">packagetype NAME</span></span> declares that <span class="extract"><span class="extract-syntax">NAME</span></span> is the name of a type of package.
2019-03-20 14:51:06 +02:00
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>
2020-05-03 03:01:21 +03:00
<p class="commentary">For example, <span class="extract"><span class="extract-syntax">packagetype _adjective</span></span> creates <span class="extract"><span class="extract-syntax">_adjective</span></span> as a possible type
2019-03-20 14:51:06 +02:00
for packages in this file.
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">The first two package types must be <span class="extract"><span class="extract-syntax">_plain</span></span> and <span class="extract"><span class="extract-syntax">_code</span></span>, in that order.
2019-03-20 14:51:06 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">Convention. All of Inform's package type names begin similarly with an
2019-03-20 14:51:06 +02:00
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
2020-05-03 03:01:21 +03:00
type <span class="extract"><span class="extract-syntax">_adjective</span></span>.
2019-03-20 14:51:06 +02:00
</p>
2020-08-27 17:50:24 +03:00
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>&#167;5. </b><span class="extract"><span class="extract-syntax">pragma TARGET "WHATEVER"</span></span> does not change the meaning of the inter file;
2019-03-20 14:51:06 +02:00
it simply provides pragmatic advice to the eventual compiler of code
2020-05-03 03:01:21 +03:00
generated from this file. <span class="extract"><span class="extract-syntax">TARGET</span></span> indicates the context for which this
is intended; at present, the only possible choice is <span class="extract"><span class="extract-syntax">target_I6</span></span>, meaning,
2019-03-20 14:51:06 +02:00
"if you are compiling me to Inform 6".
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">Convention. Inform uses this to pass on ICL (Inform Command Language)
2019-03-20 14:51:06 +02:00
commands to Inform 6, such as memory settings or command-line switches.
For example,
</p>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">pragma</span><span class="plain-syntax"> target_I6 </span><span class="string-syntax">"$MAX_LABELS=200000"</span>
2019-03-20 14:51:06 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary">(This would be meaningless if we were compiling to some other format.)
2019-03-20 14:51:06 +02:00
</p>
2020-08-27 17:50:24 +03:00
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>&#167;6. </b><span class="extract"><span class="extract-syntax">primitive PRIMITIVE IN -&gt; OUT</span></span> defines a new code statement &mdash; if inter
2019-03-20 14:51:06 +02:00
were an assembly language, these would be the opcodes. For example,
</p>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">primitive</span><span class="plain-syntax"> </span><span class="function-syntax">!move</span><span class="plain-syntax"> </span><span class="reserved-syntax">val</span><span class="plain-syntax"> </span><span class="reserved-syntax">val</span><span class="plain-syntax"> -&gt; </span><span class="reserved-syntax">void</span>
2019-03-20 14:51:06 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary">defines the primitive <span class="extract"><span class="extract-syntax">!move</span></span> as something which consumes two values and
2019-03-21 14:51:08 +02:00
produces none. (Further details on this will appear in the section on code
packages.)
2019-03-20 14:51:06 +02:00
</p>
2020-08-27 17:50:24 +03:00
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>&#167;7. Package declarations. </b>After the global area, an inter file should declare a package called <span class="extract"><span class="extract-syntax">main</span></span>,
2020-05-03 03:01:21 +03:00
which must have the package type <span class="extract"><span class="extract-syntax">_plain</span></span>.
2019-03-20 14:51:06 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">The statement <span class="extract"><span class="extract-syntax">package NAME TYPE</span></span> declares a new package, and the <span class="extract"><span class="extract-syntax">TYPE</span></span>
must be one of those declared by <span class="extract"><span class="extract-syntax">packagetype</span></span> statements in the global area.
2019-03-20 14:51:06 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">The declaration line for a package begins at the level of indentation of
the package's owner. For <span class="extract"><span class="extract-syntax">main</span></span>, it should be unindented, and this is the
2019-03-20 14:51:06 +02:00
only package allowed to appear at the top level: all other packages should
2020-05-03 03:01:21 +03:00
be inside <span class="extract"><span class="extract-syntax">main</span></span> in some way.
2019-03-20 14:51:06 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">The contents of the package are then one tab stop in from the declaration. Thus:
2019-03-20 14:51:06 +02:00
</p>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">package</span><span class="plain-syntax"> main _plain</span>
<span class="plain-syntax"> ...</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">package</span><span class="plain-syntax"> m1_RBLK1 _code</span>
<span class="plain-syntax"> ...</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">package</span><span class="plain-syntax"> m1_RBLK2 _code</span>
<span class="plain-syntax"> ...</span>
2019-03-20 14:51:06 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary">Here, <span class="extract"><span class="extract-syntax">main</span></span> contains two sub-packages, <span class="extract"><span class="extract-syntax">m1_RBLK1</span></span> and <span class="extract"><span class="extract-syntax">m1_RBLK2</span></span>, and
2019-03-20 14:51:06 +02:00
indentation is used to show which package a statement belongs to.
</p>
2020-08-27 17:50:24 +03:00
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>&#167;8. </b>After the declaration line, a package definition continues with a set
2019-03-20 14:51:06 +02:00
of symbols definitions. In effect, this is the symbols table for the
2020-05-03 03:01:21 +03:00
package written out explicitly. Each definition is a <span class="extract"><span class="extract-syntax">symbol</span></span> line, in
2019-03-20 14:51:06 +02:00
one of these three forms:
</p>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">symbol</span><span class="plain-syntax"> </span><span class="reserved-syntax">private</span><span class="plain-syntax"> TYPE NAME</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">symbol</span><span class="plain-syntax"> </span><span class="reserved-syntax">public</span><span class="plain-syntax"> TYPE NAME</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">symbol</span><span class="plain-syntax"> </span><span class="reserved-syntax">external</span><span class="plain-syntax"> TYPE NAME </span><span class="reserved-syntax">--&gt;</span><span class="plain-syntax"> SYMBOL</span>
2019-03-20 14:51:06 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary">For example,
2019-03-20 14:51:06 +02:00
</p>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">symbol</span><span class="plain-syntax"> </span><span class="reserved-syntax">public</span><span class="plain-syntax"> </span><span class="reserved-syntax">misc</span><span class="plain-syntax"> MEMORY_HEAP_SIZE</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">symbol</span><span class="plain-syntax"> </span><span class="reserved-syntax">external</span><span class="plain-syntax"> </span><span class="reserved-syntax">misc</span><span class="plain-syntax"> AllowInShowme </span><span class="reserved-syntax">--&gt;</span><span class="plain-syntax"> /main/resources/template/AllowInShowme</span>
2019-03-20 14:51:06 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary"><span class="extract"><span class="extract-syntax">private</span></span> means that the meaning and existence of <span class="extract"><span class="extract-syntax">NAME</span></span> are invisible
from outside the current package; <span class="extract"><span class="extract-syntax">public</span></span> means that other packages are
allowed to refer to <span class="extract"><span class="extract-syntax">NAME</span></span>; and <span class="extract"><span class="extract-syntax">external</span></span> means that this package is
making just such a reference, and that <span class="extract"><span class="extract-syntax">NAME</span></span> in this package is equivalent
to <span class="extract"><span class="extract-syntax">SYMBOL</span></span>, defined elsewhere. It is possible that <span class="extract"><span class="extract-syntax">SYMBOL</span></span> points only to
another symbol which is also <span class="extract"><span class="extract-syntax">external</span></span>, so that we then have to follow
2019-03-20 14:51:06 +02:00
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>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">package</span><span class="plain-syntax"> main _plain</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">package</span><span class="plain-syntax"> A _plain</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">symbol</span><span class="plain-syntax"> </span><span class="reserved-syntax">external</span><span class="plain-syntax"> </span><span class="reserved-syntax">misc</span><span class="plain-syntax"> S </span><span class="reserved-syntax">--&gt;</span><span class="plain-syntax"> /main/B/T</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">package</span><span class="plain-syntax"> B _plain</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">symbol</span><span class="plain-syntax"> </span><span class="reserved-syntax">external</span><span class="plain-syntax"> </span><span class="reserved-syntax">misc</span><span class="plain-syntax"> T </span><span class="reserved-syntax">--&gt;</span><span class="plain-syntax"> /main/B/S</span>
2019-03-20 14:51:06 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary">The symbol <span class="extract"><span class="extract-syntax">TYPE</span></span> must be one of four possibilities:
2019-03-20 14:51:06 +02:00
</p>
2020-05-03 03:01:21 +03:00
<ul class="items"><li>(a) <span class="extract"><span class="extract-syntax">label</span></span>, used to mark execution positions in code packages;
</li><li>(b) <span class="extract"><span class="extract-syntax">package</span></span>, meaning that this is the name of a package;
</li><li>(c) <span class="extract"><span class="extract-syntax">packagetype</span></span>, meaning that this is a package type;
</li><li>(d) <span class="extract"><span class="extract-syntax">misc</span></span>, meaning "anything else" &mdash; most symbols have this type.
2019-03-20 14:51:06 +02:00
</li></ul>
2020-05-03 03:01:21 +03:00
<p class="commentary">The run of <span class="extract"><span class="extract-syntax">symbol</span></span> declarations at the top of a module can become quite
2019-03-20 14:51:06 +02:00
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>
2020-05-03 03:01:21 +03:00
<p class="commentary">Convention. A conspicuous feature of inter code generated by Inform is that
many symbols have the form <span class="extract"><span class="extract-syntax">P_Name</span></span>, where <span class="extract"><span class="extract-syntax">P</span></span> is some prefix letter showing
2019-03-21 14:51:08 +02:00
what sort of thing is referred to: for example, symbols for kinds all begin
2020-05-03 03:01:21 +03:00
with the prefix <span class="extract"><span class="extract-syntax">K</span></span> (<span class="extract"><span class="extract-syntax">K_number</span></span>, <span class="extract"><span class="extract-syntax">K_text</span></span>, and so on), while variables
begin with <span class="extract"><span class="extract-syntax">V</span></span>, instances with <span class="extract"><span class="extract-syntax">I</span></span>, properties with <span class="extract"><span class="extract-syntax">P</span></span>, and so on. This
2019-03-21 14:51:08 +02:00
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>
2020-08-27 17:50:24 +03:00
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>&#167;9. </b>Where a local symbol is being equated with an external one, the <span class="extract"><span class="extract-syntax">SYMBOL</span></span>
2019-03-20 14:51:06 +02:00
given is a sort of URL showing the package to look inside. Thus
</p>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> /main/resources/template/AllowInShowme</span>
2019-03-20 14:51:06 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary">means "the symbol <span class="extract"><span class="extract-syntax">AllowInShowme</span></span> in package <span class="extract"><span class="extract-syntax">template</span></span> inside package
<span class="extract"><span class="extract-syntax">resources</span></span> inside package <span class="extract"><span class="extract-syntax">main</span></span>".
2019-03-20 14:51:06 +02:00
</p>
2020-08-27 17:50:24 +03:00
<p class="commentary firstcommentary"><a id="SP10" class="paragraph-anchor"></a><b>&#167;10. </b>Optionally, a <span class="extract"><span class="extract-syntax">private</span></span> or <span class="extract"><span class="extract-syntax">public</span></span> symbol can also specify a name it
2019-03-20 14:51:06 +02:00
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>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">symbol</span><span class="plain-syntax"> </span><span class="reserved-syntax">private</span><span class="plain-syntax"> TYPE NAME </span><span class="element-syntax">`TRANSLATION</span><span class="plain-syntax">`</span>
2019-03-20 14:51:06 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary">So, for example,
2019-03-20 14:51:06 +02:00
</p>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">symbol</span><span class="plain-syntax"> </span><span class="reserved-syntax">public</span><span class="plain-syntax"> </span><span class="reserved-syntax">misc</span><span class="plain-syntax"> launcher </span><span class="element-syntax">`launcher_U32</span><span class="plain-syntax">`</span>
2019-03-20 14:51:06 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary">Symbols tabulated as <span class="extract"><span class="extract-syntax">external</span></span> cannot be marked in this way, but of course
2019-03-20 14:51:06 +02:00
the original definition (to which the external link eventually leads) can be.
For example,
</p>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">package</span><span class="plain-syntax"> main _plain</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">package</span><span class="plain-syntax"> A _plain</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">symbol</span><span class="plain-syntax"> </span><span class="reserved-syntax">external</span><span class="plain-syntax"> </span><span class="reserved-syntax">misc</span><span class="plain-syntax"> S </span><span class="reserved-syntax">--&gt;</span><span class="plain-syntax"> /main/B/T</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">package</span><span class="plain-syntax"> B _plain</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">symbol</span><span class="plain-syntax"> </span><span class="reserved-syntax">public</span><span class="plain-syntax"> </span><span class="reserved-syntax">misc</span><span class="plain-syntax"> T </span><span class="element-syntax">`FancyName</span><span class="plain-syntax">`</span>
2019-03-20 14:51:06 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary">would result in the names <span class="extract"><span class="extract-syntax">S</span></span> and <span class="extract"><span class="extract-syntax">T</span></span> both being compiled to the name
<span class="extract"><span class="extract-syntax">FancyName</span></span> in the final code.
2019-03-20 14:51:06 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">Convention. Inform mostly makes use of this feature of inter late in code
2019-03-20 14:51:06 +02:00
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>
2020-08-27 17:50:24 +03:00
<p class="commentary firstcommentary"><a id="SP11" class="paragraph-anchor"></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>
2020-05-03 03:01:21 +03:00
<p class="commentary">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>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> WORD_NEXTTOHIGHBIT </span><span class="identifier-syntax">K_typeless_int</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">x4000</span>
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary">And here it is with an annotation:
</p>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> WORD_NEXTTOHIGHBIT </span><span class="identifier-syntax">K_typeless_int</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">x4000 </span><span class="identifier-syntax">__hex</span>
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary">The annotation, <span class="extract"><span class="extract-syntax">__hex</span></span>, 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>
2020-05-03 03:01:21 +03:00
<p class="commentary">All annotations begin with a double underscore, and some can take a number
or text literal:
</p>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="identifier-syntax">__binary</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">__table_array</span><span class="plain-syntax">=1</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">__name</span><span class="plain-syntax">=</span><span class="string-syntax">"matching key"</span>
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary">There is no built-in set of annotations, and their use does not need to be
predeclared anywhere: simply writing
</p>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> MY_CONSTANT </span><span class="identifier-syntax">K_typeless_int</span><span class="plain-syntax"> = </span><span class="constant-syntax">27</span><span class="plain-syntax"> </span><span class="identifier-syntax">__plugh</span>
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary">would create the annotation <span class="extract"><span class="extract-syntax">__plugh</span></span> 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>
2020-08-27 17:50:24 +03:00
<p class="commentary firstcommentary"><a id="SP12" class="paragraph-anchor"></a><b>&#167;12. Splats. </b>The special statement <span class="extract"><span class="extract-syntax">splat "TEXT"</span></span> or <span class="extract"><span class="extract-syntax">splat ANNOTATION "TEXT"</span></span> allows
2019-03-21 14:51:08 +02:00
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
2020-05-03 03:01:21 +03:00
one. The annotation can be any of: <span class="extract"><span class="extract-syntax">IFDEF_PLM</span></span>, <span class="extract"><span class="extract-syntax">IFNDEF_PLM</span></span>, <span class="extract"><span class="extract-syntax">IFNOT_PLM</span></span>,
<span class="extract"><span class="extract-syntax">ENDIF_PLM</span></span>, <span class="extract"><span class="extract-syntax">IFTRUE_PLM</span></span>, <span class="extract"><span class="extract-syntax">CONSTANT_PLM</span></span>, <span class="extract"><span class="extract-syntax">ARRAY_PLM</span></span>, <span class="extract"><span class="extract-syntax">GLOBAL_PLM</span></span>,
<span class="extract"><span class="extract-syntax">STUB_PLM</span></span>, <span class="extract"><span class="extract-syntax">ROUTINE_PLM</span></span>, <span class="extract"><span class="extract-syntax">ATTRIBUTE_PLM</span></span>, <span class="extract"><span class="extract-syntax">PROPERTY_PLM</span></span>, <span class="extract"><span class="extract-syntax">VERB_PLM</span></span>,
<span class="extract"><span class="extract-syntax">FAKEACTION_PLM</span></span>, <span class="extract"><span class="extract-syntax">OBJECT_PLM</span></span>, <span class="extract"><span class="extract-syntax">DEFAULT_PLM</span></span>, <span class="extract"><span class="extract-syntax">MYSTERY_PLM</span></span>.
2019-03-21 01:18:43 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">Convention. Inform creates no splats, except as needed to convert
2019-03-21 14:51:08 +02:00
Inform 6 template code into inter, in the code-generator.
2019-03-21 01:18:43 +02:00
</p>
2020-05-03 03:01:21 +03:00
<nav role="progress"><div class="progresscontainer">
<ul class="progressbar"><li class="progressprev"><a href="M-ui.html">&#10094;</a></li><li class="progresscurrentchapter">M</li><li class="progresssection"><a href="M-ui.html">ui</a></li><li class="progresscurrent">ti</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="progresssection"><a href="M-ia.html">ia</a></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-dpiti.html">&#10095;</a></li></ul></div>
</nav><!--End of weave-->
2020-03-19 02:11:25 +02:00
</main>
2019-03-20 14:51:06 +02:00
</body>
</html>