Structures
Isis software documentation
Structures
An Isis structure is a data storage construct meant to resemble
a C structure. An Isis structure holds an unordered collection of
named fields, each of which contains a value. You may create as many
structures as you wish, and you may add, modify, query, and remove
fields inside a structure at any time.
Creating a structure
(new-structure) # create new empty structure
(new-structure field-value-list) # sets initial fields and values
new-structure creates a new structure object and returns it
as a procedure. You can modify and query the structure by calling
this procedure with different kinds of arguments. If desired, you may
pass a list of field-value pairs to initialize the structure.
Adding or modifying a field
(strc field val) # adds or modifies a field
Calling a structure with 2 arguments adds a new field or resets the
value of an existing field in a structure. The first argument is the
field's reference value (the field's "name"). This reference value
may be any Isis value. The second argument is the value that
should be placed in that field.
Removing a field
(strc field Null) # removes a field
Calling a structure with a field reference and value of Null
will delete that field from the structure.
Retrieving the value of a specific field
(strc field) # retrieves value of field
Calling the structure with just the field reference retrieves the
value of that field, or returns Null if the field does not
exist.
Retrieving the entire contents of a structure
(strc) # retrieves entire structure
Calling the structure with no arguments returns the entire structure
in the form of a list of field-value pairs. By passing this list as
the argument to new-structure, a separate copy of a structure
can be made if desired.
Reading and writing structures
(write-structure port strc) # write a structure to a file
(read-structure port strc) # read a structure from a file
These functions read and write structures to files.
write-structure writes the contents of the given structure to
the given file handle port in a human-readable format.
read-structure reads fields in the same format from
port into the given structure, which may be empty or already
contain some fields (any fields that are duplicated will be
overwritten).
Examples
-> (set s1 (new-structure))
Proc
-> (s1 "framecount" 1001)
1001
-> (s1 "framesize" [320 240])
[ 320 240 ]
-> (s1 "coding" "jpeg")
"jpeg"
-> (s1 "framesize")
[ 320 240 ]
-> (s1 "coding")
"jpeg"
-> (s1 "framecount")
1001
-> (s1)
[ [ "framecount" 1001 ] [ "framesize" [ 320 240 ] ] [ "coding" "jpeg" ] ]
-> (s1 "framesize" Null)
Null
-> (s1)
[ [ "framecount" 1001 ] [ "coding" "jpeg" ] ]
-> (set s1copy (new-structure (s1)))
Proc
-> (s1copy "coding" "tiff")
"tiff"
-> (s1 "coding")
"jpeg"
-> (s1copy "coding")
"tiff"
Note below that any Isis value (not just strings) may serve as the
field "name":
-> (s1 42 "stranger")
"stranger"
-> (s1 [3 2 1] "attack!")
"attack!"
-> (s1 42)
"stranger"
-> (s1 [3 2 1])
"attack!"
-> (s1)
[ [ "framecount" 1001 ] [ "coding" "jpeg" ] [ 42 "stranger" ] [ [ 3 2 1 ] "attack!" ] ]
Below, the structure s1 is written to a file, and then read
back in to a new structure s2:
-> (set port (open-output "test.info"))
3
-> (write-structure port s1)
Proc
-> (close port)
True
-> (set port (open-input "test.info"))
3
-> (set s2 (new-structure))
Proc
-> (read-structure port s2)
Proc
-> (close port)
True
-> (s2)
[ [ "framecount" 1001 ] [ "coding" "jpeg" ] [ 42 "stranger" ] [ [ 3 2 1 ] "attack!" ] ]
Requirements:
Scripts:
| (load "structure.isis")
|