11. Phrases

Phrases are instructions to Inform to do something, or to decide whether something is true or false, or to produce a value, or to say something. Inform has around 350 phrases built-in, and the chapters so far have already defined about 100 of those. In this chapter we'll see some key phrases for organising instructions of what to do, and also see how to define entirely new phrases.

Just to run through the four sorts of phrase with examples:

(a) Phrases to do something. These are the ones used in the body of a rule. For example,

Rules like this begin with a "preamble", the beginning part which tells Inform when or how they apply, and then follow on with a list of instructions - here, just two of them. "move … to …" and "say …" are both phrases. Inform provides about 130 of these built-in. It's actually not quite true that they all do something, because one of them is:

(b) Phrases to decide whether a condition is true. These are the ones which can be used in an "if":

Not all conditions come from phrases. For example, "if the front door is closed" and "if Peter is wearing the sandals" have meanings which come from the verbs "to be" and "to wear". Inform provides about 60 built-in conditions, which give a friendly wording for questions which would be lengthy or difficult to write in any other way.

(c) Phrases to decide a value. For example:

produces a number, 4 of course, and can be used whenever a number is expected. Inform provides about 100 built-in phrases like this.

(d) Text substitutions. These are actually just phrases whose definition begins with "To say …". Example:

Inform provides about 60 built-in text substitutions.

The Phrasebook is Inform's collection of recognised phrases, and it can always be browsed using the Index panel of the same name. Even the smallest project has a good-sized phrasebook, since it contains all of the built-in phrases. But most projects also define new phrases of their own.

Here is a simple definition of a new phrase:

Inform allows us to use whatever conventions of layout we prefer, but it's customary to use indentation like this, dividing off the preamble from the phrases which follow. As can be seen, definitions of new phrases look very like rules.

What makes this definition a simple one is that the wording is fixed. The only way to use this would be from another phrase or rule, like so:

In the next section we'll see how to give more complicated definitions which, like "move … to …", allow for the wording to change with the circumstances.

In this section, let's make the following new phrase:

This does very little, of course, but it does allow the wording to be different each time the phrase is used:

and our single definition covers all of these possibilities. The bracketed part of the definition, "(item - an object)", tells Inform to expect an object in that position, and Inform enforces this carefully. So this definition might tell Inform what "admire the barricade" means, but not what

mean. Unless some other definition sorts the matter out, Inform will reply to uses like this with a Problem message:

Problem. You wrote 'admire 63' , but '63' has the wrong kind of value: a number rather than an object.

The object does not need to be named literally, but can be anything which works out to be an object: for instance,

which Inform allows because "noun", here, is a name for the object which is being acted on.

Inform decides which definition to apply in a process called "pattern matching".

The bracketed part of the example definition has the form "(name - kind)". The definition only applies if the text supplied agrees with the "kind" part - for instance, the diamonds agreed with "object", but 63 did not. If the definition does apply, then the Inform works through the rest of the phrase using "name" to mean whatever value matched. For example:

When this phrase is followed, "box" means whatever open container the pattern-matcher found when it was called for. For example, if Inform reads

then it acts on this by following the definition of "slam shut …", using the Dutch armoire object as the value of "box", so it prints:

and renders it closed.

In fact any description can be given in the definition, and that includes a single, specific value. For instance, we could define:

which would withhold this unlucky bounty. That would mean that:

would each produce uncontrollable shivers, because Inform uses the definition applying to the number 7; but

would increase the score by 6. In general Inform always follows the principle that more specific definitions take priority over more general ones. So although the definitions:

both apply to the case of "grant 7 points", Inform uses the second, because it's the more specific of the two possibilities.

Sometimes it will not be possible to tell if the value supplied meets the requirements until the story is actually playing. If, at run-time, no definition fits some phrase which has to be carried out, a run-time problem message is produced.

Finally, and more straightforwardly, we can specify variations in wording using slashes between alternative words in a "To …" definition. For instance:

allows the final word to be either "point" or "points". Slashes like this can only be used with literal words, not bracketed values, and give alternative forms only of a single word at a time; the alternative "--" means "no word at all", and thus makes it optional:

makes "grant 3" do the same as "grant 3 points".

If we need more variation than that, we should make more than one definition.

We've already seen the SHOWME command, which can be typed into the Story panel to look at the state of something, usually a thing or room. SHOWME is a testing command which has no effect once the work is released; eventual players can't use it.

Inform also has a phrase called "showme", which works in much the same way:

"showme" is a convenient way to see what's going on inside a phrase which isn't behaving as expected, or to find out the kind of a value. Here are some trickier examples. Suppose our design includes:

If we then try this:

we get, when the story starts up,

Why is this an "object", when we know that the key is actually a "thing"? After all, if we "showme key" instead, we get:

The answer is a little technical: it's because Inform guarantees that the matching key is always an object, but not that it's always a thing - it just happens to be a thing at the moment. There's not really a contradiction, because a "thing" is a kind of "object", so in fact the key is both. If we try "showme matching key", we get something like this:

