Inform 7 Home Page / Documentation


§18.33. Reading a command

1. When it happens. When reading a command from the keyboard.

2. The default behaviour. Print the prompt text; wait for the player to type something and press return. Reject an entirely blank line, and treat a command beginning "oops" as a correction to the previous one. This is a fairly complicated business, so it is probably best not to change the "for" rules for this activity: "before", and especially "after", are another matter. (Note, however, that if Inform does reject a blank line and ask for another then this all happens inside the "for" rules: no "after" occurs after the blank line, nor does a "before" happen before the second attempt by the player. It is all a single round of the activity, not two.)

3. Examples. (a) To lead absolute beginners in gently:

Before reading a command while the turn count is 1, say "(This is your chance to say what the protagonist should do next. After the '>', try typing 'take inventory'.)"

(b) The following responds politely but firmly if the player tries to type "please look", say, instead of just "look":

paste.png After reading a command:
    if the player's command includes "please":
        say "Please do not say please.";
        reject the player's command.

To explain. Fragments of what the player has typed are called snippets: "the player's command" is the entire thing. We can test if a snippet matches a given pattern like so:

if (snippet) matches (topic):

This condition is true if the given snippet exactly matches the specification. Example:

if the player's command matches "room [number]", ...

will be true if the command is ROOM 101, but not if it's EXPLORE ROOM 7.

if (snippet) does not match (topic):

This condition is true if the given snippet does not exactly match the specification.

if (snippet) includes (topic):

This condition is true if the given snippet includes words matching the specification, either at the beginning, in the middle, or at the end. Example:

if the player's command includes "room [number]", ...

will be true if the command is ROOM 101, EXPLORE ROOM 7, or ROOM 22 AHOY, but not if it's VISIT ROOM GAMMA 7.

if (snippet) does not include (topic):

This condition is true if the given snippet does not include any run of words which matches the specification.

Lastly, we took drastic action with another new phrase:

reject the player's command

This phrase should be used only in rules for the "reading a command" activity. It tells Inform not to bother analysing the text further, but to go back to the keyboard. (No time passes; no turn elapses; nothing happens in the si ulated world.)

(c) An improved version takes commands like "please drop the coin" and strips "please" from them, but then allows them to proceed normally:

paste.png After reading a command:
    if the player's command includes "please":
        say "(Quelle politesse! But no need to say please.)";
        cut the matched text.

"Matched text" is a snippet containing the words which matched against the pattern in the most recent "includes" condition, so in this case it contains just the single word "please". Two phrases allow snippets to be altered:

replace (snippet) with (text)

This phrase should be used only in "after" rules for the "reading a command" activity; it replaces the snippet of command, usually the "matched text" found immediately before, with the given text. Example:

if the player's command includes "room [number]":
    replace the matched text with "office".

cut (snippet)

This phrase should be used only in "after" rules for the "reading a command" activity; it removes the snippet of command. Example:

if the player's command includes "or else":
    cut the matched text.

Note that "replace" and "cut" can only be used in "after reading a command" rules: not when an action has been chosen and has gone ahead into its rulebooks. Once the "reading a command" activity has finished, the command is final.

(d) To make the word "grab" an abbreviation for "take all":

paste.png After reading a command:
    if the player's command matches "grab", replace the player's command with "take all".

("Snippet" is actually a kind of value, so we could say "Ah, you typed '[the player's command]'!" or some such if we liked. But in practice only three snippets are likely to be useful: the two mentioned above, "player's command" and "matched text", and the "topic understood", used when matching the "[text]" token in command grammar.)

(e) Finally, we can make still more detailed alterations to the text of the command using the techniques presented in the Advanced Text chapter. For instance:

change the text of the player's command to (text)

This phrase should be used only in "after" rules for the "reading a command" activity; it replaces the current command text entirely. Example:

After reading a command:
    let T be "[the player's command]";
    replace the regular expression "\p" in T with "";
    change the text of the player's command to T.

This converts the player's command to text, which is then manipulated by searching for any punctuation mark and replacing it with blank text (that is, deleted), and then put back again as the new command.


arrow-up.png Start of Chapter 18: Activities
arrow-left.png Back to §18.32. Supplying a missing noun/second noun
arrow-right.png Onward to §18.34. Implicitly taking something

**ExampleCloves
Accepting adverbs anywhere in a command, registering what the player typed but then cutting them out before interpreting the command.

**ExampleFragment of a Greek Tragedy
Responding to the player's input based on keywords only, and overriding the original parser entirely.

**ExampleNorth by Northwest
Creating additional compass directions between those that already exist (for instance, NNW) -- and dealing with an awkwardness that arises when the player tries to type "north-northwest". The example demonstrates a way around the nine-character limit on parsed words.

***ExampleComplimentary Peanuts
A character who responds to keywords in the player's instructions and remarks, even if there are other words included.