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: Top, Next: Introduction, Prev: (dir), Up: (dir)
20
Inform Designer's Manual
21
************************
23
This is the Inform Designer's Manual, third edition, 4 September 1996,
24
as updated 16 May 1997. It was converted to Info by Christopher J. Madsen
25
<ac608@yfn.ysu.edu>. This is revision 4 of the Info version, last updated
30
* Introduction:: About Inform and the Inform Designer's Manual
31
* Programming Language:: The Inform language tutorial and reference
32
* Using the Compiler:: Compiler options, include files, & libraries
33
* Fundamentals:: Inform revolves around objects and actions
34
* The Model World:: How Inform models the virtual world
35
* Describing and Parsing:: How Inform converses with the player
36
* Testing and Hacking:: Debugging and special effects
37
* Appendix:: Tables and summaries
38
* Answers:: Answers to all the exercises
39
* Index:: Attributes, properties, objects, & routines
40
* Concept Index:: Index of authors and ideas
41
* Secondary Index:: Other references to indexed properties
43
-- The Detailed Node Listing --
45
The Inform programming language
47
* Routines:: Constants, expressions, and functions
48
* Data Structures:: Directives, global variables, & arrays
49
* Objects:: Objects, properties, attributes, & messages
53
* The Language of Inform:: The language of Inform
54
* Compiler Options:: Compiler options and memory settings
55
* Error Messages:: All the Inform error messages
59
* Getting Started:: Introducing `Ruins', our example game
60
* Messages and Classes:: Introducing messages and classes
61
* Actions and Reactions:: Actions are generated by the user's requests
65
* Places:: Places, scenery, directions and the map
66
* Containers:: Containers, supporters and sub-objects
67
* Doors:: Doors, bridges, and ladders
68
* Switchable Objects:: Things you can turn on and off
69
* Things to Enter:: Things to enter, travel in and push around
70
* Reading Matter:: Reading matter and consultation
71
* Living Creatures:: Living creatures and conversation
72
* Light and Dark:: The light and the dark
73
* Daemons:: Daemons and the passing of time
74
* Player:: Starting, moving, changing & killing the player
75
* Constants and Scoring:: Miscellaneous constants and scoring
76
* Extending the Library:: Extending and redefining the Library
78
Describing and Parsing
80
* Describing Objects:: Describing objects and rooms
81
* Listing Objects:: Listing and grouping objects
82
* Parsing Nouns:: How nouns are parsed
83
* Plural Names:: Plural names for duplicated objects
84
* Parsing Verbs:: How verbs are parsed
85
* Grammar Tokens:: Tokens of grammar
86
* Scope:: Scope and what you can see
87
* Helping the Parser:: Helping the parser out of trouble
91
* Debugging:: Debugging verbs and tracing
92
* Run-Time Limitations:: Limitations on the run-time format
93
* Boxes:: Boxes, menus and drawings
94
* Assembly Language:: Descending into assembly language
98
* Operators:: Table of operators and their precedence
99
* Statements:: Table of all Inform statements
100
* Directives:: Table of all Inform directives
101
* Grammar:: Summary of the `Verb' and `Extend' directives
102
* Attributes:: The attributes defined by the library
103
* Properties:: The properties defined by the library
104
* Objects and Routines:: Library-defined objects and routines
105
* Actions and Fake Actions:: The actions and fakes
106
* Library Messages:: All the library messages and their numbers
107
* Entry Points:: Entry points and meaningful constants
108
* Program Order:: What order the program should be in
109
* Lexicon:: A short Inform lexicon
111
Answers to all the exercises
113
* Answer 1:: mushroom picking
114
* Answer 2:: opening medicine bottle
115
* Answer 3:: before on second noun
116
* Answer 4:: action validation
117
* Answer 5:: orange cloud surrounding player
118
* Answer 6:: Mayan directions
119
* Answer 7:: reflecting the map east-west
120
* Answer 8:: exchanging "east"/"west"
121
* Answer 9:: acquisitive bag
122
* Answer 10:: television set
123
* Answer 11:: glass and steel boxes
124
* Answer 12:: macrame bag
125
* Answer 13:: plank bridge
126
* Answer 14:: cage to open and enter
127
* Answer 15:: car that won't go east
128
* Answer 16:: pushing pumice ball uphill
129
* Answer 17:: Tyndale's Bible
130
* Answer 18:: bearded psychiatrist
131
* Answer 19:: removing conversation actions
132
* Answer 20:: computer (voice-activated)
133
* Answer 21:: Charlotte playing Simon Says
134
* Answer 22:: Charlotte's clapping game
135
* Answer 23:: Dyslexic Dan
136
* Answer 24:: extensions for one actor only
137
* Answer 25:: alarm clock
138
* Answer 26:: tricorder
139
* Answer 27:: replicator
140
* Answer 28:: communications badge
141
* Answer 29:: Zen flight computer
142
* Answer 30:: Picard and Maharg
143
* Answer 31:: Martha the telepath
144
* Answer 32:: troll afraid of the dark
145
* Answer 33:: pet moth escapes in the dark
146
* Answer 34:: thief who wanders
147
* Answer 35:: weight--watching daemon
148
* Answer 36:: scuttling claws
149
* Answer 37:: Answer to Exercise 37
150
* Answer 38:: midnight
151
* Answer 39:: nightfall and daybreak
152
* Answer 40:: mid-air location
153
* Answer 41:: long time-scale game
154
* Answer 42:: player reacting before
155
* Answer 43:: silencing player
156
* Answer 44:: the player's wayhel
157
* Answer 45:: Giant with conscience
158
* Answer 46:: chessboard of rooms
159
* Answer 47:: varying the prompt
160
* Answer 48:: Answer to Exercise 48
161
* Answer 49:: printing pronouns
162
* Answer 50:: ornate box (inventory inside)
163
* Answer 51:: very verbose mode
164
* Answer 52:: double inventory
165
* Answer 53:: Scrabble pieces
166
* Answer 54:: three denominations of coin
167
* Answer 55:: I Ching coins
168
* Answer 56:: tomato in red or green
169
* Answer 57:: the artiste formerly known as Princess
170
* Answer 58:: drinks machine
171
* Answer 59:: parsing adjectives
172
* Answer 60:: referring to objects by number
173
* Answer 61:: wild-card for a single object
174
* Answer 62:: wild-card for multiple objects
175
* Answer 63:: "fly in amber"
176
* Answer 64:: cherubim plural
177
* Answer 65:: Answer to Exercise 65
178
* Answer 66:: moving to a room by typing its name
179
* Answer 67:: genie muddling black and white
180
* Answer 68:: footnotes
181
* Answer 69:: low numbers in French
182
* Answer 70:: floating-point numbers
183
* Answer 71:: phone numbers
184
* Answer 72:: parsing times of day
185
* Answer 73:: spaceship control panel
186
* Answer 74:: implementing parser primitives
187
* Answer 75:: parsing any quoted text
188
* Answer 76:: tokens which never match
189
* Answer 77:: Answer to Exercise 77
190
* Answer 78:: third noun for parser
191
* Answer 79:: "scope" verb
192
* Answer 80:: "megalook" verb
193
* Answer 81:: putting everything in scope
194
* Answer 82:: room divided by glass window
195
* Answer 83:: dwarf breathing in dark
196
* Answer 84:: nose attached to player
197
* Answer 85:: sterilising machine
198
* Answer 86:: red sticky label
199
* Answer 87:: "lock" and "unlock" inferring keys
200
* Answer 88:: quotations in boxes
201
* Answer 89:: Invisiclues hints
202
* Answer 90:: saving the character
203
* Answer 91:: title page
204
* Answer 92:: status line invisible
205
* Answer 93:: status line showing treasure
206
* Answer 94:: status line with compass rose
207
* Answer 95:: status line with centred room
208
* Answer 96:: printf routine
211
File: inform, Node: Introduction, Next: Programming Language, Prev: Top, Up: Top
216
I will build myself a copper tower
217
With four ways out and no way in
218
But mine the glory, mine the power...
220
-- Louis MacNeice (1907-1963), Flight of the Heart
222
Inform is a system for creating adventure games, and this is the book to
225
Infocom format `story files' (adventure games, that is) can be
226
played on almost any computer, from personal organisers to mainframes,
227
with the aid of `interpreter' programs. The task of the Inform
228
`compiler' is to translate a textual description of a game into a story
229
file. The result will play identically on any machine of any model.
231
Inform is a suite of software, called the `library', as well as a
232
compiler. Without the library, it would be a major undertaking to
233
write a description of even the smallest game. The library has two
234
ingredients: the parser, a program for translating written English
235
inputs into a form games can more easily understand, and the "world
236
model", a complex web of rules common to all adventure games. Given
237
these, the designer only needs to describe things and give any
238
exceptional rules that apply. ("There is a bird here, which is a
239
normal item except that you can't pick it up.")
241
The library is rich in detail. The parser recognises over 80
242
distinct verbs and a vocabulary of about 300 words even before any
243
rooms or objects are created, and is programmable and highly flexible.
244
It can handle ambiguities, clarify its input by asking questions
245
("Which key do you mean...?") and can cope properly with plurals,
246
vagueness, conversation, pronouns and the player becoming someone else
247
in mid-game. It can be configured to languages other than English.
248
The world-model includes rooms, items, vehicles, duplicates,
249
containers, doors, things on top of other things, light and darkness,
250
switching things on and off, opening, closing and locking things,
251
looking up information in books, entering things, scoring and so forth.
253
Just as Inform has two strands -- compiler and library -- so this
254
manual has two parts: Programming and Designing. In Book One, small
255
computer programs are written to perform simple calculations, never
256
using the library. Subsections listed in slanted text on the detailed
257
contents page become technical but the rest is pitched at newcomers and
258
can be skim-read by anyone with prior experience of a programming
259
language such as C or Pascal. Book Two is entirely about making games.
261
Newcomers are invited to work through *Note Routines:: and *Note
262
Getting Started::, the "getting started" sections in Books One and Two,
263
before reading much more of either.
265
In trying to be both a tutorial and reference work, this book aims
266
itself in style halfway between the two extremes of manual, Tedium and
267
Gnawfinger's Elements of Batch Processing in COBOL-66, third edition,
268
and Mr Blobby's Blobby Book of Computer Fun. (This makes some sections
269
both leaden and patronising.) Passages which divert the main story,
270
usually to tell an unexpurgated truth which may confuse or bore a
271
newcomer, are marked with warning exclamation points `!!'. Examples of
272
program are set in typewriter font. Mundane or irrelevant passages in
273
longer examples are sometimes replaced with a line reading just "..."
275
To keep Book Two from clogging up with examples, many are set as
276
"exercises", with "answers" given in full at the back of the book.
277
Harder exercises are marked with exclamation points and some are very
278
hard indeed. I emphasize that the exercises are often intended as a
279
way of presenting answers to deliberately difficult questions, to
280
assist experts: the curse of Adventure design-languages is the feature
281
which is ideal for the simple but too inflexible to cope with the
282
complicated. For a list of exercises with page references to question
283
and answer, see under "exercises" in the Index.
285
A better tutorial than attempting the exercises, then, is probably
286
to make a simple game, as demonstrated in Chapter III, and then add an
287
example of each new feature as you work through Chapters IV and V.
289
Many sections end with a `References' paragraph referring to yet
290
more examples which can be found in Inform's demonstration games. All
291
of these have publically available source code (see the Inform home
292
page): those most frequently referred to are `Advent' (a full version
293
of the original mainframe `Adventure', which contains a good deal of
294
"everyday Inform"), `Adventureland' (a version of Scott Adams's
295
primitive classic), `Alice Through The Looking-Glass' (a heavily
296
annotated game, developed in the course of Gareth Rees's WWW tutorial
297
for Inform), `Balances' (a short story consisting of puzzles which
298
stretch the parser's abilities) and `Toyshop' (hardly a game: more an
299
incoherent collection of unusual objects). In addition, the little
300
game `Ruins' is developed in the course of Chapters III and IV of this
303
Finally, the "game" called `Museum of Inform' simulates a museum
304
whose exhibits are solutions to the exercises in this manual.
306
Copyright on Inform, the program and its source code, its example
307
games and documentation (including this book) is retained by Graham
308
Nelson, who asserts the moral right to be identified as the author
309
under the Copyrights, Designs and Patents Act 1988. Having said this,
310
I am happy for it to be freely distributed to anybody who wants a copy,
311
provided that: (a) distributed copies are not substantially different
312
from those archived by the author, (b) this and other copyright
313
messages are always retained in full, and (c) no profit is involved.
314
(Exceptions to these rules must be negotiated directly with the
315
author.) However, a story file produced with the Inform compiler (and
316
libraries) then belongs to its author, and may be sold for profit if
317
desired, provided that its game banner contains the information that it
318
was compiled by Inform, and the Inform version number.
320
The Internet source for Inform material (executables of the compiler
321
for different machines, source code, the library files and example
322
games) is the German National Research Centre for Computer Science,
323
where Volker Blasius maintains an archive at the anonymous FTP site
324
ftp.gmd.de. Inform can be found at:
326
ftp://ftp.gmd.de/if-archive/infocom/compilers/inform6
328
Another useful resource is the Inform 6 home page on the `World Wide
329
Web', which includes Gareth Rees's `Alice' tutorial, located at:
331
http://www.gnelson.demon.co.uk/inform.html
333
This manual describes Inform release 6.13 (or later), using library
334
release 6/5 (or later). Earlier Inform 6 compilers and libraries are
335
very similar but Inform 5.5 and 5/12 are very different.
337
This manual has evolved from seven earlier publications, once rather
338
makeshift and sometimes defensive ("Inform is an easel, not a
339
painting"). There were specifications of the run-time code format and
340
literary critiques of games gone by: like an oven manual padded out
341
with both a cookery book and a detailed plan of the gas mains. This
342
book contains just the instructions for the oven.
344
So there are four `companion volumes'. The Craft of Adventure is an
345
essay on the design of adventure games; The Z-Machine Standards
346
Document minutely covers the run-time format and Inform assembly
347
language, its lowest level; and The Inform Technical Manual documents
348
Inform's internal working in great detail, and includes a formal
349
context-free grammar for the Inform language. The Inform Translator's
350
Manual describes how to write a language definition file for games
351
which speak languages other than English.
353
Some of the ideas of Inform came from an incremental multi-player
354
game called Tera, on the Cambridge University mainframe, written by
355
Dilip Sequeira and the author in 1990 (whose compiler was called
356
Teraform); in turn, this stole a little from David Seal and Jonathan
357
Thackray's game assembler; which dates back to the close of the 1970s
358
and was written for `Acheton', perhaps the first worthwhile game
359
written outside America. Still, much of the Inform kernel derives
360
ultimately from the IEEE Computer article `Zork: A Computerized Fantasy
361
Simulation Game' by P. David Lebling, Marc S. Blank and Timothy A.
362
Anderson; and more was suggested by Richard Tucker and Gareth Rees,
365
The list of those who have helped the project along is legion: I
366
should like to thank them all, porters, users and critics alike, but
367
especially Volker Blasius, Paul David Doherty, Mark Howell, the ever
368
avuncular Bob Newell, Robert Pelak, Gareth Rees, Jorund Rian, Dilip
369
Sequeira, Richard Tucker, Christopher Wichura and John Wood.
371
One final word. I should like to dedicate this book, impertinently
372
perhaps, to our illustrious predecessors: Will Crowther, Don Woods and
373
the authors of Infocom, Inc.
379
And if no piece of chronicle we prove,
380
We'll build in sonnets pretty rooms;
381
As well a well wrought urn becomes
382
The greatest ashes, as half-acre tombs.
384
-- John Donne (1571?-1631), The Canonization
387
File: inform, Node: Programming Language, Next: Using the Compiler, Prev: Introduction, Up: Top
389
The Inform programming language
390
*******************************
392
Language is a cracked kettle on which we beat out tunes for bears
393
to dance to, while all the time we long to move the stars to pity.
395
-- Gustave Flaubert (1821-1880)
399
* Routines:: Constants, expressions, and functions
400
* Data Structures:: Directives, global variables, & arrays
401
* Objects:: Objects, properties, attributes, & messages
404
File: inform, Node: Routines, Next: Data Structures, Prev: Programming Language, Up: Programming Language
406
The language of routines
407
========================
411
* First Principles:: About the Inform programming language
412
* Example 1:: "Hello World", the simplest Inform program
413
* Example 2:: "Elsinore", introducing subroutines
414
* Numbers and Variables:: Using numbers and variables in Inform
415
* Arithmetic Expressions:: Inform's arithmetic operators
416
* Arguments and Return Values:: Calling and returning from routines
417
* Example 3:: "Cubes", a simple subroutine example
418
* Conditions:: Conditions are either true or false
419
* Example 4:: "Factorials", using the `if' statement
420
* Code Blocks:: Grouping statements; Using `else' and `switch'
421
* Loops:: while, do...until, for, break, & continue
422
* Example 5:: "RunPuzzle", using a simple `while' loop
423
* Jumping Around:: `quit', `jump', and the program state
424
* Printing Output:: String constants and printing output
425
* Example 6:: Printing numbers in hexadecimal
426
* Random and Indirect:: Two built-in functions: `random' and `indirect'
427
* Accepting Input:: Reading input from the keyboard
430
File: inform, Node: First Principles, Next: Example 1, Prev: Routines, Up: Routines
435
This chapter aims to introduce beginners to Inform as though it were
436
a general-purpose programming language (rather than a tool for designing
437
adventure games). The examples given will be short programs performing
438
simple calculations (rather than games). To begin with, the Inform
443
That is, the Inform compiler translates text written by the author
444
(called the "source code") into a program (called the "object code"
445
since it is the object of the exercise). This translation is only
446
done once, but the resulting program can be run many times.
450
That is, a program is divided into a number of "routines" (also
451
called "functions" or "procedures"), each being a list of orders
452
to be obeyed (though these orders are traditionally called
453
"statements"). When the program is run, only one thing happens at
454
a time: at any given moment, a single routine is being obeyed.
456
3. *Object-oriented.*
458
That is, the fabric of a typical Inform program will be woven
459
around "objects" being dealt with, which are regarded as being
460
self-contained. For example, a program to simulate a warehouse
461
might have objects representing lorries and containers; each
462
object would have a position and contents at any given time. The
463
program would have general rules describing "lorry" and
464
"container" as well as actual examples of each. A lorry would
465
have the ability to receive a message telling it to do something,
466
such as "load up with a container and leave the warehouse".
470
That is, once Inform has compiled the source code (having found no
471
mistakes), the resulting program can be run on almost any model of
472
computer. It will exhibit exactly the same behaviour on each of
473
them. It cannot depend on the "environment": it cannot suddenly
474
run out of memory and crash, for instance.
476
The computer runs an Inform program (which need not be a game) with the
477
aid of an "interpreter". There are at least 40 different interpreters
478
available for this format (called the "Z-machine" or "Infocom format")
479
and there may be a choice available for your model of computer: it is a
480
good idea to get the most modern and accurate possible. Look to see if
481
they support the Z-Machine Standard, and if so, up to what revision
485
File: inform, Node: Example 1, Next: Example 2, Prev: First Principles, Up: Routines
487
Example 1: Hello World
488
----------------------
490
Traditionally, all programming language tutorials begin by giving a
491
program which does nothing but print "Hello world" and stop. Here is
492
such a program in Inform:
494
! "Hello world" example program
497
print "Hello world^";
500
The text after the exclamation mark is a "comment", that is, it is
501
text written in the margin by the author to remind himself of what is
502
going on here. Such text means nothing to Inform, which ignores
503
anything on the same line and to the right of an exclamation mark.
505
Once commentary has been stripped out, Inform regards the source
506
code as a list of things to look at, divided by semicolons ;. It
507
treats line breaks, tab characters and spaces all as so-called "white
508
space": that is, a gap between two things whose size is unimportant.
509
Thus, exactly the same program would be produced by the source code
518
or, at the other extreme, by
520
[ Main;print"Hello world^";];
522
Laying out programs legibly is a matter of forming good habits.
524
!! The exception to the rule about ignoring white space is inside
527
"Hello world^" and "Hello world^"
529
are genuinely different pieces of text and are treated as such. Inform
530
treats text inside quotation marks with much more care than its ordinary
531
program material: for instance, an exclamation mark inside quotation
532
marks will not cause the rest of its line to be thrown away as a
535
Every program must contain a routine called Main, and in this
536
example it is the only routine. When a program is set running, the
537
first instruction obeyed is the first one in Main, and it carries on
538
line by line from there. This process is called "execution". When the
539
Main routine is finished, the program stops.
541
The routine has only one statement:
545
Printing is the process of writing text onto the computer screen. This
546
statement prints the two words "Hello world" and then skips the rest of
547
the line (or "prints a new-line"): the ^ character, in quoted text,
548
means "new-line". For example, the statement
550
print "Blue^Red^Green^"
558
print is one of 28 statements in the Inform language. The full list is
561
box break continue do font for give
562
if inversion jump move new_line objectloop print
563
print_ret quit read remove restore return rfalse
564
rtrue save spaces string style switch while
566
(Only about 20 of these are commonly used.) *Note Routines:: covers
567
all those not concerned with objects, which are left until *Note
571
File: inform, Node: Example 2, Next: Numbers and Variables, Prev: Example 1, Up: Routines
576
The following source code has three routines, Main, Rosencrantz and
580
print "Hello from Elsinore.^";
584
print "Greetings from Rosencrantz.^";
587
print "The rest is silence.^";
590
The resulting program prints up
593
Greetings from Rosencrantz.
595
but the text "The rest is silence." is never printed. Execution begins
596
at Main, and "Hello from Elsinore" is printed; next, the statement
597
Rosencrantz() causes the Rosencrantz routine to be executed. That
598
continues until it ends with the close-routine marker ], whereupon
599
execution goes back to Main just after the point where it left off:
600
since there is nothing more to do in Main, the program finishes. Thus,
601
Rosencrantz is executed but Hamlet is not.
603
In fact, when the above program is compiled, Inform notices that
604
Hamlet is never needed and prints out a warning to that effect. The
605
exact text produced by Inform varies from machine to machine, but will
606
be something like this:
608
RISC OS Inform 6.03 (May 11th 1996)
609
line 8: Warning: Routine "Hamlet" declared but not used
610
Compiled with 0 errors and 1 warning
612
Errors are mistakes in the program which cause Inform to refuse to
613
compile it, but this is only a warning. It alerts the programmer that
614
a mistake may have been made (because presumably the programmer has
615
simply forgotten to put in a statement calling Hamlet) but it doesn't
616
prevent the compilation from taking place. Note that the opening line
617
of the routine Hamlet occurs on the 8th line of the program above.
619
Usually there are mistakes in a newly-written program and one goes
620
through a cycle of running a first draft through Inform, receiving a
621
batch of error messages, correcting the draft according to these
622
messages, and trying again. A typical error message would occur if, on
623
line 3, we had mistyped Rosncrantz() for Rosencrantz(). Inform would
626
RISC OS Inform 6.03 (May 11th 1996)
627
line 5: Warning: Routine "Rosencrantz" declared but not used
628
line 8: Warning: Routine "Hamlet" declared but not used
629
line 3: Error: No such constant as "Rosncrantz"
630
Compiled with 1 error and 2 warnings (no output)
632
The error message means that on line 3 Inform ran into a name which did
633
not correspond to any known quantity (it isn't the name of any routine,
634
in particular). Note that Inform never produces the final story file
635
if errors occur during compilation: this prevents it from producing
636
damaged story files. Note also that Inform now thinks the routine
637
Rosencrantz is never used, since it didn't recognise the mistype in the
638
way that a human reader would have done. Warnings are sometimes
639
produced by accident this way, so it is generally a good idea to worry
640
about fixing errors first and warnings afterward.
643
File: inform, Node: Numbers and Variables, Next: Arithmetic Expressions, Prev: Example 2, Up: Routines
645
Numbers and variables
646
---------------------
648
Internally -- that is, whatever the outward appearance -- all
649
programs essentially manipulate numbers. Inform understands "number"
650
to be a whole number in the range -32768 to +32767. (Special
651
programming would be required to represent larger numbers or
652
fractions.) There are three notations for writing numbers in Inform:
653
here is an example of each.
659
The difference is the radix, or base, in which they are expressed. The
660
first is in decimal (base 10), the second hexadecimal (base 16, where
661
the digits after 9 are written a to f or A to F) and the third binary
662
(base 2). Once Inform has read in a number, it forgets which notation
663
was used: for instance, if the source code is altered so that $$10110
664
is replaced by 22, this makes no difference to the program produced.
666
A print statement can print numbers as well as text, though it always
667
prints them back in ordinary decimal notation. For example, the program
670
print "Today's number is ", $3f08, ".^";
675
Today's number is 16136.
677
since 16136 in base 10 is the same number as 3f08 in hexadecimal.
679
Inform recognises many other notations as "constants", that is,
680
values which are literally described in the source code. A full list
681
will appear later, but one other is that a single character between
682
single quotation marks, for instance
686
is a constant. A "character" is a single letter or typewriter-symbol,
687
and all that the programmer needs to know is that each possible
688
character has its own numerical value.
690
!! For most characters, this numerical value is the standard ASCII
691
value for the character: for instance, 'x' has numerical value 120.
692
(This is true even if Inform is being run on a model of computer which
693
doesn't normally use the ASCII character set.) Exotic characters such
694
as '@ss' (the Inform notation for German sz) have non-standard codes:
695
see the Z-Machine Standards Document if you really need to know.
697
Finally, in this initial batch of constant notations, Inform provides
698
two special constants:
703
which are used to describe the truth or otherwise of possible
706
!! true has the numerical value 1; false has the numerical value 0.
708
Inform has a concept of "variable" like that used in algebra, where
709
it is easy but limiting to express facts using only numbers:
715
Although suggestive this fails to express the general case: that any
716
number subtracted from itself leaves zero. We express this fact
717
symbolically in algebra by writing
721
where x is a variable; the implication being "whatever value x actually
722
is, the statement is still true".
724
Likewise, in Inform what seems to be a word of text may be a
725
variable which represents a number: when the source code is compiled,
726
Inform cannot know what numerical value this text represents. When the
727
program is run, it will always have a numerical value at any given
728
time. If oil_left is a variable, the statement
730
print "There are ", oil_left, " gallons remaining.^";
732
is executed as if oil_left were replaced by whatever that value
733
currently is. Later on, the same statement may be executed again,
734
producing different text because by that time oil_left has a different
737
Inform can only know that text (such as oil_left) represents a
738
variable if the source code has "declared" that it does. Each routine
739
can declare its own selection of variables on its opening line. For
740
example, in the program
745
print "Alpha is ", alpha, " while b is ", b, "^";
748
the Main routine has two variables, alpha and b. Like most names given
749
in source code (called "identifiers"), variable names can be at most 32
750
characters long and may contain letters of the alphabet, decimal digits
751
or the underscore _ character (often used to imitate a space). To
752
prevent them looking too much like numbers, though, they may not start
753
with a decimal digit. (So a44 is legal but 44a is not.) For example:
759
are all possible variable names. Inform ignores any difference between
760
upper and lower case letters in such names, for example considering
761
CHArt45 as the same name as chArT45.
763
The = sign occurring twice in the above routine is an example of an
764
"operator": a notation usually made up of the symbols on the
765
non-alphabetic keys on a typewriter and which means something is to be
766
done with the items it is written next to. In this context, = means
767
"set equal to". When the statement alpha = 2200 is executed at run
768
time, the current value of the variable alpha becomes 2200 (and it
769
keeps that value until another such statement changes it).
771
The variables alpha and b are called "local variables" because they
772
are local to Main: in effect, they are its private property. The
783
causes an error on the print statement in Rival, since alpha does not
784
exist there. Indeed, Rival could even have defined a variable of its
785
own also called alpha and this would have been a separate variable with
786
a probably different value.
789
File: inform, Node: Arithmetic Expressions, Next: Arguments and Return Values, Prev: Numbers and Variables, Up: Routines
791
Arithmetic expressions
792
----------------------
794
The Inform language is rich with operators, making it concise but
795
not always very readable. Feeling comfortable with the operators is
796
the main step towards being able to follow Inform source code.
797
Fortunately, these operators are based on the usual rules for writing
798
arithmetic formulae, which gives them a headstart in familiarity.
800
Indeed, the most commonly used operators are "arithmetic": they
801
combine one or more numbers to give one resulting number. Whenever a
802
number is expected in a statement, a general "expression" can be given
803
instead: that is, a calculation giving a number as a result. For
804
example, the statement
806
seconds = 60*minutes + 3600*hours
808
sets the variable seconds equal to 60 times the variable minutes plus
809
3600 times the variable hours. White space is not needed between
810
operators and "operands" (the numbers to be operated on): the spaces on
811
either side of the + sign are only provided for legibility.
813
Ordinary arithmetic is carried out with the operators + (plus), -
814
(minus), * (times) and / (divided by).
816
Usually dividing one integer by another leaves a remainder: for
817
example, 3 goes into 7 twice, with remainder 1. In Inform notation,
822
the % operator meaning "remainder after division", usually called just
823
"remainder". Dividing by zero is impossible and a program which tries
824
to do this will go wrong.
826
!! As a brief aside, this gives an example of how Inform can and can't
827
help the programmer to spot mistakes. The program
833
produces an error when compiled:
835
line 2: Error: Division of constant by zero
838
since Inform can see that it definitely involves doing something
839
illegal. However, Inform fails to notice anything amiss with the
847
and this program compiles correctly. The resulting story file will
848
"crash" when it is run, that is, catastrophically halt. The moral is
849
that just because Inform compiles a program without errors, it does not
850
follow that the program does what the programmer intends.
852
In a complicated expression the order in which the operators work may
853
affect the result. As most human readers would, Inform works out both
859
to 1423, because the operator * has "precedence" over + and so is acted
860
on first. Brackets may be used to overcome this:
865
evaluate to 17500 and 1446 respectively. Each operator has such a
866
"precedence level". When two operators have the same precedence level
867
(for example, + and - are of equal precedence) calculation is (almost
868
always) "left associative", that is, carried out left to right: the
877
The standard rules for writing mathematics give + and - equal
878
precedence, lower than that of * and / (which are also equal). Inform
879
agrees and also pegs % equal to * and /.
881
The final purely arithmetic operator is "unary minus". This is
882
written as a minus sign - but is not the same as ordinary subtraction.
887
means the same thing as:
891
The operator - is different from all those mentioned so far because it
892
operates only on one number. It has higher precedence than any of the
893
five "binary" operations above. For example,
897
means (-credit) - 5 and not -(credit - 5).
899
One way to imagine precedence is to think of it as glue attached to
900
the operator. A higher level means stronger glue. Thus, in
904
the glue around the * is stronger than that around the +, so that 2 and
905
700 belong bound to the *.
907
Some operators do not simply act on values but actually change the
908
current values of variables: expressions containing these are called
909
"assignments" (because they assign values as well as working them out).
910
One such operator is `set equals':
914
sets the variable alpha equal to 72. Just like + and the others, it
915
also comes up with an answer: as it happens, this value is also 72.
917
The other two assignment operators are ++ and --, which will be
918
familiar to any C programmer. They are unary operators, and can be used
919
in any of the following ways:
926
The first of these means "read off the value of variable, and afterwards
927
increase that value by one". In ++variable the "increment" (or
928
increase by 1) happens first, and then the value is read off. -- acts
929
in a similar way but "decrements" (decreases by 1). These operators
930
are provided as convenient shorthand forms, since their effect could
931
usually be achieved in other ways (just using + and -).
933
For example, suppose the variable has value 12. Then the result
934
would be 12, 13, 12 or 11 respectively; the value left in variable
935
afterwards would be 13, 13, 11 or 11.
937
Note that expressions like
939
500++ (4*alpha)-- 34 = beta
941
are meaningless: the values of 500 and 34 cannot be altered, and Inform
942
knows no way to adjust alpha so as to make 4*alpha decrease by 1. All
943
three will cause errors.
945
!! "Bitwise operators" are provided for manipulating binary numbers on
946
a digit-by-digit basis, something which is often done in programs which
947
are working with low-level data or data which has to be stored very
948
compactly. Inform provides &, bitwise AND, |, bitwise OR and ~, bitwise
949
NOT. For each digit, such an operator works out the value in the answer
950
from the values in the operands. Bitwise NOT acts on a single operand
951
and results in the number whose i-th binary digit is the opposite of
952
that in the operand (a 1 for a 0, a 0 for a 1). Bitwise AND (and OR)
953
acts on two numbers and sets the i-th digit to 1 if both operands have
954
(either operand has) i-th digit set. So, for example,
956
$$10111100 & $$01010001 == $$00010000
958
!! The remaining operators will be described as needed: the full table
959
is laid out in *Note Operators::.
962
File: inform, Node: Arguments and Return Values, Next: Example 3, Prev: Arithmetic Expressions, Up: Routines
964
Arguments and Return Values
965
---------------------------
967
As has already been said, in Inform jargon the word "function" is
968
synonymous with "routine". A function might be defined as a
971
(x1 , ... , xn) --> f(x1 , ... , xn)
973
where a set of input numbers are fed in, and a single value comes out.
974
These input numbers are called "arguments". The value coming out is the
975
"return value", or is said to be "returned".
977
All Inform routines are like this. A number of arguments are fed in
978
when the routine is "called" (that is, set running) and there is always
979
a single numerical result. This result is called the "return value"
980
because it is returned to the rest of the program. Some very simple
981
routines conceal this. For instance, consider Sonnet:
987
print "When to the sessions of sweet silent thought^";
988
print "I summon up remembrance of things past^";
991
Sonnet is a routine which takes as input no arguments at all (it is an
992
example of the n=0 case), so it is called with nothing in between the
993
round brackets. Although it does return a value (as it happens, this
994
value is true) the statement Sonnet() simply calls the routine and
995
throws the return value away. If Main were instead given by
1001
then the output would be
1003
When to the sessions of sweet silent thought
1004
I summon up remembrance of things past
1007
because the print statement in Main has been told to print the number
1008
resulting from a call to Sonnet.
1010
Thus in Inform there is no such thing as a "void function" or
1011
"procedure": every routine returns a number even though this may
1012
immediately be thrown away as unwanted.
1014
When a routine is called,
1018
the arguments given are substituted into the first variables declared
1019
for Routine, and execution begins running through Routine. Usually,
1020
there can be any number of arguments from none up to 7, though a limit
1021
of 3 applies if Inform has been told to compile an early-model story
1022
file (see *Note Run-Time Limitations:: for details).
1024
If execution runs into the ] end-of-routine marker, so that the
1025
routine is finished without having specified any definite return value,
1026
then this value is true. (This is why the printed return value of
1027
Sonnet is 1: true has the value 1.)
1030
File: inform, Node: Example 3, Next: Conditions, Prev: Arguments and Return Values, Up: Routines
1035
A more typical, though less aesthetic, example than Sonnet:
1048
which, when executed, prints
1052
The expression Cube(3) is calculated by substituting the number 3 into
1053
the variable x when Cube is set running: the result of the expression
1054
is the number returned by Cube.
1056
Any "missing arguments" in a routine call are set equal to zero, so
1057
the call Cube() is legal and does the same as Cube(0).
1060
File: inform, Node: Conditions, Next: Example 4, Prev: Example 3, Up: Routines
1062
Conditions: if, true and false
1063
------------------------------
1065
Such routines are too simple, so far, even to express many
1066
mathematical functions, and more flexibility will be needed.
1068
A "control construct" is a kind of statement which controls whether
1069
or not, and if so how many times or in what order, other statements are
1070
executed. The simplest of these is if:
1072
if (<condition>) <statement>
1074
which executes the <statement> only if the <condition>, when it is
1075
tested, turns out to be true. For example, when the statement
1077
if (alpha == 3) print "Hello";
1079
is executed, the word "Hello" is printed only if the variable alpha
1080
currently has value 3. It is important not to confuse the == operator
1081
(test whether or not equal to) with the = operator (set equal to).
1083
Conditions are always given in (round) brackets. The basic
1084
conditions are as follows:
1085
(a == b) Number a equals number b
1086
(a ~= b) Number a doesn't equal number b
1087
(a >= b) a is greater than or equal to b
1088
(a <= b) a is less than or equal to b
1089
(a > b) a is greater than b
1090
(a < b) a is less than b
1091
(o1 in o2) Object o1 possessed by o2
1092
(o1 notin o2) Object o1 not possessed by o2
1093
(o1 has a) Object o1 has attribute a
1094
(o1 hasnt a) Object o1 hasn't attribute a
1095
(o1 provides m) Object o1 provides property m
1096
(o1 ofclass c) Object o1 inherits from class c
1098
(The conditions relating to objects will be discussed later.) A useful
1099
extension to this set is provided by the special operator or, which
1100
gives alternative possibilities. For example,
1102
if (alpha == 3 or 4) print "Scott";
1103
if (alpha ~= 5 or 7 or 9) print "Amundsen";
1105
where two or more values are given with the word or between. Scott is
1106
printed if alpha has value either 3 or 4, and Amundsen if the value of
1107
alpha is not 5, is not 7 and is not 9. or can be used with any of the
1108
conditions, and any number of alternatives can be given. For example
1110
if (player in Forest or Village or Building) ...
1112
often makes code much clearer than writing three separate conditions
1115
if (x > 100 or y) ...
1117
can be convenient to check whether x is bigger than the minimum of 100
1120
Conditions can also be built up from simpler ones (just as long
1121
expressions are built up from single operators) using the three logical
1122
operators &&, || and ~~ (pronounced "and", "or" and "not"). For
1125
if (alpha == 1 && (beta > 10 || beta < -10)) print "Lewis";
1126
if (~~(alpha > 6)) print "Clark";
1128
"Lewis" is printed if alpha equals 1 and beta is outside the range -10
1129
to 10; "Clark" is printed if alpha is less than or equal to 6.
1131
The discussion above makes it look as if conditions are special
1132
kinds of expression which can only use certain operators (==, &&, or
1133
and so on). But this is not true: conditions are expressions like any
1134
other. It's legal to write
1138
for instance, and this results in 1 being printed if beta equals 4, and
1141
the result of a true condition is 1;
1142
the result of a false condition is 0.
1144
This is why true and false are defined to be 1 and 0 respectively.
1145
Thus one might write code along the lines of
1147
betaisfour = (beta == 4);
1149
if (betaisfour == true) ...
1151
though it would be easier to write
1153
betaisfour = (beta == 4);
1157
because, just as conditions can be used as numbers, so numbers can be
1158
used as conditions. Zero is considered to be "false", and all other
1159
values are considered to be "true". Thus
1161
if (1) print "Magellan";
1162
if (0) print "da Gama";
1164
always results in "Magellan", never "da Gama", being printed.
1166
One common use of variables is as "flags". A flag can only hold the
1167
value 0 or 1, false or true according to some state of the program.
1168
The fact that a number can be used as a condition allows
1169
natural-looking statements like
1171
if (lower_caves_explored) print "You've already been that way.";
1173
where lower_caves_explored is a variable being used in the program as a
1176
!! Note that && and || only work out what they absolutely need to in
1177
order to decide the truth. That is,
1181
will work out A first. If this is false, there's no need to work out B,
1182
and it never is worked out. Only if A is true is B actually tested.
1183
This only matters when working out conditions like
1185
if (x==7 && Routine(5)) ...
1187
where it can be important to know that the Routine is never called if x
1188
has a value other than 7.
1191
File: inform, Node: Example 4, Next: Code Blocks, Prev: Conditions, Up: Routines
1193
Example 4: Factorials
1194
---------------------
1196
The factorial of a positive integer n is defined as the product
1200
so that, for example, the factorial of 4 is 24. Here is an Inform
1201
routine to calculate factorials:
1204
print Factorial(7), "^";
1208
return n*Factorial(n-1);
1211
This calculates 7 factorial and comes up with 5040. (Factorials grow
1212
rapidly and 8 factorial is already too large to hold in a standard
1213
Inform number, so calling Factorial(8) would give a wrong answer.)
1215
The routine Factorial actually calls itself: this is called
1216
"recursion". Execution reaches "seven routines deep" before starting
1217
to return back up. Each of these copies of Factorial runs with its own
1218
private copy of the variable n.
1220
Recursion is hazardous. If one calls the routine
1226
then despite the reassuring presence of the word return, execution is
1227
tied up forever, unable to finish evaluating the return value. The
1228
first call to Disaster needs to make a second before it can finish; the
1229
second needs to make a third; and so on. This is an example of a
1230
programming error which will prove disastrous when the program is run,
1231
yet will cause no errors when the source code is compiled. (It can be
1232
proved that it is impossible to construct a compiler capable of
1233
detecting this general class of mistake. Inform does not even try.)
added
removed
info/inform-1
