<ulclass="crumbs"><li><ahref="../index.html">Home</a></li><li><ahref="index.html">inter</a></li><li><ahref="index.html#M">Manual</a></li><li><b>Code Packages in Textual Inter</b></li></ul></div>
<ulclass="toc"><li><ahref="M-cpiti.html#SP1">§1. Code packages</a></li><li><ahref="M-cpiti.html#SP4">§4. Contexts</a></li><li><ahref="M-cpiti.html#SP8">§8. Function calls</a></li><li><ahref="M-cpiti.html#SP10">§10. Val, ref, lab and cast</a></li><li><ahref="M-cpiti.html#SP12">§12. Labels and assembly language</a></li></ul><hrclass="tocbar">
<pclass="commentary firstcommentary"><aid="SP1"class="paragraph-anchor"></a><b>§1. Code packages. </b>To recap from <ahref="M-ti.html"class="internal">Textual Inter</a>: an Inter program is a nested hierarchy of
packages. Some of those are special <spanclass="extract"><spanclass="extract-syntax">_code</span></span> packages which define functions,
</li><li>● Their names can optionally have types: see <ahref="M-dpiti.html"class="internal">Data Packages in Textual Inter</a>
for details.
</li><li>● They cannot have subpackages. Conceptually, a code package is a single
function body. Packages are not used for "code blocks", and there are no
nested functions.
</li><li>● They cannot contain <spanclass="extract"><spanclass="extract-syntax">constant</span></span>, <spanclass="extract"><spanclass="extract-syntax">variable</span></span>, and similar instructions found
in data packages. Instead they can only contain the set of instructions which
are the subject of this section (and which are allowed only in <spanclass="extract"><spanclass="extract-syntax">_code</span></span> packages).
</li></ul>
<pclass="commentary firstcommentary"><aid="SP2"class="paragraph-anchor"></a><b>§2. </b>The basic structure of a function body like this is that it begins with some
local variable declarations, and then has its actual content inside a <spanclass="extract"><spanclass="extract-syntax">code</span></span>
<pclass="commentary">As with its global analogue, <spanclass="extract"><spanclass="extract-syntax">variable</span></span>, a <spanclass="extract"><spanclass="extract-syntax">local</span></span> instruction can optionally
<pclass="commentary">There can be at most one <spanclass="extract"><spanclass="extract-syntax">code</span></span> instruction at the top level. This is incorrect:
<spanclass="plain-syntax"></span><spanclass="reserved-syntax">val</span><spanclass="plain-syntax"></span><spanclass="string-syntax">"I am dismal.\n"</span>
<spanclass="plain-syntax"></span><spanclass="reserved-syntax">val</span><spanclass="plain-syntax"></span><spanclass="string-syntax">"I am glorious.\n"</span>
</pre>
<pclass="commentary firstcommentary"><aid="SP3"class="paragraph-anchor"></a><b>§3. </b>Surprisingly, perhaps, it's legal not to have a <spanclass="extract"><spanclass="extract-syntax">code</span></span> block at all. This
<pclass="commentary">But of course it does nothing. If the return value of such a function is used,
it will be 0.
</p>
<pclass="commentary firstcommentary"><aid="SP4"class="paragraph-anchor"></a><b>§4. Contexts. </b>At any point inside a function body (except at the very top level), the
instruction used is expected to have a given "category", decided by the
"context" at that point. These categories have names:
</p>
<ulclass="items"><li>●<spanclass="extract"><spanclass="extract-syntax">code</span></span> context. This means an instruction is expected to do something,
but not produce a resulting value.
</li><li>●<spanclass="extract"><spanclass="extract-syntax">val</span></span> context. This means an instruction is expected to produce a value.
</li><li>●<spanclass="extract"><spanclass="extract-syntax">ref</span></span> context. This means an instruction is expected to provide a
"reference" to some storage in the program. For example, it could indicate
a global variable, or a particular property of some instance.
</li><li>●<spanclass="extract"><spanclass="extract-syntax">lab</span></span> context. This means an instruction is expected to indicate a label
marking a position in that same function.
</li></ul>
<pclass="commentary">In a <spanclass="extract"><spanclass="extract-syntax">code</span></span> block, the context is initially <spanclass="extract"><spanclass="extract-syntax">code</span></span>. For example:
<spanclass="plain-syntax"></span><spanclass="reserved-syntax">local</span><spanclass="plain-syntax"> x top level has no context</span>
<spanclass="plain-syntax"></span><spanclass="reserved-syntax">code</span><spanclass="plain-syntax"> top level has no context</span>
<spanclass="plain-syntax"></span><spanclass="reserved-syntax">inv</span><spanclass="plain-syntax"></span><spanclass="function-syntax">!jump</span><spanclass="plain-syntax"> context is </span><spanclass="reserved-syntax">code</span>
<spanclass="plain-syntax"></span><spanclass="reserved-syntax">lab</span><spanclass="plain-syntax"> .SkipWarning context is </span><spanclass="reserved-syntax">lab</span>
<spanclass="plain-syntax"></span><spanclass="reserved-syntax">inv</span><spanclass="plain-syntax"></span><spanclass="function-syntax">!print</span><spanclass="plain-syntax"> context is </span><spanclass="reserved-syntax">code</span>
<spanclass="plain-syntax"></span><spanclass="reserved-syntax">val</span><spanclass="plain-syntax"></span><spanclass="string-syntax">"It'll get bigger!\n"</span><spanclass="plain-syntax"> context is </span><spanclass="reserved-syntax">val</span>
<spanclass="plain-syntax"> .SkipWarning context is </span><spanclass="reserved-syntax">code</span>
<spanclass="plain-syntax"></span><spanclass="reserved-syntax">inv</span><spanclass="plain-syntax"></span><spanclass="function-syntax">!store</span><spanclass="plain-syntax"> context is </span><spanclass="reserved-syntax">code</span>
<spanclass="plain-syntax"></span><spanclass="reserved-syntax">ref</span><spanclass="plain-syntax"> x context is </span><spanclass="reserved-syntax">ref</span>
<spanclass="plain-syntax"></span><spanclass="reserved-syntax">inv</span><spanclass="plain-syntax"></span><spanclass="function-syntax">!plus</span><spanclass="plain-syntax"> context is </span><spanclass="reserved-syntax">val</span>
<spanclass="plain-syntax"></span><spanclass="reserved-syntax">val</span><spanclass="plain-syntax"> x context is </span><spanclass="reserved-syntax">val</span>
<spanclass="plain-syntax"></span><spanclass="reserved-syntax">val</span><spanclass="plain-syntax"> x context is </span><spanclass="reserved-syntax">val</span>
<spanclass="plain-syntax"></span><spanclass="reserved-syntax">inv</span><spanclass="plain-syntax"></span><spanclass="function-syntax">!return</span><spanclass="plain-syntax"> context is </span><spanclass="reserved-syntax">code</span>
<spanclass="plain-syntax"></span><spanclass="reserved-syntax">val</span><spanclass="plain-syntax"> x context is </span><spanclass="reserved-syntax">val</span>
<pclass="commentary">In this function, the <spanclass="extract"><spanclass="extract-syntax">code</span></span> block contains five instructions, each of which
is read in a <spanclass="extract"><spanclass="extract-syntax">code</span></span> context. Each of those then has its own expectations which
set the context for its child instructions, and so on. For example, <spanclass="extract"><spanclass="extract-syntax">inv !store</span></span>
expects to see two child instructions, the first in <spanclass="extract"><spanclass="extract-syntax">ref</span></span> context and the
second in <spanclass="extract"><spanclass="extract-syntax">val</span></span> context.
</p>
<pclass="commentary">Those uses of <spanclass="extract"><spanclass="extract-syntax">inv !something</span></span> are called "primitive invocations". They are
like function calls, but where the function is built in to Inter and is not
itself defined in Inter. Each such has a "signature". For example, the
internal declaration of <spanclass="extract"><spanclass="extract-syntax">!store</span></span> is:
<pclass="commentary">So its signature is <spanclass="extract"><spanclass="extract-syntax">ref val -> val</span></span>. This expresses that its two children
should be read in <spanclass="extract"><spanclass="extract-syntax">ref</span></span> and <spanclass="extract"><spanclass="extract-syntax">val</span></span> context, and that its result is a <spanclass="extract"><spanclass="extract-syntax">val</span></span>.
(As in most C-like languages, stores are values in Inter, though in
<pclass="commentary firstcommentary"><aid="SP5"class="paragraph-anchor"></a><b>§5. </b>How is all this policed? Whereas typechecking of data is often weak in Inter,
signature checking is taken much more seriously. If the context is <spanclass="extract"><spanclass="extract-syntax">code</span></span>, then
the only legal primitives to invoke are those where the return part of the
signature is either <spanclass="extract"><spanclass="extract-syntax">void</span></span> (no value) or <spanclass="extract"><spanclass="extract-syntax">val</span></span> (a value, but which is thrown
away and ignored, as in most C-like languages). Otherwise, <spanclass="extract"><spanclass="extract-syntax">ref</span></span> context
requires a <spanclass="extract"><spanclass="extract-syntax">ref</span></span> result, and similarly for <spanclass="extract"><spanclass="extract-syntax">val</span></span> and <spanclass="extract"><spanclass="extract-syntax">lab</span></span>.
</p>
<pclass="commentary">For example, <spanclass="extract"><spanclass="extract-syntax">!return</span></span> has the signature <spanclass="extract"><spanclass="extract-syntax">val -> void</span></span>, which makes it legal
to use in a <spanclass="extract"><spanclass="extract-syntax">code</span></span> context as in the above example. But these two attempts
<pclass="commentary">The first fails because it tries to use <spanclass="extract"><spanclass="extract-syntax">!return</span></span> as if it were <spanclass="extract"><spanclass="extract-syntax">void -> void</span></span>,
i.e., with no supplied value; the second fails because it tries to use it as if
it were <spanclass="extract"><spanclass="extract-syntax">val -> val</span></span>.
<pclass="commentary firstcommentary"><aid="SP6"class="paragraph-anchor"></a><b>§6. </b>Some primitives have <spanclass="extract"><spanclass="extract-syntax">code</span></span> as one or more of their arguments. For example:
<pclass="commentary firstcommentary"><aid="SP7"class="paragraph-anchor"></a><b>§7. </b>Rather like <spanclass="extract"><spanclass="extract-syntax">code</span></span>, which executes a run of instructions as if they were a
single instruction, <spanclass="extract"><spanclass="extract-syntax">evaluation</span></span> makes a run of evaluations. Thus:
<pclass="commentary">prints just "12". The point of this is that there may be side-effects in the
earlier evaluations, of course, though there weren't in this example.
</p>
<pclass="commentary">Another converter, so to speak, is <spanclass="extract"><spanclass="extract-syntax">reference</span></span>, but this is much more limited
<pclass="commentary">which changes the property <spanclass="extract"><spanclass="extract-syntax">area</span></span> for <spanclass="extract"><spanclass="extract-syntax">Odessa</span></span> to 5000. The signature of
<spanclass="extract"><spanclass="extract-syntax">!propertyvalue</span></span> is <spanclass="extract"><spanclass="extract-syntax">val val -> val</span></span>, and ordinarily it evaluates the property.
But placed under a <spanclass="extract"><spanclass="extract-syntax">reference</span></span>, it becomes a reference to where that property
is stored, and thus allows the value to be changed with <spanclass="extract"><spanclass="extract-syntax">!store</span></span>. This:
<pclass="commentary">would by contrast be rejected with an error, as trying to use a <spanclass="extract"><spanclass="extract-syntax">val</span></span> in a <spanclass="extract"><spanclass="extract-syntax">ref</span></span>
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">reference</span></span> cannot be applied to anything other than storage (a local or global
variable, a memory location or a property value), so for example:
<pclass="commentary">is meaningless and will be rejected. There is in general no way to make, say,
a pointer to a function or instance using <spanclass="extract"><spanclass="extract-syntax">reference</span></span>. It is much more circumscribed
than the <spanclass="extract"><spanclass="extract-syntax">&</span></span> operator in C.
</p>
<pclass="commentary firstcommentary"><aid="SP8"class="paragraph-anchor"></a><b>§8. Function calls. </b>This seems a good point to say how to make function calls, since it's almost
<pclass="commentary">prints "20". Note the lack of a <spanclass="extract"><spanclass="extract-syntax">!</span></span> in front of the function name: this means
<pclass="commentary firstcommentary"><aid="SP9"class="paragraph-anchor"></a><b>§9. </b>Function calls work in a rather assembly-language-like way, and Inter makes
much less effort to type-check these for any kind of safety: so beware. It
allows them to have any of the signatures <spanclass="extract"><spanclass="extract-syntax">void -> val</span></span>, <spanclass="extract"><spanclass="extract-syntax">val -> val</span></span>,
<spanclass="extract"><spanclass="extract-syntax">val val -> val</span></span>, ... and so on: in other words, they can be called with
<ulclass="items"><li>● a call with no arguments results in <spanclass="extract"><spanclass="extract-syntax">x</span></span> and <spanclass="extract"><spanclass="extract-syntax">y</span></span> equal to 0 and 0;
</li><li>● a call with argument 7 results in <spanclass="extract"><spanclass="extract-syntax">x</span></span> and <spanclass="extract"><spanclass="extract-syntax">y</span></span> equal to 7 and 0;
</li><li>● a call with arguments 7 and 81 results in <spanclass="extract"><spanclass="extract-syntax">x</span></span> and <spanclass="extract"><spanclass="extract-syntax">y</span></span> equal to 7 and 81;
</li><li>● a call with three or more arguments has undefined results and may crash
the program altogether.
</li></ul>
<pclass="commentary firstcommentary"><aid="SP10"class="paragraph-anchor"></a><b>§10. Val, ref, lab and cast. </b>We have seen many examples already, but:
<ulclass="items"><li>●<spanclass="extract"><spanclass="extract-syntax">val V</span></span> allows us to use any simple value <spanclass="extract"><spanclass="extract-syntax">V</span></span> in any <spanclass="extract"><spanclass="extract-syntax">val</span></span> context. For
what is meant by a "simple" value, see <ahref="M-dpiti.html"class="internal">Data Packages in Textual Inter</a>.
</li><li>●<spanclass="extract"><spanclass="extract-syntax">ref R</span></span> allows us to refer to any variable, local or global, in a <spanclass="extract"><spanclass="extract-syntax">ref</span></span>
context.
</li><li>●<spanclass="extract"><spanclass="extract-syntax">lab L</span></span> allows us to refer to any label declared somewhere in the current
function body, in a <spanclass="extract"><spanclass="extract-syntax">lab</span></span> context.
</li></ul>
<pclass="commentary firstcommentary"><aid="SP11"class="paragraph-anchor"></a><b>§11. </b>The <spanclass="extract"><spanclass="extract-syntax">val</span></span> and <spanclass="extract"><spanclass="extract-syntax">ref</span></span> instructions both allow optional type markers to be placed,
<pclass="commentary">Where no type marker is given, the type is always considered <spanclass="extract"><spanclass="extract-syntax">unchecked</span></span>.
<pclass="commentary">Types of <spanclass="extract"><spanclass="extract-syntax">val</span></span> or <spanclass="extract"><spanclass="extract-syntax">ref</span></span> tend not to be checked or looked at anyway, so this
feature is currently little used. For many primitives, some of which are quite
polymorphic, it would be difficult to impose a typechecking regime anyway.
But the ability to mark <spanclass="extract"><spanclass="extract-syntax">val</span></span> and <spanclass="extract"><spanclass="extract-syntax">ref</span></span> with types is preserved as a hedge
against potential future developments, when Inter might conceivably be
tightened up to typecheck explicitly typed values.
<pclass="commentary">Similarly unuseful for the moment is <spanclass="extract"><spanclass="extract-syntax">cast</span></span>. This instruction allows us to
say "consider this value as if it had a different type". For example, if we
are using an enumerated type <spanclass="extract"><spanclass="extract-syntax">city</span></span>, we could read the enumeration values as
<pclass="commentary">but we keep <spanclass="extract"><spanclass="extract-syntax">cast</span></span> around as a hedge against future developments, in case we
ever want to typecheck strictly enough that <spanclass="extract"><spanclass="extract-syntax">val (int32) Odessa</span></span> is rejected
<pclass="commentary firstcommentary"><aid="SP12"class="paragraph-anchor"></a><b>§12. Labels and assembly language. </b>Like labels in C, these are named reference points in the code; they are written
<spanclass="extract"><spanclass="extract-syntax">.NAME</span></span>, where <spanclass="extract"><spanclass="extract-syntax">.NAME</span></span> must begin with a full stop <spanclass="extract"><spanclass="extract-syntax">.</span></span>. Labels are not values;
they cannot be stored, or computed with, or cast. They can only be used in
a <spanclass="extract"><spanclass="extract-syntax">lab</span></span> instruction.
</p>
<pclass="commentary firstcommentary"><aid="SP13"class="paragraph-anchor"></a><b>§13. </b>Two uses of <spanclass="extract"><spanclass="extract-syntax">inv</span></span> have already been covered: to call an Inter function, and
to invoke a primitive operation. The third is to execute an "assembly-language
opcode". What we mean by that is the direct use of the instruction set on the
target virtual machine we are expecting our program to run on.
</p>
<pclass="commentary">This has always been a feature of Inform 6 code. For example, some real-number
arithmetic functions in BasicInformKit are written to use heavy amounts of
Glulx assembly language, in order to access functionality not present in the
<spanclass="plain-syntax"> @</span><spanclass="identifier-syntax">fdiv</span><spanclass="plain-syntax"></span><spanclass="identifier-syntax">sp</span><spanclass="plain-syntax"></span><spanclass="constant-syntax">$40135D8E</span><spanclass="plain-syntax"></span><spanclass="identifier-syntax">log10val</span><spanclass="plain-syntax">; </span><spanclass="comment-syntax">$40135D8E is log(10)</span>
<pclass="commentary">Those "opcodes" beginning <spanclass="extract"><spanclass="extract-syntax">@</span></span> are part of the instruction set for the
Glulx virtual machine: real number arithmetic is impossible on the smaller
Z-machine, so we couldn't meaningfully compile this code to that platform,
and that is just is well because it has a completely different instruction
set of opcodes from Glulx anyway. Still, there's no denying that Inter code
using assembly immediately becomes less portable. This is why it is always
better to use Inter primitives if possible.
</p>
<pclass="commentary">Still, BasicInformKit must be compiled to Inter code somehow. We clearly need to
deal with those opcodes somehow. The standard Inform-provided kits use two
different sets of opcodes, as noted: the Z-machine and Glulx instruction sets.
One conceivable way to deal with this would have been to provide primitives
equivalent to every opcode in either set (or at least every opcode used in
the standard Inform kits). But that would hugely increase the set of primitives,
and also incur a certain amount of awkward repetition.
</p>
<pclass="commentary">Instead, the Inter specification goes to the opposite extreme. It makes no
assumptions about what assembly opcodes do, or do not, exist. Inter allows
absolutely anything, and would be quite happy to accept, say, <spanclass="extract"><spanclass="extract-syntax">inv @flytothemoon</span></span>,
even though this opcode does not exist in any known system of assembly language.<supid="fnref:1"><ahref="#fn:1"rel="footnote">1</a></sup>
</p>
<pclass="commentary">And so the above is in fact compiled to:
<pclass="commentary">And when the <ahref="../building-module/index.html"class="internal">building</a> module performed that compilation, it knew nothing
about <spanclass="extract"><spanclass="extract-syntax">@fdiv</span></span> and the rest: it just took on trust that this is meaningful.
</p>
<ulclass="footnotetexts"><liclass="footnote"id="fn:1"><pclass="inwebfootnote"><supid="fnref:1"><ahref="#fn:1"rel="footnote">1</a></sup> This can actually be useful, since it means people experimenting with new
hybrid forms of Inform can devise extra opcodes of their own.
<ahref="#fnref:1"title="return to text">↩</a></p></li></ul>
<pclass="commentary firstcommentary"><aid="SP14"class="paragraph-anchor"></a><b>§14. </b>So, how apparently generous: the Inter specification allows us to invoke
opcodes with arbitrary names. But that does not, of course, mean that those
opcodes can be compiled to code which does anything useful. The <ahref="../final-module/index.html"class="internal">final</a>
code-generation module probably won't know what to do with our hypothetical
<pclass="commentary">we see some general features of assembly language. Inter allows any number
of child instructions to be supplied — here, there are three. Since Inter knows
nothing about the meaning of <spanclass="extract"><spanclass="extract-syntax">@fdiv</span></span>, it has no way to know how many are
expected. They should all be usages of <spanclass="extract"><spanclass="extract-syntax">val</span></span>, <spanclass="extract"><spanclass="extract-syntax">lab</span></span>, or <spanclass="extract"><spanclass="extract-syntax">assembly</span></span>.
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">val</span></span> and <spanclass="extract"><spanclass="extract-syntax">lab</span></span> we have seen already. <spanclass="extract"><spanclass="extract-syntax">assembly</span></span> is a sort of punctuation
instruction which allows various oddball syntaxes of Z-machine or Glulx
assembly to be imitated in Inter. There are only seven possible <spanclass="extract"><spanclass="extract-syntax">assembly</span></span>
<ulclass="items"><li>●<spanclass="extract"><spanclass="extract-syntax">assembly stack</span></span> is probably the most common, either reading or writing
to the top of the virtual machine's stack.
</li><li>●<spanclass="extract"><spanclass="extract-syntax">assembly store_to</span></span> indicates that a storage location follows (either
<spanclass="extract"><spanclass="extract-syntax">assembly stack</span></span> or a local or global variable). This is only used in Z-machine
assembly language; Glulx assembly doesn't have this marker.
</li></ul>
<pclass="commentary">The other five apply only to "branch instructions", which perform some test
and then either return from the current function or make a jump to a label
(a "branch"), depending on the outcome of the test. By default the instruction
branches on a successful test. But alternatively it can:
<pclass="commentary">So for example the Z-machine instruction <spanclass="extract"><spanclass="extract-syntax">@random sp -> i;</span></span> compiles to Inter as:
<pclass="commentary">And note the use of <spanclass="extract"><spanclass="extract-syntax">val i</span></span>, not <spanclass="extract"><spanclass="extract-syntax">ref i</span></span>, even though the variable is being
written to here. Even Inter's normal rules of category checking do not apply