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.
187 .. rubric:: Print rules
189 In ``print`` and ``print_ret`` statements, each ``value`` can be:
191 * a numeric ``expression``, displayed as a signed decimal number,
193 * a ``"string"``, displayed literally, or
195 * a print rule. You can create your own, or use a standard one, including:
197 .. tabularcolumns:: ll
199 +-------------------------+---------------------------------------------------+
200 | ``(a) obj_id`` | the object's name, preceded by "a", "an" or "some"|
201 +-------------------------+---------------------------------------------------+
202 | ``(A) obj_id`` | as ``(a)`` but using "A", "An" or "Some" |
203 +-------------------------+---------------------------------------------------+
204 | ``(the) obj_id`` | the object's name, preceded by "the" |
205 +-------------------------+---------------------------------------------------+
206 | ``(The) obj_id`` | as ``(the)`` but using "The" |
207 +-------------------------+---------------------------------------------------+
208 | ``(number) expression`` | the numeric expression's value in words |
209 +-------------------------+---------------------------------------------------+
215 A **directive** is an instruction intended for the compiler, telling it
216 what to do at compile-time, while the source file is being translated
217 into Z-code. By convention it's given an initial capital letter (though
218 the compiler doesn't enforce this) and always ends with a semicolon.
220 .. rubric:: Directives that we've met
222 We've used all of these directives; note that for ``Class``, ``Extend``,
223 ``Object`` and ``Verb`` the full supported syntax is more sophisticated
224 than the basic form presented here:
226 .. code-block:: inform6
233 has attribute attribute ... attribute;
236 Constant const_id = expression;
237 Constant const_id expression;
240 * token token ... token -> action
241 * token token ... token -> action
243 * token token ... token -> action
247 Object obj_id "external_name" parent_obj_id
252 has attribute attribute ... attribute;
261 * token token ... token -> action
262 * token token ... token -> action
264 * token token ... token -> action;
266 ! comment text which the compiler ignores
268 [ routine_id; statement; statement; ... statement; ];
270 #Ifdef any_id; ... #Endif;
272 .. rubric:: Directives that we've not met
274 There's only a handful of useful directives which we haven't needed to
277 .. code-block:: inform6
282 Global var_id = expression;
289 but there's a whole load which are of fairly low importance for now:
291 .. code-block:: inform6
312 An object is really just a collection of variables which together
313 represent the capabilities and current status of some specific component
314 of the model world. Full variables are called properties; simpler
315 two-state variables are attributes.
317 .. rubric:: Properties
319 The library defines around forty-eight standard property variables (such
320 as ``before`` or ``name``), but you can readily create further ones just
321 by using them within an object definition.
323 You can create and initialise a property in an object's ``with`` segment:
325 .. code-block:: inform6
327 property, ! set to zero / false
329 property value, ! set to a single value
331 property value value ... value, ! set to a list of values
333 In each case, the ``value`` is either a compile-time ``expression``, or
336 .. code-block:: inform6
340 property [; statement; statement; ... statement; ],
343 You can refer to the value of a property:
345 .. code-block:: inform6
347 self.property ! only within that same object
349 obj_id.property ! everywhere
351 and you can test whether an object definition includes a given property:
353 .. code-block:: inform6
355 (obj_id provides property) ! is true or false
361 Inform provides standalone routines and embedded routines.
363 .. rubric:: Standalone routines
365 Standalone routines are defined like this:
367 .. code-block:: inform6
369 [ routine_id; statement; statement; ... statement; ];
371 and called like this:
373 .. code-block:: inform6
377 .. rubric:: Embedded routines
379 These are embedded as the value of an object's property:
381 .. code-block:: inform6
383 property [; statement; statement; ... statement; ],
385 and are usually called automatically by the library, or manually by:
387 .. code-block:: inform6
389 self.property() ! only within that same object
391 obj_id.property() ! everywhere
393 .. rubric:: Arguments and local variables
395 Both types of routine support up to fifteen local variables -- variables
396 which can be used only by the statements within the routine, and which
397 are automatically initialised to zero every time that the routine is
400 .. code-block:: inform6
402 [ routine_id var_id var_id ... var_id; statement; statement; ... statement; ];
404 property [ var_id var_id ... var_id; statement; statement; ... statement; ],
406 You can pass up to seven arguments to a routine, by listing those
407 arguments within the parentheses when you call the routine. The effect
408 is simply to initialise the matching local variables to the argument
409 values rather than to zero:
411 .. code-block:: inform6
413 routine_id(expression, expression, ... expression)
415 Although it works, this technique is rarely used with embedded routines,
416 because there is no mechanism for the library to supply argument values
417 when calling the routine.
420 .. rubric:: Return values
422 Every routine returns a single value, which is supplied either
423 explicitly by some form of return statement:
425 .. code-block:: inform6
427 [ routine_id; statement; statement; ... return expr; ]; ! returns expr
429 property [; statement; statement; ... return expr; ], ! returns expr
431 or implicitly when the routine runs out of statements. If none of these
432 ``statements`` is one -- ``return``, ``print_ret``, ``"..."` or
433 ``<<...>>`` -- that causes an explicit return, then:
435 .. code-block:: inform6
437 [ routine_id; statement; statement; ... statement; ];
441 .. code-block:: inform6
443 property [; statement; statement; ... statement; ]
447 This difference is *important*. Remember it by the letter pairs STEF:
448 left to themselves, Standalone routines return True, Embedded routines
451 Here's an example standalone routine which returns the larger of its two
454 .. code-block:: inform6
456 [ Max a b; if (a > b) return a; else return b; ];
458 and here are some examples of its use (note that the first example,
459 though legal, does nothing useful whatsoever):
461 .. code-block:: inform6
467 if (Max(x,7) == 7) ...
469 switch (Max(3,y)) { ...
472 .. rubric:: Library routines versus entry points
475 A library routine is a standard routine, included within the library
476 files, which you can optionally call from your source file if you
477 require the functionality which the routine provides. We've mentioned
478 these library routines:
480 .. code-block:: inform6
482 IndirectlyContains(parent_obj_id, obj_id)
486 PlayerTo(obj_id, flag)
493 By contrast, an entry point routine is a routine which you can provide
494 in your source file, in which case the library calls it at an
495 appropriate time. We've mentioned these optional entry point routines:
497 .. code-block:: inform6
501 InScope(actor_obj_id)
503 And this, the only mandatory one:
505 .. code-block:: inform6
509 There are full lists in "Library routines" on page 264 and "Optional
510 entry points" on page 270.
513 Reading other people's code
514 ===========================
516 Right at the start of this guide, we warned you that we weren't setting
517 out to be comprehensive; we've concentrated on presenting the most
518 important aspects of Inform, as clearly as we can. However, when you
519 read the *Inform Designer's* Manual, and more especially when you look
520 at complete games or library extensions which other designers have
521 produced, you'll come across other ways of doing things -- and it might
522 be that you, like other authors, prefer them over our methods. Just try
523 to find a style that suits you and, this is the important bit, be
524 *consistent* about its use. In this section, we highlight some of the
525 more obvious differences which you may encounter.
527 .. rubric:: Code layout
529 Every designer has his or her own style for laying out their source
530 code, and they're all worse than the one you adopt. Inform's flexibility
531 makes it easy for designers to choose a style that suits them;
532 unfortunately, for some designers this choice seems influenced by the
533 Jackson Pollock school of art. We've advised you to be consistent, to
534 use plenty of white space and indentation, to choose sensible names, to
535 add comments at difficult sections, to actively *think*, as you write
536 your code, about making it as readable as you can.
538 This is doubly true if you ever contemplate sharing a library extension
539 with the rest of the community. This example, with the name changed, is
540 from a file in the Archive:
542 .. code-block:: inform6
546 if (i in player) rtrue;
547 if (i has static || (i has scenery)) rtrue;
549 if (runroutines(j,before) ~= 0 || (j has static || (j has scenery))) {
550 print "You'll have to disconnect ",(the) i," from ",(the) j," first.^";
554 if (runroutines(i,before)~=0 || (i has static || (i has scenery))) {
555 print "You'll have to disconnect ",(the) i," from ",(the) j," first.^";
559 if (j hasnt concealed && j hasnt static) move j to player;
560 if (i hasnt static && i hasnt concealed) move i to player;
562 if (runroutines(j,after) ~= 0) rtrue;
563 print "You take ",(the) i," and ",(the) j," connected to it.^";
568 Here's the same routine after a few minutes spent purely on making it
569 more comprehensible; we haven't actually tested that it (still) works,
570 though that second ``else`` looks suspicious:
572 .. code-block:: inform6
575 if (i in player || i has static or scenery || j == nothing) return true;
577 if (RunRoutines(j,before) || j has static or scenery)
578 "You'll have to disconnect ", (the) i, " from ", (the) j, " first.";
580 if (RunRoutines(i,before) || i has static or scenery)
581 "You'll have to disconnect ", (the) i, " from ", (the) j, " first.";
583 if (j hasnt static or concealed) move j to player;
584 if (i hasnt static or concealed) move i to player;
585 if (RunRoutines(j,after)) return true;
586 "You take ", (the) i, " and ", (the) j, " connected to it.";
590 We hope you'll agree that the result was worth the tiny extra effort.
591 Code gets written once; it gets read dozens and dozens of times.
593 .. rubric:: Shortcuts
595 There are a few statement shortcuts, some more useful than others, which
598 * These five lines all do the same thing:
600 .. code-block:: inform6
606 ]; ! at the end of a standalone routine
608 * These four lines all do the same thing:
610 .. code-block:: inform6
615 ]; ! at the end of an embedded routine
617 * These four lines all do the same thing:
619 .. code-block:: inform6
621 print "string"; new_line; return true;
622 print "string^"; return true;
626 * These lines are the same:
628 .. code-block:: inform6
630 print value1; print value2; print value3;
631 print value1, value2, value3;
633 * These lines are the same:
635 .. code-block:: inform6
637 <action noun second>; return true;
638 <<action noun second>>;
640 * These lines are also the same:
642 .. code-block:: inform6
647 * These ``if`` statements are equivalent:
649 .. code-block:: inform6
651 if (MyVar == 1 || MyVar == 3 || MyVar == 7) ...
653 if (MyVar == 1 or 3 or 7) ...
655 * These ``if`` statements are equivalent as well:
657 .. code-block:: inform6
659 if (MyVar ~= 1 && MyVar ~= 3 && MyVar ~= 7) ...
660 if (MyVar ~= 1 or 3 or 7) ...
662 * In an ``if`` statement, the thing in parentheses can be *any*
663 expression; all that matters is its value: zero (false) or anything
664 else (true). For example, these statements are equivalent:
666 .. code-block:: inform6
668 if (MyVar ~= false) ...
669 if (~~(MyVar == false)) ...
671 if (~~(MyVar == 0)) ...
674 Note that the following statement specifically tests whether ``MyVar``
675 contains ``true`` (1), *not* whether its value is anything other than
678 .. code-block:: inform6
680 if (MyVar == true) ...
682 * If ``MyVar`` is a variable, the statements ``MyVar++;`` and
683 ``++MyVar;`` work the same as ``MyVar = MyVar + 1;`` For example,
684 these lines are equivalent:
686 .. code-block:: inform6
688 MyVar = MyVar + 1; if (MyVar == 3) ...
689 if (++MyVar == 3) ...
690 if (MyVar++ == 2) ...
692 What's the same about ``MyVar++`` and ``++MyVar`` is that they both
693 add one to ``MyVar``. What's different about them is the value to
694 which the construct itself evaluates: ``MyVar++`` returns the current
695 value of ``MyVar`` and then performs the increment, whereas
696 ``++MyVar`` does the "+1" first and then returns the incremented
697 value. In the example, if ``MyVar`` currently contains 2 then
698 ``++MyVar`` returns 3 and ``MyVar++`` returns 2, even though in both
699 cases the value of ``MyVar`` afterwards is 3. As another example,
700 this code (from Helga in "William Tell"):
702 .. code-block:: inform6
704 Talk: self.times_spoken_to = self.times_spoken_to + 1;
705 switch (self.times_spoken_to) {
706 1: score = score + 1;
707 print_ret "You warmly thank Helga for the apple.";
708 2: print_ret "~See you again soon.~";
709 default: return false;
713 could have been written more succinctly like this:
715 .. code-block:: inform6
717 Talk: switch (++self.times_spoken_to) {
719 print_ret "You warmly thank Helga for the apple.";
720 2: print_ret "~See you again soon.~";
721 default: return false;
725 * Similarly, the statements ``MyVar--;`` and ``--MyVar;`` work the same
726 as ``MyVar = MyVar - 1;`` Again, these lines are equivalent:
728 .. code-block:: inform6
730 MyVar = MyVar - 1; if (MyVar == 7) ...
731 if (--MyVar == 7) ...
732 if (MyVar-- == 8) ...
734 .. rubric:: "number" property and "general" attribute
736 The library defines a standard ``number`` property and a standard
737 ``general`` attribute, whose roles are undefined: they are
738 general-purpose variables available within every object to designers as
739 and when they desire.
741 We recommend that you avoid using these two variables, primarily because
742 their names are, by their very nature, so bland as to be largely
743 meaningless. Your game will be clearer and easier to debug if you
744 instead create new property variables -- with appropriate names -- as
745 part of your ``Object`` and ``Class`` definitions.
747 .. rubric:: Common properties and attributes
749 As an alternative to creating new individual properties which apply only
750 to a single object (or class of objects), it's possible to devise
751 properties and new attributes which, like those defined by the library,
752 are available on *all* objects. The need to do this is actually quite
753 rare, and is mostly confined to library extensions (for example, the
754 ``pname.h`` extension which we encountered in "Captain Fate: take 3" on
755 page 147 gives every object a ``pname`` property and a
756 ``phrase_matched`` attribute). To create them, you would use these
757 directives near the start of your source file:
759 .. code-block:: inform6
765 We recommend that you avoid using these two directives unless you really
766 do need to affect every object -- or at least the majority of them -- in
767 your game. There is a limit of forty-eight attributes (of which the
768 library currently defines around thirty) and sixty-two of these common
769 properties (of which the library currently defines around forty-eight).
770 On the other hand, the number of individual properties which you can add
771 is virtually unlimited.
773 .. rubric:: Setting up the object tree
775 Throughout this guide, we've defined the initial position of each object
776 within the overall object tree either by explicitly mentioning its
777 parent's ``obj_id`` (if any) in the first line of the object definition
778 -- what we've been calling the header information -- or, for a few
779 objects which crop up in more than one place, by using their
780 ``found_in`` properties. For example, in "William Tell" we defined
781 twenty-seven objects; omitting those which used ``found_in`` to define
782 their placement at the start of the game, we're left with object
783 definitions starting like this:
785 .. code-block:: inform6
787 Room street "A street in Altdorf"
789 Room below_square "Further along the street"
790 Furniture stall "fruit and vegetable stall" below_square
791 Prop "potatoes" below_square
792 Prop "fruit and vegetables" below_square
793 NPC stallholder "Helga" below_square
795 Room south_square "South side of the square"
797 Room mid_square "Middle of the square"
798 Furniture pole "hat on a pole" mid_square
800 Room north_square "North side of the square"
802 Room marketplace "Marketplace near the square"
803 Object tree "lime tree" marketplace
804 NPC governor "governor" marketplace
808 Object quiver "quiver"
815 You'll see that several of the objects begin the game as parents:
816 ``below_square``, ``mid_square``, ``marketplace`` and ``quiver`` all
817 have child objects beneath them; those children mention their parent as
818 the last item of header information.
820 There's an alternative object syntax which is available to achieve the
821 same object tree, using "arrows". That is, we could have defined those
822 parent-and-child objects as:
824 .. code-block:: inform6
826 Room below_square "Further along the street"
827 Furniture -> stall "fruit and vegetable stall"
829 Prop -> "fruit and vegetables"
830 NPC -> stallholder "Helga"
832 Room mid_square "Middle of the square"
833 Furniture -> pole "hat on a pole"
835 Room marketplace "Marketplace near the square"
836 Object -> tree "lime tree"
837 NPC -> governor "governor"
839 Object quiver "quiver"
844 The idea is that an object's header information *either* starts with an
845 arrow, or ends with an ``obj_id``, or has neither (having both isn’t
846 permitted). An object with neither has no parent: in this example,
847 that's all the ``Rooms``, and also the ``bow`` and the ``quiver`` (which
848 are moved to the player ``object`` in the ``Initialise`` routine) and
849 the apple (which remains without a parent until Helga gives it to
852 An object which starts with a single arrow ``->`` is defined to be a
853 child of the nearest previous object without a parent. Thus, for
854 example, the ``tree`` and ``governor`` objects are both children of the
855 ``marketplace``. To define a child of a child, you'd use two arrows
856 ``-> ->``, and so on. In "William Tell", that situation doesn't occur;
857 to illustrate how it works, imagine that at the start of the game the
858 potatoes and the other fruit and vegetables where actually *on* the
859 stall. Then we might have used:
861 .. code-block:: inform6
863 Room below_square "Further along the street"
864 Furniture -> stall "fruit and vegetable stall"
865 Prop -> -> "potatoes"
866 Prop -> -> "fruit and vegetables"
867 NPC -> stallholder "Helga"
870 That is, the objects with one arrow (the ``stall`` and ``stallholder``)
871 are children of the nearest object without a parent (the ``Room``), and
872 the objects with two arrows (the produce) are children of the nearest
873 object defined with a single arrow (the ``stall``).
875 The advantages of using arrows include:
877 * You're forced to define your objects in a "sensible" order.
879 * Fewer ``obj_ids`` may need to be used (though in this game it would
882 The disadvantages include:
884 * The fact that objects are related by the physical juxtaposition of
885 their definitions is not necessarily intuitive to all designers.
887 * Especially in a crowded room, it’s harder to be certain exactly how
888 the various parent–child relationships are initialised, other than by
889 carefully counting lots of arrows.
891 * If you relocate the parent within the initial object hierarchy to a
892 higher or lower level, you'll need also to change its children by
893 adding or removing arrows; this isn't necessary when the parent is
894 named in the child headers.
896 We prefer to explicitly name the parent, but you'll encounter both forms
899 .. rubric:: Quotes in "name" properties
901 We went to some lengths, way back in "Things in quotes" on page 55, to
902 explain the difference between double quotes ``"..."`` (strings to be
903 output) and single quotes ``'...'`` (input tokens -- dictionary words).
904 Perhaps somewhat unfortunately, Inform allows you to blur this clean
905 distinction: you can use double quotes in name properties and Verb
908 .. code-block:: inform6
910 NPC stallholder "Helga" below_square
911 with name "stallholder" "greengrocer" "monger" "shopkeeper" "merchant"
912 "owner" "Helga" "dress" "scarf" "headscarf",
915 Verb "talk" "t//" "converse" "chat" "gossip"
916 * "to"/"with" creature -> Talk
919 *Please* don't do this. You'll just confuse yourself: those are
920 dictionary words, not strings; it's just as easy -- and far clearer --
921 to stick rigidly to the preferred punctuation.
923 .. rubric:: Obsolete usages
925 Finally, remember that Inform has been evolving since 1993. Over that
926 time, Graham has taken considerable care to maintain as much
927 compatibility as possible, so that games written years ago, for earlier
928 versions of the compiler and the library, will still compile today.
929 While generally a good thing, this brings the disadvantage that a
930 certain amount of obsolete baggage is still lying around. You may, for
931 example, see games using ``Nearby`` directives (denotes parentage,
932 roughly the same as ``->``) and ``near`` conditions (roughly, having the
933 same parent), or with ``" \ "`` controlling line breaks in long
934 ``print`` statements. Try to understand them; try *not* to use them.