I6 Template Layer

Wordsize-Dependent Definitions.

The old I6 library used to confuse Z-vs-G with 16-vs-32-bit, but we try to separate these distinctions here, even though at present the Z-machine is our only 16-bit target and Glulx our only 32-bit one. The WORDSIZE constant is the word size in bytes, so is the multiplier between -> and --> offsets in I6 pointer syntax.

(1) NULL is used, as in C, to represent a null value or pointer. In C, this is conventionally 0, but here it is the maximum unsigned value which can be stored, pointing to the topmost byte in the directly addressable memory map; this means it is also -1 when regarded as a signed twos-complement integer, but we write it as an unsigned hexadecimal address for clarity's sake.

(2) WORD_HIGHBIT is the most significant bit in the VM's data word.

(3) IMPROBABLE_VALUE is one which is unlikely but still possible to be a genuine I7 value. The efficiency of some algorithms depends on how well chosen this is: they would ran badly if we chose 1, for instance.

(4) MAX_POSITIVE_NUMBER is the largest representable positive (signed) integer, in twos-complement form.

(5) REPARSE_CODE is a magic value used in the I6 library's parser to signal that some code which ought to have been parsing a command has in fact rewritten it, so that the whole command must be re-parsed afresh. (Returning this value is like throwing an exception in a language like Java, though we don't implement it that way.) A comment in the 6/11 library reads: "The parser rather gunkily adds addresses to REPARSE_CODE for some purposes. And expects the result to be greater than REPARSE_CODE (signed comparison). So Glulx Inform is limited to a single gigabyte of storage, for the moment." Guilty as charged, but the gigabyte story file is a remote prospect for now: even megabyte story files are off the horizon. Anyway, it's this comparison issue which means we need a different value for each possible word size.

Z-Machine Definitions.

The Z-machine contains certain special constants and variables at fixed position in its "header"; the addresses of these are given below. See The Z-Machine Standards Document, version 1.0, for details.

INDIV_PROP_START is the lowest number of any "individual property", an I6 internal quantity defined by the compiler when the target is Glulx but not for Z.

Glulx Definitions.

We make similar header definitions for Glulx. Extensive further definitions, of constants needed to handle the Glk I/O layer, can be found in the "Infglk" section of Glulx.i6t; they are not used in the rest of the template layer, and would only get in the way here.

Powers of Two.

I6 lacks support for logical shifts, and the Z-machine opcodes which bear on this are not always well supported, so the I6 library has traditionally used a lookup table for the values of 2^15-n where 0 ≤ n ≤ 11.

Text Styles.

These are the styles of text distinguished by the template layer, though they are not required to look different from each other on any given VM. The codes are independent of the VM targetted, though in fact they are equal to Glulx style numbers as conventionally used. (The Z-machine renders some as roman, some as bold, but for instance makes HEADER_VMSTY and SUBHEADER_VMSTY indistinguishable to the eye.) Glulx's system of styles is one of its weakest points from an IF author's perspective, since it is all but impossible to achieve the text effects one might want – boldface, for instance, or red text – and text rendering is almost the only area in which it is clearly inferior to the Z-machine, which it was designed to replace. Still, using these styles when we can will get the most out of it, and for unornamental works Glulx is fine in practice.

Colour Numbers.

These are traditional colour names: quite who it was who thought that azure was the same colour as cyan is now unclear. Colour is, again, not easy to arrange on Glulx, but there is some workaround code.

Window Numbers.

Although Glulx can support elaborate tessalations of windows on screen (if the complexity of handling this can be mastered), the Z-machine has much more limited resources in general, so the template layer assumes a simple screen model: there are just two screen areas, the scrolling main window in which commands are typed and responses printed, and the fixed status line bar at the top of the screen.

Paragraphing Flags.

I am not sure many dictionaries would countenance "to paragraph" as a verb, but never mind: the reference here is to the algorithm used to place paragraph breaks within text, which uses bitmaps composed of the following.

Descriptors in the Language of Play.

The following constants, which must be different in value from the number of any I6 attribute, are used in the LanguageDescriptors table found in the definition of the language of play.

Run-Time Problem Numbers.

The enumeration sequence here must correspond to that in the file of RTP texts, which is used to generate the HTML pages displayed by the Inform user interface when a run-time problem has occurred. (For instance, the file of RTP texts includes the heading "P17 - Can't divide by zero", equivalent to RTP_DIVZERO being 17 below.) There is no significance to the sequence, which is simply the historical order in which they were added to I7.

Template Activities.

These are the activities defined in the Standard Rules. Most, though not all, are carried out by explicit function calls in the template layer, which is why we need their ID numbers: note that NI assigns each activity a unique ID number on creation, counting upwards from 0, and that it processes the Standard Rules before any other source text. (These numbers must correspond both to those in the source of NI, and to the creation sequence in the Standard Rules.)

Template Rulebooks.

Rulebooks are created in a similar way, and again are numbered upwards from 0 in order of creation. These are the ones used in the template layer. (These numbers must correspond both to those in the source of NI, and to the creation sequence in the Standard Rules.)

Kind IDs.

These are filled in automatically by NI, and have the same names as are used in the NI source (and in the Load-.i6t sections): for instance NUMBER_TY.

Parser Error Numbers.

