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")