1. The language of routines

1.1. First principles

This chapter aims to introduce beginners to Inform as though it were a general-purpose programming language (rather than a tool for designing adventure games). The examples given will be short programs performing simple calculations (rather than games). To begin with, the Inform language is:

1. -- Compiled.

-- That is, the Inform compiler translates text written by the author (called the "source code'') into a program (called the "object code'' since it is the object of the exercise). This translation is only done once, but the resulting program can be run many times.

2. -- Procedural.

-- That is, a program is divided into a number of "routines'' (also called "functions'' or "procedures''), each being a list of orders to be obeyed (though these orders are traditionally called "statements''). When the program is run, only one thing happens at a time: at any given moment, a single routine is being obeyed.

3. -- Object-oriented.

-- That is, the fabric of a typical Inform program will be woven around "objects'' being dealt with, which are regarded as being self-contained. For example, a program to simulate a warehouse might have objects representing lorries and containers; each object would have a position and contents at any given time. The program would have general rules describing "lorry'' and "container'' as well as actual examples of each. A lorry would have the ability to receive a message telling it to do something, such as "load up with a container and leave the warehouse''.

4. -- Portable.

-- That is, once Inform has compiled the source code (having found no mistakes), the resulting program can be run on almost any model of computer. It will exhibit exactly the same behaviour on each of them. It cannot depend on the "environment'': it cannot suddenly run out of memory and crash, for instance.

The computer runs an Inform program (which need not be a game) with the aid of an "interpreter''. There are at least 40 different interpreters available for this format (called the "Z-machine'' or "Infocom format'') and there may be a choice available for your model of computer: it is a good idea to get the most modern and accurate possible. Look to see if they support the Z-Machine Standard, and if so, up to what revision number.

1.2. Example 1: Hello World

Traditionally, all programming language tutorials begin by giving a program which does nothing but print "Hello world'' and stop. Here is such a program in Inform:

    !  "Hello world" example program

    [ Main;
      print "Hello world^";
    ];

Once commentary has been stripped out, Inform regards the source code as a list of things to look at, divided by semicolons ;. It treats line breaks, tab characters and spaces all as so-called "white space'': that is, a gap between two things whose size is unimportant. Thus, exactly the same program would be produced by the source code

       [        
          Main   ;
    print
             "Hello world^"          ;
        ] 
      ;

    [ Main;print"Hello world^";];

Every program must contain a routine called Main, and in this example it is the only routine. When a program is set running, the first instruction obeyed is the first one in Main, and it carries on line by line from there. This process is called "execution''. When the Main routine is finished, the program stops.

The routine has only one statement:

    print "Hello world^"

    print "Blue^Red^Green^"

prints up:

Blue
Red
Green

box        break      continue   do       font      for         give
if         inversion  jump       move     new_line  objectloop  print
print_ret  quit       read       remove   restore   return      rfalse
rtrue      save       spaces     string   style     switch      while

1.3. Example 2: Elsinore

The following source code has three routines, Main, Rosencrantz and Hamlet:

    [ Main;
      print "Hello from Elsinore.^";
      Rosencrantz();
    ];
    [ Rosencrantz;
      print "Greetings from Rosencrantz.^";
    ];
    [ Hamlet;
      print "The rest is silence.^";
    ];

The resulting program prints up

Hello from Elsinore.
Greetings from Rosencrantz.

In fact, when the above program is compiled, Inform notices that Hamlet is never needed and prints out a warning to that effect. The exact text produced by Inform varies from machine to machine, but will be something like this:

    RISC OS Inform 6.03 (May 11th 1996)
    line 8: Warning: Routine "Hamlet" declared but not used
    Compiled with 0 errors and 1 warning

Usually there are mistakes in a newly-written program and one goes through a cycle of running a first draft through Inform, receiving a batch of error messages, correcting the draft according to these messages, and trying again. A typical error message would occur if, on line 3, we had mistyped Rosncrantz() for Rosencrantz(). Inform would then have produced:

    RISC OS Inform 6.03 (May 11th 1996)
    line 5: Warning: Routine "Rosencrantz" declared but not used
    line 8: Warning: Routine "Hamlet" declared but not used
    line 3: Error: No such constant as "Rosncrantz"
    Compiled with 1 error and 2 warnings (no output)

