DM4 §A3: Library routines

## §A3 Library routines

The Inform library files contain about three hundred routines, almost all of which are “private” in the sense that they are difficult for designers to use, not useful anyway, and subject to change without notice as the library is maintained and rewritten. The routines in this appendix are those which are “open to the public”. Designers are encouraged to make use of them.

`Achieved(tasknum)` | see §22

Signals to the library that task number `tasknum` has been achieved, so that points may be awarded if it has not been achieved before.
No return value

`AfterRoutines()` | see §6

This should be called in the action routine, such as `TakeSub`, of a group 2 action, such as `Take`, once the action has taken place but before anything is printed. It runs through the `after` rules as laid out in §6.
Routine returns `true` if the action has been interrupted by some other rule, `false` if not.

`AllowPushDir()` | see §15

Used only inside the `before` rule for a `PushDir` action, this routine signals to the library that the attempt to push an object from one place to another should be allowed.
No return value

`Banner()` | see §21

Prints the game banner. Normally unnecessary, but should be used soon after if your game suppresses the banner at the `Initialise` stage.
No return value

`ChangePlayer(obj,flag)` | see §21

Cause the player at the keyboard to play as the given object `obj`, which must provide a `number` property. If the `flag` is `true`, then subsequently print messages like “(as Ford Prefect)” in room description headers. This routine, however, prints nothing itself.
No return value

`CommonAncestor(obj1,obj2)` | see §3

A routine used internally by the library when working out visibilities, and which might as well be available for public use. Returns the nearest object in the object tree which (directly or indirectly) contains both `obj1` and `obj2`, or else returns `nothing` if no such object exists. For instance if Bedquilt contains bottle and the player is carrying a lamp, the common ancestor of lamp and bottle is Bedquilt.
Routine returns The common ancestor or `nothing`.

`DictionaryLookup(word,length)` | see §34

Takes the word stored character by character in the array `word->0`, `word->1`, …, `word->(length-1)` and looks it up in the story file's dictionary.
Routine returns The dictionary value (e.g., `'t'`, `'a'`, `'k'`, `'e'` will return `'take'`) or zero if the word isn't in the dictionary.

`GetGNAOfObject(obj)` | see §37

Determines the gender-number-animation of the short name of the given object `obj`.
Routine returns The GNA, which is a number between 0 and 11: see table of GNA values in §34.

`HasLightSource(obj)` | see §19

Determines whether or not `obj` “has light”, i.e., casts light outward to objects containing `obj`: see §19 for a more exact definition.
Routine returns `true` or `false`.

`IndirectlyContains(obj1,obj2)` | see §3

The condition `obj2 in obj1` only tests whether `obj2` is directly contained in `obj1`, so that `lamp in player` would fail if the lamp were in a rucksack carried by the player. `IndirectlyContains(player,lamp)` would return `true`. Formally, the test is whether `obj2` is a child of `obj1`, or is a child of a child of `obj1`, or … and so on. See also the library routine `CommonAncestor` above.
Routine returns `true` or `false`.

`IsSeeThrough(obj)` | see §19

Determines whether or not `obj` “is see-through”, i.e., allows light to pass through it. An object is see-through if it has `transparent`, or `supporter`, or `enterable` (unless it is also a closed `container`).
Routine returns `true` or `false`.

`Locale(obj,tx1,tx2)` | see §26

Prints out the paragraphs of room description which would appear if `obj` were the room: i.e., prints out descriptions of objects in `obj` according to the usual rules. After describing the objects which have their own paragraphs, a list is given of the remaining ones. The string `tx1` is printed if there were no previous paragraphs, and the string `tx2` otherwise. (For instance, you might want “On the ledge you can see” and “On the ledge you can also see”.) After the list, nothing else is printed, not even a full stop.
Routine returns The number of objects printed in the list, possibly zero.

`LoopOverScope(R,actor)` | see §32

Calls routine `R(obj)` for each object `obj` in scope for the given `actor`. If no `actor` is given, the actor is assumed to be the player.
No return value

`LTI_Insert(position,character)` | see §36

Inserts the given `character` at the given `position` in the standard library array `buffer` used to hold the text typed by the player, moving subsequent text along to make room. (This is protected against overflowing the buffer.)
No return value

`MoveFloatingObjects()` | see §8

