Reviewing the basics
======================
+.. highlight:: inform
+
.. 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
=======================
Superficially similar, constants and variables are actually very different
beasts.
-.. rubric:: Constants
+Constants
+---------
-A **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.
+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::
Those two examples represent the most common ways in which constants are
used in Inform.
-.. rubric:: Variables
+Variables
+---------
-A **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
+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.
Global location;
Global deadflag;
-The value of a **global variable** created in this way is initially 0, but
-you can change it at any time. For example, we used the statement::
+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;
-to reset the value of the location variable to the ``before_cottage``
-object, and we wrote::
+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 **local variable** (see "Routines" on page 179)
-and about using object properties as variables (see "Objects" on page 177).
+.. _object-defs:
Object definitions
==================
indeed the player herself is also an object (one that's automatically
defined by the library).
-The general model of an **object** definition looks like this::
+.. 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 ,
in between are three major blocks of information:
* immediately after the word ``Object`` is the header information;
-* the word ``with`` introduces the object's **properties**;
-* the word ``has`` introduces the object's **attributes**.
+* 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:
...
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
...
...
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
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 **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,
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 **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.
+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::
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
=======================================
objects in the game.
Despite what we just said, Inform relationships *are* managed in terms of
-**parent** and **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:
+: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.
of the player (and *not* of the forest), and the player is both a parent
(of the bird) and a child (of the forest).
-In this diagram, 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.
+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%
-.. list-table::
- :widths: 1 3 5
+2. The player types: ``GO EAST``
- * - 1.
- - At the start of the game:
- - .. image:: /images/heidiobj1.*
+ .. blockdiag:: /figures/heidiobj2.diag
+ :align: center
+ :scale: 80%
- * - 2.
- - The player types: ``GO EAST``
- - .. image:: /images/heidiobj2.*
+3. The player types: ``TAKE THE BIRD``
- * - 3.
- - The player types: ``TAKE THE BIRD``
- - .. image:: /images/heidiobj3.*
+ .. blockdiag:: /figures/heidiobj3.diag
+ :align: center
+ :scale: 80%
- * - 4.
- - The player types: ``GO NORTHEAST``
- - .. image:: /images/heidiobj4.*
+4. The player types: ``GO NORTHEAST``
- * - 5.
- - The player types: ``PUT BIRD IN NEST``
- - .. image:: /images/heidiobj5.*
+ .. blockdiag:: /figures/heidiobj4.diag
+ :align: center
+ :scale: 80%
- * - 6.
- - The player types: ``TAKE NEST``
- - .. image:: /images/heidiobj6.*
+5. The player types: ``PUT BIRD IN NEST``
- * - 7.
- - The player types: ``UP``
- - .. image:: /images/heidiobj7.*
+ .. blockdiag:: /figures/heidiobj5.diag
+ :align: center
+ :scale: 80%
- * - 8.
- - The player types: ``PUT NEST ON BRANCH``
- - .. image:: /images/heidiobj8.*
+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
-**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
+: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
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 **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.
+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::
+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."
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 **dictionary word**. This has to be a
-single word -- no spaces -- and generally contains only letters (and
+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
action, that's what happens next.
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',
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 **statement** is an instruction telling the interpreter to perform a
+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 **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``
+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;
deadflag = 2;
-which changes the value of the library variable ``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::
+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 only place where you'll find statements are within standalone routines
and embedded routines.
-.. rubric:: Standalone routines
+.. _standalone-routines:
-A **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::
+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; ];
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.
+ routine *is* called, by the Inform library, right at the start of a
+ game.
+
+.. _embedded-routines:
-.. rubric:: Embedded routines
+Embedded routines
+-----------------
-An **embedded routine** is much like a standalone routine, though it
+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::
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
projects / ibg.git / blobdiff