mirror of
https://github.com/ganelson/inform.git
synced 2024-07-05 00:24:22 +03:00
270 lines
20 KiB
HTML
270 lines
20 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>
|
|
<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 'Textual Inter' 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>Textual Inter</b></li></ul></div>
|
|
<p class="purpose">A specification of the inter language, as written out in text file form.</p>
|
|
|
|
<ul class="toc"><li><a href="M-ti.html#SP1">§1. A manual of a sort</a></li><li><a href="M-ti.html#SP3">§3. Outside even main</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>§1. A manual of a sort. </b>In its textual form, Inter could conceivably be used as a programming
|
|
language, albeit a low-level and verbose one, and this section is a brief
|
|
manual for that language. But the real purpose of Inter is to assist testing
|
|
and debugging of the Inform tool-chain. We can write test cases in textual
|
|
Inter to see if inter works; or we can write out memory inter to the
|
|
debugging log to see if inform7 works.
|
|
</p>
|
|
|
|
<p class="commentary">A textual inter file is a UTF-8 encoded text file which conventionally takes
|
|
the file extension ".intert". Here is an example, the test case <span class="extract"><span class="extract-syntax">Hello</span></span>:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<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"> Main _code</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">code</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">inv</span><span class="plain-syntax"> </span><span class="function-syntax">!enableprinting</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">inv</span><span class="plain-syntax"> </span><span class="function-syntax">!print</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">val</span><span class="plain-syntax"> </span><span class="string-syntax">"Hello, world.\n"</span>
|
|
</pre>
|
|
<p class="commentary">Some basic characteristics of textual Inter can be seen at a glance. It's line-based:
|
|
each line makes a single use of a "construct" like <span class="extract"><span class="extract-syntax">package</span></span> or <span class="extract"><span class="extract-syntax">code</span></span>. Lines
|
|
can be of arbitrary length. A line beginning with a <span class="extract"><span class="extract-syntax">#</span></span> (in column 1) is
|
|
a comment, and blank lines are ignored.
|
|
</p>
|
|
|
|
<p class="commentary">As in Python, indentation from the left margin is highly significant, and
|
|
must be in the form of tab characters.
|
|
</p>
|
|
|
|
<p class="commentary">Most identifiers consist of a string of one or more English upper or lower
|
|
case letters, underscores, or digits, except that it must not begin with
|
|
a digit. Identifier lengths are unlimited. A few identifiers of special sorts
|
|
begin with a special character to mark them out as special: <span class="extract"><span class="extract-syntax">!enableprinting</span></span>,
|
|
for example, is a "primitive", marked with a <span class="extract"><span class="extract-syntax">!</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">A convention followed in Inter code generated by Inform is that many identifiers
|
|
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 what sort of
|
|
thing is referred to: for example, 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 is all done only for clarity, and is not
|
|
part of the Inter specification.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>§2. </b>The main organising idea of Inter is the "package". Each program is a nested
|
|
hierarchy of packages, and each package has both a name and a "package type".
|
|
In the <span class="extract"><span class="extract-syntax">Hello</span></span> example, an outer package called <span class="extract"><span class="extract-syntax">main</span></span>, of type <span class="extract"><span class="extract-syntax">_plain</span></span>,
|
|
holds only a inner package called <span class="extract"><span class="extract-syntax">Main</span></span>, of type <span class="extract"><span class="extract-syntax">_code</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">In fact, every program must contain just one outermost package, called <span class="extract"><span class="extract-syntax">main</span></span>,
|
|
which has to have type <span class="extract"><span class="extract-syntax">_plain</span></span>, so that is unsurprising.
|
|
</p>
|
|
|
|
<p class="commentary">Packages of type <span class="extract"><span class="extract-syntax">_code</span></span> are functions. A program is not required to contain any
|
|
functions at all, and even if it does, it is not required to contain one called
|
|
<span class="extract"><span class="extract-syntax">Main</span></span>. For example, the Inter program into which BasicInformKit is compiled
|
|
does not provide a <span class="extract"><span class="extract-syntax">Main</span></span>, and we could imagine kits which provided, say, only
|
|
some variables and arrays. But if we want a program to compile and run in a
|
|
stand-alone way, then it needs a <span class="extract"><span class="extract-syntax">Main</span></span> function as a place to begin running.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>§3. Outside even main. </b>Though this does not happen in the <span class="extract"><span class="extract-syntax">Hello</span></span> example, a handful of instructions
|
|
can appear at the top of the program, outside even <span class="extract"><span class="extract-syntax">main</span></span>. These really just
|
|
define conventions used in the rest of the program, rather than describing
|
|
what the program does, and that is why they are on the outside.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>§4. </b><span class="extract"><span class="extract-syntax">version NUMBER</span></span> indicates that the file was written in that version of
|
|
the Inter language. <span class="extract"><span class="extract-syntax">NUMBER</span></span> is a semantic version number, and it forces
|
|
<a href="index.html" class="internal">inter</a> to reject the file if the version of the Inter specification
|
|
understood by <a href="index.html" class="internal">inter</a> is not compatible with the one in the file. (Note
|
|
that this about the version of the specification, not the version of <a href="index.html" class="internal">inter</a>
|
|
as a program.)
|
|
</p>
|
|
|
|
<p class="commentary">See <a href="../bytecode-module/1-tiv.html" class="internal">The Inter Version (in bytecode)</a> for more on the significance of this.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>§5. </b><span class="extract"><span class="extract-syntax">pragma TARGET "WHATEVER"</span></span> does not change the meaning of the inter file;
|
|
it simply provides pragmatic advice to the eventual compiler of code
|
|
generated from this file. <span class="extract"><span class="extract-syntax">TARGET</span></span> indicates the context for which this
|
|
is intended.
|
|
</p>
|
|
|
|
<p class="commentary">At present Inform 7 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="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">pragma</span><span class="plain-syntax"> Inform6 </span><span class="string-syntax">"$MAX_LABELS=200000"</span>
|
|
</pre>
|
|
<p class="commentary">When a program containing this instruction is generated to C, say, then this
|
|
is ignored completely. And in fact, now that Inform has adopted Inform 6.36 as
|
|
its preferred copy of I6, memory settings have become unnecessary and are
|
|
ignored by I6 anyway, so even this use of <span class="extract"><span class="extract-syntax">pragma</span></span> may yet disappear.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>§6. </b><span class="extract"><span class="extract-syntax">packagetype _NAME</span></span> declares that <span class="extract"><span class="extract-syntax">_NAME</span></span> can be used as a package type.
|
|
It's actually unnecessary to write this explicitly, which is why the <span class="extract"><span class="extract-syntax">Hello</span></span>
|
|
example did not begin with:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">packagetype</span><span class="plain-syntax"> _plain</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">packagetype</span><span class="plain-syntax"> _code</span>
|
|
</pre>
|
|
<p class="commentary">If the program creates, say, <span class="extract"><span class="extract-syntax">package MOMA _museum</span></span>, then the necessary
|
|
package type instruction <span class="extract"><span class="extract-syntax">packagetype _museum</span></span> will be inferred automatically.
|
|
Nevertheless, it's valid to spell this out.
|
|
</p>
|
|
|
|
<p class="commentary">All package types have names beginning with an underscore <span class="extract"><span class="extract-syntax">_</span></span>. Authors of
|
|
Inter programs are free to choose any types they like, and Inform tends to
|
|
use semantically meaningful type names like <span class="extract"><span class="extract-syntax">_adjective</span></span>. Only two package
|
|
types are special: <span class="extract"><span class="extract-syntax">_code</span></span>, which as we have seen marks that a package is a
|
|
function, and <span class="extract"><span class="extract-syntax">_linkage</span></span>, which is used only for a special package called
|
|
<span class="extract"><span class="extract-syntax">connectors</span></span>. Stand-alone programs never contain that package: see
|
|
<a href="../bytecode-module/index.html" class="internal">bytecode</a> for an explanation of what it is for.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>§7. </b><span class="extract"><span class="extract-syntax">primitive !PRIMITIVE SIGNATURE</span></span> declares that a primitive invocation of
|
|
this name and signature can be used in the program. Primitives occur only
|
|
inside of functions, where they are "invoked", and they are operations
|
|
sufficiently basic that they cannot themselves be written as other Inter
|
|
functions. For example, in <span class="extract"><span class="extract-syntax">Hello</span></span> we saw:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">inv</span><span class="plain-syntax"> </span><span class="function-syntax">!print</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">val</span><span class="plain-syntax"> </span><span class="string-syntax">"Hello, world.\n"</span>
|
|
</pre>
|
|
<p class="commentary">This is an invocation of the primitive <span class="extract"><span class="extract-syntax">!print</span></span>, which prints text. The
|
|
"signature" of this is <span class="extract"><span class="extract-syntax">val -> void</span></span>, meaning that it expects to have one
|
|
argument, a value, and produces no result.
|
|
</p>
|
|
|
|
<p class="commentary">The declarations for the two primitives in <span class="extract"><span class="extract-syntax">Hello</span></span> would look like this:
|
|
</p>
|
|
|
|
<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">!enableprinting</span><span class="plain-syntax"> </span><span class="reserved-syntax">void</span><span class="plain-syntax"> -> </span><span class="reserved-syntax">void</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">primitive</span><span class="plain-syntax"> </span><span class="function-syntax">!print</span><span class="plain-syntax"> </span><span class="reserved-syntax">val</span><span class="plain-syntax"> -> </span><span class="reserved-syntax">void</span>
|
|
</pre>
|
|
<p class="commentary">But once again they do not need to be given, because they are part of the
|
|
standard set of Inter primitives supported by <a href="index.html" class="internal">inter</a>. So these definitions
|
|
are implicitly made as needed.
|
|
</p>
|
|
|
|
<p class="commentary">In principle, though, the program could create entirely novel primitives:
|
|
</p>
|
|
|
|
<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">!flytoarabia</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"> </span><span class="reserved-syntax">val</span><span class="plain-syntax"> -> </span><span class="reserved-syntax">void</span>
|
|
</pre>
|
|
<p class="commentary">And this will work perfectly well... except that <a href="index.html" class="internal">inter</a> will not be able
|
|
to code-generate from the result without modification, because it won't know
|
|
how to fly to Arabia. So in practice, unless you are experimenting with
|
|
modified versions of Inter, do not use the <span class="extract"><span class="extract-syntax">primitive</span></span> construct at all.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>§8. </b>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
|
|
only package allowed to appear at the top level: all other packages should
|
|
be inside <span class="extract"><span class="extract-syntax">main</span></span> in some way.
|
|
</p>
|
|
|
|
<p class="commentary">The contents of the package are then one tab stop in from the declaration. Thus:
|
|
</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"> 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>
|
|
</pre>
|
|
<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
|
|
indentation is used to show which package a statement belongs to.
|
|
</p>
|
|
|
|
<p class="commentary">Packages of any type can freely be created inside packages of any other type,
|
|
except that <span class="extract"><span class="extract-syntax">_code</span></span> packages cannot have subpackages. So this hypothetical bit of
|
|
Inter is illegal:
|
|
</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"> my_function _code</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">package</span><span class="plain-syntax"> inner_part _code</span>
|
|
<span class="plain-syntax"> ...</span>
|
|
<span class="plain-syntax"> ...</span>
|
|
</pre>
|
|
<p class="commentary">Here, <span class="extract"><span class="extract-syntax">inner_part</span></span> cannot be made a subpackage of <span class="extract"><span class="extract-syntax">my_function</span></span> because <span class="extract"><span class="extract-syntax">_code</span></span>
|
|
packages have no subpackages.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>§9. </b>The remaining statements to cover fall into two categories.
|
|
</p>
|
|
|
|
<ul class="items"><li>● Those used outside functions, i.e., packages of type <span class="extract"><span class="extract-syntax">_code</span></span>, are covered in
|
|
<a href="M-dpiti.html" class="internal">Data Packages in Textual Inter</a>.
|
|
</li><li>● Those used in functions, i.e., packages of type <span class="extract"><span class="extract-syntax">_code</span></span>, are covered in
|
|
<a href="M-cpiti.html" class="internal">Code Packages in Textual Inter</a>.
|
|
</li></ul>
|
|
<nav role="progress"><div class="progresscontainer">
|
|
<ul class="progressbar"><li class="progressprev"><a href="M-ui.html">❮</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">❯</a></li></ul></div>
|
|
</nav><!--End of weave-->
|
|
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|