The traditional ways in which the I6 library's parser, which we adopt here more or less intact, can give up on a player's command. See the Inform Designer's Manual, 4th edition, for details.

Scope Searching Reasons.

The parser makes use of a mechanism for searching through the objects currently "in scope", which basically means visible to the actor who would perform the action envisaged by the command being parsed. It is sometimes useful to behave differently depending on why this scope searching is being done, so the following constants enumerate the possibilities.

I6's EACH_TURN_REASON, REACT_BEFORE_REASON and REACT_AFTER_REASON have been removed from this list as no longer meaningful; hence the lacuna in numbering.

Token Types.

Tokens are the indecomposable pieces of a grammar line making up a possible reading of a command; some are literal words, others stand for "any named object in scope", and so on. The following codes identify the possibilities. The *_TOKEN constants must not be altered without modifying the I6 compiler to match (so, basically, they must not be altered at all).

GPR Return Values.

GRP stands for "General Parsing Routine", an I6 routine which acts as a grammar token: again, see the Inform Designer's Manual, 4th edition, for details.

In Library 6/11, GPR_NOUN is defined as $ff00, but this would fail on Glulx: it needs to be $ffffff00 on 32-bit virtual machines. It appears that GPR_NOUN to GPR_CREATURE, though documented in the old Inform Translator's Manual, were omitted when this was consolidated into the DM4, so that they effectively disappeared from view. But they might still be useful for implementing inflected forms of nouns, so we have retained them here regardless.

List Styles.

These constants make up bitmaps of the options in use when listing objects.

Lengths Of Time.

Inform measures time in minutes.

Empty Text.

The I6 compiler does not optimise string compilation: if it needs to compile the (packed, read-only) string "exemplum" twice, it will compile two copies. This is slightly wasteful on memory, though in practice the loss is not enough for us to care. But we do want to avoid this in I7 because, to make string-sorting algorithms more efficient, we want direct numerical comparison of packed addresses to be equivalent to string comparison: and that means the text "exemplum" has to be compiled once and once only. There's a general mechanism for this in NI, but the single case most often needed is the empty text, since this is the default value for text variables and properties: we give it a name as follows.

Empty Table.

Similarly: the default value for the "table" kind of value, a Table containing no rows and no columns.

Empty Set.

The falsity proposition describes the empty set of objects, and is the zero value for the "description" kind of value.

Score and Rankings Table.

The following command tells NI to compile constant definitions for MAX_SCORE and/or RANKING_TABLE, in cases where there are scores and rankings. If there's no score, we define MAX_SCORE as 0 anyway; if there's no ranking table, RANKING_TABLE is left undefined, so that we can #ifdef this possibility later.

Template Attributes.

An I6 attribute is equivalent to an I7 "either/or property", though the latter are not always translated into I6 attributes because the Z-machine has only a limited number of attributes to use. Here, we define attributes used by the template.

Many concepts in I6 correspond directly to their successors in I7, even if details may vary. (Value properties are a case in point.) Attributes are the opposite of this: indeed, no I6 concept is more fragmented in its I7 equivalents. All but one of the old I6 library attributes are still used (the general attribute, for miscellaneous use, has been removed: it more often invited abuse than use); and a few new attributes have been added. But they are used for a variety of purposes. Some do correspond exactly to either/or properties in I7, but others are a sort of signature for I7 kinds. (So that for I7 use they are read-only.) Others still are used by the template layer as part of the implementation of services for I7, but are not visible to I7 source text as storage.

Template Properties.

As remarked above, these more often correspond to value properties in I7. To an experienced I6 user, though, the death toll of abolished I6 properties in I7 is breathtaking: in alphabetical order, after, cant_go, daemon, each_turn, invent, life, number, orders, react_after, react_before, time_left, time_out, when_closed, when_off, when_on, when_open. In May 2008, the direction properties n_to, s_to, e_to, ..., out_to joined the list of the missing.

The losses are numerous because of the shift from I6's object orientation to I7's rule orientation: information about the behaviour of objects is no longer thought of as data attached to them. At that, it could have been worse: a few unused I6 library properties have been retained for possible future use.

Loss of Life.

The loss of life is so appalling that I6 will not even compile a story file which doesn't define the property number life (well, strictly speaking, it checks the presence of constants suggesting the I6 library first, but the template layer does define constants like that). We define it as a null constant to be sure of avoiding any valid property number; I6 being typeless, that enables the veneer to compile again. (The relevant code is in CA__Pr, defined in the veneer.c section of I6.)

Action Count.

The number of valid I7 actions in existence.

Fake Actions.

Though sometimes useful for I6 coding tricks, fake actions – action numbers not corresponding to any action, but different from those of valid actions, and useable with a number of action syntaxes – are not conceptually present in I7 source text. They can only really exist at the I6 level because I6 is typeless; in I7 terms, there is no convenient kind of value which could represent both actions and fake actions while protecting each from confusion with the other.

See the Inform Designer's Manual, 4th edition, for what these are used for.

The following fake actions from the I6 library have been dropped here: ##LetGo, ##Receive, ##ThrownAt, ##Prompt, ##Places, ##Objects, ##Order, ##NotUnderstood.

Formal Parameters.

These are needed for efficient run-time ambiguity resolution.