1.4. Numbers and variables

Internally -- that is, whatever the outward appearance -- all programs essentially manipulate numbers. Inform understands "number'' to be a whole number in the range -32768 to +32767. (Special programming would be required to represent larger numbers or fractions.) There are three notations for writing numbers in Inform: here is an example of each.

    -4205
    $3f08
    $$1000111010110

A print statement can print numbers as well as text, though it always prints them back in ordinary decimal notation. For example, the program

    [ Main;
      print "Today's number is ", $3f08, ".^";
    ];

prints up

Today's number is 16136.

Inform recognises many other notations as "constants'', that is, values which are literally described in the source code. A full list will appear later, but one other is that a single character between single quotation marks, for instance

    'x'

Finally, in this initial batch of constant notations, Inform provides two special constants:

true
false

Inform has a concept of "variable'' like that used in algebra, where it is easy but limiting to express facts using only numbers:

34 - 34 = 0

11 - 11 = 0

694 - 694 = 0

x - x = 0

Likewise, in Inform what seems to be a word of text may be a variable which represents a number: when the source code is compiled, Inform cannot know what numerical value this text represents. When the program is run, it will always have a numerical value at any given time. If oil_left is a variable, the statement

    print "There are ", oil_left, " gallons remaining.^";

Inform can only know that text (such as oil_left) represents a variable if the source code has "declared'' that it does. Each routine can declare its own selection of variables on its opening line. For example, in the program

    [ Main alpha b;
      alpha = 2200;
      b = 201;
      print "Alpha is ", alpha, " while b is ", b, "^";
    ];

    turns_still_to_play
    chart45
    X

The = sign occurring twice in the above routine is an example of an "operator'': a notation usually made up of the symbols on the non-alphabetic keys on a typewriter and which means something is to be done with the items it is written next to. In this context, = means "set equal to''. When the statement alpha = 2200 is executed at run time, the current value of the variable alpha becomes 2200 (and it keeps that value until another such statement changes it).

The variables alpha and b are called "local variables'' because they are local to Main: in effect, they are its private property. The program

    [ Main alpha;
      alpha = 2200;
      Rival();
    ];
    [ Rival;
      print alpha;
    ];

1.5. Arithmetic expressions

The Inform language is rich with operators, making it concise but not always very readable. Feeling comfortable with the operators is the main step towards being able to follow Inform source code. Fortunately, these operators are based on the usual rules for writing arithmetic formulae, which gives them a headstart in familiarity.

Indeed, the most commonly used operators are "arithmetic'': they combine one or more numbers to give one resulting number. Whenever a number is expected in a statement, a general "expression'' can be given instead: that is, a calculation giving a number as a result. For example, the statement

    seconds = 60*minutes + 3600*hours

Ordinary arithmetic is carried out with the operators + (plus), - (minus), * (times) and / (divided by).

Usually dividing one integer by another leaves a remainder: for example, 3 goes into 7 twice, with remainder 1. In Inform notation,

7/3 evaluates to 2
7%3 evaluates to 1

In a complicated expression the order in which the operators work may affect the result. As most human readers would, Inform works out both of

    23 + 2 * 700
    2 * 700 + 23

    (23 + 2) * 700
    2 * (700 + 23)

    a - b - c

    (a - b) - c

The final purely arithmetic operator is "unary minus''. This is written as a minus sign - but is not the same as ordinary subtraction. The expression:

    -credit

    0 - credit

    -credit - 5

One way to imagine precedence is to think of it as glue attached to the operator. A higher level means stronger glue. Thus, in

    23 + 2 * 700

Some operators do not simply act on values but actually change the current values of variables: expressions containing these are called "assignments'' (because they assign values as well as working them out). One such operator is 'set equals':

    alpha = 72

The other two assignment operators are ++ and --, which will be familiar to any C programmer. They are unary operators, and can be used in any of the following ways:

    variable++
    ++variable
    variable--
    --variable