“Floating objects” is Inform library jargon for “objects which use `found_in` to be present in several locations at once”. This routine adjusts the positions of objects across the whole game, ensuring that they are consistent with the current states of the property `found_in` and the attribute `absent`, and should be called after any game event which has changed these states.
No return value

`NextWord()` | see §28

Finds the next dictionary word in the player's input, that is, the word at position `wn` in the input, moving the word number `wn` on by one. (The first word is at position 1.)
Routine returns The dictionary value, or 0 if the word is not in the dictionary or if the word stream has run out, or the constant `THEN1__WD` if the “word” was a full stop, or the constant `COMMA_WORD` if it was a comma.

`NextWordStopped()` | see §28

Finds the next dictionary word in the player's input, that is, the word at position `wn` in the input, moving the word number `wn` on by one. (The first word is at position 1.)
Routine returns The dictionary value, or 0 if the word is not in the dictionary, or the constant `THEN1__WD` if the “word” was a full stop, or the constant `COMMA_WORD` if it was a comma, or −1 if the word stream has run out.

`NounDomain(o1,o2,type)`

This routine is one of the keystones of the parser, but see also `ParseToken` below: the objects given are the domains to search through when parsing, almost always the location and the actor, and the `type` indicates a token. The only tokens safely usable are: `NOUN_TOKEN`, for `noun`, `HELD_TOKEN`, for `held` and `CREATURE_TOKEN`, for `creature`. The routine parses the best single object name it can from the current position of `wn`.
Routine returns `nothing` for “no match”, or the object matched for a success, or the constant `REPARSE_CODE` to indicate that it had to ask a clarifying question: this reconstructed the input drastically and the parser must begin all over again. `NounDomain` should only be used by general parsing routines and these should always return `GPR_REPARSE` if `NounDomain` returned `REPARSE_CODE`, thus passing the buck upwards.

`ObjectIsUntouchable(obj,flag)` | see §32

Determines whether any solid barrier, that is, any `container` that is not `open`, lies between the player and `obj`. If `flag` is `true`, this routine never prints anything; otherwise it prints a message like “You can't, because … is in the way.” if any barrier is found.
Routine returns `true` if a barrier is found, `false` if not.

`OffersLight(obj)` | see §19

Determines whether or not `obj` “offers light”, i.e., contains light so that its contents are visible to each other: see §19 for a more exact definition.
Routine returns `true` or `false`.

`ParseToken(tokentype,tokendata)` | see §31

This is the library's own “general parsing routine”, and parses the word stream against the specified token. Because some of these tokens require too much setting-up work to parse, and anyway are not very useful, only two token types are open to the public. If `tokentype` is `ELEMENTARY_TT`, then `tokendata` must have one of the following values: `NOUN_TOKEN`, `HELD_TOKEN`, `MULTI_TOKEN`, `MULTIHELD_TOKEN`, `MULTIEXCEPT_TOKEN`, `MULTIINSIDE_TOKEN`, `CREATURE_TOKEN` and `NUMBER_TOKEN`. Alternatively, `tokentype` can be `SCOPE_TT` and `tokendata` must then be a “scope routine”.
Routine returns `GPR_FAIL` if parsing fails; `GPR_PREPOSITION` if a match is made but results in no data; `GPR_NUMBER` if a match is made, resulting in a number; `GPR_MULTIPLE` if a match is made, resulting in a multiple object; `GPR_REPARSE` if the parser has had to rewrite the text being parsed and would now like parsing to begin again from scratch; otherwise, an object which the parser has matched against the text.

`PlaceInScope(obj)` | see §32

Used in “scope routines” (only) when `scope_stage` is set to 2 (only). Places `obj` in scope for the token currently being parsed. No other objects are placed in scope as a result of this, unlike the case of `ScopeWithin`.
No return value

`PlayerTo(obj,flag)` | see §21

Moves the player to `obj`, which can either be a location or something `enterable`. If `flag` is `false`, then run a `Look` action to print out a room description: but if `flag` is `true`, print nothing, and if `flag` is 2, print a room description but abbreviate it if the room has been visited before.
No return value

`PronounNotice(obj)` | see §33

Resets the pronouns to the object `obj`. This means that all pronouns which can match against the object are set equal to it: for instance, “Aunt Jemima” would match `'her'` but not `'it'`, “the grapes” would match `'them'` and so on.
No return value

`PronounValue(pronoun)` | see §33

