mirror of
https://github.com/ganelson/inform.git
synced 2024-06-26 04:00:43 +03:00
402 lines
36 KiB
HTML
402 lines
36 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Secret features of Inform</title>
|
|
<link rel="stylesheet" href="https://www.w3schools.com/w3css/4/w3.css">
|
|
<link rel="stylesheet" href="https://www.w3schools.com/lib/w3-theme-black.css">
|
|
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.3.0/css/font-awesome.min.css">
|
|
|
|
<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">
|
|
<link href="docs-assets/ConsoleText-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"><span class="selectedlink">home</span></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><span class="unlink">secrets</span></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 'Secret features of Inform' generated by Inweb-->
|
|
<div class="breadcrumbs">
|
|
<ul class="crumbs"><li><b>Secret features of Inform</b></li></ul></div>
|
|
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>§1. </b>Undocumented features of Inform are no longer very secret (here you are reading
|
|
about them, after all), but they can be hard to find by raking through the source
|
|
code at random. What we mean by "undocumented features" here are capabilities
|
|
intentionally included in Inform, but not mentioned in any of the user-facing
|
|
documentation. That documentation used to be just the two books built in to the
|
|
apps (Writing with Inform and The Recipe Book), but those are now supplemented
|
|
by the manuals for the three command-line tools <a href="inform7/index.html" class="internal">inform7</a>, <a href="inbuild/index.html" class="internal">inbuild</a> and
|
|
<a href="inter/index.html" class="internal">inter</a>, which cover many features invisible from within the app and at
|
|
present available only for command-line users.
|
|
</p>
|
|
|
|
<p class="commentary">This page covers a handful of other features still, but which are intended mainly
|
|
for maintainers of Inform and may change at any time without notice.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>§2. </b>In working out what the compiler is doing (or has just done), the debugging log
|
|
is always the first thing to investigate. This a text file like a running
|
|
journal of what the compiler is doing; if it halts partway, either with problem
|
|
messages or an internal error, then the log is still written up to that point, and
|
|
can be revealing. The log can be viewed in the Inform apps, but usually
|
|
only if an "advanced" preference setting has been ticked. Once that is done,
|
|
the log appears as one of the tabs in the Results pane after each compilation
|
|
(successful or not). A similar preference setting enables the Inform 6 output
|
|
to be viewed, too, though of course only if the compiler gets that far.
|
|
</p>
|
|
|
|
<p class="commentary">The compiler is more instrumented than a first look at the log might suggest.
|
|
Most of its "debugging aspects" are switched off by default: if they were all
|
|
switched on, the log would be simply enormous. Each aspect has a textual name —
|
|
for example, "predicate calculus" shows the logical propositions formed and
|
|
simplified inside the compiler. (On each run, the bottom of the debugging log
|
|
lists the range of available aspects.) There are four ways to change what
|
|
aspects are switched on:
|
|
</p>
|
|
|
|
<ul class="items"><li>(1) Add a sentence like "Include predicate calculus in the debugging log." to
|
|
the source text for the project. For obvious reasons, this can only take effect
|
|
after sentences begin to be understood by the compiler, but in practice that's
|
|
early enough to be useful.
|
|
</li><li>(2) Add a command-line switch like <span class="extract"><span class="extract-syntax">-log predicate-calculus</span></span> (note that any
|
|
spaces in the name are replaced by hyphens) when running <span class="extract"><span class="extract-syntax">inform7</span></span> from the
|
|
command line. <span class="extract"><span class="extract-syntax">-log list</span></span> prints a list of the aspects.
|
|
</li><li>(3) If you're interested in how Inform is reading an assertion sentence (say, "A
|
|
ball is on the oak table"), try placing the special sentences <span class="extract"><span class="extract-syntax">*.</span></span> and <span class="extract"><span class="extract-syntax">*.</span></span>
|
|
either side of it. This switches on, and then off again, a convenient mode of
|
|
logging which shows (i) the primary verb, (ii) the full sentence diagram, (iii)
|
|
any logical propositions derived from that, and (iv) any inferences drawn as a
|
|
result. The log output is mostly self-explanatory, but the notation <span class="extract"><span class="extract-syntax">X =14 Y</span></span> (or
|
|
some other number) means that the assertion-maker is coupling the tree nodes <span class="extract"><span class="extract-syntax">X</span></span>
|
|
and <span class="extract"><span class="extract-syntax">Y</span></span> together in Case 14 of the <a href="assertions-module/4-ass.html" class="internal">Assertions (in assertions)</a> algorithm. For
|
|
example, in the log output from the following, you'll
|
|
see <span class="extract"><span class="extract-syntax">[ball/PROPER_NOUN_NT] =36 [is on/RELATIONSHIP_NT]</span></span>:
|
|
</li></ul>
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="identifier-syntax">The</span><span class="plain-syntax"> </span><span class="identifier-syntax">French</span><span class="plain-syntax"> </span><span class="identifier-syntax">Kitchen</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">a</span><span class="plain-syntax"> </span><span class="identifier-syntax">room</span><span class="plain-syntax">. </span><span class="identifier-syntax">An</span><span class="plain-syntax"> </span><span class="identifier-syntax">oak</span><span class="plain-syntax"> </span><span class="identifier-syntax">table</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">in</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> </span><span class="identifier-syntax">Kitchen</span><span class="plain-syntax">.</span>
|
|
<span class="plain-syntax">*. </span><span class="identifier-syntax">A</span><span class="plain-syntax"> </span><span class="identifier-syntax">ball</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">on</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> </span><span class="identifier-syntax">oak</span><span class="plain-syntax"> </span><span class="identifier-syntax">table</span><span class="plain-syntax">. *.</span>
|
|
</pre>
|
|
<ul class="items"><li>(4) If you're interested in how Inform is reading a phrase inside a rule or
|
|
phrase definition, and particularly in the running of the Dash typechecker, try
|
|
placing the special phrases <span class="extract"><span class="extract-syntax">***;</span></span> and <span class="extract"><span class="extract-syntax">***;</span></span> either side of whatever phrase
|
|
you're interested in. This shows exactly what code path through Dash is being
|
|
followed, and which kind conformances are being checked. For example:
|
|
</li></ul>
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="identifier-syntax">To</span><span class="plain-syntax"> </span><span class="identifier-syntax">consider</span><span class="plain-syntax"> (</span><span class="identifier-syntax">N</span><span class="plain-syntax"> - </span><span class="identifier-syntax">a</span><span class="plain-syntax"> </span><span class="identifier-syntax">number</span><span class="plain-syntax">):</span>
|
|
<span class="plain-syntax"> ***;</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">showme</span><span class="plain-syntax"> </span><span class="identifier-syntax">N</span><span class="plain-syntax"> </span><span class="identifier-syntax">times</span><span class="plain-syntax"> </span><span class="identifier-syntax">N</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> ***.</span>
|
|
</pre>
|
|
<ul class="items"><li>(5) It is also possible to write <span class="extract"><span class="extract-syntax">*** "predicate calculus";</span></span> to switch on just
|
|
a single named debugging aspect, so:
|
|
</li></ul>
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="identifier-syntax">Every</span><span class="plain-syntax"> </span><span class="identifier-syntax">turn</span><span class="plain-syntax">:</span>
|
|
<span class="plain-syntax"> *** </span><span class="string-syntax">"predicate calculus"</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">now</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> </span><span class="identifier-syntax">rock</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">in</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> </span><span class="identifier-syntax">bucket</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> ***.</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>§3. </b>Inform compiles first to an intermediate representation called Inter, and only
|
|
then compiles that in turn to its actual output. The Inter produced is then
|
|
discarded and normally never leaves memory, so it's invisible to the user. When
|
|
debugging, though, we sometimes want to see what it was.
|
|
</p>
|
|
|
|
<p class="commentary">Two special debugging aspects are provided for this.
|
|
</p>
|
|
|
|
<ul class="items"><li>● "Include Inter in the debugging log." will cause Inform (strictly speaking,
|
|
<a href="inter/index.html" class="internal">inter</a>) to write out the entire compiled Inter tree, in its textual form, into
|
|
the debugging log. Be warned that this is an awful lot of output, and will cause
|
|
a pause of an extra couple of seconds just to write.
|
|
</li><li>● "Include Inform Inter in the debugging log." will cause only the Inter
|
|
generated by Inform itself to be logged. Logged earlier in the run, this is a
|
|
smaller tree not yet containing material from kits such as BasicInformKit or
|
|
WorldModelKit. (Smaller, yes: small, no.)
|
|
</li><li>● If you're interested only in the code for a single phrase or rule, place the
|
|
pseudo-phrase <span class="extract"><span class="extract-syntax">*** "inter";</span></span> somewhere (anywhere — makes no difference) inside
|
|
its body. Note that this shows the Inter generated by the whole definition, and of
|
|
course that never happens if problem messages are generated instead. For example:
|
|
Every turn:
|
|
*** "inter";
|
|
now the rock is in the bucket.
|
|
</li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>§4. </b>The "Test... with... " feature of Inform is familiar to most users, since it's
|
|
used by almost all of the examples, usually with source text like:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="identifier-syntax">Test</span><span class="plain-syntax"> </span><span class="identifier-syntax">me</span><span class="plain-syntax"> </span><span class="identifier-syntax">with</span><span class="plain-syntax"> </span><span class="string-syntax">"examine box / take box"</span><span class="plain-syntax">.</span>
|
|
</pre>
|
|
<p class="commentary">Less well-known is that it can also run unit tests built in to the compiler. For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="identifier-syntax">Test</span><span class="plain-syntax"> </span><span class="identifier-syntax">description</span><span class="plain-syntax"> (</span><span class="identifier-syntax">internal</span><span class="plain-syntax">) </span><span class="identifier-syntax">with</span><span class="plain-syntax"> </span><span class="identifier-syntax">a</span><span class="plain-syntax"> </span><span class="identifier-syntax">number</span><span class="plain-syntax"> </span><span class="identifier-syntax">which</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">even</span><span class="plain-syntax">.</span>
|
|
</pre>
|
|
<p class="commentary">The test here is called <span class="extract"><span class="extract-syntax">description</span></span>. The marker <span class="extract"><span class="extract-syntax">(internal)</span></span> is what causes
|
|
this sentence to be read as an internal test case. Most tests, <span class="extract"><span class="extract-syntax">description</span></span>
|
|
among them, then expect some details to follow the word <span class="extract"><span class="extract-syntax">with</span></span>. In this case,
|
|
it's a description, "a number which is even", and what the test does is to
|
|
convert this to a logical proposition and print that proposition out.
|
|
</p>
|
|
|
|
<p class="commentary">What happens is not that <a href="inform7/index.html" class="internal">inform7</a> prints the test output to the console, or
|
|
even to the debugging log. It compiles the test output into the story file it is
|
|
generating, so that this is printed out when the story file runs. That may sound
|
|
needlessly indirect, but it's convenient both in the app and also for intest to
|
|
check. Add the above test sentence to some project, click Go in the app and you
|
|
see the result.
|
|
</p>
|
|
|
|
<ul class="items"><li>● <span class="extract"><span class="extract-syntax">Test description (internal)</span></span> converts a description such as "a number which
|
|
is even" to a proposition, showing the kinds of its variables and whether they
|
|
are free or bound:
|
|
</li></ul>
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">1. a number which is even</span>
|
|
<span class="plain-syntax"><< number(x) & even(x) >></span>
|
|
<span class="plain-syntax">x (free) - number.</span>
|
|
</pre>
|
|
<ul class="items"><li>● <span class="extract"><span class="extract-syntax">Test eps (internal)</span></span> tests just the EPS-file-maker part of the spatial map
|
|
index, and therefore isn't very useful.
|
|
</li><li>● <span class="extract"><span class="extract-syntax">Test evaluation (internal)</span></span> is used for verifying that literal arithmetic
|
|
quantities written in unusual notations are evaluated correctly. For example,
|
|
<span class="extract"><span class="extract-syntax">Test evaluation (internal) with 1 sq m divided by 20cm.</span></span>
|
|
</li><li>● <span class="extract"><span class="extract-syntax">Test headline (internal)</span></span> is not a test at all! It simply prints out a
|
|
dividing subheading in the test output — if a project makes hundreds of
|
|
internal tests then these subheadings make the output much more legible. For
|
|
example, <span class="extract"><span class="extract-syntax">Test headline (internal) with Unquantified relative clauses.</span></span> puts the
|
|
subheading "Unquantified relative clauses" at this point in the test output.
|
|
</li><li>● <span class="extract"><span class="extract-syntax">Test index (internal)</span></span> produces just one element of the index for test
|
|
purposes, as a chunk of HTML. For example, <span class="extract"><span class="extract-syntax">Test index (internal) with Mp.</span></span>
|
|
tests the <span class="extract"><span class="extract-syntax">Mp</span></span> (spatial map) element.
|
|
</li><li>● <span class="extract"><span class="extract-syntax">Test kind (internal)</span></span> is not much use, but can produce four different
|
|
listings of the kinds known to Inform, according to whether the <span class="extract"><span class="extract-syntax">with ...</span></span> text
|
|
is <span class="extract"><span class="extract-syntax">1</span></span>, <span class="extract"><span class="extract-syntax">2</span></span>, <span class="extract"><span class="extract-syntax">3</span></span> or <span class="extract"><span class="extract-syntax">4</span></span>.
|
|
</li><li>● <span class="extract"><span class="extract-syntax">Test pattern (internal)</span></span> is for testing that the rather complex grammar
|
|
used for "action patterns" in Inform is being parsed correctly. It has two
|
|
different forms: if the <span class="extract"><span class="extract-syntax">with ...</span></span> text begins with <span class="extract"><span class="extract-syntax">list</span></span> then a list of
|
|
actions is expected, and if not, then the text should describe a single action
|
|
(though possibly quite vaguely). For example:
|
|
</li></ul>
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="identifier-syntax">Test</span><span class="plain-syntax"> </span><span class="identifier-syntax">pattern</span><span class="plain-syntax"> (</span><span class="identifier-syntax">internal</span><span class="plain-syntax">) </span><span class="identifier-syntax">with</span><span class="plain-syntax"> </span><span class="identifier-syntax">asking</span><span class="plain-syntax"> </span><span class="identifier-syntax">Hans</span><span class="plain-syntax"> </span><span class="identifier-syntax">to</span><span class="plain-syntax"> </span><span class="identifier-syntax">try</span><span class="plain-syntax"> </span><span class="identifier-syntax">taking</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> </span><span class="identifier-syntax">counter</span><span class="plain-syntax">.</span>
|
|
<span class="identifier-syntax">Test</span><span class="plain-syntax"> </span><span class="identifier-syntax">pattern</span><span class="plain-syntax"> (</span><span class="identifier-syntax">internal</span><span class="plain-syntax">) </span><span class="identifier-syntax">with</span><span class="plain-syntax"> </span><span class="identifier-syntax">list</span><span class="plain-syntax"> </span><span class="identifier-syntax">looking</span><span class="plain-syntax"> </span><span class="identifier-syntax">or</span><span class="plain-syntax"> </span><span class="identifier-syntax">taking</span><span class="plain-syntax"> </span><span class="identifier-syntax">inventory</span><span class="plain-syntax"> </span><span class="identifier-syntax">in</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> </span><span class="identifier-syntax">presence</span><span class="plain-syntax"> </span><span class="identifier-syntax">of</span><span class="plain-syntax"> </span><span class="identifier-syntax">Hans</span><span class="plain-syntax"> </span><span class="identifier-syntax">in</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> </span><span class="identifier-syntax">Laboratory</span><span class="plain-syntax">.</span>
|
|
</pre>
|
|
<ul class="items"><li>● <span class="extract"><span class="extract-syntax">Test refinery (internal)</span></span> shows how assertion sentences are "refined". For
|
|
example, <span class="extract"><span class="extract-syntax">Test refinery (internal) with Jane is a woman.</span></span>
|
|
</li><li>● <span class="extract"><span class="extract-syntax">Test sentence (internal)</span></span> is very like <span class="extract"><span class="extract-syntax">description</span></span>, but expects a whole
|
|
sentence, that is, something with no free variables rather than one:
|
|
</li></ul>
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">1. everyone likes Peter</span>
|
|
<span class="plain-syntax"><< ForAll x IN< person(x) IN> : amity(x, 'peter') >></span>
|
|
<span class="plain-syntax">x - object.</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>§5. </b>inform7 has a test suite of roughly 2000 test cases, some of which are large
|
|
and elaborate. Running through this test suite must be done at the command line
|
|
(indeed, the tests are not shipped inside the apps, only as part of the inform
|
|
Git repository). The <a href="../../intest/index.html" class="internal">intest</a> tool is provided for this, and reading the
|
|
<a href="../../intest/index.html" class="internal">intest</a> manual is a good place to begin. A test suite to be operated by
|
|
<a href="../../intest/index.html" class="internal">intest</a> is configured by a <span class="extract"><span class="extract-syntax">*.intest</span></span> file, and the full details of how the
|
|
I7 suite works are laid out in <span class="extract"><span class="extract-syntax">inform/inform7/Tests/inform7.intest</span></span>. About 25%
|
|
of the tests are the Examples from the manuals; another 25% more or less
|
|
systematically poke at language features, and edge cases which proved tricky in
|
|
the past; and the remaining 50% test that the compiler produces correct problem
|
|
messages.
|
|
</p>
|
|
|
|
<p class="commentary">Tests in the suite can be divided up into the following categories:
|
|
</p>
|
|
|
|
<ul class="items"><li>● Those in <span class="extract"><span class="extract-syntax">inform/inform7/Tests/Test Basic</span></span> are Basic Inform tests, run
|
|
through the compiler in <span class="extract"><span class="extract-syntax">-basic</span></span> mode, meaning that the language features for
|
|
interactive fiction, the command parser and the world model are all missing.
|
|
(These tests run relatively quickly as a result.) With no command parser loop,
|
|
such programs run by printing some output and stopping.
|
|
</li><li>● Those in <span class="extract"><span class="extract-syntax">inform/inform7/Tests/Test Cases</span></span> are standard tests of Inform not
|
|
related to Examples in the documentation. This is a mixed bag which has
|
|
accumulated over the years.
|
|
</li><li>● Those in <span class="extract"><span class="extract-syntax">inform/resources/Documentation/Examples</span></span> are the examples from the
|
|
manuals — this makes up about 25% of the whole suite, and in practice tests
|
|
interactive-fiction features of Inform pretty systematically, besides ensuring
|
|
that the examples in the manual do what we claim that they do. Note that the
|
|
name of an example shown in the manual may not be the same as its Intest case
|
|
name: thus, "Bruneseau's Journey" has test case name <span class="extract"><span class="extract-syntax">Candle</span></span>. But you can use
|
|
intest's <span class="extract"><span class="extract-syntax">-find</span></span> feature if stuck:
|
|
</li></ul>
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">../intest/Tangled/intest</span><span class="ConsoleText-plain-syntax"> inform7</span><span class="ConsoleText-identifier-syntax"> -find</span><span class="ConsoleText-plain-syntax"> Bruneseau</span>
|
|
<span class="ConsoleText-plain-syntax">Test cases matching 'Bruneseau':</span>
|
|
<span class="ConsoleText-plain-syntax">Candle = Bruneseau's Journey</span>
|
|
</pre>
|
|
<ul class="items"><li>● A few test cases are extracted and run from the extension documentation for
|
|
extensions supplied with Inform, such as "Locksmith".
|
|
</li><li>● Those in <span class="extract"><span class="ConsoleText-extract-syntax">inform/inform7/Tests/Test Internals</span></span> run internal test cases (see
|
|
above).
|
|
</li><li>● Those in <span class="extract"><span class="ConsoleText-extract-syntax">inform/inform7/Tests/Test Makes</span></span> are a small number of
|
|
demonstration programs which are hybrids running partly in C, partly in Inform.
|
|
These are built using individual makefiles — hence the name. The test cases
|
|
correspond to the example projects in the documentation on this: see
|
|
<a href="inform7/M-cifc.html" class="internal">Calling Inform from C (in inform7)</a>.
|
|
</li><li>● Those in <span class="extract"><span class="ConsoleText-extract-syntax">inform/inform7/Tests/Test Problems</span></span> are Inform source texts
|
|
expected to cause the compiler to halt with a problem message: they check that
|
|
it does in fact do so, and that the problem is correctly worded. See below.
|
|
</li><li>● Those in <span class="extract"><span class="ConsoleText-extract-syntax">inform/inform7/Tests/Test Releases</span></span> are for testing the release
|
|
instructions which <a href="inform7/index.html" class="internal">inform7</a> generates and supplies to <a href="inblorb/index.html" class="internal">inblorb</a>. (Note that
|
|
<a href="inblorb/index.html" class="internal">inblorb</a> itself is not run in these tests: only the instructions are checked.
|
|
But <a href="inblorb/index.html" class="internal">inblorb</a> has its own test suite, in which of course it is run.)
|
|
</li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>§6. </b>Each individual test has a name. The following naming conventions apply:
|
|
</p>
|
|
|
|
<ul class="items"><li>● No two different cases have the same name.
|
|
</li><li>● If a test case name ends in <span class="extract"><span class="ConsoleText-extract-syntax">-G</span></span>, it will be compiled to Glulx and run
|
|
through the <span class="extract"><span class="ConsoleText-extract-syntax">dumb-glulxe</span></span> interpreter.
|
|
</li><li>● If it ends <span class="extract"><span class="ConsoleText-extract-syntax">-C</span></span>, it will be compiled to ANSI C, then run through a C
|
|
compiler to produce a stand-alone executable, and that is what will then be run.
|
|
</li><li>● If the name has neither of these endings, it will be compiled to the
|
|
Z-machine and run through the <span class="extract"><span class="ConsoleText-extract-syntax">dumb-frotz</span></span> interpreter.
|
|
</li><li>● Names beginning <span class="extract"><span class="ConsoleText-extract-syntax">BIP-</span></span> are Basic Inform tests which systematically verify
|
|
that language features work. These tests mostly come in all three flavours, so
|
|
for example <span class="extract"><span class="ConsoleText-extract-syntax">BIP-Let</span></span>, <span class="extract"><span class="ConsoleText-extract-syntax">BIP-Let-G</span></span> and <span class="extract"><span class="ConsoleText-extract-syntax">BIP-Let-C</span></span> check the same functionality
|
|
when code-generating for the Z-machine, for Glulx and for C. (In a few cases to
|
|
do with real arithmetic, there's no Z-machine test.)
|
|
</li><li>● Names beginning <span class="extract"><span class="ConsoleText-extract-syntax">PM_</span></span> are tests of problem messages: for example,
|
|
<span class="extract"><span class="ConsoleText-extract-syntax">PM_ConflictedReturnKinds</span></span> or <span class="extract"><span class="ConsoleText-extract-syntax">PM_PropertiesEquated</span></span>. Almost every I7 problem
|
|
message has a code-name like this, and a corresponding test case. Though these
|
|
code-names are not displayed on the Results page shown in the Inform app when a
|
|
misbehaving project generates these problems, the code-names of any issued
|
|
problem messages are listed in the debugging log, which also gives a file and
|
|
line number reference to the Inform source code showing where the problem was
|
|
generated.
|
|
</li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>§7. </b>The complete test suite takes a long time to run — typically 10 to 11 minutes
|
|
on the author's computer in 2022, even running 16 simultaneous tests on
|
|
different cores. It's sometimes more practical to run subsets of the suite. For
|
|
example, if debugging the part of Inform which generates C code from Inter,
|
|
there's no point verifying the problem messages or the 900 or so tests which
|
|
compile to Z or Glulx.
|
|
</p>
|
|
|
|
<ul class="items"><li>● The Intest keywords <span class="extract"><span class="ConsoleText-extract-syntax">cases</span></span>, <span class="extract"><span class="ConsoleText-extract-syntax">examples</span></span>, and <span class="extract"><span class="ConsoleText-extract-syntax">problems</span></span> catch just the Test
|
|
Cases, document examples, and Test Problems cases respectively.
|
|
</li><li>● There are also "test groups" stored in <span class="extract"><span class="ConsoleText-extract-syntax">inform/inform7/Tests/Groups</span></span>. See
|
|
the <a href="../../intest/index.html" class="internal">intest</a> documentation for how to set up these groups, though they're
|
|
pretty self-explanatory.
|
|
</li></ul>
|
|
<p class="commentary">For example, these three commands:
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">../intest/Tangled/intest</span><span class="ConsoleText-plain-syntax"> inform7 all</span>
|
|
<span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">../intest/Tangled/intest</span><span class="ConsoleText-plain-syntax"> inform7 problems</span>
|
|
<span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">../intest/Tangled/intest</span><span class="ConsoleText-plain-syntax"> inform7 :calculus</span>
|
|
</pre>
|
|
<p class="commentary">run the full test suite, just the Test Problems cases, and just the <span class="extract"><span class="ConsoleText-extract-syntax">:calculus</span></span>
|
|
group respectively. (Note the colon.) Particularly useful groups include <span class="extract"><span class="ConsoleText-extract-syntax">:c</span></span>,
|
|
which performs every test involving C output, and <span class="extract"><span class="ConsoleText-extract-syntax">:basic</span></span>, which performs the
|
|
whole BIP sub-suite.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>§8. </b>Internal errors in <a href="inform7/index.html" class="internal">inform7</a> generate the infamous "abject failure" problem
|
|
message. These are essentially failed assertions in the compiler, but they cause
|
|
a clean termination of the process with exit code 1, just as any more orthodox
|
|
problem message would. A Results page in HTML is generated normally. As a
|
|
result, they're no harder for the GUI apps to deal with than any other sort of
|
|
problem would be.
|
|
</p>
|
|
|
|
<p class="commentary">Harder to handle is an actual crash of the <a href="inform7/index.html" class="internal">inform7</a> executable, in which an
|
|
abrupt exit occurs where no problem message is generated: say if it dereferences
|
|
a null pointer, or divides by zero. This of course should never happen, but we
|
|
want the GUI apps to be able to cope if it does. And in order to test that, we
|
|
give <a href="inform7/index.html" class="internal">inform7</a> the ability to simulate such crashes.
|
|
</p>
|
|
|
|
<p class="commentary">This is done with three words too unspeakable to write, the "secret hieroglyphs
|
|
of dread power". They're actually not much to look at. The first is:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="identifier-syntax">ni</span><span class="plain-syntax">--</span><span class="identifier-syntax">crash</span><span class="plain-syntax">--1 </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">a</span><span class="plain-syntax"> </span><span class="identifier-syntax">room</span><span class="plain-syntax">.</span>
|
|
</pre>
|
|
<p class="commentary">This crashes out with exit code 1. The second and third are much the same, but
|
|
are written <span class="extract"><span class="extract-syntax">ni--crash--10</span></span> and <span class="extract"><span class="extract-syntax">ni--crash--11</span></span>, giving exit codes 10 and 11.
|
|
(On MacOS, at least, these are what result from derefencing a bad pointer or
|
|
overflowing the stack through infinite recursion.)
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>§9. </b>If Inform does crash, or throw an internal error, or even simply produce an
|
|
unwanted problem message, but in circumstances which are unclear, then it's
|
|
useful to see a stack backtrace at the point where the error came to light.
|
|
This is where Intest's <span class="extract"><span class="extract-syntax">-debug</span></span> feature is useful. For example:
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">../intest/Tangled/intest</span><span class="ConsoleText-plain-syntax"> inform7</span><span class="ConsoleText-identifier-syntax"> -debug</span><span class="ConsoleText-plain-syntax"> Acidity</span>
|
|
</pre>
|
|
<p class="commentary">This runs the test <span class="extract"><span class="ConsoleText-extract-syntax">Acidity</span></span>, but with the <span class="extract"><span class="ConsoleText-extract-syntax">inform7</span></span> executable running in
|
|
the lldb debugger (on MacOS, anyway), and moreover with it set to deliberately
|
|
cause a division by zero after any problem message is generated. This forces
|
|
<span class="extract"><span class="ConsoleText-extract-syntax">inform7</span></span> to exit into the debugger, at which point a stack backtrace can be
|
|
seen (in lldb, anyway) by typing <span class="extract"><span class="ConsoleText-extract-syntax">bt</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">Of course, Inform is unlikely to crash on any of the tests in the regular test
|
|
suite: more likely you have some wacky source text causing a crash or unwanted
|
|
problem message, but which isn't in the suite. In that case, though, you just
|
|
need to create a temporary test case for it — the author likes to keep this as the
|
|
file <span class="extract"><span class="ConsoleText-extract-syntax">inform/inform7/Tests/Test Cases/temp.txt</span></span>, and then:
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">../intest/Tangled/intest</span><span class="ConsoleText-plain-syntax"> inform7</span><span class="ConsoleText-identifier-syntax"> -debug</span><span class="ConsoleText-plain-syntax"> temp</span>
|
|
</pre>
|
|
<p class="commentary">does the trick. But be sure not to add this temporary file to the repository.
|
|
</p>
|
|
|
|
<!--End of weave-->
|
|
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|