22. Advanced Phrases

Most of the time, what's created in an Inform source text will have a name which can be used as a value - sometimes openly so, sometimes not. In this book, we haven't gone out of our way to make that point, because there was no real need to do so. It's possible to make heavy use of rulebooks and write large-scale Inform projects without ever needing to use a rulebook's name as a value in its own right, for example. But if we want to create sophisticated extensions to Inform, or to use modern techniques such as functional and generic programming, we need to be fluent in the language of kinds.

Inform's language of kinds has four ingredients: base kinds, constructions, kind variables and kinds of kinds.

1. Base kinds. Inform provides the following base kinds for values:

together with a few others, such as "response" and "verb", to do with linguistic features.

And Inform allows us to create new base kinds either by making more specialised kinds of object:

Or by making new enumerations or arithmetical kinds:

2. Constructions. These are ways to make new kinds from existing ones. The construction most often used is "list of…". For any kind K, there is a kind called list of K. So the range of possible kinds in Inform is actually infinite, because:

are all different from each other. Inform has nine constructions, as follows:

Some of these have appeared in previous chapters, but in abbreviated form. For example, "rulebook" abbreviates "action based rulebook producing nothing", and "either/or property" is a synonym for "truth state valued property". The kinds of descriptions and phrases haven't been covered yet, but are coming up in the sections following.

These constructions can of course be combined:

Brackets can be used to clarify matters:

Nothing will make that a simple idea, but it's unambiguous and can be puzzled out with practice.

3. Variables. In a way, that's everything: there are just base kinds and constructions on them, and those construct every possible kind in Inform. But the language we use to describe kinds is larger than that, because it allows us to describe many kinds at once, in the same way that Inform reads the word "something" as applying to many objects at once, not as a single object.

Kind variables will be covered later in the chapter, but the idea is that:

allows us to describe the kinds acceptable in a phrase so that a wide range of possibilities are allowed. The above matches both:

The letter K in the definition stood for any kind; in the first use of "hunt" here, K turned out to be "number", and in the second it was "text". On the other hand Inform would reject:

because there is no kind K which can make this match the definition.

There are potentially 26 kind variables, A to Z, though it's customary to use them in the order K, L, M, …, and it's very rare to need more than two at a time.

4. Kinds of kind. Inform understands several names which look as if they are kinds, but actually aren't:

(Again, these are built in to Inform.) They are not kinds because they're just too loose and vague. Instead, they can be used in phrase definitions to match against multiple possibilities:

This makes "announce X" work for any value X which can be said. All the same, "sayable value" is not a kind. It could never be safe for this to be the kind of a variable, because Inform would never know what could be done with the contents (except that it could be printed out).

5. Secret inner workings. There isn't a fifth ingredient, but if there were, it would be a handful of names used in matching some of the core built-in phrases of Inform which have so-called inline i6 definitions. These are not intended for anyone else to use, and are just an internal convenience; they aren't publicly documented and might change without notice. They don't describe kinds at all, because they tell the matcher to look for something else instead. For instance, there's one called "condition", which means "match a condition rather than a value". They appear in red ink in the Phrasebook index.

In the chapter on Descriptions, we saw that a description can be any source text which describes one or more objects: it might be as simple as "the Corn Market", or as complicated as "open containers which are in dark rooms". More or less the only restriction is that it must be unambiguous as to what counts and what does not: "three containers" is ambiguous as a description because it does not say which three.

We've now seen several interesting tricks with descriptions. In fact, if D is a description, then

are all standard things to do. These examples make it look as if it must be possible to define phrases which act on descriptions, and in fact it is, because a description can be a value in itself. For example,

are values of kind "description of numbers" and "description of objects" respectively. In general, if K is any kind then "description of K" is also a kind. Here is how we might make use of that:

This makes "enumerate lighted rooms" run off a list of lighted rooms in a textual format different from the standard one produced by "say the list of lighted rooms". Inside the definition, "collection" can be used wherever a description might be used: here, for instance, we use it as the range for the repeat loop. (That's only possible because the range is limited in size: Inform wouldn't have allowed us to range through, say, all texts.)