which is even more technical - people never need to print the names of abstract property names during play, so Inform doesn't provide any good way of doing it. It is reduced to printing out an internal ID number ("property 23") instead of the name ("matching key"). This can't be helped: "showme" is a way to lift the lid and see what's going on inside Inform's machinery, and some of the corners are dark.

All the same, "showme" can be very useful in tinkering with rules to make them work properly. It prints nothing at all in a Release version of a project, so it's impossible for these private notes to be shown accidentally to our eventual readers.

A variety of "conditions" have already appeared in this documentation. A condition is a phrase which describes a situation which might be true, or might be false, and examples might include:

These are all examples of sentences, formed by putting nouns either side of a verb, and clearly a wide range of conditions can be written this way. But there are also a few special conditions built into Inform which have a fixed wording, and test questions difficult to address with ordinary sentences. For instance:

Another example of a condition not easily written as a sentence is:

Whether it's put to the player like this or not, testing a condition is really asking a question, and there is always a yes/no answer. In Inform this answer is not usually a value (unlike in some other computer programming languages), but it can be made into one.

Firstly, we need a special kind of value to hold answers like this. It's called "truth state", and it has just two possible values, written as "true" and "false". We then need:

As another example, in most stories this:

…will produce a line:

In short, "truth state" is a kind of value like any other. That means it can be the kind of a variable:

and it can similarly be used in table columns, lists, or anywhere else where values are allowed.

Inform's most powerful phrases are those which control the others, making them repeat, or be skipped.

The sense of an "if" can be reversed by using the word "unless" instead:

"Unless" is clearly unnecessary, but it can be a good way to make the source text easier for humans to read.

As we have seen, there are many different forms of condition in Inform. They usually take a form quite like an assertion sentence, except that they're questions and not statements of fact. For example:

Questions like this are checked by Inform to see if they make sense. The following doesn't, for instance:

This produces the baffled reply:

Problem. In the line 'if 10 is a door, say "Huzzah!"' , I can't determine whether or not '10 is a door', because it seems to ask if a number is some sort of door.

In practice it is not enough to apply "if" to a single phrase alone: we want to give a whole list of phrases to be followed repeatedly, or to be followed only if a condition holds.

We do this by grouping them together, and there are two ways to do this. One is as follows:

Here we group two phrases together under the same "if". Note that the comma has been replaced by a colon, and that the indentation in the list of phrases shows how they are grouped together. In the example above, the source moves two tabs in from the margin; the maximum allowed is 25.

Indentation is the convention used in this manual and in the examples, but not everybody likes this Pythonesque syntax. So Inform also recognises a more explicit form, in which the beginning and ending are marked with the words "begin" and "end":

