X-Git-Url: https://jxself.org/git/?a=blobdiff_plain;f=chapters%2F04.rst;h=b01d7732d021218faeb9ddf0eb2f9d8f5193539b;hb=81deb40a92a715b3ef8037535806b01d4fe2f5fa;hp=8958b593acfd262bec6a10bac624ef842ae908ad;hpb=f9eb50b5024de49b2df4b5daab471731840195d3;p=ibg.git diff --git a/chapters/04.rst b/chapters/04.rst index 8958b59..b01d773 100644 --- a/chapters/04.rst +++ b/chapters/04.rst @@ -4,27 +4,26 @@ .. highlight:: inform +.. default-role:: samp + .. epigraph:: - | *G was a gamester, who had but ill-luck;* - | *H was a hunter, and hunted a buck.* + | |CENTER| *G was a gamester, who had but ill-luck;* + | |CENTER| *H was a hunter, and hunted a buck.* .. only:: html .. image:: /images/picG.png :align: left -.. raw:: latex - - \dropcap{g} - -oing through the design of our first game in the previous chapter has +|G|\oing through the design of our first game in the previous chapter has introduced all sorts of Inform concepts, often without giving you much detail about what's been happening. So let's review some of what we've learnt so far, in a slightly more organised fashion. We'll talk about -"Constants and variables" on page 49, "Object definitions" on page 50, -"Object relationships -- the object tree" on page 52, "Things in quotes" on -page 55, and "Routines and statements" on page 56. +:ref:`const-var`, :ref:`object-defs`, :ref:`object-tree`, +:ref:`things-in-quotes` and :ref:`routines-statements`. + +.. _const-var: Constants and variables ======================= @@ -32,7 +31,8 @@ Constants and variables Superficially similar, constants and variables are actually very different beasts. -.. rubric:: Constants +Constants +--------- A :term:`constant` is a name to which a value is given once and once only; you can't later use that name to stand for a different value. Think of it @@ -51,7 +51,8 @@ and as a number:: Those two examples represent the most common ways in which constants are used in Inform. -.. rubric:: Variables +Variables +--------- A :term:`variable` is a name to which a value is given, but that value can be changed to a different one at any time. Think of it as a blackboard on @@ -69,16 +70,21 @@ but you can change it at any time. For example, we used the statement:: location = before_cottage; -to reset the value of the ``location`` variable to the +.. Generated by autoindex +.. index:: + pair: location; library variable + +to reset the value of the :var:`location` variable to the ``before_cottage`` object, and we wrote:: if (nest in branch) deadflag = 2; -to reset the value of the ``deadflag`` variable to 2. +to reset the value of the :var:`deadflag` variable to 2. + +Later, we'll talk about the :term:`local variable` (see :ref:`routines`) +and about using object properties as variables (see :ref:`objects`). -Later, we'll talk about the :term:`local variable` (see "Routines" on -page 179) and about using object properties as variables (see "Objects" on -page 177). +.. _object-defs: Object definitions ================== @@ -89,20 +95,16 @@ room is an object, each item that the player sees and touches is an object; indeed the player herself is also an object (one that's automatically defined by the library). -.. todo:: - - The set-off below needs to be tweaked or perhaps a custom lexer - created to get italics in the right places. - -The general model of an :term:`object` definition looks like this:: +The general model of an :term:`object` definition looks like this: - Object obj_id "external_name" parent_obj_id - with property value , - property value , - ... - property value , - has attribute attribute ... attribute - ; + | `Object {obj_id} "{external_name}" {parent_obj_id}` + | `with` + | `{property} {value},` + | `{property} {value},` + | `...` + | `{property} {value},` + | `has {attribute} {attribute} ... {attribute}` + | `;` The definition starts with the word ``Object`` and ends with a semicolon; in between are three major blocks of information: @@ -111,26 +113,27 @@ in between are three major blocks of information: * the word ``with`` introduces the object's :term:`properties`; * the word ``has`` introduces the object's :term:`attributes`. -.. rubric:: Object headers +Object headers +-------------- An object header comprises up to three items, all optional: -* An internal ``obj_id`` by which other objects refer to this object. It's +* An internal `{obj_id}` by which other objects refer to this object. It's a single word (though it can contain digits and underscores) of up to thirty-two characters, and it must be unique within the game. You can - omit the ``obj_id`` if this object isn't referred to by any other + omit the `{obj_id}` if this object isn't referred to by any other objects. For example: ``bird``, ``tree``, ``top_of_tree``. -* An ``external_name``, in double quotes, which is what the interpreter +* An `{external_name}`, in double quotes, which is what the interpreter uses when referring to the object. It can be one or more words, and need not be unique (for instance, you might have several ``"Somewhere in the desert"`` rooms). Although not mandatory, it's best to give *every* - object an ``external_name``. For example: ``"baby bird"``, ``"tall + object an `{external_name}`. For example: ``"baby bird"``, ``"tall sycamore tree"``, ``"At the top of the tree"``. -* The internal ``obj_id`` of another object which is the initial location +* The internal `{obj_id}` of another object which is the initial location of this object (its "parent" -- see the next section) at the start of the game. This is omitted from objects which have no initial parent; it's *always* omitted from a room. @@ -143,8 +146,8 @@ An object header comprises up to three items, all optional: ... The ``tree`` starts like this; the only real difference is that, because - the player character can't move a ``scenery`` object, it's always going - to be in the ``clearing``:: + the player character can't move a :attr:`scenery` object, it's always + going to be in the ``clearing``:: Object tree "tall sycamore tree" clearing ... @@ -159,9 +162,10 @@ An object header comprises up to three items, all optional: ... We don't use the arrows method in this guide, though we do describe - how it works in "Setting up the object tree" on page 185. + how it works in :ref:`setting-up-tree`. -.. rubric:: Object properties +Object properties +----------------- An object's property definitions are introduced by the ``with`` keyword. An object can have any number of properties, and they can be defined in any @@ -182,23 +186,24 @@ Here are examples of the properties that we've come across so far:: By happy coincidence, those examples also demonstrate most of the different types of value which can be assigned to a property. The value associated -with the ``description`` property in this particular example is a string of -characters in double quotes; the value associated with this ``e_to`` -property is the internal identity of an object; the ``name`` property is a -bit unusual -- its value is a list of dictionary words, each in single -quotes; the ``each_turn`` property has a value which is an :term:`embedded -routine` (see "Embedded routines" on page 58). The only other type of -value which is commonly found is a simple number; for example:: +with the :prop:`description` property in this particular example is a +string of characters in double quotes; the value associated with this +:prop:`e_to` property is the internal identity of an object; the +:prop:`name` property is a bit unusual -- its value is a list of dictionary +words, each in single quotes; the :prop:`each_turn` property has a value +which is an :term:`embedded routine` (see :ref:`embedded-routines`). The +only other type of value which is commonly found is a simple number; for +example:: capacity 10, In all, the library defines around forty-eight standard properties -- like -``name`` and ``each_turn`` -- which you can associate with your objects; -there's a complete list in "Object properties" on page 266. And in -"William Tell: in his prime" on page 91 we show you how to invent your own -property variables. +:prop:`name` and :prop:`each_turn` -- which you can associate with your +objects; there's a complete list in :ref:`object-props`. And in :doc:`08` +we show you how to invent your own property variables. -.. rubric:: Object attributes +Object attributes +----------------- An object's attribute list is introduced by the ``has`` keyword. An object can have any number of attributes, and they can be listed in any order, @@ -223,10 +228,11 @@ Each of those answers a question: Is this object a container? Does it provide light? and so on. If the attribute is present then the answer is Yes; if the attribute isn't present, the answer is No. -The library defines around thirty standard attributes, listed in "Object -attributes" on page 269. Although you *can* devise additional attributes --- see "Common properties and attributes" on page 185 -- in practice you -seldom need to. +The library defines around thirty standard attributes, listed in +:ref:`object-attrs`. Although you *can* devise additional attributes -- +see :ref:`common-props` -- in practice you seldom need to. + +.. _object-tree: Object relationships -- the object tree ======================================= @@ -363,14 +369,17 @@ given object with the ``parent``, ``child`` and ``children`` routines, and this is one feature that you will be using frequently. There are also other routines associated with the object tree, to help you keep track of the objects or move them around. We'll see them one by one in the next -chapters. For a quick summary, see "Objects" on page 177. +chapters. For a quick summary, see :ref:`objects`. + +.. _things-in-quotes: Things in quotes ================ Inform makes careful distinction between double and single quotes. -.. rubric:: Double quotes +Double quotes +------------- Double quotes ``"..."`` surround a :term:`string` -- a letter, a word, a paragraph, or almost any number of characters -- which you want the @@ -407,13 +416,14 @@ which could equally have been defined thus:: Constant Headline "^A simple Inform example^by Roger Firth and Sonja Kesserich.^"; -and as the value of an object ``description`` property:: +and as the value of an object :prop:`description` property:: description "Too young to fly, the nestling tweets helplessly.", Later, you'll find that they're also very common in ``print`` statements. -.. rubric:: Single quotes +Single quotes +------------- Single quotes ``'...'`` surround a :term:`dictionary word`. This has to be a single word -- no spaces -- and generally contains only letters (and @@ -427,8 +437,12 @@ into individual words, which it then looks up in the dictionary. If it finds all the words, and they seem to represent a sensible course of action, that's what happens next. +.. Generated by autoindex +.. index:: + pair: name; library property + So far, we've seen dictionary words used as the values of an object -``name`` property:: +:prop:`name` property:: name 'bird^s' 'nest' 'twigs' 'moss', @@ -436,15 +450,18 @@ and indeed that's just about the only place where they commonly occur. You'll save yourself a lot of confusion by remembering the distinction: Double quotes for Output, Single quotes for Input (DOSI). +.. _routines-statements: + Routines and statements ======================= A routine is a collection of statements, which are performed (or we often say "are executed") at run-time by the interpreter. There are two types of routine, and about two dozen types of statement (there's a complete list in -"Statements" on page 174; see also "Inform language" on page 257). +:ref:`statements`; see also :doc:`/appendices/e`). -.. rubric:: Statements +Statements +---------- A :term:`statement` is an instruction telling the interpreter to perform a particular task -- to "do something" -- while the game is being played. A @@ -455,7 +472,7 @@ encountered only a few. We saw:: which is an example of an :term:`assignment` statement, so-called because the equals sign ``=`` assigns a new value (the internal ID of our -``before_cottage`` room) to a variable (the global variable ``location`` +``before_cottage`` room) to a variable (the global variable :var:`location` which is part of the library). Later we saw:: if (nest in branch) deadflag = 2; @@ -476,7 +493,11 @@ interpreter executes that statement: it performs an assignment:: deadflag = 2; -which changes the value of the library variable ``deadflag`` from its +.. Generated by autoindex +.. index:: + pair: deadflag; library variable + +which changes the value of the library variable :var:`deadflag` from its current value to 2. Incidentally, ``if`` statements are often written on two lines, with the "controlled" statement indented. This makes it easier to read, but doesn't change the way that it works:: @@ -491,7 +512,10 @@ talk about these other possibilities later. For now, just remember that the only place where you'll find statements are within standalone routines and embedded routines. -.. rubric:: Standalone routines +.. _standalone-routines: + +Standalone routines +------------------- A :term:`standalone routine` is a series of statements, collected together and given a name. When the routine is "called" -- by its given name -- @@ -530,7 +554,10 @@ call. routine *is* called, by the Inform library, right at the start of a game. -.. rubric:: Embedded routines +.. _embedded-routines: + +Embedded routines +----------------- An :term:`embedded routine` is much like a standalone routine, though it doesn't have a name and doesn't end in a semicolon. This is the one that @@ -567,9 +594,8 @@ embedded routines, each designed to perform a task which is appropriate for the property whose value it is; we'll also see that it is possible to call an embedded routine yourself, using an ``obj_id.property()`` syntax -- in this example, we could call the routine by writing ``branch.each_turn()``. -There's more about these topics in "Routines and arguments" on page 67, "A -diversion: working with routines" on page 104 and in "Routines" on -page 179. +There's more about these topics in :ref:`routines-args`, +:ref:`working-with-routines` and in :ref:`routines`. That ends our review of the ground covered in our first game. We'll have more to say about most of this later, but we're trying not to overload you