1 ========================
3 ========================
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 :ref:`reading-other-code`, about a few ways of doing
24 things that we've chosen not to tell you about, but which you're quite
25 likely to encounter if you look at Inform code written by other designers.
27 The tone here is perhaps a little dry, but trust us: in walking this
28 dusty ground we touch on just about everything that is fundamental in
29 your overall understanding of Inform. And as always, the *Inform
30 Designer's Manual* provides rounder and more comprehensive coverage.
35 In this guide we’ve used the placeholder ``expression`` a few times;
36 here's roughly what we mean.
38 * An ``expression`` is a single ``value``, or several ``values``
39 combined using ``operators`` and sometimes parentheses ``(...)``.
41 * Possible ``values`` include:
43 * a literal number (-32768 to 32767)
45 * something that's represented as a number (a character ``'a'`` , a
46 dictionary word ``'aardvark'`` , a string ``"aardvark's adventure"``
47 or an action ``##Look`` )
49 * the internal identifier of a constant, an object, a class or a routine
51 * (only in a run-time statement, not in a compile-time directive) the
52 contents of a variable, or the return value from a routine.
54 * Possible ``operators`` include:
56 * an arithmetic operator: ``+ - * / % ++``
57 * a bitwise logical operator: ``& | ~``
58 * a numeric comparison operator: ``== ~= > < >= <=``
59 * an object conditional operator: ``ofclass in notin provides has hasnt``
60 * a boolean combinational operator: ``&& || ~~``
66 Many of the items which you define in your source file -- objects,
67 variables, routines, etc. -- need to be given a name so that other items
68 can refer to them. We call this name an item's internal identifier
69 (because it's used only within the source file and isn't visible to the
70 player), and we use the placeholders ``obj_id``, ``var_id``,
71 ``routine_id``, etc. to represent where it's used. An internal ID
73 * can be up to thirty-two characters long
75 * must start with a letter or underscore, and then continue with letters
76 ``A-Z`` , underscore ``_`` and digits ``0-9`` (where upper-case and
77 lower-case letters are treated as indistinguishable)
79 * should generally be unique across all files: your source file, the
80 standard library files, and any library contributions which you've
81 used (except that a routine's local variables are not visible outside
89 A :term:`statement` is an instruction intended for the interpreter, telling
90 it what to do at run-time. It *must* be given in lower-case, and always
91 ends with a semicolon.
93 Some statements, like ``if``, control one or more other statements. We
94 use the placeholder ``statement_block`` to represent either a single
95 ``statement``, or any number of ``statements`` enclosed in braces:
99 We might need some custom syntax highlighting here
101 .. code-block:: inform
105 { statement; statement; ... statement; }
107 Statements that we've met
108 -------------------------
110 Our games have used these statements, about half of the Inform
113 .. code-block:: inform
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>>;
155 Statements that we've not met
156 -----------------------------
158 Although our example games haven't needed to use them, these looping
159 statements are sometimes useful:
161 .. code-block:: inform
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:: inform
185 In particular, avoid using the deprecated jump statement if you possibly can.
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:
198 .. tabularcolumns:: ll
200 +-------------------------+---------------------------------------------------+
201 | ``(a) obj_id`` | the object's name, preceded by "a", "an" or "some"|
202 +-------------------------+---------------------------------------------------+
203 | ``(A) obj_id`` | as ``(a)`` but using "A", "An" or "Some" |
204 +-------------------------+---------------------------------------------------+
205 | ``(the) obj_id`` | the object's name, preceded by "the" |
206 +-------------------------+---------------------------------------------------+
207 | ``(The) obj_id`` | as ``(the)`` but using "The" |
208 +-------------------------+---------------------------------------------------+
209 | ``(number) expression`` | the numeric expression's value in words |
210 +-------------------------+---------------------------------------------------+
216 A :term:`directive` is an instruction intended for the compiler, telling it
217 what to do at compile-time, while the source file is being translated into
218 Z-code. By convention it's given an initial capital letter (though the
219 compiler doesn't enforce this) and always ends with a semicolon.
221 Directives that we've met
222 -------------------------
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:: inform
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 Directives that we've not met
275 -----------------------------
277 There's only a handful of useful directives which we haven't needed to
280 .. code-block:: inform
285 Global var_id = expression;
292 but there's a whole load which are of fairly low importance for now:
294 .. code-block:: inform
317 An object is really just a collection of variables which together
318 represent the capabilities and current status of some specific component
319 of the model world. Full variables are called properties; simpler
320 two-state variables are attributes.
325 The library defines around forty-eight standard property variables (such
326 as ``before`` or ``name``), but you can readily create further ones just
327 by using them within an object definition.
329 You can create and initialise a property in an object's ``with`` segment:
331 .. code-block:: inform
333 property, ! set to zero / false
335 property value, ! set to a single value
337 property value value ... value, ! set to a list of values
339 In each case, the ``value`` is either a compile-time ``expression``, or
342 .. code-block:: inform
346 property [; statement; statement; ... statement; ],
349 You can refer to the value of a property:
351 .. code-block:: inform
353 self.property ! only within that same object
355 obj_id.property ! everywhere
357 and you can test whether an object definition includes a given property:
359 .. code-block:: inform
361 (obj_id provides property) ! is true or false
368 Inform provides standalone routines and embedded routines.
373 Standalone routines are defined like this:
375 .. code-block:: inform
377 [ routine_id; statement; statement; ... statement; ];
379 and called like this:
381 .. code-block:: inform
388 These are embedded as the value of an object's property:
390 .. code-block:: inform
392 property [; statement; statement; ... statement; ],
394 and are usually called automatically by the library, or manually by:
396 .. code-block:: inform
398 self.property() ! only within that same object
400 obj_id.property() ! everywhere
402 Arguments and local variables
403 -----------------------------
405 Both types of routine support up to fifteen local variables -- variables
406 which can be used only by the statements within the routine, and which
407 are automatically initialised to zero every time that the routine is
410 .. code-block:: inform
412 [ routine_id var_id var_id ... var_id; statement; statement; ... statement; ];
414 property [ var_id var_id ... var_id; statement; statement; ... statement; ],
416 You can pass up to seven arguments to a routine, by listing those
417 arguments within the parentheses when you call the routine. The effect
418 is simply to initialise the matching local variables to the argument
419 values rather than to zero:
421 .. code-block:: inform
423 routine_id(expression, expression, ... expression)
425 Although it works, this technique is rarely used with embedded routines,
426 because there is no mechanism for the library to supply argument values
427 when calling the routine.
432 Every routine returns a single value, which is supplied either
433 explicitly by some form of return statement:
435 .. code-block:: inform
437 [ routine_id; statement; statement; ... return expr; ]; ! returns expr
439 property [; statement; statement; ... return expr; ], ! returns expr
441 or implicitly when the routine runs out of statements. If none of these
442 ``statements`` is one -- ``return``, ``print_ret``, ``"..."` or
443 ``<<...>>`` -- that causes an explicit return, then:
445 .. code-block:: inform
447 [ routine_id; statement; statement; ... statement; ];
451 .. code-block:: inform
453 property [; statement; statement; ... statement; ]
457 This difference is *important*. Remember it by the letter pairs STEF:
458 left to themselves, Standalone routines return True, Embedded routines
461 Here's an example standalone routine which returns the larger of its two
464 .. code-block:: inform
466 [ Max a b; if (a > b) return a; else return b; ];
468 and here are some examples of its use (note that the first example,
469 though legal, does nothing useful whatsoever):
471 .. code-block:: inform
477 if (Max(x,7) == 7) ...
479 switch (Max(3,y)) { ...
481 Library routines versus entry points
482 ------------------------------------
484 A library routine is a standard routine, included within the library
485 files, which you can optionally call from your source file if you
486 require the functionality which the routine provides. We've mentioned
487 these library routines:
489 .. code-block:: inform
491 IndirectlyContains(parent_obj_id, obj_id)
495 PlayerTo(obj_id, flag)
502 By contrast, an entry point routine is a routine which you can provide
503 in your source file, in which case the library calls it at an
504 appropriate time. We've mentioned these optional entry point routines:
506 .. code-block:: inform
510 InScope(actor_obj_id)
512 And this, the only mandatory one:
514 .. code-block:: inform
518 There are full lists in :ref:`library-routines` and :ref:`entry-points`.
520 .. _reading-other-code:
522 Reading other people's code
523 ===========================
525 Right at the start of this guide, we warned you that we weren't setting
526 out to be comprehensive; we've concentrated on presenting the most
527 important aspects of Inform, as clearly as we can. However, when you
528 read the *Inform Designer's* Manual, and more especially when you look
529 at complete games or library extensions which other designers have
530 produced, you'll come across other ways of doing things -- and it might
531 be that you, like other authors, prefer them over our methods. Just try
532 to find a style that suits you and, this is the important bit, be
533 *consistent* about its use. In this section, we highlight some of the
534 more obvious differences which you may encounter.
539 Every designer has his or her own style for laying out their source
540 code, and they're all worse than the one you adopt. Inform's flexibility
541 makes it easy for designers to choose a style that suits them;
542 unfortunately, for some designers this choice seems influenced by the
543 Jackson Pollock school of art. We've advised you to be consistent, to
544 use plenty of white space and indentation, to choose sensible names, to
545 add comments at difficult sections, to actively *think*, as you write
546 your code, about making it as readable as you can.
548 This is doubly true if you ever contemplate sharing a library extension
549 with the rest of the community. This example, with the name changed, is
550 from a file in the Archive:
552 .. code-block:: inform
556 if (i in player) rtrue;
557 if (i has static || (i has scenery)) rtrue;
559 if (runroutines(j,before) ~= 0 || (j has static || (j has scenery))) {
560 print "You'll have to disconnect ",(the) i," from ",(the) j," first.^";
564 if (runroutines(i,before)~=0 || (i has static || (i has scenery))) {
565 print "You'll have to disconnect ",(the) i," from ",(the) j," first.^";
569 if (j hasnt concealed && j hasnt static) move j to player;
570 if (i hasnt static && i hasnt concealed) move i to player;
572 if (runroutines(j,after) ~= 0) rtrue;
573 print "You take ",(the) i," and ",(the) j," connected to it.^";
578 Here's the same routine after a few minutes spent purely on making it
579 more comprehensible; we haven't actually tested that it (still) works,
580 though that second ``else`` looks suspicious:
582 .. code-block:: inform
585 if (i in player || i has static or scenery || j == nothing) return true;
587 if (RunRoutines(j,before) || j has static or scenery)
588 "You'll have to disconnect ", (the) i, " from ", (the) j, " first.";
590 if (RunRoutines(i,before) || i has static or scenery)
591 "You'll have to disconnect ", (the) i, " from ", (the) j, " first.";
593 if (j hasnt static or concealed) move j to player;
594 if (i hasnt static or concealed) move i to player;
595 if (RunRoutines(j,after)) return true;
596 "You take ", (the) i, " and ", (the) j, " connected to it.";
600 We hope you'll agree that the result was worth the tiny extra effort.
601 Code gets written once; it gets read dozens and dozens of times.
606 There are a few statement shortcuts, some more useful than others, which
609 * These five lines all do the same thing:
611 .. code-block:: inform
617 ]; ! at the end of a standalone routine
619 * These four lines all do the same thing:
621 .. code-block:: inform
626 ]; ! at the end of an embedded routine
628 * These four lines all do the same thing:
630 .. code-block:: inform
632 print "string"; new_line; return true;
633 print "string^"; return true;
637 * These lines are the same:
639 .. code-block:: inform
641 print value1; print value2; print value3;
642 print value1, value2, value3;
644 * These lines are the same:
646 .. code-block:: inform
648 <action noun second>; return true;
649 <<action noun second>>;
651 * These lines are also the same:
653 .. code-block:: inform
658 * These ``if`` statements are equivalent:
660 .. code-block:: inform
662 if (MyVar == 1 || MyVar == 3 || MyVar == 7) ...
664 if (MyVar == 1 or 3 or 7) ...
666 * These ``if`` statements are equivalent as well:
668 .. code-block:: inform
670 if (MyVar ~= 1 && MyVar ~= 3 && MyVar ~= 7) ...
671 if (MyVar ~= 1 or 3 or 7) ...
673 * In an ``if`` statement, the thing in parentheses can be *any*
674 expression; all that matters is its value: zero (false) or anything
675 else (true). For example, these statements are equivalent:
677 .. code-block:: inform
679 if (MyVar ~= false) ...
680 if (~~(MyVar == false)) ...
682 if (~~(MyVar == 0)) ...
685 Note that the following statement specifically tests whether ``MyVar``
686 contains ``true`` (1), *not* whether its value is anything other than
689 .. code-block:: inform
691 if (MyVar == true) ...
693 * If ``MyVar`` is a variable, the statements ``MyVar++;`` and
694 ``++MyVar;`` work the same as ``MyVar = MyVar + 1;`` For example,
695 these lines are equivalent:
697 .. code-block:: inform
699 MyVar = MyVar + 1; if (MyVar == 3) ...
700 if (++MyVar == 3) ...
701 if (MyVar++ == 2) ...
703 What's the same about ``MyVar++`` and ``++MyVar`` is that they both
704 add one to ``MyVar``. What's different about them is the value to
705 which the construct itself evaluates: ``MyVar++`` returns the current
706 value of ``MyVar`` and then performs the increment, whereas
707 ``++MyVar`` does the "+1" first and then returns the incremented
708 value. In the example, if ``MyVar`` currently contains 2 then
709 ``++MyVar`` returns 3 and ``MyVar++`` returns 2, even though in both
710 cases the value of ``MyVar`` afterwards is 3. As another example,
711 this code (from Helga in "William Tell"):
713 .. code-block:: inform
715 Talk: self.times_spoken_to = self.times_spoken_to + 1;
716 switch (self.times_spoken_to) {
717 1: score = score + 1;
718 print_ret "You warmly thank Helga for the apple.";
719 2: print_ret "~See you again soon.~";
720 default: return false;
724 could have been written more succinctly like this:
726 .. code-block:: inform
728 Talk: switch (++self.times_spoken_to) {
730 print_ret "You warmly thank Helga for the apple.";
731 2: print_ret "~See you again soon.~";
732 default: return false;
736 * Similarly, the statements ``MyVar--;`` and ``--MyVar;`` work the same
737 as ``MyVar = MyVar - 1;`` Again, these lines are equivalent:
739 .. code-block:: inform
741 MyVar = MyVar - 1; if (MyVar == 7) ...
742 if (--MyVar == 7) ...
743 if (MyVar-- == 8) ...
745 "number" property and "general" attribute
746 -----------------------------------------
748 The library defines a standard ``number`` property and a standard
749 ``general`` attribute, whose roles are undefined: they are
750 general-purpose variables available within every object to designers as
751 and when they desire.
753 We recommend that you avoid using these two variables, primarily because
754 their names are, by their very nature, so bland as to be largely
755 meaningless. Your game will be clearer and easier to debug if you
756 instead create new property variables -- with appropriate names -- as
757 part of your ``Object`` and ``Class`` definitions.
761 Common properties and attributes
762 --------------------------------
764 As an alternative to creating new individual properties which apply only to
765 a single object (or class of objects), it's possible to devise properties
766 and new attributes which, like those defined by the library, are available
767 on *all* objects. The need to do this is actually quite rare, and is mostly
768 confined to library extensions (for example, the ``pname.h`` extension
769 which we encountered in :doc:`12` gives every object a ``pname`` property
770 and a ``phrase_matched`` attribute). To create them, you would use these
771 directives near the start of your source file:
773 .. code-block:: inform
779 We recommend that you avoid using these two directives unless you really
780 do need to affect every object -- or at least the majority of them -- in
781 your game. There is a limit of forty-eight attributes (of which the
782 library currently defines around thirty) and sixty-two of these common
783 properties (of which the library currently defines around forty-eight).
784 On the other hand, the number of individual properties which you can add
785 is virtually unlimited.
789 Setting up the object tree
790 --------------------------
792 Throughout this guide, we've defined the initial position of each object
793 within the overall object tree either by explicitly mentioning its
794 parent's ``obj_id`` (if any) in the first line of the object definition
795 -- what we've been calling the header information -- or, for a few
796 objects which crop up in more than one place, by using their
797 ``found_in`` properties. For example, in "William Tell" we defined
798 twenty-seven objects; omitting those which used ``found_in`` to define
799 their placement at the start of the game, we're left with object
800 definitions starting like this:
802 .. code-block:: inform
804 Room street "A street in Altdorf"
806 Room below_square "Further along the street"
807 Furniture stall "fruit and vegetable stall" below_square
808 Prop "potatoes" below_square
809 Prop "fruit and vegetables" below_square
810 NPC stallholder "Helga" below_square
812 Room south_square "South side of the square"
814 Room mid_square "Middle of the square"
815 Furniture pole "hat on a pole" mid_square
817 Room north_square "North side of the square"
819 Room marketplace "Marketplace near the square"
820 Object tree "lime tree" marketplace
821 NPC governor "governor" marketplace
825 Object quiver "quiver"
832 You'll see that several of the objects begin the game as parents:
833 ``below_square``, ``mid_square``, ``marketplace`` and ``quiver`` all
834 have child objects beneath them; those children mention their parent as
835 the last item of header information.
837 There's an alternative object syntax which is available to achieve the
838 same object tree, using "arrows". That is, we could have defined those
839 parent-and-child objects as:
841 .. code-block:: inform
843 Room below_square "Further along the street"
844 Furniture -> stall "fruit and vegetable stall"
846 Prop -> "fruit and vegetables"
847 NPC -> stallholder "Helga"
849 Room mid_square "Middle of the square"
850 Furniture -> pole "hat on a pole"
852 Room marketplace "Marketplace near the square"
853 Object -> tree "lime tree"
854 NPC -> governor "governor"
856 Object quiver "quiver"
861 The idea is that an object's header information *either* starts with an
862 arrow, or ends with an ``obj_id``, or has neither (having both isn’t
863 permitted). An object with neither has no parent: in this example,
864 that's all the ``Rooms``, and also the ``bow`` and the ``quiver`` (which
865 are moved to the player ``object`` in the ``Initialise`` routine) and
866 the apple (which remains without a parent until Helga gives it to
869 An object which starts with a single arrow ``->`` is defined to be a
870 child of the nearest previous object without a parent. Thus, for
871 example, the ``tree`` and ``governor`` objects are both children of the
872 ``marketplace``. To define a child of a child, you'd use two arrows
873 ``-> ->``, and so on. In "William Tell", that situation doesn't occur;
874 to illustrate how it works, imagine that at the start of the game the
875 potatoes and the other fruit and vegetables where actually *on* the
876 stall. Then we might have used:
878 .. code-block:: inform
880 Room below_square "Further along the street"
881 Furniture -> stall "fruit and vegetable stall"
882 Prop -> -> "potatoes"
883 Prop -> -> "fruit and vegetables"
884 NPC -> stallholder "Helga"
887 That is, the objects with one arrow (the ``stall`` and ``stallholder``)
888 are children of the nearest object without a parent (the ``Room``), and
889 the objects with two arrows (the produce) are children of the nearest
890 object defined with a single arrow (the ``stall``).
892 The advantages of using arrows include:
894 * You're forced to define your objects in a "sensible" order.
896 * Fewer ``obj_ids`` may need to be used (though in this game it would
899 The disadvantages include:
901 * The fact that objects are related by the physical juxtaposition of
902 their definitions is not necessarily intuitive to all designers.
904 * Especially in a crowded room, it’s harder to be certain exactly how
905 the various parent–child relationships are initialised, other than by
906 carefully counting lots of arrows.
908 * If you relocate the parent within the initial object hierarchy to a
909 higher or lower level, you'll need also to change its children by
910 adding or removing arrows; this isn't necessary when the parent is
911 named in the child headers.
913 We prefer to explicitly name the parent, but you'll encounter both forms
916 Quotes in "name" properties
917 ---------------------------
919 We went to some lengths, way back in :ref:`things-in-quotes`, to explain
920 the difference between double quotes ``"..."`` (strings to be output) and
921 single quotes ``'...'`` (input tokens -- dictionary words). Perhaps
922 somewhat unfortunately, Inform allows you to blur this clean distinction:
923 you can use double quotes in name properties and Verb directives:
925 .. code-block:: inform
927 NPC stallholder "Helga" below_square
928 with name "stallholder" "greengrocer" "monger" "shopkeeper" "merchant"
929 "owner" "Helga" "dress" "scarf" "headscarf",
932 Verb "talk" "t//" "converse" "chat" "gossip"
933 * "to"/"with" creature -> Talk
936 *Please* don't do this. You'll just confuse yourself: those are
937 dictionary words, not strings; it's just as easy -- and far clearer --
938 to stick rigidly to the preferred punctuation.
943 Finally, remember that Inform has been evolving since 1993. Over that
944 time, Graham has taken considerable care to maintain as much
945 compatibility as possible, so that games written years ago, for earlier
946 versions of the compiler and the library, will still compile today.
947 While generally a good thing, this brings the disadvantage that a
948 certain amount of obsolete baggage is still lying around. You may, for
949 example, see games using ``Nearby`` directives (denotes parentage,
950 roughly the same as ``->``) and ``near`` conditions (roughly, having the
951 same parent), or with ``" \ "`` controlling line breaks in long
952 ``print`` statements. Try to understand them; try *not* to use them.