Inform 7 Home Page / Documentation

§11.3. Pattern matching

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

To admire (item - an object):
    say "You take a long look at [item].".

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

admire the diamonds;
admire Mr Cogito;
admire the honey sandwich;

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

admire "blue cheese";
admire 63;

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' Reveal.png, 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,

After dropping something in the Auction House:
    admire the noun.

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:

To slam shut (box - an open container):
    say "With great panache, you slam shut [the box].";
    now the box is closed.

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

slam shut the Dutch armoire;

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:

With great panache, you slam shut the Dutch armoire.

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:

To grant (bonus - a number) points:
    increase the score by the bonus.

To grant (bonus - 7) points:
    say "You shiver uncontrollably."

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

grant 7 points;
grant seven points;

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

grant six points;

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:

To grant (bonus - a number) points: ...
To grant (bonus - 7) points: ...

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:

To grant (bonus - a number) point/points: ...

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:

To grant (bonus - a number) point/points/--: ...

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

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

arrow-up.png Start of Chapter 11: Phrases
arrow-left.png Back to §11.2. The phrasebook
arrow-right.png Onward to §11.4. The showme phrase

Writing a phrase, with several variant forms, whose function is to follow a rule several times.

**ExampleFerragamo Again
Using the same phrase to produce different results with different characters.