For example, suppose the variable has value 12. Then the result would be 12, 13, 12 or 11 respectively; the value left in variable afterwards would be 13, 13, 11 or 11.

Note that expressions like

    500++        (4*alpha)--     34 = beta

1.6. Arguments and Return Values

As has already been said, in Inform jargon the word "function'' is synonymous with "routine''. A function might be defined as a correspondence

(x1, ..., xn) ---> f(x1, ..., xn)

All Inform routines are like this. A number of arguments are fed in when the routine is "called'' (that is, set running) and there is always a single numerical result. This result is called the "return value'' because it is returned to the rest of the program. Some very simple routines conceal this. For instance, consider Sonnet:

    [ Main;
      Sonnet();
    ];
    [ Sonnet;
      print "When to the sessions of sweet silent thought^";
      print "I summon up remembrance of things past^";
    ];

    [ Main;
      print Sonnet();
    ];

then the output would be

When to the sessions of sweet silent thought
I summon up remembrance of things past
1

Thus in Inform there is no such thing as a "void function'' or "procedure'': every routine returns a number even though this may immediately be thrown away as unwanted.

When a routine is called,

    Routine(arg1, ...)

If execution runs into the ] end-of-routine marker, so that the routine is finished without having specified any definite return value, then this value is true. (This is why the printed return value of Sonnet is 1: true has the value 1.)

1.7. Example 3: Cubes

A more typical, though less aesthetic, example than Sonnet:

    [ Main;
      print Cube(1), " ";
      print Cube(2), " ";
      print Cube(3), " ";
      print Cube(4), " ";
      print Cube(5), "^";
    ];
    [ Cube x;
      return x*x*x;
    ];

which, when executed, prints

1 8 27 64 125

Any "missing arguments'' in a routine call are set equal to zero, so the call Cube() is legal and does the same as Cube(0).

1.8. Conditions: if, true and false

Such routines are too simple, so far, even to express many mathematical functions, and more flexibility will be needed.

A "control construct'' is a kind of statement which controls whether or not, and if so how many times or in what order, other statements are executed. The simplest of these is if:

if (<condition>) <statement>

    if (alpha == 3) print "Hello";

Conditions are always given in (round) brackets. The basic conditions are as follows:

(a == b)	Number a equals number b
(a ~= b)	Number a doesn't equal number b
(a >= b)	a is greater than or equal to b
(a <= b)	a is less than or equal to b
(a > b)	a is greater than b
(a < b)	a is less than b
(o1 in o2)	Object o1 possessed by o2
(o1 notin o2)	Object o1 not possessed by o2
(o1 has a)	Object o1 has attribute a
(o1 hasnt a)	Object o1 hasn't attribute a
(o1 provides m)	Object o1 provides property m
(o1 ofclass c)	Object o1 inherits from class c

(The conditions relating to objects will be discussed later.) A useful extension to this set is provided by the special operator or, which gives alternative possibilities. For example,

    if (alpha == 3 or 4) print "Scott";
    if (alpha ~= 5 or 7 or 9) print "Amundsen";

    if (player in Forest or Village or Building) ...

    if (x > 100 or y) ...

