1
This is Info file inform.info, produced by Makeinfo-1.64 from the input
4
This is the Inform Designer's Manual, third edition, 4 September 1996,
5
as updated 16 May 1997. It was converted to Info by Christopher J.
6
Madsen <ac608@yfn.ysu.edu>.
8
Copyright 1996,1997 Graham Nelson and Christopher J. Madsen
10
Permission is granted to make and distribute copies of this manual
12
(a) distributed copies are not substantially different from those
13
archived by the author,
14
(b) this and other copyright messages are always retained in full, and
15
(c) no profit is involved.
18
File: inform, Node: Code Blocks, Next: Loops, Prev: Example 4, Up: Routines
20
Code blocks, else and switch
21
----------------------------
23
A feature of all control constructs is that instead of just giving a
24
<statement>, one can give a list of statements grouped together into a
25
unit called a "code block". Such a group begins with an open brace {
26
and ends with a close brace }. For example,
29
{ print "The square of alpha is ";
34
If alpha is 3, nothing is printed; if alpha is 9,
36
The square of alpha is 81.
38
is printed. (As usual the layout is a matter of convention: it is
39
usual to write code blocks on margins indented inwards by some standard
40
number of characters.) In some ways, code blocks are like routines,
41
and at first it may seem inconsistent to write routines between [ and ]
42
brackets and code blocks between braces { and }. However, code blocks
43
cannot have private variables of their own and do not return values:
44
and it is possible for execution to break out of code blocks again, or
45
to jump from block to block, which is impossible with routines.
47
An if statement can optionally have the form
49
if (<condition>) <statement1> else <statement2>
51
in which case <statement1> is executed if the condition is true, and
52
<statement2> if it is false. For example,
54
if (alpha == 5) print "Five."; else print "Not five.";
56
Note that the condition is only checked once. The statement
62
else print "Not five.";
64
cannot ever print both "Five" and then "Not five".
66
The else clause has a snag attached: the problem of "hanging elses".
70
print "Clearly if alpha=1 and beta=2.^";
74
is ambiguous as to which if statement the else attaches to. The answer
75
(in Inform 6, though this has changed since earlier versions of the
76
language) is that an else always pairs to its nearest if, unless there
77
is bracing to indicate the contrary. Thus the else above pairs with
78
the beta condition, not the alpha condition.
80
In any case it is much safer to use braces to express what is meant,
85
print "Clearly if alpha=1 and beta=2.^";
87
print "Clearly if alpha=1 but beta not 2.^";
90
The if...else... construct is ideal for switching execution between two
91
possible "tracks", like railway signals, but it is a nuisance trying to
92
divide between many different outcomes this way. To follow the
93
analogy, the construct switch is like a railway turntable.
95
print "The train on platform 1 is going to ";
96
switch(DestinationOnPlatform(1))
97
{ 1: print "Dover Priory.";
98
2: print "Bristol Parkway.";
99
3: print "Edinburgh Waverley.";
102
Each possible value must be a constant, so
105
{ beta: print "The variables alpha and beta are equal!";
110
Any number of outcomes can be specified, and values can be grouped
111
together to a common outcome. For example,
113
print "The mission STS-", num, " was flown on the Space Shuttle";
115
{ 1 to 5, 9: print " Columbia.";
116
6 to 8: print " Challenger.";
117
10 to 25: if (num == 12) print " Discovery";
118
print ", but it was given a flight number like 51-B.";
122
will result in a true statement being printed (as long as num is
123
between 1 and, at time of writing, 78), if an incomplete one. The
124
default clause is executed if the original expression matches none of
125
the other values, and it must always come last if given at all. In
126
this case, it means that if num is 62, then
128
The mission STS-62 was flown on the Space Shuttle.
132
Note that each clause is automatically a code block and needs no
133
braces { to } to delimit it from the rest of the routine: this
134
shorthand makes switch statements much more legible.
137
File: inform, Node: Loops, Next: Example 5, Prev: Code Blocks, Up: Routines
139
while, do...until, for, break, continue
140
---------------------------------------
142
The other four Inform control constructs are all "loops", that is,
143
ways to repeat the execution of a given statement (or code block).
144
Discussion of one of the four, called objectloop, is deferred until
145
*Note Using the Tree::.
147
The two basic forms of loop are while and do...until:
149
while (<condition>) <statement>
150
do <statement> until (<condition>)
152
The first repeatedly tests the condition and, provided it is still true,
153
executes the statement. (If the condition is not even true the first
154
time, the statement is never executed.) For example:
158
while (x*x > n) x=x-1;
162
a (fairly chronic) method for finding square roots. (If SquareRoot(200)
163
is called, then x runs down through the values 200, 199, ..., 14, at
164
which point x*x <= n since 14 * 14 = 196.)
166
The do...until loop repeats the given statement until the condition
167
is found to be true. (Even if the condition is already satisfied, like
168
(true), the statement is always executed the first time through.)
170
One particular kind of while loop is needed so often that there is an
171
abbreviation for it, called for. For example,
174
while (counter <= 10)
175
{ print counter, " ";
179
which produces the output
183
(Recall that counter++ adds 1 to the variable counter.) Languages like
184
BASIC make extensive use of this kind of loop. For example, in BBC
185
BASIC, the above loop would be written
187
FOR counter = 1 TO 10
191
NEXT is a word which (slightly clumsily) means "the code block ends
192
here", and is therefore the equivalent of Inform's }. The whole is used
193
to mean "for values of the counter running through 1 to 10, do...",
194
hence the choice of the word FOR.
196
Inform (like the language C) uses a more flexible construct than
197
this, but which is still called for. It can produce any loop in the
206
where <start> and <update> are assignments. The notation to achieve
209
for (<start> : <condition> : <update>) ...
211
For example, the loop described above is achieved by
213
for (counter=1 : counter<=10 : counter++)
216
Note that if the condition is false even the first time, the loop is
217
never executed. For instance,
219
for (counter=1 : counter<0 : counter++)
224
!! At this point it is worth mentioning that several assignments can
225
be combined into a single statement in Inform. For example,
229
(three assignments separated by commas) is a single statement. This is
230
never useful in ordinary code, where the assignments can be divided up
231
by semicolons in the usual way. In for loops it is useful, though:
233
for (i=1, j=5: i<=5: i++, j--) print i, " ", j, ", ";
235
produces the output "1 5, 2 4, 3 3, 4 2, 5 1,".
237
Any of the three parts of a for statement can be omitted. If the
238
condition is missed out, it is assumed to be always true, i.e. there is
239
no check made to see if the loop should be ended and so the loop
242
On the face of it, the following loops all repeat forever:
244
while (true) <statement>
245
do <statement> until (false)
248
But there is always an escape. One way is to return from the current
249
routine. Another is to jump to a label outside the loop (jump will be
250
covered in *Note Jumping Around:: below). It's neater to use the
251
statement break, which causes execution to "break out of" the current
252
innermost loop or switch statement: it can be read as "finish early".
253
All these ways out are entirely "safe", and there is no harm in leaving
254
a loop only half-done.
256
The other simple statement used inside loops is continue. This
257
causes the current iteration to end immediately, but does not end the
258
whole loop. For example,
261
{ if (i==3) continue;
265
will output "1 2 4 5".
268
File: inform, Node: Example 5, Next: Jumping Around, Prev: Loops, Up: Routines
270
Example 5: A number puzzle
271
--------------------------
273
The routine RunPuzzle is an interesting example of a loop which,
274
though apparently simple enough, contains a trap for the unwary.
284
print "1^(taking ", count, " steps to reach 1)^";
287
if (n%2 == 0) return n/2; ! If n is even, halve it
288
return 3*n + 1; ! If n is odd, triple and add 1
291
The call RunPuzzle(10), for example, results in the output
294
(taking 6 steps to reach 1)
296
The source code assumes that, no matter what the initial value of n,
297
enough iteration will end up back at 1. If this did not happen, the
298
program would lock up into an infinite loop, printing numbers forever.
300
The routine is apparently very simple, so it would seem reasonable
301
that by thinking carefully enough about it, we ought to be able to
302
decide whether or not it is "safe" to use (i.e., whether it can be
303
guaranteed to finish or not).
305
And yet nobody knows whether this routine is "safe". The conjecture
306
that all n eventually step down to 1 is at least fifty years old but
307
has never been proved, having resisted all mathematical attack.
308
(Alarmingly, RunPuzzle(27) takes 111 iterations to fall back down to 1.)
311
File: inform, Node: Jumping Around, Next: Printing Output, Prev: Example 5, Up: Routines
313
quit, jump and the program state
314
--------------------------------
316
There are four statements left which control the flow of execution.
317
quit ends the program immediately (as if a return had taken place from
318
the Main routine). This drastic measure is best reserved for points in
319
the program which have detected some error condition so awful that
320
there is no point carrying on. Better yet, do not use it at all.
322
The jump statement transfers execution to some other named place in
323
the same routine. (Some programming languages call this goto. Since
324
it can be and has been put to ugly uses, the construct itself was at
325
one time frowned on as a vulgar construct leading programmers into sin.
326
Good use of control constructs will almost always avoid the need for
327
jump and result in more legible programs. But sin is universal.)
329
To use jump a notation is needed to mark particular places in the
330
source code. Such markers are called "labels". For example:
335
print "I have now printed this ", i++, " times.^";
339
This program has one label, Marker. A statement consisting only of a
340
full stop and then an identifier means "put a label here and call it
343
!!!! An Inform program has the ability to save a snapshot of its entire
344
state and to restore back to that previous state. This snapshot
345
includes values of variables, the point where code is currently being
346
executed, and so on. Just as we cannot know if the universe is only
347
six thousand years old, as creationists claim, having been endowed by
348
God with a carefully faked fossil record; so an Inform program cannot
349
know if it has been executing all along or if it was only recently
350
restarted. The statements required are save and restore:
355
This is a rare example of an Inform feature which may depend on the host
356
machine's state of health: for example, if all disc storage is full,
357
then save will fail. It should always be assumed that these statements
358
may well fail. A jump to the label provided occurs if the operation
359
has been a success. (This is irrelevant in the case of a restore
360
since, if all has gone well, execution is now resuming from the
361
successful branch of the save statement: because that is where
362
execution was when the state was saved.)
365
File: inform, Node: Printing Output, Next: Example 6, Prev: Jumping Around, Up: Routines
370
When text is printed, normally each character is printed exactly as
371
specified in the source code. Four characters, however, have special
372
meanings. As explained above ^ means "print a new-line". The
373
character ~, meaning "print a quotation mark", is needed since
374
quotation marks otherwise finish strings. Thus,
376
"~Look,~ says Peter. ~Socks can jump.~^Jane agrees."
380
"Look," says Peter. "Socks can jump."
383
The third remaining special character is @, which is used for
384
accented characters and other unusual effects, as described below.
385
Finally, \ is reserved for "folding lines", and used to be needed in
386
Inform 5 when text spilled over more than one line. (It's no longer
387
needed but kept so that old programs still work.) If you really want
388
to print a ~, a ^, an @ or a \, see below.
390
Text still spills over more than one line, even in the present
391
golden age of Inform 6. When a statement like
393
print "Here in her hairs
394
the painter plays the spider, and hath woven
395
a golden mesh t'untrap the hearts of men
396
faster than gnats in cobwebs";
398
is read in by Inform, the line breaks are replaced with a single space
399
each. Thus the text printed is: "Here in her hairs the painter plays
400
the spider, and hath woven a golden mesh..." and so on. (There is one
401
exception: if a line finishes with a ^ (new-line) character, then no
402
space is added before the next line begins.)
404
So far, only the print statement has been used for printing, to
405
print both numbers and strings (that is, double-quoted pieces of text).
406
Since Inform is primarily a language for writing Adventure games, its
407
business is text, and it provides many other facilities for printing.
411
is a statement which simply prints a new-line (otherwise known as a
412
carriage return, as if the lever on the carriage of an old manual
413
typewriter had been pulled to move it right back to the left margin and
414
turn it forward one line). This is equivalent to
418
but is a convenient abbreviation. Similarly,
422
prints a sequence of that many spaces.
426
prints the version number of Inform which was used to compile the
427
program (it might, for instance, print "6.01").
429
box <string1> ... <stringn>
431
displays a reverse-video box in the centre of the screen, containing
438
and is usually used for popping up quotations: for example,
440
box "Passio domini nostri" "Jesu Christi Secundum" "Joannem"
445
Jesu Christi Secundum
448
(the opening line of the libretto to Arvo Part's `St John Passion').
450
Text is normally displayed in ordinary (or "Roman") type. Its actual
451
appearance will vary from machine to machine running the program. On
452
many machines, it will be displayed using a "font" which is
453
variably-pitched, so that for example a "w" will be wider on-screen
454
than an "i". Such text is much easier to read, but makes it very
455
difficult to print out diagrams. The statement
457
print "+------------+
461
will print something quite irregular if the characters "-", "+" and " "
462
(space) do not all have the same width. Because one sometimes does
463
want to print such a diagram (to represent a sketch-map, say, or to
464
print out a table), the statement font is provided:
469
font off switches into a fixed-pitch display style (in which all
470
characters definitely have the same width); font on goes back to the
473
In addition to this, a few textual effects can be achieved.
477
switches to ordinary Roman text (the default), and there are also
483
(reverse meaning "reverse colour": e.g. yellow on blue if the normal
484
text appearance is blue on yellow). An attempt will be made to
485
approximate these effects on any machine, but it may be that underline
486
comes out as italicised text, for example, or that bold is rendered by
487
printing ordinary Roman text but in a different colour.
489
Inform programs are starting to be written which communicate in
490
languages other than English: Italian, Dutch, German, French and
491
Spanish games have all been attempted. A comprehensive range of
492
accented characters is available: these are reached with the aid of the
495
Most accented characters are written as @, followed by an accent marker,
496
then the letter on which the accent appears:
497
@^ put a circumflex on the next letter: a,e,i,o,u,A,E,I,O or U
498
@' put an acute on the next letter: a,e,i,o,u,y,A,E,I,O,U or Y
499
@` put a grave on the next letter: a,e,i,o,u,A,E,I,O or U
500
@: put a diaeresis on the next letter: a,e,i,o,u,A,E,I,O or U
501
@c put a cedilla on the next letter: c or C
502
@~ put a tilde on the next letter: a,n,o,A,N or O
503
@" put a slash on the next letter: o or O
504
@o put a ring on the next letter: a or A
506
In addition, there are a few others:
508
@<< continental European quotation marks
514
@th Icelandic accents
519
@!! Spanish (upside-down) exclamation mark
520
@?? Spanish (upside-down) question mark
524
print "Les @oeuvres d'@Aesop en fran@ccais, mon @'el@`eve!";
525
print "Na@:ive readers of the New Yorker will re@:elect Mr Clinton.";
526
print "Carl Gau@ss first proved the Fundamental Theorem of Algebra.";
528
Accented characters can also be referred to as constants, like other
529
characters. Just as 'x' represents the character lower-case-X, so
530
'@^A' represents capital-A-circumflex.
532
!! The @ escape character has two other uses. One gets around the
533
problem that, so far, it is impossible to print an "@". A double @
534
sign, followed by a number, prints the character with this numerical
535
code. The most useful cases are:
536
@@92 comes out as "\"
537
@@64 comes out as "@"
538
@@94 comes out as "^"
539
@@126 comes out as "~"
541
enabling us to print the four characters which can't be typed directly
542
because they have other meanings.
544
!!!! The second use is more obscure. Inform keeps a stock of 32
545
pseudo-variables to hold text, numbered from 0 to 31.
546
@00 prints out as the current contents of string 0
548
@31 prints out as the current contents of string 31
550
and these variables are set with the string statement:
552
string 0 "toadstool";
554
sets string 0 to the text of the word "toadstool". (There is a
555
technical reason why these strings cannot be set equal to any text:
556
only to literal text, as in the above example, or to strings previously
557
declared using the Low_string directive.)
559
Finally, it is time to discuss print. There are two forms, print
560
and print_ret. The only difference is that the second prints out an
561
extra new-line character and returns from the current routine with the
562
value true. Thus, print_ret should be read as "print and then return",
565
print_ret "That's enough of that.";
569
print "That's enough of that.^"; rtrue;
571
In fact, as an abbreviation, it can even be shortened to:
573
"That's enough of that.";
575
Although Inform newcomers are often confused by the fact that this
576
apparently innocent statement actually causes a return from the current
577
routine, it's an abbreviation which very much pays off in
578
adventure-writing situations. Note that if the program:
581
"Hello, and now for a number...";
585
is compiled, Inform will produce the warning message:
587
line 3: Warning: This statement can never be reached.
590
because the bare string on line 2 is printed using print_ret: so the
591
text is printed, then a new-line is printed, and then a return takes
592
place immediately. As the warning message indicates, there is no way
593
the statement on line 3 can ever be executed.
595
So what can be printed? The answer is a list of terms, separated by
598
print "The value is ", value, ".";
600
contains three terms. A term can take the following forms:
601
<a numerical quantity> printed as a (signed, decimal) number
602
<text in double-quotes> printed as text
603
(<rule>) <quantity> printed according to some special rule
605
Inform provides a stock of special printing rules built-in, and also
606
allows the programmer to create new ones. The most important rules are:
607
(char) print out the character which this is the numerical code for
608
(string) print this string out
609
(address) print out the text at this array address
610
(this is seldom used, and then mainly to print the
611
text of a word entry in a game's dictionary)
613
!! print (string) ... requires a little explanation.
618
prints out "Hello!", whereas
623
prints a mysterious number. This is because strings are internally
624
represented by numbers (just as everything else is).
626
The remaining stock of rules is provided for use in conjunction with
627
the Library and is documented in Chapter V: briefly,
628
(the) print definite article then name of this object
629
(The) ditto, but capitalised
630
(name) ditto, but with no article
631
(a) ditto, but with the indefinite article
632
(number) print this number out in English
633
(property) (for debugging) print the name of this property
634
(object) (ditto) print the hardware-name of this object
636
Note that (the) in lower case does something different from (The) with
637
an upper case T. This is very unusual! (Directive names, which will
638
turn up in *Note Data Structures::, variable names and so on are
639
allowed to use upper case and the case is simply ignored, so that fRoG
640
means the same as frog. But statement keywords, like print or (name),
641
have to be in lower case -- except for (The).)
643
To create a new rule, provide a routine with this name, and use the
644
rule-name in brackets.
647
File: inform, Node: Example 6, Next: Random and Indirect, Prev: Printing Output, Up: Routines
649
Example 6: Printing in hexadecimal
650
----------------------------------
652
The following pair of routines provides for printing out a number as
653
a four-digit, unsigned hexadecimal number. For example, so that
660
y = (x & $ff00) / $100;
662
print (hdigit) y/$10, (hdigit) y, (hdigit) x/$10, (hdigit) x;
666
if (x<10) print x; else print (char) 'a'+x-10;
669
Once these routines have been defined, hex and hdigit are available
670
anywhere in the same program for use as new printing rules.
673
File: inform, Node: Random and Indirect, Next: Accepting Input, Prev: Example 6, Up: Routines
675
Built-in functions 1: random and indirect
676
-----------------------------------------
678
Inform provides a small stock of functions ready-defined, but which
679
are used much as other functions are. All but two of these concern
680
objects and will be left until chapter 3.
682
random has two forms:
686
returns a uniformly random number in the range 1, 2, ..., N. N should
687
always be a positive number (between 1 and 32767) for this to work
690
random(two or more constant quantities, separated by commas)
692
returns a uniformly random choice from this selection. Thus,
694
print (string) random("red", "blue", "green", "purple", "orange");
696
randomly prints the name of one of these five colours (each being
697
equally likely to appear). Likewise,
699
print random(13, 17);
701
has a 50% chance of printing 13, and a 50% chance of printing 17.
703
!!!! The other built-in function discussed here is indirect.
705
indirect(function, arg1, arg2, ...)
707
calls the given function with given arguments. Thus, this is
710
function(arg1, arg2, ...)
712
but has the additional virtue that the function can be given, not just
713
as a literal function name, but as some calculated value:
715
indirect(random(OneRoutine, OtherRoutine), 45);
717
has a 50% chance of calling OneRoutine(45), and a 50% chance of calling
718
OtherRoutine(45). indirect should be used with caution: if supplied
719
with a numerical first argument which doesn't correspond to any
720
function in the program, the program may resoundingly crash. In any
721
event, it is often best to achieve such effects using messages to
725
File: inform, Node: Accepting Input, Prev: Random and Indirect, Up: Routines
730
!!!! Inform programmers seldom need to take input from the keyboard,
731
in practice, since in all game situations the Library's parser routines
732
take care of all that. However, for completeness this section covers
733
the read statement which is the main route by which keyboard input is
734
taken. It will not make much sense to readers who have not yet read
735
the rest of this book.
739
read <text array> <parse buffer> <routine>
741
where the <routine> is optional: if provided, it is called just before
742
the input takes place so that the screen's top line or lines of data
743
(the "status line" present in many games) can be renewed.
745
What the statement does is to read in a single line of text (waiting
746
until the user has finished typing a line and then pressed RETURN),
747
copy this text into the text array and then try to comprehend it,
748
writing the results of this comprehension exercise ("parsing") into the
751
Before the statement is reached, the program should have entered the
752
maximum number of characters which can be accepted (say, 60) into the
753
0th entry of the text array; the statement will then write the actual
754
number typed into the 1st entry, and the characters themselves into
755
entries 2 and onward. Thus,
757
text_array -> 0 = 60;
759
for (n = 0: n< text_array->1: n++) print (char) text_array->(n+2);
762
will read in a line of up to 60 characters, and then print it back
763
again. (The array text_array must have been created first, and so must
764
the local variable n, of course.)
766
Note that in this case, no "parse buffer" has been given (0 was
767
given in its place). If, instead of 0, an array is given here, then
768
the read statement makes an attempt to divide up the input text into
769
individual words, and to match these words against the game's
770
dictionary. See *Note Special Data Structures:: for details.
773
File: inform, Node: Data Structures, Next: Objects, Prev: Routines, Up: Programming Language
775
The language of data structures
776
===============================
780
* Directives and Constants:: Directives and global constants
781
* Global Variables:: Variables usable by the entire program
782
* Arrays:: Arrays hold a sequence of values
783
* Example 7:: An array example: shuffling a pack of cards
784
* Special Data Structures:: Seven special data structures in all programs
787
File: inform, Node: Directives and Constants, Next: Global Variables, Prev: Data Structures, Up: Data Structures
789
Directives and constants
790
------------------------
792
Every example program so far has consisted only of a sequence of
793
routines, each within beginning and end markers [ and ]. Such routines
794
have no way of communicating with each other, and therefore of sharing
795
information with each other, except by making function calls back and
796
forth. This arrangement is not really suited to a large program whose
797
task may be to simulate something complicated (such as the world of an
798
adventure game): it would be useful to have some kind of central
799
registry of information which all routines have access to, as and when
802
Information available to all routines in this way is said to be
803
"global", rather than "local" to any one routine. (As will appear in
804
*Note Objects::, there is also an intermediate possibility where
805
information is available only to a cluster of routines working on
806
roughly the same part of a program.)
808
This global information can be organised in a variety of ways. Such
809
organised groups are called "data structures". For example, a typical
810
data structure might be a list of 10 values. The term "data structure"
811
did not appear in *Note Routines:: because information was only ever
812
held in variables, the simplest possible kind of structure (one value
815
Data structures are added to Inform programs using commands called
816
"directives" in between definitions of routines. It's important to
817
distinguish between these, which direct Inform to do something now
818
(usually, to create something) and the statements which occur inside
819
routines, which are merely translated in some way but not acted on
820
until the program has finished being compiled and is run.
822
In fact, one directive has already appeared: the one written [,
823
which means "translate the following routine up to the next ]". In all
824
there are 38 Inform directives, as follows:
826
Abbreviate Array Attribute Class Constant Default
827
Dictionary End Endif Extend Fake_action Global
828
Ifdef Ifndef Ifnot Ifv3 Ifv5 Iftrue
829
Iffalse Import Include Link Lowstring Message
830
Nearby Object Property Release Replace Serial
831
Switches Statusline Stub System_file Trace Verb
834
Several of these are rather technical and will not be used by many
835
programmers (such as Trace, Stub, Default, System_file, Abbreviate,
836
Dictionary). Others control fine points of what is compiled and what
837
isn't (Ifdef, Ifnot, and so on; Message, Replace). These not-very
838
important directives are covered in Chapter II.
840
This leaves 9 central directives for creating data structures, and
841
these are the ones which it is important to know about:
843
Array Attribute Class Constant Extend Global
846
It is conventional to write these with the initial letter capitalised:
847
this makes directives look unlike statements. Attribute, Class, Object
848
and Property are the subject of *Note Objects::.
850
The simplest directive with a "global" effect on the program -- an
851
effect all over the program, that is, not just in one routine -- is
852
Constant. The following program, an unsatisfying game of chance, shows
853
a typical use of Constant.
855
Constant MAXIMUM_SCORE = 100;
858
print "You have scored ", random(MAXIMUM_SCORE),
859
" points out of ", MAXIMUM_SCORE, ".^";
862
The maximum score value is used twice in the routine Main. Of
863
course the program is the same as it would have been if the constant
864
definition were not present, and MAXIMUM_SCORE were replaced by 100 in
865
both places where it occurs. The advantage of using Constant is that
866
it makes it possible to change this value from 100 to, say, 50 with
867
only a single change, and it makes the source code more legible to the
868
reader by explaining what the significance of the number 100 is
871
If no value is specified for a constant, as in the line
875
then the constant is created with value 0.
878
File: inform, Node: Global Variables, Next: Arrays, Prev: Directives and Constants, Up: Data Structures
883
As commented above, so far the only variables allowed have been
884
"local variables", each private to their own routines. A "global
885
variable" is a variable which is accessible to all code in every
886
routine. Once a global variable has been declared, it is used in just
887
the same way as a local variable. The directive for declaring a global
892
This creates a variable called score, which at the start of the program
893
has the value 36. score can be altered or used anywhere in the program
894
after the line on which it is defined.
897
File: inform, Node: Arrays, Next: Example 7, Prev: Global Variables, Up: Data Structures
902
An "array" is an indexed collection of (global) variables, holding a
903
set of numbers organised into a sequence. It allows general rules to be
904
given for how a group of variables should be treated. For instance,
907
Array pack_of_cards --> 52;
909
creates a stock of 52 variables, referred to in the program as
911
pack_of_cards-->0 pack_of_cards-->1 ... pack_of_cards-->51
913
There are two basic kinds of array: "word arrays" (written using --> as
914
above) and "byte arrays" (written using -> similarly). Whereas the
915
entries of a word array can hold any number, the entries of a byte
916
array can only be numbers in the range 0 to 255 inclusive. (The only
917
advantage of this is that it is more economical on memory, and
918
beginners are advised to use word arrays instead.)
920
In addition to this, Inform provides arrays which have a little extra
921
structure: they are created with the 0th entry holding the number of
922
entries. A word array with this property is called a table; a byte
923
array with this property is a string.
925
For example, the array defined by
927
Array continents table 5;
929
has six entries: continents-->0, which holds the number 5, and five more
930
entries, indexed 1 to 5. (The program is free to change continents-->0
931
later but this will not change the size: the size of an array can never
932
change.) As an example of using string arrays:
934
Array password string "DANGER";
935
Array phone_number string "1978-345-2160";
937
PrintString(password);
939
PrintString(phone_number);
941
[ PrintString the_array i;
942
for (i=1: i<=the_array->0: i++)
943
print (char) the_array->i;
946
The advantage of string arrays, then, is that one can write a general
947
routine like PrintString which works for arrays of any size.
949
To recapitulate, Inform provides four kinds of array in all:
953
There are also four different ways to set up an array with its initial
954
contents (so the directive can take 16 forms in all). In all of the
955
examples above, the array entries will all contain 0 when the program
958
Instead, we can give a list of constant values. For example,
960
Array primes --> 2 3 5 7 11 13;
962
is a word array created with six entries, primes-->0 to primes-->5,
963
initially holding the values 2 to 13.
965
The third way to create an array gives some text as an initial value
966
(because one common use for arrays is as "strings of characters" or
967
"text buffers"). The two string arrays above were set up this way. As
970
Array players_name -> "Frank Booth";
972
sets up the byte array players_name as if the directive had been
974
Array players_name -> 'F' 'r' 'a' 'n' 'k' ' ' 'B' 'o' 'o' 't' 'h';
976
!!!! The fourth way to create an array is obsolete and is kept only so
977
that old programs still work. This is to give a list of values in
978
between end-markers [ and ], separated by commas or semi-colons. Please
979
don't use this any longer.
981
*Warning:* It is up to the programmer to see that no attempt is made
982
to read or write non-existent entries of an array. (For instance,
983
pack_of_cards-->1000.) Such mistakes are notorious for causing programs
984
to fail in unpredictable ways, difficult to diagnose. Here for example
985
is an erroneous program:
988
Array fives --> 5 10 15 20 25;
990
for (n=1: n<=10: n++) ten-->n = -1;
991
print fives-->0, "^";
994
This program ought to print 5 (since that's the 0-th entry in the array
995
fives), but in fact it prints -1. The problem is that the entries of
996
ten are ten-->0 up to ten-->9, not (as the program implicitly assumes)
997
ten-->1 to ten-->10. So the value -1 was written to ten-->10, an entry
998
which does not exist. At this point anything could have happened. As
999
it turned out, the value was written into the initial entry of the next
1000
array along, "corrupting" the data there.
1003
File: inform, Node: Example 7, Next: Special Data Structures, Prev: Arrays, Up: Data Structures
1005
Example 7: Shuffling a pack of cards
1006
------------------------------------
1008
This program simulates the shuffling of a pack of playing cards.
1009
The cards are represented by numbers in the range 0 (the Ace of Hearts)
1010
to 51 (the King of Spades). The pack itself has 52 positions, from
1011
position 0 (on the top) to position 51 (on the bottom). It is
1012
therefore represented by the array
1016
whose i-th entry is the card number at position i. A new pack as
1017
produced by the factory, still in order, would therefore be represented
1018
with card i in position i: the pack would have the Ace of Hearts on top
1019
and the King of Spades on the bottom.
1021
Constant SHUFFLES = 100;
1022
Array pack_of_cards --> 52;
1024
[ ExchangeTwo x y z;
1026
! Initially x and y are both zero
1029
{ x = random(52) - 1; y = random(52) - 1;
1032
! x and y are now randomly selected, different numbers
1033
! in the range 0 to 51
1035
z = pack_of_cards-->x;
1036
pack_of_cards-->x = pack_of_cards-->y;
1037
pack_of_cards-->y = z;
1043
1 to 9: print n%13 + 1;
1050
{ 0: print "Hearts";
1052
2: print "Diamonds";
1058
! Create the pack in "factory order":
1059
for (i=0:i<52:i++) pack_of_cards-->i = i;
1060
! Exchange random pairs of cards for a while:
1061
for (i=0:i<SHUFFLES:i++) ExchangeTwo();
1062
print "The pack has been shuffled to contain:^";
1064
print (Card) pack_of_cards-->i, "^";
1067
Note the use of a "printing rule" called Card to describe card
1068
number i. Note also that 100 exchanges of pairs of cards is only just
1069
enough to make the pack appear well shuffled. Redefining SHUFFLES as
1070
10000 makes the program take longer; redefining it as 10 makes the
1071
result very suspect.
1073
!! The example code shuffles the pack in a simple way, but there are
1074
more efficient methods. Here's one supplied by Dylan Thurston, giving
1075
perfect randomness in 51 exchanges.
1077
pack_of_cards-->0 = 0;
1079
{ j = random(i+1) - 1;
1080
pack_of_cards-->i = pack_of_cards-->j; pack_of_cards-->j = i;
1084
File: inform, Node: Special Data Structures, Prev: Example 7, Up: Data Structures
1086
Seven special data structures
1087
-----------------------------
1089
!! All Inform programs automatically contain seven special data
1090
structures, each being one of a kind: the object tree, the grammar, the
1091
table of actions, the release number, the serial code, the "statusline
1092
flag" and the dictionary. These data structures are tailor-made for
1093
adventure games and (except for the object tree) can be ignored for
1094
every other kind of program. So they are mostly covered in Book Two.
1096
1. For the object tree (and the directives Object and Class), see
1099
2. For grammar (and the directives Verb and Extend), see Chapter V,
1100
*Note Parsing Verbs:: and *Note Grammar Tokens::.
1102
3. For actions (and the <...> and <<...>> statements and the ##
1103
constant notation), see Chapter III, *Note Actions and Reactions::.
1105
4. The release number (which is printed automatically by the library
1106
in an Inform-written adventure game) is 1 unless otherwise
1107
specified. The directive
1111
does this. Conventionally release 1 would be the first published
1112
copy, and releases 2, 3, ... would be amended re-releases. See
1113
Chapter III, *Note Getting Started::, for an example.
1115
5. The serial number is set automatically to the date of compilation
1116
in the form 960822 ("22nd August 1996"). This can be overridden
1117
if desired with the directive
1121
where the text must be a string of 6 digits.
1123
6. The "status line flag" chooses between styles of "status line" at
1124
the top of an adventure game's screen display. See Chapter IV,
1125
*Note Daemons::, for use of the Statusline directive.
1127
7. The dictionary is automatically built by Inform. It is a stock of
1128
all the English words which the game might want to recognise from
1129
what the player has typed: it includes any words written in
1130
constants like 'duckling', as well as any words given in name
1131
values or in grammar. For example
1133
if (first_word == 'herring') print "You typed the word herring!";
1135
is a legal statement. Inform notices that herring -- because it
1136
is in single quotes -- is a word the program may one day need to
1137
be able to recognise, so it adds the word to the dictionary. Note
1138
that the constant 'herring' is a dictionary word but the constant
1139
'h' is the ASCII value of lower-case H. (Single-letter dictionary
1140
words are seldom needed, but can be written using an ugly syntax
1141
if need be: #n$h is the constant meaning "the dictionary word
1142
consisting only of the letter H".)
1144
!!!! From this description, the dictionary appears to be something
1145
into which words are poured, never to re-emerge. The benefit is felt
1146
when the read statement comes to try to parse some input text:
1148
read text_array parse_buffer;
1150
It must be emphasized that the read statement performs only the simplest
1151
possible form of parsing, and should not be confused with the very much
1152
more elaborate parser included in the Inform library.
1154
What it does is to break down the line of input text into a sequence
1155
of words, in which commas and full stops count as separate words in
1156
their own right. (An example is given in Chapter V, *Note Parsing
1157
Nouns::.) Before using read, the entry
1161
should be set to the maximum number of words which parsing is wanted
1162
for. (Any further words will be ignored.) The number of words
1163
actually parsed from the text is written in
1167
and a block of data is written into the array for each of these words:
1169
parse_buffer-->(n*2 - 1)
1171
holds the dictionary value of the n-th word (if n counts 1, 2, 3, ...).
1172
If the word isn't in the dictionary, this value is zero.
1177
parse_buffer->(n*4 + 1)
1179
are set to the number of letters in word n, and the offset of word n in
1184
[ PleaseTypeYesOrNo i;
1188
print "Please type ~yes~ or ~no~> ";
1190
if (parse-->1 == 'yes') rtrue;
1191
if (parse-->1 == 'no') rfalse;
1196
File: inform, Node: Objects, Prev: Data Structures, Up: Programming Language
1198
The language of objects
1199
=======================
1201
Objects make up the substance of the world. That is why they
1202
cannot be composite.
1204
-- Ludwig Wittgenstein (1889-1951), Tractatus
1208
* About Objects:: Objects and communication
1209
* Object Tree:: The object tree and functions for reading it
1210
* Creating Objects:: Creating objects and setting up the object tree
1211
* Using the Tree:: `move', `remove', `in', and `objectloop'
1212
* Objects with Properties:: Creating objects with properties
1213
* Private Properties:: Using `private' properties for encapsulation
1214
* Using Attributes:: Using `give' and `has' to manipulate attributes
1215
* Classes and Inheritance:: Creating classes of related objects
1216
* Messages:: You communicate with objects via messages
1217
* Access to Superclass Values:: Using an overridden value from a parent class
1218
* Philosophy:: The theory behind this object-oriented design
1219
* Sending Messages:: Send messages to routines, strings, and classes
1220
* Dynamic Objects:: Creating and deleting objects at run time
1221
* Common vs Individual:: Object properties can be common or individual
1224
File: inform, Node: About Objects, Next: Object Tree, Prev: Objects, Up: Objects
1226
Objects and communication
1227
-------------------------
1229
The objects in a program are its constituent parts: little lumps of
1230
code and data. The starting point of an "object-oriented language" is
1231
that it's good design to tie up pieces of information in bundles with
1232
the pieces of program which deal with them. But the idea goes further:
1234
1. An object is something you can communicate with. (It's like a
1235
company where many people work in the same building, sharing the
1236
same address: to the outside world it behaves like a single
1239
2. Information inside the object can be kept concealed from the
1240
outside world (like a company's confidential files). This is
1241
sometimes called "encapsulation".
1243
3. The outside world can only ask the object to do something, and has
1244
no business knowing how it will be done. (The company might
1245
decide to change its stock-control system one day, but the outside
1246
world should never even notice that this has happened, even though
1247
internally it's a dramatic shift.)
1249
All three principles have been seen already for routines: (1) you can
1250
call a routine, but you can't call "only this part of a routine"; (2)
1251
the local variables of a routine are its own private property, and the
1252
rest of the program can't find out or alter their values; (3) as long
1253
as the routine still accomplishes the same task, it can be rewritten
1254
entirely and the rest of the program will carry on working as if no
1255
change had been made.
1257
Why bother with all this? There are two answers. First and
1258
foremost, Inform was designed to make adventure games, where objects
1259
are the right idea for representing items and places in the game.
1260
Secondly, the `object' approach makes sense as a way of organising any
1261
large, complicated program.
1263
The other key idea is communication. One can visualise the program
1264
as being a large group of companies, constantly writing letters to each
1265
other to request information or ask for things to be done. In a
1266
typical "message", one object A sends a detailed question or
1267
instruction to another object B, which replies with a simple answer.
1268
(Again, we've seen this already for routines: one routine calls
1269
another, and the other sends back a return value.)
1271
Routines are only one of the four basic kinds of Inform object, which
1274
* routines, declared using [...];
1276
* strings in double-quotes "like so";
1278
* collections of routines and global variables, declared using Object;
1280
* prototypes for such collections, called "classes" and declared using Class.
1282
These four kinds are called "metaclasses". If O is an object, then the
1287
will always tell you what kind it is, which will be one of the four
1290
Routine String Object Class
1294
metaclass("Violin Concerto no. 1")
1296
evaluates to String, whereas
1300
should always be Routine (since Main should always be the name of the
1301
routine where an Inform program begins to run). From *Note Routines::
1302
we already know about metaclasses Routine and String, so it's the other
1303
two cases which this section will concentrate on.
1305
!!!! Why only these four kinds? Why are strings objects, and not (say)
1306
variables or dictionary words? Object-oriented languages vary greatly
1307
in to what extreme they take the notion of object: in the dogmatic
1308
Smalltalk-80, every ingredient of any kind in a program is called an
1309
object: the program itself, the number 17, each variable and so on.
1310
Inform is much more moderate. Routines, Objects and classes are
1311
genuinely object-like, and it just so happens that it's convenient to
1312
treat strings as objects (as we shall see). But Inform stops there.
1315
File: inform, Node: Object Tree, Next: Creating Objects, Prev: About Objects, Up: Objects
1317
Built-in functions 2: the object tree
1318
-------------------------------------
1320
Routines, strings and (as we shall see) classes are scattered about
1321
in an Inform program, in no particular order, and nothing links them
1322
together. Object objects are special in that they are joined up in the
1323
"object tree" which grows through every Inform program.
1325
In this tree, objects have a kind of family relationship to each
1326
other: each one has a parent, a child and a sibling. (The analogy here
1327
is with family trees.) Normally such a relation is another object in
1328
the tree, but instead it can be
1332
which means "no object at all". For example, consider the tree:
1338
Note Sceptre -> Cucumber -> Torch -> Magic Rod
1342
The Mailbox and Player are both children of the Meadow, which is their
1343
parent, but only the Mailbox is the child of the Meadow. The Magic Rod
1344
is the sibling of the Torch, which is the sibling of the Cucumber, and
1347
Inform provides special functions for reading off positions in the tree:
1348
parent, sibling and child all do the obvious things, and in addition
1349
there's a function called children which counts up how many children an
1350
object has (where grandchildren don't count as children). For instance,
1352
parent ( Mailbox ) == Meadow
1353
children ( Player ) == 4
1354
child ( Player ) == Sceptre
1355
child ( Sceptre ) == nothing
1356
sibling ( Torch ) == Magic Rod
1358
It is a bad idea to apply these functions to the value nothing (since
1359
it is not an object, but a value representing the absence of one). One
1360
can detect whether a quantity is a genuine object or not using
1365
is nothing for any value X which isn't an object: in particular,
1367
metaclass(nothing) == nothing
1369
!! Hopefully it's clear why the tree is useful for writing adventure
1370
games: it provides a way to simulate the vital idea of one thing being
1371
contained inside another. But even in non-adventure game programs it
1372
can be a convenience. For instance, it is an efficient way to hold
1373
tree structures and linked lists of information.
added
removed
info/inform-2