Purely as a convenience, we can also write "member of" or "members of" in this context. For instance, in the enumerate definition, it would have been just as good to write "…running through the members of the collection…" in the repeat. (Similarly, we could write "number of members of the collection" or "a random member of the collection", which looks grammatically tidier than writing "number of the collection" or "random of the collection" - though in fact both of these do work.)

Finally, it's sometimes useful in an abstract situation to test

Given any two kinds K and L, the kind "phrase K -> L" is now a kind. (This is meant to look like a mathematical function arrow.) For example, the phrase defined by

has the kind "phrase number -> number". Brackets and commas are used if the phrase combines several values, so

has the kind "phrase (text, number) -> text". The word "nothing" is used if there are no values in, or no value out - thus

has kind "phrase nothing -> number", and

has the kind "phrase (length, length) -> nothing".

But how are we to get at these values? The answer is that we need to give a phrase a name in order to do so. For example:

This is the same syntax used to name rules, and the idea is the same. If we try "showme doubling", the result is

The main thing we want to do with a phrase is to apply it. So:

produces

There are versions of "applied to" for phrases applied to 0 to 3 values:

So for example:

For phrases which do not produce a value, we use "apply":

Thus:

The default value for "phrase K -> nothing" is a phrase which does nothing. For example, if we write:

then S is created holding the default phrase numbers -> nothing, and if we then try it out with:

we will indeed find that nothing happens.

The default value for "phrase K -> L" is a phrase which, no matter what value of K it applies to, always produces the default value of L. (It's a sort of equivalent of the zero function in mathematics - indeed that's exactly what it is, if L is "number".) So:

produces:

Here Q is set to the default phrase because we didn't give it any other value; it has the name we might expect ("default value of phrase number -> time") and it works as advertised, producing 9:00 am no matter what number is fed in.

More ambitiously, and supposing that we have a kind called "colour" whose first possible value is "red":

produces:

When a mass of computations has to be done, the traditional approach is to work through them in a "repeat" loop. One modern alternative, growing in popularity, is to form a list of inputs; then apply the same computation to each input in turn to form a list of results (this is called "mapping"); throw out any bad or unwanted results ("filtering"); and then combine the surviving results into a single composite answer ("reducing", though some programming languages call this "folding" or "accumulation"; it's a much-reinvented idea).

Inform provides all three of these fundamental list-processing operations. There is no special term for a "map", because Inform treats it as another case of "applied to".

More divertingly, suppose we define:

Then we can write a chain of three maps in succession:

to produce the value {"sx", "sxtn", "ght", "thrty-ght", "frtn"}.

Next, filtering. Here we make use of descriptions, in order to say what values will be allowed through the filter. So:

To get the full effect of filtering, we probably need to define an adjective or two. For example:

We can then write, for example:

which produces the list {"fifteen", "twenty-nine", "minus four"}.

Lastly, reduction. In order to combine a whole list of values, we need a phrase to combine any two. Here are some samples:

And here are some sample reductions:

sets X to 19, the highest of the values, and Y to the text "sxsxtnghtthrty-ghtfrtn". In each case a list has been reduced to a single value which somehow combines the contents.

Is map/filter/reduce always a good idea? Devotees point out that almost any computation can be thought of in this way, and in systems where the work has to be distributed around multiple processors it can be a very powerful tool. (There are programming languages without loops where it's essentially the only tool.) At its best, it reads very elegantly: one assembles all of the tools needed - definitions of doubling, lengthy, spelling out, concatenation and so on - and then each actual task is expressed in a single line at the end.

On the other hand, there are also times when this is a needlessly complicated disguise for what could more easily be done with a "repeat" loop, and also more efficiently since assembling and dismantling lists in memory does take some overhead time. So these list operations are not a panacea, but it's good to have them available.

The following looks quite innocent:

It's clear at a glance what this is intended to do, but at a second glance things aren't so straightforward. "Value" is not itself a kind - it's too big and unspecific. For instance, if we were to allow a variable to be just "a value", we could freely set it to 12 one minute and to "dahlias" the next, and such a variable would be dangerous since we would never know what could safely be done with its contents. A phrase like this one is called "generic", because it's not so much a single, actual phrase as a recipe to make phrases. (Inform automatically works out which kinds we need the phrase for, and creates a version of the phrase for those kinds.)

So "value" is not a kind, but a kind of kind. Inform has several of these:

These act as ways to say "a value of any kind matching this can go here". For example, "value" is a way to say "any kind at all"; "arithmetic value" is any kind which arithmetic can be performed on (any kind with the little calculator icon in the Arithmetic part of the Kinds index); and so on. If we write:

the restriction to "arithmetic value" means that although "double 3", "double 6 kg", etc., would be matched, "double the Entire Game" would not - you can't perform arithmetic on scenes. Similarly, it would have been tidier to write:

because then Inform will make it clearer why "say X twice" won't work if X is one of those rare values which it can't say (an activity, for instance).

The Kinds index shows which kinds match against which of these "kinds of kind". For instance, it shows that "time"

which means that time is something we can do arithmetic on, and can say.

The examples of generic phrases in the previous section were really only toy examples. Suppose we want a phrase which will take any arithmetic value and triple it. We could do something like this:

But this only prints the answer. Suppose we want to be given the value back, instead: how can we write the phrase? The trouble is that, not knowing the kind of V, we can't say what kind will be produced. We need a way of saying "the same kind comes out as went in". Inform expresses that using kind variables:

Here, K stands for any kind which matches "arithmetic value". Inform supports exactly 26 of these symbols, which are written A to Z, but it's customary to use K and L. (They can be written in the plural if we like: e.g., "list of Ks". But they must always use a capital letter: "list of k" is not allowed.)

Each symbol we use has to be declared in exactly one of the bracketed ingredients for the phrase - here, the declaration is "arithmetic value of kind K". That creates K and says that it has to be arithmetic; if we'd just said "value of kind K", it could have been anything. (Alternatively, we could use any of the kinds of kind in the previous section.)

For a more ambitious example, here is one way to define the mapping operation described earlier in the chapter:

Here we need two symbols to explain the complicated way that the values going in and out have to match up to each other. Note also the way that the temporary variable "result" is created:

Ordinarily, of course, "L" is not a kind. But within the body of a phrase definition, it means whatever kind L matched against.

When a symbol occurs several times in the same definition, subtle differences can arise according to which appearance is the declaration. These are not quite the same:

The difference arises - though very rarely - if V has some different kind compared to the list entries, but which can be used as if it were of that kind. For example,

Here V is a snippet, but L is a list of texts; and a snippet can be used in place of a text, but not vice versa. So this will match the second definition, because K is set to "text", but it won't match the first, where K is set to "snippet".

Sometimes a phrase needs to know what kind it's to work on, but isn't going to be given any particular value of it. For example:

Note that there's no hyphen, and no name for the bracketed token - it only sets K. We can then have, say:

But "assay texts" would throw a problem message, because we can't repeat through all possible texts. For a different reason,

would not be allowed - "open doors" is a description which applies to some doors and not others; it isn't a kind. It would make no sense to talk about "default value of open door", for example.

Recall the definition:

Suppose we then try to "slam shut the wall safe" at a time during play when the wall safe is already closed. An error message will then be printed during play, since there must be a mistake in the design. The combination of checking both when Inform builds the story file and then continuously when the story file is played guarantees that, in all cases, a varying item such as "box" in the definition of "To slam shut (box - open container)" always satisfies the condition laid down.

Instead suppose we also have the following definition:

We now have two definitions of "slam shut". Sometimes the box it's applied to will be closed, in which case only the second definition fits, and will be the one used. But if the box is open, both definitions fit. Which will happen? The rule is:

Rule 1 ensures that a definition involving "open container" takes priority over one which merely involves "container", for instance.

And therefore when the box is open, it's the more specific phrase to do with open containers which is invoked: so, with great panache, the box is slammed shut.

On the other hand, neither of these patterns is narrower than the other:

Some containers are transparent, some not; some transparent things are containers, some not. Rule 1 therefore does not apply, so it is the later of the two phrases which takes effect.

Another possible ambiguity occurs when a phrase might match two lexically different possibilities using the same words.

could be construed as a usage of either of these cases:

These of course have different effects - one produces the name with a definite article, the other just the name, so the difference is important.

The rule here is that whichever possibility contains the most words, in this case "say the (…)", takes precedence, because it's assumed to be a more specific form of the less wordy version.