Most programming languages allow programmers to store and manipulate values in arrays, associative arrays, queues, and stacks. Instead, OmniMark provides a data container called a "shelf" which can be used to accomplish all of the tasks normally carried out by these various structures in other programming languages. Like arrays, shelves can be indexed by numeric values that reflect the position of the elements they contain or, like associative arrays, these elements can be given names (keys) and then indexed by those keys.

A shelf is a data structure that is used to store one or more values of a certain type. Stream shelves can be used to store one or more string values, integer shelves to store one or more numeric values, and switch shelves to store one or more Boolean values. You can also create shelves of user defined data types that are created using records.

A global stream shelf declaration that creates a shelf of variable size named quotations would look like this:

  global stream quotations variable

A constant integer shelf declaration that creates a shelf named "numbers" that contains three numeric values would look like this:

  constant  integer numbers initial {1, 2, 3}

A local integer shelf declaration that creates an integer shelf named "count1" that can contain three (and only three) numeric values would look like this:

  local integer count1 size 3

If you want to create a shelf with initial values that are different from the defaults, you can do this by adding an initial keyword to the declaration, followed by the values you want on the shelf being enclosed in curly braces. For example:

  global integer count2 size 4 initial {1, 2, 3, 4}

This declaration creates a global integer shelf named "count2" that can hold four values with initial values of "1", "2", "3", and "4". You could also create a variable-sized shelf that contains a number of initial values, as follows:

  global integer count3 variable initial {1, 2, 3, 4}

The only difference between these two shelves (other than their names) is that while "count2" is a fixed-size shelf holding four values, "count3" begins with four values and can be expanded or contracted to hold as many as required. If you're not sure how many values you will need to store on a shelf, it's best to declare it with a variable size.

It is not necessary to specify size for a multi-item fixed-sized global, constant or local shelf if you provide initial values. So the following is allowed:

  constant integer weekday-number initial
      {0 with key "monday",
       1 with key "tuesday",
       2 with key "wednesday",
       3 with key "thursday",
       4 with key "friday",
       5 with key "saturday",
       6 with key "sunday"}

If variable is not specified and no size is given, but an initialpart is, then you have a fixed sized shelf whose size is the number of items in the initial part.

Additionally, shelves of a particular size can be created without having to assign initial values to the shelf items. This is accomplished by using the initial-size keyword:

  global integer count4 variable initial-size 4

This shelf declaration creates an integer named "count4" that starts with space for four items and can be expanded or contracted as required.

To store the string "Now is the winter of our discontent" in the stream shelf "quotations", you would use the following action:

  set new quotation to "Now is the winter of our discontent"

You may want to know where on the shelf this value was stored. Unless you explicitly specify which item on a shelf you want a value stored in, it will be stored in the current item. A shelf is basically an ordered list of items ranging from 1 to n. The default behavior of a shelf is that all new items are added after n. If you use set to store a different value on the shelf without specifying a different item, it will simply replace the n value on the shelf.

To change this default behavior, you can use either of two shelf indexing methods. The first index is based upon the position number of a value on a shelf. For example, the following code sets a value in the third position of the "quotation" shelf:

  set quotation[3] to "Words, words, words."

The second index is based upon names or "keys" that are assigned to each value on a shelf. To set the key of the current item on a shelf, you would use the following code:

  set key of quotation  to "Richard III"

To set the key of a particular item on a shelf, you would use the same code, but adding a position index:

  set key of quotation[3] to "Hamlet"

Using the key index of a shelf is very like using the position index, except instead of using the [...] keyword, you use the {...} keyword:

  set quotation{"Hamlet"} to "To be or not to be?"

It is possible to set a key on a shelf item when it is created. This is accomplished by setting the key in the same action in which the new item is created. For example, to create a new item on the "quotation" shelf that has a value of "Alas, poor Yorick." with the key "Hamlet", you would use the action:

  set new quotation{"Hamlet"} to "Alas, poor Yorick."

Up to this point, every time we have created a new item on a shelf, it has been added at the lastmost position of the shelf. If you want to create a new item somewhere else on a shelf, this can be accomplished by using the before or after keywords in the same action used to create the new item. For example, if you want to create a new item that will exist immediately before the second item on a shelf, you would use the following action:

  set new quotation before[2] to "A horse, a horse!"

This would create a new item containing the value "A horse, a horse!" between the first and second items on the "quotation" shelf. Since the item numbers are based on shelf position, this new item would become item 2, and the item that was number 2 would become number 3. If the values had assigned keys, of course, these keys would not change.

If you wanted to create a new item on a shelf just after an item that had the key "Macbeth", you would use the action:

  set new quotation after {"Macbeth"} to "A horse, a horse!"

To illustrate all of this, the following program creates a global stream shelf. The first item on that shelf is given a value and a key. Then another item is created at the "default" end of the shelf, and given a key. Another is created before the second item on the shelf. And another is created after the item having the specified key.

  process
     local stream quotation variable
     set new quotation{"Hamlet"} to "To be or not to be?"
     set new quotation{"Macbeth"} to "Is this a dagger...?"
     set new quotation{"Richard III"} before [2] to "A horse, a horse!"
     set new quotation{"Romeo"} after {"Richard III"} to "But, soft! What light through yonder window breaks?"
  
     repeat over quotation
        output key of quotation
            || " - "
            || quotation || "%n"
     again

This program will have the following output:

  Hamlet - To be or not to be?
  Richard III - A horse, a horse!
  Romeo -But, soft! What light through yonder window breaks?
  Macbeth - Is this a dagger...?

Prerequisite Concepts    Shelves

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACY LIBRARIES ] [ ERRORS ]