Conditions can also be built up from simpler ones (just as long expressions are built up from single operators) using the three logical operators &&, || and ~~ (pronounced "and'', "or'' and "not''). For example,

    if (alpha == 1 && (beta > 10 || beta < -10)) print "Lewis";
    if (~~(alpha > 6)) print "Clark";

The discussion above makes it look as if conditions are special kinds of expression which can only use certain operators (==, &&, or and so on). But this is not true: conditions are expressions like any other. It's legal to write

    print (beta == 4);

for instance, and this results in 1 being printed if beta equals 4, and 0 otherwise. Thus:

the result of a true condition is 1;
the result of a false condition is 0.

    betaisfour = (beta == 4);
    ...
    if (betaisfour == true) ...

    betaisfour = (beta == 4);
    ...
    if (betaisfour) ...

    if (1) print "Magellan";
    if (0) print "da Gama";

One common use of variables is as "flags''. A flag can only hold the value 0 or 1, false or true according to some state of the program. The fact that a number can be used as a condition allows natural-looking statements like

    if (lower_caves_explored) print "You've already been that way.";

1.9. Example 4: Factorials

The factorial of a positive integer n is defined as the product $$ 1 \times 2 \times 3 \times ... \times n $$ so that, for example, the factorial of 4 is 24. Here is an Inform routine to calculate factorials:

    [ Main;
      print Factorial(7), "^";
    ];
    [ Factorial n;
      if (n==1) return 1;
      return n*Factorial(n-1);
    ];

The routine Factorial actually calls itself: this is called "recursion''. Execution reaches "seven routines deep'' before starting to return back up. Each of these copies of Factorial runs with its own private copy of the variable n.

Recursion is hazardous. If one calls the routine

    [ Disaster;
      return Disaster();
    ];

1.10. Code blocks, else and switch

A feature of all control constructs is that instead of just giving a <statement>, one can give a list of statements grouped together into a unit called a "code block''. Such a group begins with an open brace { and ends with a close brace }. For example,

    if (alpha > 5)
    {   print "The square of alpha is ";
        print alpha*alpha;
        print ".^";
    }

If alpha is 3, nothing is printed; if alpha is 9,

The square of alpha is 81.

An if statement can optionally have the form

if (<condition>) <statement1> else <statement2>

    if (alpha == 5) print "Five."; else print "Not five.";

    if (alpha == 5)
    {   print "Five.";
        alpha = 10;
    }
    else print "Not five.";

The else clause has a snag attached: the problem of "hanging elses''.

    if (alpha == 1)
        if (beta == 2)
            print "Clearly if alpha=1 and beta=2.^";
        else
            print "Ambiguous.^";

In any case it is much safer to use braces to express what is meant, as in:

    if (alpha == 1)
    {   if (beta == 2)
            print "Clearly if alpha=1 and beta=2.^";
        else
            print "Clearly if alpha=1 but beta not 2.^";
    }

    print "The train on platform 1 is going to ";
    switch(DestinationOnPlatform(1))
    {   1: print "Dover Priory.";
        2: print "Bristol Parkway.";
        3: print "Edinburgh Waverley.";
    }

    switch(alpha)
    {   beta: print "The variables alpha and beta are equal!";
    }

Any number of outcomes can be specified, and values can be grouped together to a common outcome. For example,

    print "The mission STS-", num, " was flown on the Space Shuttle";
    switch(num)
    {   1 to 5, 9: print " Columbia.";
        6 to 8:    print " Challenger.";
        10 to 25:  if (num == 12) print " Discovery";
                   print ", but it was given a flight number like 51-B.";
        default:   print ".";
    }

will result in a true statement being printed (as long as num is between 1 and, at time of writing, 78), if an incomplete one. The default clause is executed if the original expression matches none of the other values, and it must always come last if given at all. In this case, it means that if num is 62, then

The mission STS-62 was flown on the Space Shuttle.

Note that each clause is automatically a code block and needs no braces { to } to delimit it from the rest of the routine: this shorthand makes switch statements much more legible.

1.11. while, do...until, for, break, continue

The other four Inform control constructs are all "loops'', that is, ways to repeat the execution of a given statement (or code block). Discussion of one of the four, called objectloop, is deferred until Section 3.4.

The two basic forms of loop are while and do...until:

while (<condition>) <statement>
do <statement> until (<condition>)

    [ SquareRoot n;
      x = n;
      while (x*x > n) x=x-1;
      return x;
    ];

The do...until loop repeats the given statement until the condition is found to be true. (Even if the condition is already satisfied, like (true), the statement is always executed the first time through.)

One particular kind of while loop is needed so often that there is an abbreviation for it, called for. For example,

    counter = 1;
    while (counter <= 10)
    {   print counter, " ";
        counter++;
    }

which produces the output

1 2 3 4 5 6 7 8 9 10

    FOR counter = 1 TO 10
        PRINT counter;" ";
    NEXT

Inform (like the language C) uses a more flexible construct than this, but which is still called for. It can produce any loop in the form

<start>
while (<condition>)
{ ...
<update>
}

for (<start> : <condition> : <update>) ...

    for (counter=1 : counter<=10 : counter++)
        print counter, " ";

    for (counter=1 : counter<0 : counter++)
        print "Banana";

Any of the three parts of a for statement can be omitted. If the condition is missed out, it is assumed to be always true, i.e. there is no check made to see if the loop should be ended and so the loop continues forever.

On the face of it, the following loops all repeat forever:

while (true) <statement>
do <statement> until (false)
for (::) <statement>

The other simple statement used inside loops is continue. This causes the current iteration to end immediately, but does not end the whole loop. For example,

    for (i=1: i<=5: i++)
    {   if (i==3) continue;
        print i, " ";
    }

1.12. Example 5: A number puzzle

The routine RunPuzzle is an interesting example of a loop which, though apparently simple enough, contains a trap for the unwary.

    [ RunPuzzle n count;

      do
      {   print n, " ";
          n = NextNumber(n);
          count++;
      }
      until (n==1);
      print "1^(taking ", count, " steps to reach 1)^";
    ];
    [ NextNumber n;
      if (n%2 == 0) return n/2;     ! If n is even, halve it
      return 3*n + 1;               ! If n is odd, triple and add 1
    ];

The call RunPuzzle(10), for example, results in the output

10 5 16 8 4 2 1
(taking 6 steps to reach 1)

The routine is apparently very simple, so it would seem reasonable that by thinking carefully enough about it, we ought to be able to decide whether or not it is "safe'' to use (i.e., whether it can be guaranteed to finish or not).

And yet nobody knows whether this routine is "safe''. The conjecture that all n eventually step down to 1 is at least fifty years old but has never been proved, having resisted all mathematical attack. (Alarmingly, RunPuzzle(27) takes 111 iterations to fall back down to 1.)

1.13. quit, jump and the program state

There are four statements left which control the flow of execution. quit ends the program immediately (as if a return had taken place from the Main routine). This drastic measure is best reserved for points in the program which have detected some error condition so awful that there is no point carrying on. Better yet, do not use it at all.

The jump statement transfers execution to some other named place in the same routine. (Some programming languages call this goto. Since it can be and has been put to ugly uses, the construct itself was at one time frowned on as a vulgar construct leading programmers into sin. Good use of control constructs will almost always avoid the need for jump and result in more legible programs. But sin is universal.)

To use jump a notation is needed to mark particular places in the source code. Such markers are called "labels''. For example:

    [ Main i;
      i=1;
      .Marker;
      print "I have now printed this ", i++, " times.^";
      jump Marker;
    ];

1.14. Printing output

When text is printed, normally each character is printed exactly as specified in the source code. Four characters, however, have special meanings. As explained above means "print a new-line''. The character ~, meaning "print a quotation mark'', is needed since quotation marks otherwise finish strings. Thus,

    "~Look,~ says Peter. ~Socks can jump.~^Jane agrees."

is printed as

"Look,'' says Peter. "Socks can jump.''
Jane agrees.

Text still spills over more than one line, even in the present golden age of Inform 6. When a statement like

    print "Here in her hairs
           the painter plays the spider, and hath woven
           a golden mesh t'untrap the hearts of men
           faster than gnats in cobwebs";

So far, only the print statement has been used for printing, to print both numbers and strings (that is, double-quoted pieces of text). Since Inform is primarily a language for writing Adventure games, its business is text, and it provides many other facilities for printing.

new_line

print "^"

spaces <number>

inversion

box <string1> ... <stringn>

string1
string2
...
stringn

    box "Passio domini nostri" "Jesu Christi Secundum" "Joannem"

displays

Passio domini nostri
Jesu Christi Secundum
Joannem

Text is normally displayed in ordinary (or "Roman'') type. Its actual appearance will vary from machine to machine running the program. On many machines, it will be displayed using a "font'' which is variably-pitched, so that for example a "w'' will be wider on-screen than an "i''. Such text is much easier to read, but makes it very difficult to print out diagrams. The statement

    print "+------------+
          ^+   Hello    +
          ^+------------+^";

    font on
    font off

In addition to this, a few textual effects can be achieved.

    style roman

    style bold
    style underline
    style reverse

Inform programs are starting to be written which communicate in languages other than English: Italian, Dutch, German, French and Spanish games have all been attempted. A comprehensive range of accented characters is available: these are reached with the aid of the escape character, @.

Most accented characters are written as @, followed by an accent marker, then the letter on which the accent appears:

@^	put a circumflex on the next letter: a,e,i,o,u,A,E,I,O or U
@'	put an acute on the next letter: a,e,i,o,u,y,A,E,I,O,U or Y
@'	put a grave on the next letter: a,e,i,o,u,A,E,I,O or U
@:	put a diaeresis on the next letter: a,e,i,o,u,A,E,I,O or U
@c	put a cedilla on the next letter: c or C
@~	put a tilde on the next letter: a,n,o,A,N or O
@\	put a slash on the next letter: o or O
@o	put a ring on the next letter: a or A

In addition, there are a few others:

@ss	German sz
@<<	continental European quotation marks
@>>
@ae	ligatures
@AE
@oe
@OE
@th	Icelandic accents
@et
@Th
@Et
@LL	pound sign
@!!	Spanish (upside-down) exclamation mark
@??	Spanish (upside-down) question mark

For instance,

    print "Les @oeuvres d'@Aesop en fran@ccais, mon @'el@`eve!";
    print "Na@:ive readers of the New Yorker will re@:elect Mr Clinton.";
    print "Carl Gau@ss first proved the Fundamental Theorem of Algebra.";

Finally, it is time to discuss print. There are two forms, print and print_ret. The only difference is that the second prints out an extra new-line character and returns from the current routine with the value true. Thus, print_ret should be read as "print and then return'', and

    print_ret "That's enough of that.";

    print "That's enough of that.^"; rtrue;

    "That's enough of that.";

    [ Main;
      "Hello, and now for a number...";
      print 45*764;
    ];

    line 3: Warning: This statement can never be reached.
    >   print 45*764;

So what can be printed? The answer is a list of terms, separated by commas. For example,

    print "The value is ", value, ".";

The remaining stock of rules is provided for use in conjunction with the Library and is documented in Chapter V: briefly,

(the)	print definite article then name of this object
(The)	ditto, but capitalised
(name)	ditto, but with no article
(a)	ditto, but with the indefinite article
(number)	print this number out in English
(property)	(for debugging) print the name of this property
(object)	(ditto) print the hardware-name of this object

Note that (the) in lower case does something different from (The) with an upper case T. This is very unusual! (Directive names, which will turn up in Section 2, variable names and so on are allowed to use upper case and the case is simply ignored, so that fRoG means the same as frog. But statement keywords, like print or (name), have to be in lower case -- except for (The).)

To create a new rule, provide a routine with this name, and use the rule-name in brackets.

1.15. Example 6: Printing in hexadecimal

The following pair of routines provides for printing out a number as a four-digit, unsigned hexadecimal number. For example, so that

    print (hex) 16339;

    [ hex x y;
      y = (x & $ff00) / $100;
      x = x & $ff;
      print (hdigit) y/$10, (hdigit) y, (hdigit) x/$10, (hdigit) x;
    ];
    [ hdigit x;
      x = x % $10;
      if (x<10) print x; else print (char) 'a'+x-10;
    ];

1.16. Built-in functions 1: random and indirect

Inform provides a small stock of functions ready-defined, but which are used much as other functions are. All but two of these concern objects and will be left until chapter 3.

random has two forms:

random(N)

random(two or more constant quantities, separated by commas)

    print (string) random("red", "blue", "green", "purple", "orange");

    print random(13, 17);

1.17. Accepting input

    text_array -> 0 = 60;
    read text_array 0;
    for (n = 0: n< text_array->1: n++) print (char) text_array->(n+2);
    new_line;

Note that in this case, no "parse buffer'' has been given (0 was given in its place). If, instead of 0, an array is given here, then the read statement makes an attempt to divide up the input text into individual words, and to match these words against the game's dictionary. See Section 2.5 for details.