7 .. image:: /images/picF.png
14 inally our three example games are written; we've shown you as much of
15 the Inform language as we've needed to, and made a lot of observations
16 about how and why something should be done. Despite all that, there's
17 much that we've left unsaid, or touched on only lightly. In this chapter
18 we'll revisit key topics and review some of the more significant
19 omissions, to give you a better feel for what's important, and what can
20 be ignored for the time being; when you become an accomplished designer,
21 you will decide what matters and what can be left on the shelf.
23 We'll also talk, in "Reading other people's code" on page 181, about a
24 few ways of doing things that we've chosen not to tell you about, but
25 which you're quite likely to encounter if you look at Inform code
26 written by other designers.
28 The tone here is perhaps a little dry, but trust us: in walking this
29 dusty ground we touch on just about everything that is fundamental in
30 your overall understanding of Inform. And as always, the *Inform
31 Designer's Manual* provides rounder and more comprehensive coverage.
37 In this guide we’ve used the placeholder ``expression`` a few times;
38 here's roughly what we mean.
40 * An ``expression`` is a single ``value``, or several ``values``
41 combined using ``operators`` and sometimes parentheses ``(...)``.
43 * Possible ``values`` include:
45 * a literal number (-32768 to 32767)
47 * something that's represented as a number (a character ``'a'`` , a
48 dictionary word ``'aardvark'`` , a string ``"aardvark's adventure"``
49 or an action ``##Look`` )
51 * the internal identifier of a constant, an object, a class or a routine
53 * (only in a run-time statement, not in a compile-time directive) the
54 contents of a variable, or the return value from a routine.
56 * Possible ``operators`` include:
58 * an arithmetic operator: ``+ - * / % ++``
59 * a bitwise logical operator: ``& | ~``
60 * a numeric comparison operator: ``== ~= > < >= <=``
61 * an object conditional operator: ``ofclass in notin provides has hasnt``
62 * a boolean combinational operator: ``&& || ~~``
68 Many of the items which you define in your source file -- objects,
69 variables, routines, etc. -- need to be given a name so that other items
70 can refer to them. We call this name an item's internal identifier
71 (because it's used only within the source file and isn't visible to the
72 player), and we use the placeholders ``obj_id``, ``var_id``,
73 ``routine_id``, etc. to represent where it's used. An internal ID
75 * can be up to thirty-two characters long
77 * must start with a letter or underscore, and then continue with letters
78 ``A-Z`` , underscore ``_`` and digits ``0-9`` (where upper-case and
79 lower-case letters are treated as indistinguishable)
81 * should generally be unique across all files: your source file, the
82 standard library files, and any library contributions which you've
83 used (except that a routine's local variables are not visible outside
90 A **statement** is an instruction intended for the interpreter, telling
91 it what to do at run-time. It *must* be given in lower-case, and always
92 ends with a semicolon.
94 Some statements, like ``if``, control one or more other statements. We
95 use the placeholder ``statement_block`` to represent either a single
96 ``statement``, or any number of ``statements`` enclosed in braces:
100 We might need some custom syntax highlighting here
102 .. code-block:: inform6
106 { statement; statement; ... statement; }
108 .. rubric:: Statements that we've met
110 Our games have used these statements, about half of the Inform
113 .. code-block:: inform6
115 give obj_id attribute;
116 give obj_id attribute attribute ... attribute;
118 if (expression) statement_block
119 if (expression) statement_block else statement_block
121 move obj_id to parent_obj_id;
123 objectloop (var_id) statement_block
126 print value, value, ... value;
129 print_ret value, value, ... value;
136 style underline; print...; style roman;
138 switch (expression) {
139 value: statement; statement; ... statement;
141 default: statement; statement; ... statement;
145 "string", value, ... value;
149 <action noun second>;
153 <<action noun second>>;
156 .. rubric:: Statements that we've not met
158 Although our example games haven't needed to use them, these looping
159 statements are sometimes useful:
161 .. code-block:: inform6
166 do statement_block until (expression)
168 for (set_var : loop_while_expression : update_var) statement_block
170 while (expression) statement_block
172 On the other hand, we suggest that you put the following statements on
173 hold for now; they're not immediately relevant to everyday code and have
174 mostly to do with printing and formatting:
176 .. code-block:: inform6
185 In particular, avoid using the deprecated jump statement if you possibly can.
188 ..rubric:: Print rules
190 In ``print`` and ``print_ret`` statements, each ``value`` can be:
192 * a numeric ``expression``, displayed as a signed decimal number,
194 * a ``"string"``, displayed literally, or
196 * a print rule. You can create your own, or use a standard one, including:
199 .. tabularcolumns:: ll
201 +-------------------------+---------------------------------------------------+
202 | ``(a) obj_id`` | the object's name, preceded by "a", "an" or "some"|
203 +-------------------------+---------------------------------------------------+
204 | ``(A) obj_id`` | as ``(a)`` but using "A", "An" or "Some" |
205 +-------------------------+---------------------------------------------------+
206 | ``(the) obj_id`` | the object's name, preceded by "the" |
207 +-------------------------+---------------------------------------------------+
208 | ``(The) obj_id`` | as ``(the)`` but using "The" |
209 +-------------------------+---------------------------------------------------+
210 | ``(number) expression`` | the numeric expression's value in words |
211 +-------------------------+---------------------------------------------------+
217 A **directive** is an instruction intended for the compiler, telling it
218 what to do at compile-time, while the source file is being translated
219 into Z-code. By convention it's given an initial capital letter (though
220 the compiler doesn't enforce this) and always ends with a semicolon.
222 .. rubric:: Directives that we've met
224 We've used all of these directives; note that for ``Class``, ``Extend``,
225 ``Object`` and ``Verb`` the full supported syntax is more sophisticated
226 than the basic form presented here:
228 .. code-block:: inform6
235 has attribute attribute ... attribute;
238 Constant const_id = expression;
239 Constant const_id expression;
242 * token token ... token -> action
243 * token token ... token -> action
245 * token token ... token -> action
249 Object obj_id "external_name" parent_obj_id
254 has attribute attribute ... attribute;
263 * token token ... token -> action
264 * token token ... token -> action
266 * token token ... token -> action;
268 ! comment text which the compiler ignores
270 [ routine_id; statement; statement; ... statement; ];
272 #Ifdef any_id; ... #Endif;
274 .. rubric:: Directives that we've not met
276 There's only a handful of useful directives which we haven't needed to
279 .. code-block:: inform6
284 Global var_id = expression;
291 but there's a whole load which are of fairly low importance for now:
293 .. code-block:: inform6
314 An object is really just a collection of variables which together
315 represent the capabilities and current status of some specific component
316 of the model world. Full variables are called properties; simpler
317 two-state variables are attributes.
319 .. rubric:: Properties
321 The library defines around forty-eight standard property variables (such
322 as ``before`` or ``name``), but you can readily create further ones just
323 by using them within an object definition.
325 You can create and initialise a property in an object's ``with`` segment:
327 .. code-block:: inform6
329 property, ! set to zero / false
331 property value, ! set to a single value
333 property value value ... value, ! set to a list of values
335 In each case, the ``value`` is either a compile-time ``expression``, or
338 .. code-block:: inform6
342 property [; statement; statement; ... statement; ],
345 You can refer to the value of a property:
347 .. code-block:: inform6
349 self.property ! only within that same object
351 obj_id.property ! everywhere
353 and you can test whether an object definition includes a given property:
355 .. code-block:: inform6
357 (obj_id provides property) ! is true or false
363 Inform provides standalone routines and embedded routines.
365 .. rubric:: Standalone routines
367 Standalone routines are defined like this:
369 .. code-block:: inform6
371 [ routine_id; statement; statement; ... statement; ];
373 and called like this:
375 .. code-block:: inform6
379 .. rubric:: Embedded routines
381 These are embedded as the value of an object's property:
383 .. code-block:: inform6
385 property [; statement; statement; ... statement; ],
387 and are usually called automatically by the library, or manually by:
389 .. code-block:: inform6
391 self.property() ! only within that same object
393 obj_id.property() ! everywhere
395 .. rubric:: Arguments and local variables
397 Both types of routine support up to fifteen local variables -- variables
398 which can be used only by the statements within the routine, and which
399 are automatically initialised to zero every time that the routine is
402 .. code-block:: inform6
404 [ routine_id var_id var_id ... var_id; statement; statement; ... statement; ];
406 property [ var_id var_id ... var_id; statement; statement; ... statement; ],
408 You can pass up to seven arguments to a routine, by listing those
409 arguments within the parentheses when you call the routine. The effect
410 is simply to initialise the matching local variables to the argument
411 values rather than to zero:
413 .. code-block:: inform6
415 routine_id(expression, expression, ... expression)
417 Although it works, this technique is rarely used with embedded routines,
418 because there is no mechanism for the library to supply argument values
419 when calling the routine.
422 .. rubric:: Return values
424 Every routine returns a single value, which is supplied either
425 explicitly by some form of return statement:
427 .. code-block:: inform6
429 [ routine_id; statement; statement; ... return expr; ]; ! returns expr
431 property [; statement; statement; ... return expr; ], ! returns expr
433 or implicitly when the routine runs out of statements. If none of these
434 ``statements`` is one -- ``return``, ``print_ret``, ``"..."` or
435 ``<<...>>`` -- that causes an explicit return, then:
437 .. code-block:: inform6
439 [ routine_id; statement; statement; ... statement; ];
443 .. code-block:: inform6
445 property [; statement; statement; ... statement; ]
449 This difference is *important*. Remember it by the letter pairs STEF:
450 left to themselves, Standalone routines return True, Embedded routines
453 Here's an example standalone routine which returns the larger of its two
456 .. code-block:: inform6
458 [ Max a b; if (a > b) return a; else return b; ];
460 and here are some examples of its use (note that the first example,
461 though legal, does nothing useful whatsoever):
463 .. code-block:: inform6
469 if (Max(x,7) == 7) ...
471 switch (Max(3,y)) { ...
474 .. rubric:: Library routines versus entry points
477 A library routine is a standard routine, included within the library
478 files, which you can optionally call from your source file if you
479 require the functionality which the routine provides. We've mentioned
480 these library routines:
482 .. code-block:: inform6
484 IndirectlyContains(parent_obj_id, obj_id)
488 PlayerTo(obj_id, flag)
495 By contrast, an entry point routine is a routine which you can provide
496 in your source file, in which case the library calls it at an
497 appropriate time. We've mentioned these optional entry point routines:
499 .. code-block:: inform6
503 InScope(actor_obj_id)
505 And this, the only mandatory one:
507 .. code-block:: inform6
511 There are full lists in "Library routines" on page 264 and "Optional
512 entry points" on page 270.
515 Reading other people's code
516 ===========================
518 Right at the start of this guide, we warned you that we weren't setting
519 out to be comprehensive; we've concentrated on presenting the most
520 important aspects of Inform, as clearly as we can. However, when you
521 read the *Inform Designer's* Manual, and more especially when you look
522 at complete games or library extensions which other designers have
523 produced, you'll come across other ways of doing things -- and it might
524 be that you, like other authors, prefer them over our methods. Just try
525 to find a style that suits you and, this is the important bit, be
526 *consistent* about its use. In this section, we highlight some of the
527 more obvious differences which you may encounter.
529 .. rubric:: Code layout
531 Every designer has his or her own style for laying out their source
532 code, and they're all worse than the one you adopt. Inform's flexibility
533 makes it easy for designers to choose a style that suits them;
534 unfortunately, for some designers this choice seems influenced by the
535 Jackson Pollock school of art. We've advised you to be consistent, to
536 use plenty of white space and indentation, to choose sensible names, to
537 add comments at difficult sections, to actively *think*, as you write
538 your code, about making it as readable as you can.
540 This is doubly true if you ever contemplate sharing a library extension
541 with the rest of the community. This example, with the name changed, is
542 from a file in the Archive:
544 .. code-block:: inform6
548 if (i in player) rtrue;
549 if (i has static || (i has scenery)) rtrue;
551 if (runroutines(j,before) ~= 0 || (j has static || (j has scenery))) {
552 print "You'll have to disconnect ",(the) i," from ",(the) j," first.^";
556 if (runroutines(i,before)~=0 || (i has static || (i has scenery))) {
557 print "You'll have to disconnect ",(the) i," from ",(the) j," first.^";
561 if (j hasnt concealed && j hasnt static) move j to player;
562 if (i hasnt static && i hasnt concealed) move i to player;
564 if (runroutines(j,after) ~= 0) rtrue;
565 print "You take ",(the) i," and ",(the) j," connected to it.^";
570 Here's the same routine after a few minutes spent purely on making it
571 more comprehensible; we haven't actually tested that it (still) works,
572 though that second ``else`` looks suspicious:
574 .. code-block:: inform6
577 if (i in player || i has static or scenery || j == nothing) return true;
579 if (RunRoutines(j,before) || j has static or scenery)
580 "You'll have to disconnect ", (the) i, " from ", (the) j, " first.";
582 if (RunRoutines(i,before) || i has static or scenery)
583 "You'll have to disconnect ", (the) i, " from ", (the) j, " first.";
585 if (j hasnt static or concealed) move j to player;
586 if (i hasnt static or concealed) move i to player;
587 if (RunRoutines(j,after)) return true;
588 "You take ", (the) i, " and ", (the) j, " connected to it.";
592 We hope you'll agree that the result was worth the tiny extra effort.
593 Code gets written once; it gets read dozens and dozens of times.
595 .. rubric:: Shortcuts
597 There are a few statement shortcuts, some more useful than others, which
600 * These five lines all do the same thing:
602 .. code-block:: inform6
608 ]; ! at the end of a standalone routine
610 * These four lines all do the same thing:
612 .. code-block:: inform6
617 ]; ! at the end of an embedded routine
619 * These four lines all do the same thing:
621 .. code-block:: inform6
623 print "string"; new_line; return true;
624 print "string^"; return true;
628 * These lines are the same:
630 .. code-block:: inform6
632 print value1; print value2; print value3;
633 print value1, value2, value3;
635 * These lines are the same:
637 .. code-block:: inform6
639 <action noun second>; return true;
640 <<action noun second>>;
642 * These lines are also the same:
644 .. code-block:: inform6
649 * These ``if`` statements are equivalent:
651 .. code-block:: inform6
653 if (MyVar == 1 || MyVar == 3 || MyVar == 7) ...
655 if (MyVar == 1 or 3 or 7) ...
657 * These ``if`` statements are equivalent as well:
659 .. code-block:: inform6
661 if (MyVar ~= 1 && MyVar ~= 3 && MyVar ~= 7) ...
662 if (MyVar ~= 1 or 3 or 7) ...
664 * In an ``if`` statement, the thing in parentheses can be *any*
665 expression; all that matters is its value: zero (false) or anything
666 else (true). For example, these statements are equivalent:
668 .. code-block:: inform6
670 if (MyVar ~= false) ...
671 if (~~(MyVar == false)) ...
673 if (~~(MyVar == 0)) ...
676 Note that the following statement specifically tests whether ``MyVar``
677 contains ``true`` (1), *not* whether its value is anything other than
680 .. code-block:: inform6
682 if (MyVar == true) ...
684 * If ``MyVar`` is a variable, the statements ``MyVar++;`` and
685 ``++MyVar;`` work the same as ``MyVar = MyVar + 1;`` For example,
686 these lines are equivalent:
688 .. code-block:: inform6
690 MyVar = MyVar + 1; if (MyVar == 3) ...
691 if (++MyVar == 3) ...
692 if (MyVar++ == 2) ...
694 What's the same about ``MyVar++`` and ``++MyVar`` is that they both
695 add one to ``MyVar``. What's different about them is the value to
696 which the construct itself evaluates: ``MyVar++`` returns the current
697 value of ``MyVar`` and then performs the increment, whereas
698 ``++MyVar`` does the "+1" first and then returns the incremented
699 value. In the example, if ``MyVar`` currently contains 2 then
700 ``++MyVar`` returns 3 and ``MyVar++`` returns 2, even though in both
701 cases the value of ``MyVar`` afterwards is 3. As another example,
702 this code (from Helga in "William Tell"):
704 .. code-block:: inform6
706 Talk: self.times_spoken_to = self.times_spoken_to + 1;
707 switch (self.times_spoken_to) {
708 1: score = score + 1;
709 print_ret "You warmly thank Helga for the apple.";
710 2: print_ret "~See you again soon.~";
711 default: return false;
715 could have been written more succinctly like this:
717 .. code-block:: inform6
719 Talk: switch (++self.times_spoken_to) {
721 print_ret "You warmly thank Helga for the apple.";
722 2: print_ret "~See you again soon.~";
723 default: return false;
727 * Similarly, the statements ``MyVar--;`` and ``--MyVar;`` work the same
728 as ``MyVar = MyVar - 1;`` Again, these lines are equivalent:
730 .. code-block:: inform6
732 MyVar = MyVar - 1; if (MyVar == 7) ...
733 if (--MyVar == 7) ...
734 if (MyVar-- == 8) ...
736 .. rubric:: "number" property and "general" attribute
738 The library defines a standard ``number`` property and a standard
739 ``general`` attribute, whose roles are undefined: they are
740 general-purpose variables available within every object to designers as
741 and when they desire.
743 We recommend that you avoid using these two variables, primarily because
744 their names are, by their very nature, so bland as to be largely
745 meaningless. Your game will be clearer and easier to debug if you
746 instead create new property variables -- with appropriate names -- as
747 part of your ``Object`` and ``Class`` definitions.
749 .. rubric:: Common properties and attributes
751 As an alternative to creating new individual properties which apply only
752 to a single object (or class of objects), it's possible to devise
753 properties and new attributes which, like those defined by the library,
754 are available on *all* objects. The need to do this is actually quite
755 rare, and is mostly confined to library extensions (for example, the
756 ``pname.h`` extension which we encountered in "Captain Fate: take 3" on
757 page 147 gives every object a ``pname`` property and a
758 ``phrase_matched`` attribute). To create them, you would use these
759 directives near the start of your source file:
761 .. code-block:: inform6
767 We recommend that you avoid using these two directives unless you really
768 do need to affect every object -- or at least the majority of them -- in
769 your game. There is a limit of forty-eight attributes (of which the
770 library currently defines around thirty) and sixty-two of these common
771 properties (of which the library currently defines around forty-eight).
772 On the other hand, the number of individual properties which you can add
773 is virtually unlimited.
775 .. rubric:: Setting up the object tree
777 Throughout this guide, we've defined the initial position of each object
778 within the overall object tree either by explicitly mentioning its
779 parent's ``obj_id`` (if any) in the first line of the object definition
780 -- what we've been calling the header information -- or, for a few
781 objects which crop up in more than one place, by using their
782 ``found_in`` properties. For example, in "William Tell" we defined
783 twenty-seven objects; omitting those which used ``found_in`` to define
784 their placement at the start of the game, we're left with object
785 definitions starting like this:
787 .. code-block:: inform6
789 Room street "A street in Altdorf"
791 Room below_square "Further along the street"
792 Furniture stall "fruit and vegetable stall" below_square
793 Prop "potatoes" below_square
794 Prop "fruit and vegetables" below_square
795 NPC stallholder "Helga" below_square
797 Room south_square "South side of the square"
799 Room mid_square "Middle of the square"
800 Furniture pole "hat on a pole" mid_square
802 Room north_square "North side of the square"
804 Room marketplace "Marketplace near the square"
805 Object tree "lime tree" marketplace
806 NPC governor "governor" marketplace
810 Object quiver "quiver"
817 You'll see that several of the objects begin the game as parents:
818 ``below_square``, ``mid_square``, ``marketplace`` and ``quiver`` all
819 have child objects beneath them; those children mention their parent as
820 the last item of header information.
822 There's an alternative object syntax which is available to achieve the
823 same object tree, using "arrows". That is, we could have defined those
824 parent-and-child objects as:
826 .. code-block:: inform6
828 Room below_square "Further along the street"
829 Furniture -> stall "fruit and vegetable stall"
831 Prop -> "fruit and vegetables"
832 NPC -> stallholder "Helga"
834 Room mid_square "Middle of the square"
835 Furniture -> pole "hat on a pole"
837 Room marketplace "Marketplace near the square"
838 Object -> tree "lime tree"
839 NPC -> governor "governor"
841 Object quiver "quiver"
846 The idea is that an object's header information *either* starts with an
847 arrow, or ends with an ``obj_id``, or has neither (having both isn’t
848 permitted). An object with neither has no parent: in this example,
849 that's all the ``Rooms``, and also the ``bow`` and the ``quiver`` (which
850 are moved to the player ``object`` in the ``Initialise`` routine) and
851 the apple (which remains without a parent until Helga gives it to
854 An object which starts with a single arrow ``->`` is defined to be a
855 child of the nearest previous object without a parent. Thus, for
856 example, the ``tree`` and ``governor`` objects are both children of the
857 ``marketplace``. To define a child of a child, you'd use two arrows
858 ``-> ->``, and so on. In "William Tell", that situation doesn't occur;
859 to illustrate how it works, imagine that at the start of the game the
860 potatoes and the other fruit and vegetables where actually *on* the
861 stall. Then we might have used:
863 .. code-block:: inform6
865 Room below_square "Further along the street"
866 Furniture -> stall "fruit and vegetable stall"
867 Prop -> -> "potatoes"
868 Prop -> -> "fruit and vegetables"
869 NPC -> stallholder "Helga"
872 That is, the objects with one arrow (the ``stall`` and ``stallholder``)
873 are children of the nearest object without a parent (the ``Room``), and
874 the objects with two arrows (the produce) are children of the nearest
875 object defined with a single arrow (the ``stall``).
877 The advantages of using arrows include:
879 * You're forced to define your objects in a "sensible" order.
881 * Fewer ``obj_ids`` may need to be used (though in this game it would
884 The disadvantages include:
886 * The fact that objects are related by the physical juxtaposition of
887 their definitions is not necessarily intuitive to all designers.
889 * Especially in a crowded room, it’s harder to be certain exactly how
890 the various parent–child relationships are initialised, other than by
891 carefully counting lots of arrows.
893 * If you relocate the parent within the initial object hierarchy to a
894 higher or lower level, you'll need also to change its children by
895 adding or removing arrows; this isn't necessary when the parent is
896 named in the child headers.
898 We prefer to explicitly name the parent, but you'll encounter both forms
901 .. rubric:: Quotes in "name" properties
903 We went to some lengths, way back in "Things in quotes" on page 55, to
904 explain the difference between double quotes ``"..."`` (strings to be
905 output) and single quotes ``'...'`` (input tokens -- dictionary words).
906 Perhaps somewhat unfortunately, Inform allows you to blur this clean
907 distinction: you can use double quotes in name properties and Verb
910 .. code-block:: inform6
912 NPC stallholder "Helga" below_square
913 with name "stallholder" "greengrocer" "monger" "shopkeeper" "merchant"
914 "owner" "Helga" "dress" "scarf" "headscarf",
917 Verb "talk" "t//" "converse" "chat" "gossip"
918 * "to"/"with" creature -> Talk
921 *Please* don't do this. You'll just confuse yourself: those are
922 dictionary words, not strings; it's just as easy -- and far clearer --
923 to stick rigidly to the preferred punctuation.
925 .. rubric:: Obsolete usages
927 Finally, remember that Inform has been evolving since 1993. Over that
928 time, Graham has taken considerable care to maintain as much
929 compatibility as possible, so that games written years ago, for earlier
930 versions of the compiler and the library, will still compile today.
931 While generally a good thing, this brings the disadvantage that a
932 certain amount of obsolete baggage is still lying around. You may, for
933 example, see games using ``Nearby`` directives (denotes parentage,
934 roughly the same as ``->``) and ``near`` conditions (roughly, having the
935 same parent), or with ``" \ "`` controlling line breaks in long
936 ``print`` statements. Try to understand them; try *not* to use them.