A shelf is an ordered collection of values of a particular type. You can access items on a shelf either by item number or by key value. A key is a text value. Each key on a shelf must be unique.

In OmniMark, all variables are also shelves, even if they only contain a single value.

Creating a shelf

A shelf can be of fixed or variable size. In fact, an ordinary variable declaration creates a shelf with a fixed size of 1 item:

  local integer word-count

You can create shelves of a fixed size by specifying the size in the declaration:

  local stream days-of-the-week size 7

You can create a variable sized shelf, by specifying variable in the declaration.

  local integer word-count variable

Addressing items on a shelf

If a shelf has only one item, you can address that item by the name of the shelf alone:

  output template-file-name

If there are multiple items on the shelf you can address each item by specifying the item number in square brackets:

  set template-file-name[5] to "foo.txt"

The item number can be expressed either as an integer literal or as an integer expression:

  open template-file
   as file template-file-name[last-template-number + 1]

To address an item by its key, enclose the key string in curly braces:

  set template-file-name{"home-page"} to "home.txt"

The key can be expressed either as a literal string or as a string expression:

  output grid-cell{"d" % row || "-" || "d" % col}

You can access the key of a shelf item using the expression key of:

  output key of shopping-list[2]
  set key of template-file-name[7] to "order-page"
  do when key of shopping-list[2] = "radishes"

You can retrieve the item number of an item using the expression item of, but you cannot change an item number:

  output "d" % item of template-file-name{"order-page"}

It is an error to attempt to access a non-existent key. You can test to see if an item on a shelf has a key using the is keyed test:

  output key of shopping-list[2] when shopping-list[2] is keyed

You can test to see if a shelf has an item with a particular key using the has key test:

  output shopping-list{"radishes"} when shopping-list has key "radishes"

Adding and removing items on a variable shelf

You can add items to a variable shelf with the new and set new keywords. The following line creates a new item on the shelf word-count with the key "Hamlet" and the value 32058:

  set new word-count{"Hamlet"} to 32058

You don't have to give every item a key. If all you need is a simple array, you can create shelf items without specifying keys:

  local stream shopping-list variable
  set new shopping-list to "lettuce"

Alternatively, you can create a shelf which has keys but no values. This is useful if you want to create an array in which every item is guaranteed to be unique. You can test a key for uniqueness before adding it to a shelf:

  local stream shopping-list variable
  do when shopping-list hasnt key "lettuce"
     new shopping-list{"lettuce"}
  done

By default, new items are added to the end of the shelf. You can specify a different location using the keywords before and after:

  local stream shopping-list variable
  set new shopping-list{"lettuce"} after {"cabbage"}

You can remove an item from a shelf using the remove keyword:

  remove word-count{"Hamlet"}
  remove shopping-list[7]

Note that adding or removing items from a shelf causes the item numbers of all the items above the insertion point to change. Item numbers are not permanently attached to items. They are indexes into the shelf by position, not properties of the items. Keys, on the other hand, are properties of each shelf item, so the relationship between an item and its key is maintained when items are added or removed from a shelf.

Repeating over a shelf

You can perform an operation on each item on a shelf in turn using the repeat over loop:

  repeat over shopping-list
     output shopping-list || "%n"
  again

Within a repeat-over block, you refer to the current item using the base-name of the shelf, without an indexer. You can retrieve the current item number using #item. You can test for the first and last items using #first and #last.

The following program creates a shelf, using various methods to position items on the shelf:

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

This program will 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...?

The current item

Every shelf has a current item. If you refer to the shelf without using an indexer, the reference is to the current item.

The default current item is the last item. You can change the current item in one of three ways:

1. The current item is the next item in succession each time through a repeat over loop.
2. You can designate the current item with a using statement.
3. You can establish the current item for a shelf passed (as modifiable or read-only) to a function call.

There are two cases where a shelf has no current item:

1. when it has zero items
2. when the current item established by using has been removed

Operations on shelves

You can perform a number of operations on shelves:

• You can copy the contents of one shelf to another by using the copy keyword.
• You can remove all the items from a variable shelf by using the clear keyword.
• You copy the contents of a variable shelf to another shelf and then clear the contents of the first shelf using the copy-clear keyword.
• You can determine the number of items on a shelf using the keyword number of.

Deprecated indexing methods

Earlier versions of OmniMark used a different indexing method. This method is deprecated but is supported for compatibility with programs written for older versions.

item and @ are deprecated synonyms for [...]. The keywords key and ^ are deprecated synonyms for {...}.

Prerequisite Concepts    Variables and Constants

Related Syntax    clear    global, local, constant, field    has key    is keyed    key of    new    number of    record, declare record    remove    remove key of    repeat over, #item, #last, #first

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