Add a bunch of autogenerated index entries.

[ibg.git] / chapters / 04.rst

======================
 Reviewing the basics
======================

.. highlight:: inform

.. epigraph::

   | |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

|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
:ref:`const-var`, :ref:`object-defs`, :ref:`object-tree`,
:ref:`things-in-quotes` and :ref:`routines-statements`.

.. _const-var:

Constants and variables
=======================

Superficially similar, constants and variables are actually very different
beasts.

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
as a stone tablet on which you carve a number: a carving can't be undone,
so that you see the same number every time you look at the stone.

So far, we've seen a ``Constant`` being set up with its value as a string
of characters::

    Constant Story "Heidi";

and as a number::

    Constant MAX_CARRIED 1;

Those two examples represent the most common ways in which constants are
used in Inform.

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
which you mark a number in chalk: whenever you need to, just wipe the board
and write up a new number.

We haven't set up any variables of our own yet, though we've used a couple
which the library created like this::

    Global location;
    Global deadflag;

The value of a :term:`global variable` created in this way is initially 0,
but you can change it at any time.  For example, we used the statement::

     location = before_cottage;

.. 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 :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`).

.. _object-defs:

Object definitions
==================

The most important information you should have gleaned from the previous
chapter is that your entire game is defined as a series of objects.  Each
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::

        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:

* immediately after the word ``Object`` is the header information;
* the word ``with`` introduces the object's :term:`properties`;
* the word ``has`` introduces the object's :term:`attributes`.

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
  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
  objects.

  For example: ``bird``, ``tree``, ``top_of_tree``.

* 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
  sycamore tree"``, ``"At the top of the tree"``.

* 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.

  For example: the definition of the ``bird`` starts like this, specifying
  that at the start of the game, it can be found in the ``forest`` room
  (though later the player character will pick it up and move it around)::

      Object   bird "baby bird" forest
      ...

  The ``tree`` starts like this; the only real difference is that, because
  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
      ...

  .. note::

     There's an alternative method for defining an object's initial
     location, using "arrows" rather than the parent's internal ``obj_id``.
     For example, the definition of the bird could have started like this::

         Object   -> bird "baby bird"
         ...

     We don't use the arrows method in this guide, though we do describe
     how it works in :ref:`setting-up-tree`.

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
order.  Each definition has two parts: a name, and a value; there's a space
between the two parts, and a comma at the end.

Think of each property as a variable which is specifically associated with
that object.  The variable's initial setting is the supplied value; if
necessary, it can be reset to other values during play (though in fact most
property values don't change in this way).

Here are examples of the properties that we've come across so far::

    description "The nest is carefully woven of twigs and moss.",
    e_to forest,
    name 'baby' 'bird' 'nestling',
    each_turn [; if (nest in branch) deadflag = 2; ],

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 :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
: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.

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,
with a space between each.

As with properties, you can think of each attribute as a variable which is
specifically associated with that object.  However, an attribute is a much
more limited form of variable, since it can have only two possible states:
present, and absent (also known as set/clear, on/off, or true/false;
incidentally, a two-state variable like this is often called a
:term:`flag`).  Initially, an attribute is either present (if you mention
its name in the list) or absent (otherwise); if necessary, its state can
change during play (and this is relatively common).  We often say that a
certain object currently *has* a certain attribute, or that conversely it
*hasn't* got it.

The attributes that we've come across so far are::

     container light open scenery static supporter

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
: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
=======================================

Not only is your game composed entirely of objects, but also Inform takes
great care to keep track of the relationships between those objects.  By
"relationship" we don't mean that Walter is Wilhelm's son, while Helga and
Wilhelm are just good friends; it's a much more comprehensive exercise in
recording exactly where each object is located, relative to the other
objects in the game.

Despite what we just said, Inform relationships *are* managed in terms of
:term:`parent` and :term:`child` objects, though in a much broader sense
than Wilhelm and Walter.  When the player character is in a particular room
-- for example the forest -- we can say that:

* the forest object is *the* parent of the player object, or alternatively
* the player object is *a* child of the forest object.

Also, if the player is carrying an object -- for example the nest -- we say
that:

* the player object is *the* parent of the nest object, or that
* the nest object is *a* child of the player object.

Note the emphasis there: an object has exactly *one* parent (or no parent
at all), but can have *any number* of child objects (including none).

For an example of an object having more than one child, think about the way
we defined the nest and tree objects::

    Object   nest "bird's nest" clearing
    ...

    Object   tree "tall sycamore tree" clearing
    ...

We used the third of the header items to say that the clearing was the
parent of the nest, and also that the clearing was the parent of the tree;
that is, both nest and tree are child objects of the clearing.

.. note::

   A "room" isn't anything magical; it's just an object which *never* has a
   parent, and which *may* from time to time have the player object as a
   child.

When we defined the bird, we placed it in the forest, like so::

    Object   bird "baby bird" forest
    ...

We didn't place any other objects in that room, so at the start of the game
the forest was the parent of the bird (and the bird was the only child of
the forest).  But what happens when the player character, initially in the
``before_cottage`` room, goes EAST to the forest?  Answer: the player's
parent is now the forest, and the forest has two children -- the bird *and*
the player.  This is a key principle of the way Inform manages its objects:
the parent--child relationships between objects change continuously, often
dramatically, as the game progresses.

Another example of this: suppose the player character picks up the bird.
This causes another change in the relationships.  The bird is now a child
of the player (and *not* of the forest), and the player is both a parent
(of the bird) and a child (of the forest).

Here we show how the object relationships change during the course of the
game.  The straight lines represent parent--child relationships, with the
parent object at the top of the line, and the child object at the bottom.

1. At the start of the game:

   .. blockdiag:: /figures/heidiobj1.diag
      :align: center
      :scale: 80%

2. The player types: ``GO EAST``

   .. blockdiag:: /figures/heidiobj2.diag
      :align: center
      :scale: 80%

3. The player types: ``TAKE THE BIRD``

   .. blockdiag:: /figures/heidiobj3.diag
      :align: center
      :scale: 80%

4. The player types: ``GO NORTHEAST``

   .. blockdiag:: /figures/heidiobj4.diag
      :align: center
      :scale: 80%

5. The player types: ``PUT BIRD IN NEST``

   .. blockdiag:: /figures/heidiobj5.diag
      :align: center
      :scale: 80%

6. The player types: ``TAKE NEST``

   .. blockdiag:: /figures/heidiobj6.diag
      :align: center
      :scale: 80%

7. The player types: ``UP``

   .. blockdiag:: /figures/heidiobj7.diag
      :align: center
      :scale: 80%

8. The player types: ``PUT NEST ON BRANCH``

   .. blockdiag:: /figures/heidiobj8.diag
      :align: center
      :scale: 80%

In this short example, we've taken a lot of time and space to spell out
exactly how the objects relationship patterns -- generally known as the
:term:`object tree` -- appear at each stage.  Normally you wouldn't bother
with this much detail (a) because the interpreter does most of the work for
you, and (b) because in a real game there are usually too many objects for
you to keep track of.  What's important is that you understand the basic
principles: at any moment in time an object either has no parent (which
probably means either that it's a room, or that it's floating in hyperspace
and not currently part of the game) or exactly one parent -- the object
that it's "in" or "on" or "a part of".  However, there's no restriction on
the number of children that an object can have.

There's a practical use for these relationships, covered in detail further
on.  As a designer, you can refer to the current parent or children of any
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 :ref:`objects`.

.. _things-in-quotes:

Things in quotes
================

Inform makes careful distinction between double and single 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
interpreter to display while the game is being played.  You can use the
tilde ``~`` to represent a double quote inside the string, and the
circumflex ``^`` to represent a newline (line break) character.  Upper-case
and lower-case letters are treated as different.

A long string can be split over several lines; Inform transforms each 
line break (and any spaces around it) into a single space (extra spaces 
*not* at a line break are preserved, though).  These two strings are 
equivalent::

    "This is a      string of characters."

    "This
      is
            a    string
                       of characters."

When the interpreter displays a long character string -- for example, while
describing a feature-packed room -- it employs automatic word-wrapping to
fit the text to the player's screen.  This is where you might insert ``^``
characters to force line breaks to appear, thus presenting the text as a
series of paragraphs.  So far, we've seen strings used as the value of a
``Constant``::

    Constant Headline
          "^A simple Inform example
           ^by Roger Firth and Sonja Kesserich.^";

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 :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.

Single quotes
-------------

Single quotes ``'...'`` surround a :term:`dictionary word`.  This has to be
a single word -- no spaces -- and generally contains only letters (and
occasionally numbers and hyphens), though you can use ``^`` to represent an
apostrophe inside the word.  Upper-case and lower-case letters are treated
as identical; also, the interpreter normally looks only at the first nine
characters of each word that the player types.

When the player types a command, the interpreter divides what was typed
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
:prop:`name` property::

     name 'bird^s' 'nest' 'twigs' 'moss',

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
:ref:`statements`; see also :doc:`/appendices/e`).

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
real game usually has lots and lots of statements, but so far we've
encountered only a few.  We saw::

     location = before_cottage;

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 :var:`location`
which is part of the library).  Later we saw::

     if (nest in branch) deadflag = 2;

which is actually *two* statements: an assignment, preceded by an ``if``
statement::

     if (nest in branch) ...

The ``if`` statement tests a particular condition; if the condition is
true, the interpreter executes whatever statement comes next; if it isn't
true, the interpreter ignores the next statement.  In this example, the
interpreter is testing whether the ``nest`` object is "in" or "on" (which
we now know means "is a child of") the ``branch`` object.  For most of the
game, that condition is not true, and so the interpreter ignores the
following statement.  Eventually, when the condition becomes true, the
interpreter executes that statement: it performs an assignment::

    deadflag = 2;

.. 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::

    if (nest in branch)
        deadflag = 2;

The thing that's being controlled by the ``if`` statement doesn't have to
be an assignment; it can be any kind of statement.  In fact, you can have
lots of statements, not just one, controlled by an ``if`` statement.  We'll
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.

.. _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 --
those statements are executed.  Here's the one that we've defined::

    [ Initialise; location = before_cottage; ];

Because it's such a tiny routine, we placed it all on a single line.  Let's
rewrite it to use several lines (as with the ``if`` statement, this improves
the readability, but doesn't affect how it works)::

    [ Initialise;
        location = before_cottage;
    ];

The ``[ Initialise;`` is the start of the routine, and defines the name by
which it can be "called".  The ``];`` is the end of the routine.  In
between are the statements -- sometimes known as the body of the routine --
which are executed when the routine is called.  And how is that done?  By a
statement like this::

    Initialise();

That single statement, the routine's name followed by opening and closing
parentheses, is all that it takes to call a routine.  When it comes across
a line like this, the interpreter executes the statements -- in this
example there's only one, but there may be ten, twenty, even a hundred of
them -- in the body of the routine.  Having done that, the interpreter
resumes what it was doing, on the line following the ``Initialise();``
call.

.. note::

   You may have noticed that, although we've defined a routine named
   ``Initialise``, we've never actually called it.  Don't worry -- the
   routine *is* called, by the Inform library, right at the start of a 
   game.

.. _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
we defined::

     [; if (nest in branch) deadflag = 2; ]

except that we didn't write it in isolation like that: instead, we defined
it to be the value of an object property::

     each_turn [; if (nest in branch) deadflag = 2; ],

which would have worked just the same if we'd written it like this::

     each_turn [;
         if (nest in branch)
             deadflag = 2;
     ],

All embedded routines are defined in this manner: as the value of an object
property.  That's where they're embedded -- inside an object.  The
introductory characters ``[;`` maybe look a little odd, but it's really
only the same syntax as for a standalone routine, only without a name
between the ``[`` and ``;``.

For calling an embedded routine, thus causing the statements it contains to
be executed, the method that we described for a standalone routine won't
work.  An embedded routine has no name, and needs none; it's
*automatically* called by the library at appropriate moments, which are
determined by the role of the property for which it is the value.  In our
example, that's at the end of every turn in which the player character is
in the same room as the branch.  Later, we'll see other examples of
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 :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
with facts at this early stage.  What we'd like you to do is to look back
at the source of the game, and ensure that you can recognise all the
elements which this chapter has described.  Then, we'll move on to fix a
few of the game's more important defects.