OmniMark provides a number of different simple data types, such as
integer
, switch
, and string
. Shelf items of these types, however, can only hold a single
value. In many cases you may want a shelf item that can hold multiple related values. Examples include shelves
that describe the metadata fields attached to a document or shelves that describe a point on a two-dimensional
grid.
Here is how you would declare a record
type to hold the metadata for a document:
declare record metadata-label field string author field string title field string publisher field integer year field switch in-print initial { true }
Each field
in the record
is itself of a particular type and is declared just as a local
shelf of that type would be declared, substituting the word field
for the word local
.
However, the record declaration by itself only defines a type. It does not create an actual shelf. Even though you can declare initial values for the fields, this only specifies what the initial values of those fields will be when an actual record is created.
To create an actual shelf of type metadata-label, you use a standard local
or global
declaration:
process local metadata-label doc-info
Once you have a shelf of type metadata-label, you can read and write the individual fields of the
record instance. To address a particular field of a record instance, you use the shelf name, followed by a colon,
followed by the field name:
process local metadata-label doc-info set doc-info:author to "Sir Arthur Conan Doyle" set doc-info:title to "The Hound of the Baskervilles" set doc-info:publisher to "George Newnes" set doc-info:year to 1902 set author-name to doc-info:author output doc-info:title
You can pass a record instance to a function:
define string source function format-metadata (value metadata-label x) as output "<H1>%n" || x:title || "</H1><P><B>by " || x:author || "</B></P>%n<P>" || x:publisher || "(" || "d" % x:year || ") " output "<I>out of print</I>" unless x:in-print output "</P>"
You can also return a record instance from a function:
define metadata-label function get-doc-info () as local metadata-label x set x:author to "Sir Arthur Conan Doyle" set x:title to "The Hound of the Baskervilles" set x:publisher to "George Newnes" set x:year to 1902 return x
You can initialize a record instance by writing a function that takes the field values as arguments and
returns a record instance:
define point function make-point (value integer x, value integer y) as local point a set a:x to x set a:y to y return a
You can then call this function to initialize a record instance, either when the shelf is declared,
or in the body of a rule or function:
process local point foo local point bar initial { make-point (12, 32) } set foo to make-point (14, 81)
You will frequently want to convert the value of a record to text for output. If you usually want the output
to take the same format, you can write a conversion function to convert from a
record instance to a string
. The following conversion function converts a point record
instance to a comma-separated pair of values:
define string conversion-function value point p as return "d" % p:x || "," || "d" % p:y
Once this function is part of your program you can output a string
representation of a point like
this:
process local point foo initial { make-point (23, 86) } output foo
A record may be used to represent mathematical concepts, such as a point, and therefore it may be desirable to
perform mathematical operations on records. For example, you may want to add two instances of the type point together. You could write a function specifically to add points:
define point function add-points (value point a, value point b) as local point c set c:x to a:x + b:x set c:y to a:y + b:y return c
However, it would be more elegant if you could use the OmniMark +
operator to add instances of
points. This can be done by overloading OmniMark's +
operator:
define overloaded point infix-function value point a + value point b as local point c set c:x to a:x + b:x set c:y to a:y + b:y return c
Once this function is defined, you can add two point instances together like this:
process local point foo initial { make-point (23, 86) } local point bar initial { make-point (74, 98) } local point baz set baz to foo + bar
While you can treat record shelves like regular shelves for most purposes, there are some important
differences. Record shelf items are not in fact records themselves, the way an integer
shelf item really
is an integer
. A record shelf item is actually a reference to a record instance.
As long as you address the individual fields of a record, this makes no difference. The difference comes when
you use a record shelf item alone. Consider what happens in the following code:
process local integer i initial { 2 } local integer j initial { 4 } set j to i set i to 5 output "d" % j
As expected, this program outputs 2, the last value assigned to the shelf j
.
Now consider this program:
declare record point field integer x field integer y process local point alpha local point omega set alpha:x to 2 set alpha:y to 4 set omega:x to 3 set omega:y to 9 set omega to alpha set alpha:x to 12 set alpha:y to 15 output "d" % omega:x || "|" || "d" % omega:y
You might expect the output of this program to be 2|4 since that is the set of values in the record alpha when we assigned alpha to omega. However, if you run the program you will see that the actual output is 12|15, the last values assigned to alpha.
This happens because alpha and omega are both references to record
instances, not the names of the records themselves. When we assigned alpha to omega
therefore, we made the shelf omega
reference the same record instance as the shelf
alpha
. That left us with two references to one record instance and no references to the other
record instance. When we changed the values of the record instance referenced by alpha, we
were also changing the values of the record instance referenced by omega, since both
alpha and omega
reference the same
instance.
Since there were no references to the orphaned record instance that used to be referenced by omega, that record instance was no longer available to the program. Sooner or later, it will be cleaned up and disposed of automatically by OmniMark's garbage collector.
The fact that records are references has important consequences for how you compare two records.
But if set
copies references to records, how do you copy the values of one record instance to
another? One way is to do it field
by field
:
set alpha:x to 2 set alpha:y to 4 set omega:x to 3 set omega:y to 9 set omega:x to alpha:x set omega:y to alpha:y
However, this is cumbersome. Another approach is to write a function to copy instance of points:
define function copy-point (value point a, value point b) as set b:x to a:x set b:y to a:y process ; ... copy-point (alpha, omega)
You may notice something odd about this function: Both a and b are passed
to copy-point as value
arguments and value
arguments cannot be modified. Yet we are
changing the values of record b. Why does this work? It works because a
and
b
are both references to record instances, not records themselves. It is the references that are
passed by value
and the
references are not being changed, only the record instances that they refer to.