2. The language of data structures

2.1. Directives and constants

Every example program so far has consisted only of a sequence of routines, each within beginning and end markers [ and ]. Such routines have no way of communicating with each other, and therefore of sharing information with each other, except by making function calls back and forth. This arrangement is not really suited to a large program whose task may be to simulate something complicated (such as the world of an adventure game): it would be useful to have some kind of central registry of information which all routines have access to, as and when needed.

Information available to all routines in this way is said to be "global'', rather than "local'' to any one routine. (As will appear in Section 3, there is also an intermediate possibility where information is available only to a cluster of routines working on roughly the same part of a program.)

This global information can be organised in a variety of ways. Such organised groups are called "data structures''. For example, a typical data structure might be a list of 10 values. The term "data structure'' did not appear in Section 1 because information was only ever held in variables, the simplest possible kind of structure (one value on its own).

Data structures are added to Inform programs using commands called "directives'' in between definitions of routines. It's important to distinguish between these, which direct Inform to do something now (usually, to create something) and the statements which occur inside routines, which are merely translated in some way but not acted on until the program has finished being compiled and is run.

In fact, one directive has already appeared: the one written [, which means "translate the following routine up to the next ]''. In all there are 38 Inform directives, as follows:

Abbreviate  Array       Attribute  Class        Constant     Default
Dictionary  End         Endif      Extend       Fake_action  Global
Ifdef       Ifndef      Ifnot      Ifv3         Ifv5         Iftrue   
Iffalse     Import      Include    Link         Lowstring    Message     
Nearby      Object      Property   Release      Replace      Serial      
Switches    Statusline  Stub       System_file  Trace        Verb        
Version     [

This leaves 9 central directives for creating data structures, and these are the ones which it is important to know about:

Array       Attribute   Class      Constant     Extend       Global
Object      Property    Verb

The simplest directive with a "global'' effect on the program -- an effect all over the program, that is, not just in one routine -- is Constant. The following program, an unsatisfying game of chance, shows a typical use of Constant.

    Constant MAXIMUM_SCORE = 100;

    [ Main;
      print "You have scored ", random(MAXIMUM_SCORE),
      " points out of ", MAXIMUM_SCORE, ".^";
    ];

If no value is specified for a constant, as in the line

    Constant DEBUG;

2.2. Global variables

As commented above, so far the only variables allowed have been "local variables'', each private to their own routines. A "global variable'' is a variable which is accessible to all code in every routine. Once a global variable has been declared, it is used in just the same way as a local variable. The directive for declaring a global variable is Global:

    Global score = 36;

2.3. Arrays

An "array'' is an indexed collection of (global) variables, holding a set of numbers organised into a sequence. It allows general rules to be given for how a group of variables should be treated. For instance, the directive

    Array pack_of_cards --> 52;

    pack_of_cards-->0   pack_of_cards-->1   ...   pack_of_cards-->51

In addition to this, Inform provides arrays which have a little extra structure: they are created with the 0th entry holding the number of entries. A word array with this property is called a table; a byte array with this property is a string.

For example, the array defined by

    Array continents table 5;

    Array password string "DANGER";
    Array phone_number string "1978-345-2160";
    ...
    PrintString(password);
    ...
    PrintString(phone_number);
    ...
    [ PrintString the_array i;
        for (i=1: i<=the_array->0: i++)
            print (char) the_array->i;
    ];

To recapitulate, Inform provides four kinds of array in all:

    -->   ->   table   string

Instead, we can give a list of constant values. For example,

    Array primes --> 2 3 5 7 11 13;

The third way to create an array gives some text as an initial value (because one common use for arrays is as "strings of characters'' or "text buffers''). The two string arrays above were set up this way. As another example,

    Array players_name -> "Frank Booth";

    Array players_name -> 'F' 'r' 'a' 'n' 'k' ' ' 'B' 'o' 'o' 't' 'h';

    Array ten --> 10;
    Array fives --> 5 10 15 20 25;
    [ Main n;
      for (n=1: n<=10: n++) ten-->n = -1;
      print fives-->0, "^";
    ];

2.4. Example 7: Shuffling a pack of cards

This program simulates the shuffling of a pack of playing cards. The cards are represented by numbers in the range 0 (the Ace of Hearts) to 51 (the King of Spades). The pack itself has 52 positions, from position 0 (on the top) to position 51 (on the bottom). It is therefore represented by the array

    pack_of_cards-->i

    Constant SHUFFLES = 100;
    Array pack_of_cards --> 52;

    [ ExchangeTwo x y z;

      !   Initially x and y are both zero

      while (x==y)
      {   x = random(52) - 1; y = random(52) - 1;
      }

      !   x and y are now randomly selected, different numbers
      !   in the range 0 to 51

      z = pack_of_cards-->x;
      pack_of_cards-->x = pack_of_cards-->y;
      pack_of_cards-->y = z;
    ];

    [ Card n;
      switch(n%13)
      {   0: print "Ace";
          1 to 9: print n%13 + 1;
          10: print "Jack";
          11: print "Queen";
          12: print "King";
      }
      print " of ";
      switch(n/13)
      {   0: print "Hearts";
          1: print "Clubs";
          2: print "Diamonds";
          3: print "Spades";
      }
    ];

    [ Main i;
      !   Create the pack in "factory order":
      for (i=0:i<52:i++) pack_of_cards-->i = i;
      !   Exchange random pairs of cards for a while:
      for (i=0:i<SHUFFLES:i++) ExchangeTwo();
      print "The pack has been shuffled to contain:^";
      for (i=0:i<52:i++)
          print (Card) pack_of_cards-->i, "^";
    ];

2.5. Seven special data structures