(Pythonesque because it's a style popularised by the programming language Python, named in turn after "Monty Python's Flying Circus".)

We often need code which does one thing in one circumstance, and another the rest of the time. We could do this like so:

but this is not very elegant, and besides, what if the action we take when N is 2 changes N so that it becomes something else?

Instead we use "otherwise":

If the chain of conditions being tried consists of checking the same value over and over, we can use a convenient abbreviated form:

This form of "if" layout is not allowed to use "begin" and "end" instead of indentation: it would look too messy, and would scarcely be an abbreviation. It is also not allowed to use "unless" instead of "if", because the result would be too tangled to follow.

The next control phrase is "while", which has the form:

We must be careful not to commit mistakes like the following:

which, as sure as eggs is eggs (which is very sure indeed), writes out

forever. (Inform won't prevent this: we will find out the hard way when the story is played.) While we would probably never write anything so blatant as that, the mistake is all too easy to commit in disguised form. We should never design a loop, as repetitions like this are called, without worrying about if and when it will finish.

As with "if", we can use "begin" and "end" instead of a tabulated layout if we want to --

(The "begin" of an "if" must of course match an "end if", not an "end while", and so on.)

Experience shows that it is much more legible to lay out "while" loops as blocks, even in these rare cases when only a single phrase forms the body of the block.

The other kind of loop in Inform is "repeat". The trouble with "while" is that it's not obvious at a glance when or whether the loop will finish, and nor is there any book-keeping to measure progress. A "repeat" loop is much more predictable, and is more or less certain to finish.

There are several forms of "repeat", of which the simplest is similar to the old FOR/NEXT loop from the home-computer programming language BASIC, for those with long memories:

We are allowed to "nest" loops, that is, to put one inside another.

If we then write

then the result is

Thus the innermost phrase, the say which mentions "y", happens 25 times.

Whenever dealing with numbers in Inform we may need to remember that if the Settings for the project are set to use the Z-machine, the range is restricted to -32768 up to 32767. Repeating with a counter up to exactly 32767 is hazardous, because the counter can never break through this barrier: it's infinity, so far as Inform is concerned, and that can cause the repetitions to go on forever. (On Glulx, numbers can be very much larger.)

Inform is not used very much for numerical work, so the kind of repeat loop described in the previous section is not much used. Inform's natural domain is really the world of things and rooms, so the following kind of repeat is much more useful.

As with counting the "number of …" objects satisfying some property, we can run through a wide variety of possibilities - any description whose range is possible for Inform to search. For example:

The following lists the whereabouts of all men in lighted rooms:

One small note of caution: if what the "repeat" loop does is to change the things being repeated through, changing in particular whether items not yet reached will qualify to be repeated through, the results can be unexpected. Rather than writing "repeat with X running through D", it may be safer to try "while there is D (called X)", though note that this will only finish if X is always changed so that it no longer qualifies.

So "repeat" and "while" phrases cause a block of other phrases to be repeated, over and over. The number of repetitions and the flow of "control" has so far been controlled only by the way the original loop was described.

But in fact it's also possible to change this from inside the block being repeated, using these:

In Monopoly terms, "next" is "Advance to Go" rather than "go directly, do not pass Go, do not collect $200" - the next iteration begins with the variable, if there is one, having cleanly moved on to the next value, just as if the loop had been run through in the normal way. ("Next" is called "continue" in a fair number of programming languages, so Inform issues a specific problem message to help people who forget this.)

Now that it's possible to define phrases where different things are done in different circumstances, we sometimes want to halt early. This is what "stop" is for.

There are sometimes several slightly different ways to perform a given task but which have substantially the same definition. In the following example:

…a phrase has been set up which can be used in three ways:

Note that commas must be used to divide these "phrase options" from the rest of the text of the phrase. Within the definition of the phrase, the option's name is a valid condition, and

tests whether it is set; we can also test if it is not set using:

A more substantial example from the Standard Rules is given by a phrase used mostly for internal, technical reasons:

Note that this phrase is allowed to have multiple options specified, whereas "go hiking" above was not: this is because it was defined thus:

The significant difference is the word "and/or" instead of "or", which signals that more than one option can apply at a time.

A variable, as we have seen, is a name for a value which changes, though always remaining of the same kind. For instance, if "target" is a number variable (or "number that varies") then it may change value from 2 to 4, but not from 2 to "fishknife".

To make complicated decisions, phrases often need to remember values on a temporary basis. We have already seen this for the counter in a "repeat" loop, which exists only inside that loop, and then is no longer needed.

We can also make temporary variables using "let":

Temporary variables made by "let" are only temporarily in existence while a phrase is being carried out. Their values often change: we could say

for instance, or indeed we could "let x be 10" and then "let x be 11". But although we are allowed to change the value, we are not allowed to change the kind of value. The name "x" must always have the same kind of value throughout the phrase to which it belongs, so the following will not be allowed:

(The difference between using "let" and "now" here is that "let" can create a new temporary variable, whereas "now" can only alter things already existing: on the other hand, "now" can change many other things as well, whereas "let" applies only to temporary variables.)

We can create new conditions by defining a phrase with "to decide whether" (or equivalently "to decide if"):

If the player is indeed in darkness, the decision is "yes" because the "decide yes" stops the process right there. We can now write, for instance,

In fact, "danger lurks" is now a condition as good as any other, and can be used wherever a condition would be given. Rules can apply only "when danger lurks", for instance.

We can also supply definitions of adjectives like this. So far, new adjectives have been defined like so:

If we want to give a definition which involves more complex logic, we can use a special form allowing us to make arbitrary decisions. In this longer format, the same definition would look like so:

Here "it" refers to the supporter in question. Note that there are now two colons in this sentence, one after "Definition", the other after the clause being defined. But that apart, it's a phrase like any other: it must end in "yes" or "no" just as the "danger lurks" example must. "Decide no" and "decide yes" are needed so often that they can be abbreviated by leaving out "decide":

A condition is a yes/no decision, but we can also take decisions where the result is a value. Suppose we want to create a concept of the "grand prize", which will have different values at different times in play. Each time the "grand prize" is referred to, Inform will have to decide what its value is, and the following tells Inform how to make that decision:

Note that we have to say what kind the answer will be: here it's a kind of thing called "treasure" (which we're supposing has already been created), and as it turns out only two treasures are ever eligible anyway (we're also supposing that the plover's egg and the silver bars are treasures already created, of course). And note also that the phrase must in all cases end with a "decide on …" to say what the answer is:

Now that we have "grand prize" created, we can use it just as we would use any other value, so for instance:

As this is something of a dialect difference between English speakers, "what" and "which" are synonymous here, i.e., we could equally well write something like:

(A phrase to decide if something-or-other is exactly the same thing as a phrase to decide a truth state, and indeed, if we want to then we can use "decide on T", where T is a truth state, in its definition. For instance:

"Decide on true" is exactly equivalent to the more normally used "decide yes", and of course it is optional. The last line is more interesting since it effectively delegates the answer to another condition.)

A point which has come up several times in recent chapters is that enumerated kinds of value have a natural ordering. For example, if we write:

…then we not only have seven possible values, we have put them into a sequence, in order of their naming. We can't perform arithmetic on colours, of course, but we can perform comparisons on them. Thus "red < yellow" is true, while "green >= violet" is not. (More on comparisons in the chapter on Numbers and Equations, which also covers arithmetic.)

It's also sometimes useful to get at the sequence directly. First, the two ends:

And now how to step forward and back: