inform7/retrospective/6L02/I6T/Introduction.i6t

B/introt: Introduction Template.
 
@Purpose: A short introduction to the template and its organisation.
 
@-------------------------------------------------------------------------------

@p The Software Stack.
The term "software stack" is sometimes used to refer to the total
body of code running in a computer. As the word "stack" implies, there
tends to be a fairly clear division between components, and an architecture
in which one component is supported by another. The ground on which the
stack rests is the hardware. Then come device drivers, for communicating
with hardware, and a kernel of very low-level code to regulate who talks to
the hardware and when. On top of that are usually several layers of
operating-system facilities and utility programs, and on top of all of that
are Firefox, iTunes and other consumer programs which the user has made a
conscious decision to run. These top-level programs are visible, while the
lower layers are concealed from the user and are generally very reliable,
so it is easy to forget that they are there at all.

Similarly, when writing and testing a work with I7, it's easy to think that
the only code running is the code directly generated by the source text.
In fact, though, it runs inside a simulated computer called the virtual
machine (or VM), and the VM has a software stack just as other computers do.
Here the distinction between "program" and "operating system" is more
blurred, because it can afford to be -- the VM only ever has a single
program running, and is not connected to any valuable hardware or data, so
there is no need to protect the system's integrity from a malicious program,
or to protect one program from the failings of another running at the same
time. But there is still a recognisable software stack. From top to bottom,
the VM at run-time contains:

(a) The rules, text and tables written by the author of this specific work of IF;
(b) Material contributed by Extensions which the author chose to borrow from;
(c) Rules, phrases and other constructions made by the Standard Rules
extension, whose use is compulsory;
(d1) Infrastructure for rulebooks and code for maintaining a world model
common to all works of IF;
(d2) The code needed to manage complex data structures such as relations,
tables, texts, and so on;
(e) The interface to the VM, which is abstracted so that higher levels
do not need to know whether Glulx or the Z-machine is being used.

Here (d1) and (d2) are independent blocks, so the picture is roughly so:

\centerline{\it the player typing at a keyboard}

\centerline{(a) MATERIAL WRITTEN BY THE AUTHOR}

\centerline{(b) EXTENSIONS CHOSEN BY THE AUTHOR}

\centerline{(c) THE STANDARD RULES}

\centerline{(d1) MECHANICS OF PLAY\qquad (d2) DATA STRUCTURE SUPPORT}

\centerline{(e) VIRTUAL MACHINE INTERFACE}

\centerline{\it virtual machine "hardware"}

NI is not like a compiler for a conventional program, because it has to
conjure up the entire software stack whenever it compiles anything. (Until
2008, NI compiled code which ran on top of the traditional I6 library:
nowadays it compiles stand-alone code which never uses the |#Include|
directive. While it's true that the I6 compiler does add a very thin extra
layer of code itself -- the "veneer" -- in all other respects NI
specifies every single line of I6 code which makes up the eventual story
file.)

NI compiles layers (a), (b) and (c) from the I7 source text found in the
project file, in the Extensions installed by the user, and in the Standard
Rules extension which comes pre-installed. But parts (d1), (d2) and (e)
are almost exactly the same I6 code whatever may be sitting above them:
they are simply copied, with minor variations, from a large body of standing
code installed in the I7 application which is called the "template".

@p Segments and Paragraphs.
The template is divided into about 40 individual "segments", each stored
in its own file and with the |.i6t| file extensions. This stands for
"I6 template", because the code generated by NI is Inform 6 (I6) code.
What makes the file a template rather than being raw code is that it is
divided into named paragraphs which contain both commentary and also I6
code: when NI turns a template into the output code, the commentary
(and each paragraph heading) is stripped out.

See the Inform documentation for how to modify the template in use for
any particular project: I6 code can be added before, instead of or after
any named segment or paragraph, and in addition, it's possible to replace
entire segment files with your own versions stored in the Materials folder
for a project.

@p Architecture.
To recap, then, the template contributes the following parts of the software
stack:

\centerline{(d1) MECHANICS OF PLAY\qquad (d2) DATA STRUCTURE SUPPORT}

\centerline{(e) VIRTUAL MACHINE INTERFACE}

A more detailed version of this diagram organises its segments follows:

{\it NI Control}. |Main.i6t|, |Load-Core.i6t| (and several others like it),
|Output.i6t|, |Definitions.i6t|.

{\it Mechanics of Play I: Rules}. |OrderOfPlay.i6t|, |Actions.i6t|,
|Activities.i6t|, |Rulebooks.i6t|.

{\it II: Infrastructure}. |Parser.i6t|, |ListWriter.i6t|, |OutOfWorld.i6t|,
|WorldModel.i6t|, |Light.i6t|, |Tests.i6t|.

{\it III: Basic Services}. |Language.i6t|, |MStack.i6t|, |Chronology.i6t|,
|Printing.i6t|, |RTP.i6t|, |Utilities.i6t|.

{\it Data Structure Support I: Basics}. |Number.i6t|, |Time.i6t|,
|Tables.i6t|, |Sort.i6t|, |Relations.i6t|, |Figures.i6t|.

{\it II: Block Values}. |Text.i6t|, |RegExp.i6t|, |Char.i6t|,
|UnicodeData.i6t|, |StoredAction.i6t|, |Lists.i6t|, |RelationKind.i6t|,
|BlockValues.i6t|, |Flex.i6t|.

