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: Creating Objects, Next: Using the Tree, Prev: Object Tree, Up: Objects
20
Creating objects 1: setting up the tree
21
---------------------------------------
23
The object tree's initial state is created with the directive
27
Object -> "starfish" ...
28
Object -> "oyster" ...
29
Object -> -> "pearl" ...
32
(where the bulk of the definitions are here abbreviated to "..."), sets
37
"starfish" --> "oyster" --> "sand"
41
The idea is that if no arrows -> are given in the Object definition,
42
then the object has no parent: if one -> is given, then the object is a
43
child of the last object to be defined with no arrows; if two are
44
given, then it's a child of the last object defined with only one
45
arrow; and so on. (The list of definitions looks a little like the
46
tree picture turned on its side.)
48
An object definition consists of a "head" followed by a "body",
49
which is itself divided into "segments" (though there the similarity
50
with caterpillars ends). The head takes the form:
52
Object <arrows> <name> "textual name" <parent>
54
but all of these four entries are optional.
56
1. The <arrows> are as described above. Note that if one or more
57
arrows are given, that automatically specifies what object this is
58
the child of, so a <parent> cannot be given as well.
60
2. The <name> is what the object can be called inside the program;
61
it's analogous to a variable name.
63
3. The "textual name" can be given if the object's name ever needs to
64
be printed by the program when it is running.
66
4. The <parent> is an object which this new object is to be a child
67
of. (This is an alternative to supplying arrows.)
69
So much is optional that even the bare directive
73
is allowed, though it makes a nameless and featureless object which is
74
unlikely to be useful.
77
File: inform, Node: Using the Tree, Next: Objects with Properties, Prev: Creating Objects, Up: Objects
79
Statements for objects: move, remove, objectloop
80
------------------------------------------------
82
The positions of objects in the tree are by no means fixed: they are
83
created in a particular formation but are often shuffled around
84
extensively during the program's execution. (In an adventure game,
85
where the objects represent items and rooms, objects are moved in the
86
tree whenever the player picks something up or moves around.) The
89
move <object> to <object>
91
moves the first-named object to become a child of the second-named one.
92
All of the first object's own children "move along with it", i.e.,
93
remain its own children. For instance, following the example in *Note
96
move Cucumber to Mailbox;
102
Mailbox -----------> Player
104
Cucumber -> Note Sceptre -> Torch -> Magic Rod
108
It must be emphasized that move prints nothing on the screen, and indeed
109
does nothing at all except to rearrange the tree. When an object
110
becomes the child of another in this way, it always becomes the
111
"eldest" child in the family-tree sense; that is, it is the new child()
112
of its parent, pushing the previous children over into being its
113
siblings. It is, however, illegal to move an object out of such a
116
move Torch to nothing;
118
because nothing is not an object as such. The effect is instead
123
which would now result in
127
Mailbox -----------> Player Battery
129
Cucumber -> Note Sceptre -> Magic Rod
131
So the "object tree" is often fragmented into many little trees.
133
Since objects move around a good deal, it's useful to be able to test
134
where an object currently is; the condition in is provided for this.
139
is true if and only if the Cucumber is one of the direct children of
140
the Mailbox. (Cucumber in Mailbox is true, but Cucumber in Meadow is
145
is only an abbreviation for
149
but it's worth having since it occurs so often.
151
The one loop statement missed out in *Note Routines:: was objectloop.
153
objectloop(<variable-name>) <statement>
155
runs through the <statement> once for each object in the tree, putting
156
each object in turn into the variable. For example,
158
objectloop(x) print (name) x, "^";
160
prints out a list of the textual names of every object in the tree.
161
(Objects which aren't given any textual names in their descriptions
162
come out as "?".) More powerfully, any condition can be written in the
163
brackets, as long as it begins with a variable name.
165
objectloop(x in Mailbox) print (name) x, "^";
167
prints the names only of those objects which are direct children of the
171
File: inform, Node: Objects with Properties, Next: Private Properties, Prev: Using the Tree, Up: Objects
173
Creating objects 2: with properties
174
-----------------------------------
176
So far Objects are just tokens with names attached which can be
177
shuffled around in a tree. They become interesting when data and
178
routines are attached to them, and this is what the body of an object
181
The body contains up to four segments, which can occur in any order;
182
each of the four is optional. The segments are called
184
with has class private
186
class will be left until later. The most important segment is with,
187
which specifies things to be attached to the object. For example,
189
Object magpie "black-striped bird"
190
with wingspan, worms_eaten;
192
attaches two variables to the bird, one called wingspan, the other
193
called worms_eaten. Notice that when more than one variable is given,
194
commas are used to separate them: and the object definition as a whole
195
is ended by a semicolon, as always. The values of the magpie's
196
variables are referred to in the rest of the program as
201
which can be used exactly the way normal (global) variables are used.
202
Note that the object has to be named along with the variable, since
204
crested_glebe.wingspan
207
are different variables.
209
Variables which are attached to objects in this way are called
210
"properties". More precisely, the name wingspan is said to be a
211
property, and is said to be "provided" by both the magpie and
212
crested_glebe objects.
214
The presence of a property can be tested using the provides
215
condition. For example,
217
objectloop (x provides wingspan) ...
219
executes the code ... for each object x in the game which is defined
220
with a wingspan property.
222
!! Although the provision of a property can be tested, it cannot be
223
changed while the program is running. The value of magpie.wingspan may
224
change, but not the fact that the magpie has a wingspan.
226
When the above magpie definition is made, the initial values of
231
are both 0. To create the magpie with a given wingspan, we have to
232
specify an initial value: we do this by giving it after the name, e.g.
234
Object magpie "black-striped bird"
235
with wingspan 5, worms_eaten;
237
and now the program begins with magpie.wingspan equal to 5, and
238
magpie.worms_eaten still equal to 0. (For consistency perhaps there
239
should be an equals sign before the 5, but if this were the syntax then
240
Inform programs would be horribly full of equals signs.)
242
!! Properties can be arrays instead of global variables. If two or more
243
consecutive values are given for the same property, it becomes an
246
Object magpie "black-striped bird"
247
with name "magpie" "bird" "black-striped" "black" "striped",
248
wingspan 5, worms_eaten;
250
magpie.name is not a global variable (and cannot be treated as such: it
251
doesn't make sense to add 1 to it), it is an --> array. This must be
252
accessed using two special operators, .& and .#.
256
means "the array which is held in magpie's name property", so that the
257
actual name values are in the entries
264
The size of this array can be discovered with
268
which evaluates to the twice the number of entries, in this case, to 10.
269
(Twice the number of entries because it is actually the number of byte
270
array, ->, entries: byte arrays take only half as much storage as word
273
!! name is actually a special property created by Inform. It has the
274
unique distinction that textual values in double-quotes (like the five
275
words given in magpie.name above) are entered into the game's
276
dictionary, and not treated as ordinary strings. (Normally one would
277
use single-quotes for this. The rule here is anomalous and goes back
278
to the misty origins of Inform 1.) If you prefer a consistent style,
281
Object magpie "black-striped bird"
282
with name 'magpie' 'bird' 'black-striped' 'black' 'striped',
283
wingspan 5, worms_eaten;
285
works equally well (except that single-character names like "X" then
286
have to be written #n$X).
288
Finally, properties can also be routines. In the definition
290
Object magpie "black-striped bird"
291
with name "magpie" "bird" "black-striped" "black" "striped",
294
[; return magpie.wingspan + magpie.worms_eaten;
298
magpie.flying_strength is neither a variable nor an array, but a
299
routine, given in square brackets as usual. (Note that the Object
300
directive continues where it left off after the routine-end marker, ].)
301
Routines which are written in as property values are called "embedded"
302
and are mainly used to receive messages (as we shall see).
304
!!!! Embedded routines are unlike ordinary ones in two ways:
305
1. An embedded routine has no name of its own, since it is referred to
306
as a property such as magpie.flying_strength instead.
308
2. If execution reaches the ] end-marker of an embedded routine, then
309
it returns false, not true (as a non-embedded routine would). The
310
reason for this will only become clear in Chapter III when before
311
and after rules are discussed.
314
File: inform, Node: Private Properties, Next: Using Attributes, Prev: Objects with Properties, Up: Objects
316
private properties and encapsulation
317
------------------------------------
319
!! An optional system is provided for "encapsulating" certain
320
properties so that only the object itself has access to them. These
321
are defined by giving them in a segment of the object declaration
322
called private. For instance,
324
Object sentry "sentry"
325
private pass_number 16339,
328
if (attempt == sentry.pass_number)
330
"Stand off, stranger.";
333
makes the sentry provide two properties: challenge, which is public,
334
and pass_number, which can be used only by the sentry's own embedded
337
!!!! This makes the provides condition slightly more interesting than it
338
appeared in the previous section. The answer to the question of whether
341
sentry provides pass_number
343
depends on who's asking: this condition is true if it is tested in one
344
of the sentry's own routines, and otherwise false. A private property
345
is so well hidden that nobody else can even know whether or not it
349
File: inform, Node: Using Attributes, Next: Classes and Inheritance, Prev: Private Properties, Up: Objects
351
Attributes, give and has
352
------------------------
354
In addition to properties, objects have flag variables attached.
355
(Recall that flags are variables which are either true or false: the
356
flag is either flying, or not.) However, these are provided in a way
357
which is quite different. Unlike property names, attribute names have
358
to be declared before use with a directive like:
362
Once this declaration is made, every object in the tree has a tedious
363
flag attached, which is either true or false at any given time. The
364
state can be tested by the has condition:
366
if (magpie has tedious) ...
368
tests whether the magpie's tedious flag is currently set, or not.
370
The magpie can be created already having attributes using the has
371
segment in its declaration:
373
Object magpie "black-striped bird"
374
with wingspan, worms_eaten
377
The has segment contains a list of attributes (with no commas in
378
between) which should be initially set. In addition, an attribute can
379
have a tilde ~ in front, indicating "this is definitely not held".
380
This is usually what would have happened anyway, but class inheritance
381
(see below) disturbs this.
383
Finally, the state of such a flag is changed in the running of the
384
program using the give statement:
388
sets the magpie's tedious attribute, and
390
give magpie ~tedious;
392
clears it again. The give statement can take a list of attributes, too:
394
give door ~locked open;
396
for example, meaning "take away locked and add on open".
399
File: inform, Node: Classes and Inheritance, Next: Messages, Prev: Using Attributes, Up: Objects
401
Classes and inheritance
402
-----------------------
404
Having covered routines and strings in *Note Routines::, and Objects
405
above, the fourth and final metaclass to discuss is that of "classes".
406
A class is a kind of prototype object from which other objects are
407
copied. These other objects are sometimes called "instances" or
408
"members" of the class, and are said to "inherit from" it.
410
For example, clearly all birds ought to have wingspans, and the
414
[; return magpie.wingspan + magpie.worms_eaten;
417
(attached to the magpie in the example above) is using a formula which
418
should work for any bird. We might achieve this by using directives as
424
[; return self.wingspan + self.worms_eaten;
430
Bird "crested glebe";
436
The first definition sets up a new class called Bird. Every example
437
of a Bird now automatically provides wingspan, a flying_strength
438
routine and a count of worms_eaten. Note that the four actual birds
439
are created using the Bird class-name instead of the usual plain Object
440
directive, but this is only a convenient short form for definitions
447
where class is the last of the four object definition segments. It's
448
just a list of classes which the object has to inherit from.
450
The Bird routine for working out flying_strength has to be written
451
in such a way that it can apply to any bird. It has to say "the flying
452
strength of any bird is equal to its wingspan plus the number of worms
453
it has eaten". To do this, it has used the special value self, which
454
means "whatever object is being considered at the moment". More of
455
this in the next section.
457
Note also that the Bird with specifies a wingspan of 7. This is the
458
value which its members will inherit, unless their own definitions
459
over-ride this, as the magpie and great Auk objects do. Thus the
462
Bird Value of wingspan Value of worms_eaten
468
!!!! In rare cases, clashes between what a class says and what the
469
object says are resolved differently: see *Note Messages and Classes::.
471
Inform has "multiple inheritance", which means that any object can
472
inherit from any number of classes. Thus, an object has no single
473
class; rather, it can be a member of several classes at once.
475
Every object is a member of at least one class, because the four
476
"metaclasses" Routine, String, Object and Class are themselves classes.
477
(Uniquely, Class is a member of itself.) The magpie above is a member
478
of both Bird and Object.
480
To complicate things further, classes can themselves inherit from
490
makes kestrel a member of both BirdOfPrey and of Bird. Informally,
491
BirdOfPrey is called a "subclass" of Bird.
493
Given all this, it's impossible to have a function called class,
494
analogous to metaclass, to say what class something belongs to.
495
Instead, there is a condition called ofclass:
497
kestrel ofclass Class
501
kestrel ofclass BirdOfPrey
503
kestrel ofclass Object
504
"Canterbury" ofclass String
506
are all true. This condition is especially handy for use with
509
objectloop (x ofclass Bird) move x to Aviary;
511
moves all the birds to the Aviary.
514
File: inform, Node: Messages, Next: Access to Superclass Values, Prev: Classes and Inheritance, Up: Objects
519
That completes the story of how to create objects, and it's time to
520
begin communicating with them by means of messages. Every message has
521
a sender, a receiver and some parameter values attached, and it always
522
produces a reply (which is just a single value). For instance,
524
x = lamp.addoil(5, 80);
526
sends the message addoil with parameters 5 and 80 to the object lamp,
527
and puts the reply value into x. Just as properties like
528
magpie.wingspan are variables attached to objects, so messages are
529
received by routines attached to objects, and message-sending is very
530
like making an ordinary Inform function call. The "reply" is what was
531
called the return value in *Note Routines::, and the "parameters" used
532
to be called function call arguments. But slightly more is involved,
533
as will become apparent.
535
What does the lamp object do to respond to this message? First of all,
536
it must do something. If the programmer hasn't specified an addoil
537
routine for the lamp, then an error message will be printed out when
538
the program is run, along the lines of
540
*** The object "lamp" does not provide the property "addoil" ***
542
Not only does lamp.addoil have to exist, but it has to hold one of the
543
four kinds of object, or else nothing. What happens next depends on
544
the metaclass of lamp.addoil:
546
metaclass What happens: The reply is:
547
========= ============================ =========================
549
Routine the routine is called with the routine's return value
551
String the string is printed, true
552
followed by a new-line
553
Object nothing the object
554
Class nothing the class
555
nothing nothing false, or 0, or nothing
556
(all different ways of
559
!! If lamp.addoil is a list rather than a single value then the first
560
entry is the one looked at, and the rest are ignored.
564
print kestrel.flying_strength();
566
will print out 15, by calling the flying_strength routine provided by
567
the kestrel (the same one it inherited from Bird), which adds its
568
wingspan of 15 to the number of worms it has so far eaten (none), and
569
then returns 15. (You can see all the messages being sent in a game as
570
it runs with the debugging verb "messages": see *Note Debugging:: for
573
!! For examples of all the other kinds of receiving property, here is
574
roughly what happens when the Inform library tries to move the player
575
northeast from the current room (the location) in an adventure game:
577
x = location.ne_to();
578
if (x == nothing) "You can't go that way.";
579
if (x ofclass Object) move player to x;
581
This allows directions to be given with some flexibility in properties
582
like ne_to and so on:
584
Object Octagonal_Room "Octagonal Room"
586
ne_to "The north-east doorway is barred by an invisible wall!",
589
[; if (Amulet has worn)
590
{ print "A section of the eastern wall suddenly parts before
591
you, allowing you into...^";
596
[; if (random(5) ~= 1) return Gateway;
597
print "The floor unexpectedly gives way, dropping you through
598
an open hole in the plaster...^";
599
return random(Maze1, Maze2, Maze3, Maze4);
602
Two special variables help with the writing of message routines:
603
self and sender. self always has as value the Object which is
604
receiving the message, while sender has as value the Object which sent
605
it, or nothing if it wasn't sent from Object (but from some
606
free-standing routine). For example,
609
[; if (~~(sender ofclass CIA_Operative))
610
"Sorry, you aren't entitled to know that.";
615
File: inform, Node: Access to Superclass Values, Next: Philosophy, Prev: Messages, Up: Objects
617
Access to superclass values
618
---------------------------
620
!! A fairly common situation in Inform coding is that one has a general
621
class of objects, say Treasure, and wants to create an instance of this
622
class which behaves slightly differently. For example, we might have
626
[; if (self provides deposit_points)
627
score = score + self.deposit_points;
628
else score = score + 5;
629
"You feel a sense of increased esteem and worth.";
632
and we want to create an instance called Bat_Idol which (say) flutters
633
away, resisting deposition, but only if the room is dark:
635
Treasure Bat_Idol "jewelled bat idol"
637
[; if (location == thedark)
639
"There is a clinking, fluttering sound!";
644
In place of ..., we have to copy out all of the previous code about
645
depositing treasures. This is clumsy: what we really want is a way of
646
sending the deposit message to Bat_Idol but "as if it had not changed
647
the value of deposit it inherited from Treasure". We achieve this with
648
the so-called superclass operator, ::. (The term "superclass" is
649
borrowed from the Smalltalk-80 system, where it is more narrowly
650
defined.) Thus, in place of ..., we could simply write:
652
self.Treasure::deposit();
654
to send itself the deposit message again, but this time diverted to the
655
property as provided by Treasure.
657
The :: operator works on all property values, not just for message
660
object.class::property
662
evaluates to the value of the given property which the class would
663
normally pass on (or gives an error if the class doesn't provide that
664
property or if the object isn't a member of that class). Note that ::
665
exists as an operator in its own right, so it is perfectly legal to
668
x = Treasure::deposit; Bat_Idol.x();
670
To continue the avian theme, BirdOfPrey might have its own
671
flying_strength routine:
674
[; return self.Bird::flying_strength() + self.people_eaten;
677
reflecting the idea that, unlike other birds, these can gain strength by
681
File: inform, Node: Philosophy, Next: Sending Messages, Prev: Access to Superclass Values, Up: Objects
686
!!!! This section is best skipped until the reader feels entirely happy
687
with the rest of Chapter I. It is aimed mainly at those worried about
688
whether the ideas behind the apparently complicated system of classes
689
and objects are sound. (As Stephen Fry once put it, "Socialism is all
690
very well in practice, but does it work in theory?") We begin with two
694
a member of the program's object tree, or a routine in the
695
program, or a literal string in the program. (Routines and
696
strings can't, of course, be moved around in the object tree, but
697
the tests ofclass and provides can be applied to them, and they
698
can be sent messages.) Objects are part of the compiled program
702
an abstract name for a set of objects in the game, which may have
703
associated with it a set of characteristics shared by its objects.
704
Classes themselves are frequently described by text in the
705
program's source code, but are not part of the compiled program
708
Here are the full rules:
709
1. Compiled programs are composed of objects, which may have variables
710
attached called "properties".
712
2. Source code contains definitions of both objects and classes.
714
3. Any given object in the program either is, or is not, a member of
717
4. For every object definition in the source code, an object is made
718
in the final program. The definition specifies which classes this
719
object is a member of.
721
5. If an object X is a member of class C, then X "inherits" property
722
values as given in the class definition of C.
724
The details of how inheritance takes place are omitted here. But
725
note that one of the things which can be inherited from class C is
726
being a member of some other class, D.
728
6. For every class definition, an object is made in the final program
729
to represent it, called its "class-object".
731
For example, suppose we have a class definition like:
736
The class Dwarf will generate a class-object in the final program,
737
also called Dwarf. This class-object exists in order to receive
738
messages like create and destroy and, more philosophically, in
739
order to represent the concept of "dwarfness" within the simulated
742
It is important to remember that the class-object of a class is
743
not normally a member of that class. The concept of dwarfness is
744
not itself a dwarf: the condition Dwarf ofclass Dwarf is false.
745
Individual dwarves provide a property called beard_colour, but the
746
class-object of Dwarf does not: the concept of dwarfness has no
749
7. Classes which are automatically defined by Inform are called
750
"metaclasses". There are four of these: Class, Object, Routine
753
It follows by rule (6) that every Inform program contains the
754
class-objects of these four, also called Class, Object, Routine
757
8. Every object is a member of one, and only one, metaclass:
758
1. The class-objects are members of Class, and no other class.
760
2. Routines in the program (including those given as property
761
values) are members of Routine and no other class.
763
3. Static strings in the program (including those given as
764
property values) are members of String, and of no other class.
766
4. The objects defined in the source code are members of Object,
767
and possibly also of other classes defined in the source code.
769
It follows from (8.1) that Class is the unique class whose
770
class-object is one of its own members: the condition Class
771
ofclass Class is true, whereas X ofclass X is false for every
774
There is one other unusual feature of metaclasses, and it is a
775
rule provided for pragmatic reasons (see below) even though it is
778
9. Contrary to rules (5) and (8.1), the class-objects of the four
779
metaclasses do not inherit from Class.
781
This concludes the list of rules. To see what they entail, one needs to
782
know the definitions of the four metaclasses. These definitions are
783
never written out in any textual form inside Inform, as it happens, but
784
here are definitions equivalent to what actually does happen. (There
785
is no such directive as Metaclass: none is needed, since only Inform
786
itself can define metaclasses, but the definitions here pretend that
791
In other words, this is a class from which nothing is inherited. So the
792
ordinary objects described in the source code only have the properties
793
which the source code says they have.
796
with create [; ... ],
797
recreate [ instance; ... ],
798
destroy [ instance; ... ],
799
copy [ instance1 instance2; ... ],
802
So class-objects respond only to these five messages, which are
803
described in detail in the next section, and provide no other
804
properties: *except* that by rule (9), the class-objects Class, Object,
805
Routine and String provide no properties at all. The point is that
806
these five messages are concerned with object creation and deletion at
807
run time. But Inform is a compiler and not, like Smalltalk-80 or other
808
highly object-oriented languages, an interpreter. We cannot create the
809
program while it is actually running, and this is what it would mean to
810
send requests for creation or deletion to Class, Object, Routine or
811
String. (We could write the above routines to allow the requests to be
812
made, but to print out some error if they ever are: but it is more
813
efficient to have rule (9) instead.)
816
with call [ parameters...; ... ];
818
Routines therefore provide only call. See the next section for how to
822
with print [; print_ret (string) self; ],
823
print_to_array [ array; ... ];
825
Strings therefore provide only print and print_to_array. See the next
826
section for how to use these.
828
To demonstrate this, here is an Inform code representation of what
829
happens when the message
835
if (~~(O provides M)) "Error: O doesn't provide M";
838
{ nothing, Object, Class: return P;
839
Routine: return P.call(p1, p2, ...);
840
String: return P.print();
843
(The messages call and print are actually implemented by hand, so this
844
is not actually a circular definition. Also, this is simplified to
845
remove details of what happens if P is an array.)
848
File: inform, Node: Sending Messages, Next: Dynamic Objects, Prev: Philosophy, Up: Objects
850
Sending messages to routines, strings or classes
851
------------------------------------------------
853
!! In the examples so far, messages have only been sent to proper
854
Objects. But it's a logical possibility to send messages to objects of
855
the other three metaclasses too: the question is whether they are able
856
to receive any. The answer is yes, because Inform provides 8
857
properties for such objects, as follows.
859
The only thing you can do with a Routine is to call it. Thus, if
860
Explore is the name of a routine, then
862
Explore.call(2, 4); and Explore(2, 4);
864
are equivalent expressions. The message call(2,4) means "run this
865
routine with parameters (2,4)". This is not quite redundant, because
866
it can be used more flexibly than ordinary function calls:
868
x = Explore; x.call(2, 4);
870
The call message replies with the routine's return value.
872
Two different messages can be sent to a String. The first is print,
873
which is provided because it logically ought to be, rather than because
874
it is useful. So, for example,
876
("You can see an advancing tide of bison!").print();
878
prints out the string, followed by a new-line; the print message replies
881
!!!! print_to_array is more useful. It copies out the text of the
882
string into entries 2, 3, 4, ... of the supplied byte array, and writes
883
the number of characters as a word into entries 0 and 1. That is, if A
884
has been declared as a suitably large array,
886
("A rose is a rose is a rose").print_to_array(A);
888
will cause the text of the string to be copied into the entries
890
A->2, A->3, ..., A->27
892
with the value 26 written into
896
And the reply value of the message is also 26, for convenience.
898
Five different messages can be sent to objects of metaclass Class,
899
i.e., to classes, and these are detailed in the next section. (But an
900
exception to this is that no messages at all can be sent to the four
901
metaclasses Class, Object, Routine and String.)
904
File: inform, Node: Dynamic Objects, Next: Common vs Individual, Prev: Sending Messages, Up: Objects
906
Creating and deleting objects
907
-----------------------------
909
A vexed problem in all object-oriented systems is that it is often
910
elegant to grow data structures organically, simply conjuring new
911
objects out of mid-air and attaching them to the structure already
912
built. The problem is that since resources cannot be infinite, there
913
will come a point where no new objects can be conjured up. The program
914
must be written so that it can cope with this, and this can present the
915
programmer with some difficulty, since the conditions that will prevail
916
when the program is being run may be hard to predict.
918
In an adventure-game setting, object creation is useful for
919
something like a beach full of stones: if the player wants to pick up
920
more and more stones, the game needs to create a new object for each
921
stone brought into play.
923
Inform allows object creation, but it insists that the programmer
924
must specify in advance what the maximum resources ever needed will be:
925
for example, the maximum number of stones which can ever be in play.
926
Although this is a nuisance, the reward is that the resulting program
927
is guaranteed to work correctly on every machine running it (or else to
928
fail in the same way on every machine running it).
930
The model is this. When a class is defined, a number N is
931
specified, which is the maximum number of created instances of the
932
class which the programmer will ever need at once. When the program is
933
running, "instances" can be created (up to this limit); or deleted.
934
One can imagine the class having a stock of instances, so that creation
935
consists of giving out one of the stock-pile and deletion consists of
938
Classes can receive the following five messages:
942
What is the current value of N? That is, how many more instances can
947
Replies with a newly created instance, or with nothing if no more can
952
Destroys the instance I, which must previously have been created.
956
Re-initialises the instance I, as if it had been destroyed and then
961
Copies I to be equal to J, where both have to be instances of the class.
963
!! Note that recreate and copy can be sent for any instances, not just
964
instances which have previously been created. For example,
966
Plant.copy(Gilded_Branch, Poison_Ivy)
968
copies over all the Plant properties and attributes from Poison_Ivy to
969
Gilded_Branch, but leaves all the rest alone. Likewise,
971
Treasure.recreate(Gilded_Branch)
973
only resets the properties to do with Treasure, leaving the Plant
976
Unless the definition of a class C is made in a special way,
977
C.remaining() will always reply 0, C.destroy() will cause an error and
978
C.create() will be refused. This is because the magic number N for a
981
The "special way" is to give N in brackets after the class name. For
982
example, if the class definition for Leaf begins:
986
then initially Leaf.remaining() will reply 100, and the first 100
987
create() messages will certainly be successful. Others will only
988
succeed if leaves have been destroyed in the mean time. In all other
989
respects Leaf is an ordinary class.
991
!! Object creation and destruction may need to be more sophisticated
992
than this. For example, we might have a data structure in which every
993
object of class A is connected in some way with four objects of class
994
B. When a new A is created, four new Bs need to be created for it; and
995
when an A is destroyed, its four Bs need to be destroyed. In an
996
adventure game setting, we might imagine that every Dwarf who is
997
created has to carry an Axe of his own.
999
When an object has been created (or recreated), but before it has
1000
been "given out" to the program, a create message is sent to it (if it
1001
provides create). This gives the object a chance to set itself up
1002
sensibly. Similarly, when an object is about to be destroyed, but
1003
before it actually is, a destroy message is sent to it (if it provides
1004
destroy). For example:
1010
[ x; self.beard_colour = random("black", "red", "white", "grey");
1012
! Give this new dwarf an axe, if there are any to spare
1014
x = Axe.create(); if (x ~= nothing) move x to self;
1018
! Destroy any axes being carried by this dwarf
1020
objectloop (x in self && x ofclass Axe) Axe.destroy(x);
1024
File: inform, Node: Common vs Individual, Prev: Dynamic Objects, Up: Objects
1026
Footnote on common vs. individual properties
1027
--------------------------------------------
1029
!!!! The properties used in the sections above are all examples of
1030
"individual properties", which some objects provide and others do not.
1031
There are also "common properties" which, because they are inherited
1032
from the class Object, are held by every member of Object. An example
1033
is capacity. The capacity can be read for an ordinary game object
1034
(say, a crate) even if it doesn't specify a capacity for itself, and
1035
the resulting "default" value will be 100. However, this is only a
1036
very weak form of inheritance -- you can't change the crate's capacity
1037
value and the condition crate provides capacity evaluates to false.
1039
The properties defined by the Inform library, such as capacity, are
1040
all common: mainly because common properties are marginally faster to
1041
access and marginally cheaper on memory. Only 62 are available, of
1042
which the library uses up 48. Individual properties, on the other
1043
hand, are practically unlimited. It is therefore worth declaring a
1044
common property only in those cases where it will be used very often in
1045
your program. You can declare common properties with the directive:
1049
which should be made after the inclusion of "Parser" but before first
1050
use of the new name. The class Object will now pass on this property,
1051
with value 0, to all its members. This so-called "default value" can
1052
optionally be specified. For example, the library itself makes the
1055
Property capacity 100;
1057
which is why all containers in a game which don't specify any particular
1058
capacity can hold up to 100 items.
1061
File: inform, Node: Using the Compiler, Next: Fundamentals, Prev: Programming Language, Up: Top
1066
I was promised a horse, but what I got instead
1067
was a tail, with a horse hung from it almost dead.
1069
-- Palladas of Alexandria (319?-400?)
1070
-- translated by Tony Harrison (1937-)
1074
* The Language of Inform:: The language of Inform
1075
* Compiler Options:: Compiler options and memory settings
1076
* Error Messages:: All the Inform error messages
1079
File: inform, Node: The Language of Inform, Next: Compiler Options, Prev: Using the Compiler, Up: Using the Compiler
1081
The language of Inform
1082
======================
1086
* ICL:: The Inform Command Language
1087
* Controlling Compilation:: Controlling what is compiled
1088
* Linking:: Using the linker
1091
File: inform, Node: ICL, Next: Controlling Compilation, Prev: The Language of Inform, Up: The Language of Inform
1096
The Inform compiler is quite configurable: it has a number of
1097
settings which can be altered to suit the convenience of the user.
1098
Many of these settings are "switches", which usually have just two
1099
possible states, off or on. However, some can be set to a single-digit
1102
The other numerical settings are "memory settings", which control
1103
how much of your computer's memory Inform uses while running (too low
1104
and it may not be able to compile games of the size you desire; too
1105
high and it may choke any other programs in the computer for space).
1107
Finally, there are "path variables", which contain text and are used
1108
to sort out filenames for the files Inform uses or creates. The usage
1109
of these variables varies widely from machine to machine, or rather,
1110
from one operating system to another.
1112
If Inform seems to work adequately for you already, this section can
1113
safely be ignored until the day comes to compile a really big project.
1114
Times like that call for the ability to conveniently change many
1115
settings at once, and a tiny language called "ICL" is provided for you
1116
to supply detailed specifications.
1118
On many systems, though not usually the Apple Macintosh, the user sets
1119
Inform running by typing a command at the "command line", that is, in
1120
response to a prompt printed by the computer. For example, under RISC
1121
OS one would press function key f12 from the desktop and be given the
1122
prompt *, to which one might reply
1126
On computers with more doggedly windowed interfaces, there will be a
1127
higher-level interface of some kind provided with Inform, which should
1128
come with its own brief documentation.
1130
The usual way to alter switches on the command line is to give a
1131
word of options after the inform command, introduced by a minus sign.
1132
The switches are all single letters, and by default are mostly off. For
1133
example, the -x switch causes Inform to print a row of hash signs as it
1137
RISC OS Inform 6.01 (April 25th 1996)
1138
::###############################################################
1140
One hash sign is printed for every 100 textual lines of source code
1141
compiled. (On my own machine, an Acorn Risc PC 700, about 10 hashes
1142
are printed every second: that is, the compilation speed is about 1000
1143
lines per second.) Although -x is provided to indicate that a slow
1144
compilation is continuing normally, many designers use it to get a
1145
feeling for how large their games are, and it's a morale boost when the
1146
row of hashes spills over onto a second screen line.
1148
Inform has documentation built-in on the subject of switches and
1149
other ICL features, which may vary from machine to machine. Running
1150
Inform with no filename will print this "help information". In
1151
addition, -h1 will print details of filenaming conventions in use on
1152
your machine, and -h2 will print a list of switches and their settings.
1154
The full command line syntax is
1156
inform <ICL commands> <source file> <output file>
1158
where only the <source file> is mandatory. By default, the full names
1159
to give the source and output files are derived in a way suitable for
1160
the machine Inform is running on: on a PC, for instance, advent may be
1161
understood as asking to compile advent.inf to advent.z5. This is called
1162
"filename translation". No detailed information on filenaming rules is
1163
given here, because it varies so much from machine to machine: see the
1164
-h1 on-line documentation. Note however that a filename can contain
1165
spaces if it is written in double-quotes.
1167
One possible ICL command is to give a filename in brackets: e.g.,
1169
inform -x (skyfall_setup) ...
1171
sets the -x switch, then runs through the text file skyfall_setup
1172
executing each line as an ICL command. As an example, this file might
1175
! Setup file for "Skyfall"
1177
-d ! Contract double spaces
1178
$max_objects=1000 ! 500 of them snowflakes
1179
(usual_setup) ! include my favourite settings, too
1180
+module_path=mods ! keep modules in the "mods" directory
1182
Note that ICL can include comments after !, just as in Inform.
1183
Otherwise, an ICL file has one command per line (with no dividing
1184
semicolons), and the possibilities are as follows:
1188
set these switches; or unset any switch preceded by a tilde ~. (For
1189
example, -a~bc sets a, unsets b and sets c.)
1193
list current memory settings
1197
ask for information on what this memory setting is for
1201
set the whole collection of memory settings to suitable levels for a
1206
ditto, for a slightly larger game
1210
ditto, for a reasonably big one
1214
alter the named memory setting to the given level
1218
set the named pathname variable to the given filename, which should be
1219
one or more filenames of directories, separated by commas
1221
compile <filename> <filename>
1223
compile the first-named file, containing source code, writing the
1224
output program to the (optional) second-named file
1228
execute this ICL file (files may call each other in this way)
1231
File: inform, Node: Controlling Compilation, Next: Linking, Prev: ICL, Up: The Language of Inform
1233
Controlling what is compiled
1234
----------------------------
1236
Several directives instruct Inform to "compile this part next" or
1237
"only compile this...". First,
1241
instructs Inform to compile the whole of the source code in the given
1242
file, and only carry on compiling from here once that is complete. It
1243
is exactly equivalent to removing the Include directive and replacing it
1244
with the whole file "filename". (The rules for how Inform interprets
1245
"filename" vary from machine to machine: run Inform with the -h1 switch
1246
for information.) Note that you can write
1248
Include ">shortname";
1250
to mean "the file called "shortname" which is in the same directory
1251
that the present file came from". This is convenient if all the files
1252
making up the source code of your game are housed together.
1254
!! Next, there are a number of "conditional compilation" directives.
1255
They take the general form of a condition:
1257
Ifdef <name>; Is the name defined as having some meaning?
1258
Ifndef <name>; Is the name undefined?
1259
Iftrue <condition>; Is this condition true?
1260
Iffalse <condition>; Is this condition false?
1262
followed by a chunk of Inform and then either
1266
and another chunk of Inform, or just
1270
At this point it is perhaps worth mentioning that (most) directives
1271
can also be interspersed with statements in routine declarations,
1272
provided they are preceded by a # sign. For example:
1275
#Iftrue MAX_SCORE > 1000;
1276
print "My, what a long game we're in for!^";
1278
print "Let's have a quick game, then.^";
1283
which actually only compiles one of the two print statements, according
1284
to what the value of the constant MAX_SCORE is.
1286
!!!! Four more arcane directives control conditional compilation.
1288
Default <name> <value>;
1290
defines <name> as a constant if it wasn't already the name of something:
1291
so it's equivalent to the manoeuvre
1294
Constant <name> = <value>;
1299
Stub <name> <number>;
1301
defines a routine with this name and number of local variables, if it
1302
isn't already the name of something: so it's equivalent to
1305
[ <name> x1 x2 ... x<number>;
1309
!!!! Large blocks of code intended to be used in many different games,
1310
such as the files which make up the Inform library, should be marked
1311
somewhere with the directive
1315
If this is done, it is possible for an outside program including the
1316
file to use Replace. The idea is that a sequence like:
1318
Replace DoSomething;
1320
Include "SomeLibrary";
1322
[ DoSomething; "Tarantaraa!"; ];
1324
allows a routine DoSomething, which would normally be defined in the
1325
Include file "SomeLibrary", to be defined in this file instead. The
1326
definition in the Include file is simply ignored. In this way, one can
1327
override the library routines without actually having to modify the
1328
library source code. To recap, the rule here is that a routine's
1329
definition is ignored if both (a) it occurs in a declared "system
1330
file", and (b) its name has been given in a Replace directive.
1332
One way to follow what is being compiled is to use the Message
1333
directive. The compiler can be made to print messages at compile time
1336
Message "information"
1337
Message error "error message"
1338
Message fatalerror "fatal error message"
1339
Message warning "warning message"
1344
Message fatalerror "This code can only be compiled by Inform 6.1";
1347
(By a special rule, the condition VN_1610-is-defined is true if and only
1348
if the version number is 6.10 or more; similarly for other four-digit
1349
numbers beginning with a 1.) Informational messages are simply
1352
Message "Library extension by Boris J. Parallelopiped";
1354
just prints out this line (with a carriage return).
1357
File: inform, Node: Linking, Prev: Controlling Compilation, Up: The Language of Inform
1362
The process of "linking" is as follows. A game being compiled
1363
(called the "external" program) may Link one or more pre-compiled
1364
sections of code called "modules". Suppose the game Jekyll has a
1365
subsection called Hyde. Then these two methods of making Jekyll are,
1367
1. Putting Include "Hyde"; in the source code for "Jekyll", and
1370
2. Compiling "Hyde" with the -M ("module") switch set, then putting
1371
Link "Hyde"; into the same point in the source code for "Jekyll",
1372
and compiling "Jekyll".
1374
Option (2) is much faster as long as "Hyde" does not change very often,
1375
since its ready-compiled module can be left lying around while "Jekyll"
1378
Because "linking the library" is by far the most common use of the
1379
linker, this is made simple. All you have to do is compile your game
1380
with the -U switch set, or, equivalently, to begin your source code with
1382
Constant USE_MODULES;
1384
(This assumes that you already have pre-compiled copies of the two
1385
library modules: if not, you'll need to make them with
1387
inform -M library.parserm
1388
inform -M library.verblibm
1390
(where library.parserm should be replaced with the filename for your
1391
copy of the library file "parserm", and likewise for "verblibm").) Note
1392
that it is essential not to make any Attribute or Property declarations
1393
`before' the Include "Parser" line in the source code, though `after'
1394
that point is fine. (Library 6/2 and later will print an error message
1395
if you make this mistake, but under 6/1 it can be a source of
1396
mysterious problems.)
1398
!!!! You can also write your own library modules, or indeed subdivide a
1399
large game into many modular parts. But there are certain restrictions
1400
to the possibilities. (Real experts may want to look at the Technical
1401
Manual here.) Here's a brief list of these:
1403
1. The module must make the same Property and Attribute directives as
1404
the main program. Including the library file "linklpa.h" ("link
1405
library properties and attributes") declares the library's stock, so it
1406
would be sensible to begin a module with
1410
and then include a similar file defining all the extra common properties
1411
and attributes which are needed by the program (if any).
1413
2. The module cannot contain grammar (i.e., use Verb or Extend
1414
directives) or create fake actions.
1416
3. The module can only use global variables defined outside the module
1417
if they are explicitly declared before use using the Import directive.
1422
allows the rest of the module's source code to refer to the variable
1423
frog (which must be defined in the outside program). Note that the
1424
Include file "linklv.h" ("link library variables") imports all the
1425
library variables, so it would be sensible to include this.
1427
4. An object in the module can't inherit from a class defined outside
1428
the module. (But an object outside can inherit from a class inside.)
1430
5. Certain constant values in the module must be known at
1431
module-compile-time (and must not, for instance, be a symbol only
1432
defined outside the module). For instance: the size of an array must be
1433
known now, not later; the number of duplicate members of a Class; and
1434
the quantities being compared in an Iftrue or Iffalse.
1436
6. The module can't: define the Main routine; use the Stub or Default
1437
directives; or define an object whose parent object is not also in the
1440
These restrictions are mild in practice. As an example, here is a
1441
short module to play with:
1443
Include "linklpa"; ! Make use of the properties, attributes
1444
Include "linklv"; ! and variables from the Library
1447
objectloop (x has light)
1448
print (The) x, " is currently giving off light.^";
1451
It should be possible to compile this -M and then to Link it into
1452
another game, making the routine LitThings exist in that game.
added
removed
info/inform-3