Finds the current setting of `pronoun`, which has to be the dictionary value of a legal pronoun in the current language: in the case of English, that means `'it'`, `'him'`, `'her'` or `'them'`.
Routine returns The setting, or `nothing` if it is unset.

`ScopeWithin(obj)` | see §32

Used in “scope routines” (only) when `scope_stage` is set to 2 (only). Places the contents of `obj` in scope for the token currently being parsed, and applies the rules of scope recursively so that contents of see-through objects are also in scope, as is anything added to scope.
No return value

`SetPronoun(pronoun,obj)` | see §33

Changes the current setting of `pronoun`, which has to be the dictionary value of a legal pronoun in the current language: in the case of English, that means `'it'`, `'him'`, `'her'` or `'them'`.
No return value

`SetTime(time,rate)` | see §20

Set the game clock (a 24-hour clock) to the given `time` (in seconds since the start of the day), to run at the given rate r: r = 0 means it does not run, if r > 0 then r seconds pass every turn, if r < 0 then −r turns pass every second.
No return value

`StartDaemon(obj)` | see §20

Makes the daemon of the object `obj` active, so that its `daemon` routine will be called at the end of every turn.
No return value

`StartTimer(obj,period)` | see §20

Makes the timer of the object `obj` active. Its `time_left` property is set initially to `period`, then decreased by 1 at the end of every turn in which it was positive. At the end of the turn when it was zero, the timer is stopped and the object's `time_out` property is called.
No return value

`StopDaemon(obj)` | see §20

Makes the daemon of the object `obj` no longer active, so that its `daemon` routine will no longer be called at the end of every turn.
No return value

`StopTimer(obj)` | see §20

Makes the timer of the object `obj` no longer active, so that its `time_left` routine will no longer be decreased and `time_out` will not be called as originally scheduled.
No return value

`TestScope(obj,actor)` | see §32

Tests whether the object `obj` is in scope to the given `actor`. If no `actor` is given, the actor is assumed to be the player.
Routine returns `true` or `false`.

`TryNumber(wordnum)` | see §28

Tries to parse the word at `wordnum` as a non-negative number, recognising decimal numbers and English ones from “one” to “twenty”.
Routine returns −1000 if it fails altogether, or the number, except that values exceeding 10000 are rounded down to 10000.

`UnsignedCompare(a,b)`

The usual `>` condition performs a signed comparison, and occasionally, usually when comparing addresses in memory of routines or strings, you need an unsigned comparison.
Routine returns Returns 1 if a > b, 0 if a = b and −1 if a < b, regarding a and b as unsigned numbers between 0 and 65535. (That is, regarding `-1` as 65535, `-2` as 65534, …, `-32768` as 32768.)

`WordAddress(wordnum)` | see §28

Find where word number `wordnum` from what the player typed is stored.
Routine returns The `->` array holding the text of the word.

`WordInProperty(word,obj,prop)` | see §34

Tests whether `word` is one of the dictionary values listed in the array given as the property `prop` of object `obj`. (Most often used to see if a given dictionary word is one of the `name` values.)
Routine returns `true` or `false`.

`WordLength(wordnum)` | see §28

Find the length (number of letters) of the word numbered `wordnum` from what the player typed.
Routine returns The length.

`WriteListFrom(obj,st)` | see §27

Write a list of `obj` and its siblings, with the style being `st`. To list all the objects inside `X`, list from `child(X)`. The style is made up by adding together some of the following constants:

`NEWLINE_BIT` | New-line after each entry
`INDENT_BIT` | Indent each entry according to depth
`FULLINV_BIT` | Full inventory information after entry
`ENGLISH_BIT` | English sentence style, with commas and ‘and’
`RECURSE_BIT` | Recurse downwards with usual rules
`ALWAYS_BIT` | Always recurse downwards
`TERSE_BIT` | More terse English style
`PARTINV_BIT` | Only brief inventory information after entry
`DEFART_BIT` | Use the definite article in list
`WORKFLAG_BIT` | At top level (only), only list objects which have the `workflag` attribute
`ISARE_BIT` | Prints “ is " or “ are " before list
`CONCEAL_BIT` | Misses out `concealed` or `scenery` objects

`YesOrNo()`

Assuming that a question has already been printed, wait for the player to type “yes”, “y”, “no” or “n”.
Routine returns `true` for “yes” or “y”, `false` for “no” or “n”.