{\it Virtual Machine Interface}. |ZMachine.i6t| {\it or} |Glulx.i6t| and
|FileIO.i6t|.

To elaborate:

{\it NI Control}. As well as containing commentary and I6 code, template
files can also contain commands to tell NI to do something more interesting
than simply copying over material verbatim into its output. Four of the
segments use this ability a great deal: the remaining segments hardly use
it at all. These four segments therefore don't fit anywhere in the diagram
of the software stack above. "Main.i6t" controls the top-level logic of NI
and gives the sequence of operations; "Load-.i6t" specifies the basic
kinds of value known to NI -- numbers, times, texts, rulebooks and so on;
"Output.i6t" is essentially the arrangement used to join all the many
fragments of I6 from the template and the I7 source text into a single
end-to-end I6 program which will become the story file; "Definitions.i6t"
defines many named constants which are used across the template.

{\it Mechanics of Play I: Rules}. "OrderOfPlay.i6t" is the highest-level
description of what happens when a story file runs: it contains the I6
|Main| routine, and definitions of the primitive rules in the most
important rulebooks. 

"Actions.i6t" and "Activities.i6t" contain code which runs actions
and activities, respectively: these sit on top of "Rulebooks.i6t", which
performs general rulebook-running.

{\it Mechanics of Play II: Infrastructure}. "Parser.i6t" breaks down a
command typed by the player into a slate of variables which can be formed
into an action. "ListWriter.i6t" is a general-purpose service for printing
lists of objects satisfying various descriptions, and formatted in different
ways. "OutOfWorld.i6t" provides code to handle out-of-world actions not
needing direct access to VM internals: PRONOUNS and SUPERBRIEF, for instance.
"Tests.i6t" provides code for the testing commands -- TEST, ACTIONS,
SHOWME and so forth.

"WorldModel.i6t" contains code for performing object movements and the
like in such a way that the world model rules are preserved: it handles
component parts, decides touchability and so on. "Light.i6t" determines
the level of light and decides on visibility.

{\it Mechanics of Play III: Basic Services}. "Language.i6t" provides
English-language messages issued by template routines and the Standard
Rules during play: replacing this segment is the way to translate I7 story
files into other languages of play. (It's the equivalent of the old I6
"language definition files", and retains most of the same structure.)
"MStack.i6t" provides a small general-purpose memory stack.
"Chronology.i6t" performs the continuous monitoring required to ensure
that past-tense conditions work: for instance we can only determine whether
or not "the Black Door has been open" if we have spent the whole time so
far checking on whether it is open or not, and this is where the checking
is done. "Printing.i6t" handles paragraph-breaking, the printing of
object names with suitable articles attached, and miscellaneous other
printing needs. "RTP.i6t" issues run-time problem messages as needed:
these should appear only if the story file does something clearly illegal,
and point to bugs not yet removed from the author's code. "Utilities.i6t"
provides miscellaneous utility functions at a very low level, such as for
unsigned comparison of two numbers.

{\it Data Structure Support I: Basics}. Many kinds of value need no
maintenance, and little or no support. "Number.i6t" and "Time.i6t"
contain code to parse numbers and times of day from text typed by the
player, together with a few basic operations: for instance, the rounding
off of times of day. "Tables.i6t" provides access to table entries,
specified in a variety of direct and indirect ways; this makes use of
"Sort.i6t", which abstracts a choice of sorting algorithms for use on
tables and other I6 data. "Relations.i6t" provides code for testing and
asserting relations: the information about what is related to what else is
stored in a variety of different ways, depending on the relation, to make
best use of memory. "Figures.i6t" displays figures and plays back sound
effects, or rather, passes instructions to do so down to the VM.

{\it Data Structure Support II: Block Values}. Kinds of value can be divided
into the ordinary ones -- number, object, time and so on -- together with
"block values" such as text, stored action and list. Block values have
to be stored in dynamically allocated memory from a heap. It would be wasteful
to include all of this code, and to spare memory for the heap, if no block
values were actually needed, so the following segments are only compiled if
the source text makes specific reference to at least one block value.
"Text.i6t" manages strings of text, which can shrink or stretch to arbitrary
lengths: it makes use of "RegExp.i6t" for regular expression matching and
search-and-replace; and also of "Char.i6t" for code to deal with lower and
upper casing of letters, and "UnicodeData.i6t" to provide character set
details, mechanically converted from the Unicode 4.0 standard.
"StoredAction.i6t" manages stored actions: it can convert the current action
into a stored one, and also try a long-stored action so that it now takes
place. "Lists.i6t" manages the flexibly sized lists produced by values whose
kind is list of numbers, list of texts, list of lists of lists of stored
actions, and so forth: it can merge, insert, delete, resize, rotate, and
reverse lists, and makes use once again of "Sort.i6t" (q.v.) to sort them.

"BlockValues.i6t" provides the basic support for kinds of value which
can't be stored as single words of data.

At the lowest level, "Flex.i6t" manages flexible memory allocation as
required by "BlockValues.i6t": it organises the heap of unclaimed memory,
for instance, and maks allocations and deallocations when needed.

{\it Virtual Machine Interface}. Depending on the Settings used for the
I7 project being compiled, we either use "ZMachine.i6t" or "Glulx.i6t":
if Glulx, we also add "FileIO.i6t", which provides support for the
limited file-handling abilities offered by Glulx.

Properly speaking, there is one further template file: "Introduction.i6t".
It provides the commentary you are now reading, but has no other function,
contains no code, and is finished now anyway.