A shelf is an ordered collection of values of a particular data 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.
A shelf can be of fixed or variable size. In fact, an ordinary variable declaration creates a shelf with a
fixed size of 1:
local integer word-count
You can create shelves of a fixed size by specifying the size
in the declaration:
local string days-of-the-week size 7
You can create a variable sized shelf, by specifying variable
in the declaration.
local integer word-count variable
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-items[2] set key of template-file-name[7] to "order-page" do when key of shopping-list-items[2] = "radishes" buy-radishes (shopping-list-items) done
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-items[2] when shopping-list-items[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-items{"radishes"} when shopping-list-items has key "radishes"
You can add items to a variable-size 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 do not have to give every item a key. If all you need is a simple array, you can create shelf items
without specifying keys:
local string shopping-list-items variable set new shopping-list-items 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 string shopping-list-items variable do when shopping-list-items hasnt key "lettuce" new shopping-list-items{"lettuce"} done
Alternatively, the guarded form of new
can be used: the previous example is equivalent to
local string shopping-list-items variable new? shopping-list-items{"lettuce"}
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 string shopping-list-items variable set new shopping-list-items{"lettuce"} after {"cabbage"}
You can remove an item from a shelf using the remove
keyword:
remove word-count{"Hamlet"} remove shopping-list-items[7]
Note that adding or removing items from a shelf causes the item numbers of all the items above the insertion or removal 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: when a shelf item is added or removed from a shelf, the other items on that shelf retain their keys, if any.
The items on a shelf can be iterated over using the repeat over
loop:
repeat over shopping-list-items output shopping-list-items || "%n" again
Within a repeat over
loop, you refer to the current item using the name of the shelf, without an
indexer. Alternatively, you can use an alias in the header of the repeat over
loop:
repeat over shopping-list-items as list-item output list-item || "%n" again
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 string 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...?
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.
repeat over
loop.
using
statement.
read-only
, modifiable
, or
write-only
) to a function call.
There are two cases where a shelf has no current item:
using
has been removed
You can perform a number of operations on shelves:
copy
keyword.
clear
keyword.
copy-clear
keyword.
number of
.