Galaxy Communicator Documentation:

Frames, Property Lists, and Typed Objects

Developers of Communicator-compliant systems will use the GAL_CLAUSE type exclusively, and will not use the list of predicate frames at all. The remaining frame types and predicate list are used internally by MIT in their parsing and semantic interpretation. We provide a brief summary of their use of these types as a point of interest; these distinctions are ignored entirely in the Galaxy Communicator infrastructure.

Frame Syntax

The printed representation of a frame is used both for presentation by functions like Gal_PrFrame and for digestion by functions like Gal_ReadFrameFromString.

"{"<type> <name> <key> <value> <key> <value> ... "}"

In other words, a frame begins with a left curly bracket ("{"), followed immediately by a type, followed by a whitespace-delimited name, and then a sequence of alternating whitespace-delimited keys and values, followed by a right curly bracket ("}").

Legal types are c (GAL_CLAUSE), q (GAL_TOPIC), p (GAL_PRED)
The whitespace between the final value and the closing bracket is optional
There can be no space between the opening bracket and the type
The name is obligatory; the type is optional (default is GAL_CLAUSE)
Where whitespace is permitted, any amount of whitespace is permitted (except in GAL_BINARY)

The convention for keys is that they should be alphanumeric and begin with a colon (":"). Nothing in the system enforces these conventions, though.

Note that the keys :pred and :PRED are special to Gal_ReadFrameFromString and its relatives.

Examples

{c foo }
{p mod }

{ object }

Object Types

Each value of a frame key in a key-value pair is a structure called a Gal_Object, which is a typed data structure. The following table lists the available types. All types not only used internally are available for both brokering and frames.

data type	Gal_ObjectType	C type
frame	GAL_FRAME	Gal_Frame
string	GAL_STRING	(char *)
integer	GAL_INT	32 bit integer
float	GAL_FLOAT	32 bit float
list	GAL_LIST	a Gal_Object list
symbol	GAL_SYMBOL	(only used internally)
pointer	GAL_PTR	(only used internally)
topic frame	GAL_TOPIC_FRAME	Gal_Frame
clause frame	GAL_CLAUSE_FRAME	Gal_Frame
predicate frame	GAL_PREDICATE_FRAME	Gal_Frame
binary data	GAL_BINARY	array of 8 bit integers
16 bit integer	GAL_INT_16	array of 16 bit integers
32 bit integer	GAL_INT_32	array of 32 bit integers
64 bit integer	GAL_INT_64	array of 64 bit integers
32 bit float	GAL_FLOAT_32	array of 32 bit floats
64 bit float	GAL_FLOAT_64	array of 64 bit floats
broker proxy	GAL_PROXY	GalSS_BrokerProxy *
keyword	GAL_KEYWORD	(only used internally)
tag	GAL_TAG	(only used internally)
token	GAL_TOKEN	(only used internally)

Object syntax

The printed representation of an object is used both for presentation by functions like Gal_PrObject and for digestion by functions like Gal_ReadObjectFromString.

Gal_ObjectType	format example	comments
GAL_STRING	`"foo"`	Strings are delimited by double quotes ("), and internal whitespace is preserved
GAL_FRAME	`{c foo :value 1 }`	Frame values have the same form as frames, and thus support arbitrary recursion
GAL_INT	`5`	Positive and negative values handled
GAL_FLOAT	`5.6`	Positive and negative values handled
GAL_LIST	`( 5 "foo" {c bar } )`	lists are delimited by left and right parentheses ("(", ")"). Elements of the list can be any object type (so different object types can be mixed in the same list). Whitespace after opening parenthesis and before closing parenthesis is no longer obligatory, although whitespace between list elements still is
GAL_BINARY	`%% <decoded_length> <encoded_length> <data>`	Whitespace separating the four elements must be exactly one space; the data is encoded using a variant of uuencode (see source code for algorithm)

Other types (GAL_INT_16, etc.) do not have any printed representations which can be recognized by Gal_ReadObjectFromString.

Examples

{c main :initialize 1 }
{c rec :status "typed" :confidence_measures ( 0.5 4.6 2.756 ) }

{c error :error_description {c system_unavailable :timeout 40 } }

The types GAL_TOKEN, GAL_SYMBOL and GAL_KEYWORD are not intended to be used for values in frames, as we understand it. However, if the string representation of your frame contains a value consisting of a single token without delimiting quotes, it may be recognized as one of these elements.

Frame Functions

Frame Create, Free, and Copy Functions

Gal_Frame Gal_MakeFrame(const char *name, Gal_FrameType type);
Creates a frame of the specified type, type. The name should begin with an alphabetic character and contain no spaces.

Memory management
The frame is allocated from an internal supply of frames. The name is copied using strdup.

void Gal_FreeFrame(Gal_Frame fr);
"Frees" the frame, fr.

Memory management
All the values of the keys in the frame are freed using Gal_FreeObject, as are all the elements in the predicate list. The frame is returned to the internal supply of frames for reuse.

Gal_Frame Gal_CopyFrame(Gal_Frame fr);
Copies the frame, fr, and all its contents.

Memory management
All the values of the frame keys are copied using Gal_CopyObject, as are all the elements of the predicate list.

Gal_Frame Gal_MakeClauseFrame(const char *name)

Creates a frame of type GAL_CLAUSE. See Gal_MakeFrame.

Frame Comparison Predicates

int Gal_FrameEqual(Gal_Frame sf1, Gal_Frame sf2);
Returns 1 if the frames have the same name and type and have matching property and predicate lists. Having matching property lists currently means that sf1 has all the keys in sf2 and the corresponding values are judged equal using Gal_ObjectEqual. Having matching predicate lists currently means that sf2 has predicates that match all the predicates of sf1.

int Gal_MatchFrame(Gal_Frame sf1, Gal_Frame sf2);
Returns 1 if the frames have the same name and type and have matching property lists. Having matching property lists currently means that sf1 has all the keys in sf2 and the corresponding values are judged equal, where equality for GAL_FRAME is judged recursively by Gal_MatchFrame, equality for GAL_LIST is such that each element in the key value for sf2 has a match in the corresponding value for sf1 (where the match is judged recursively on the same terms as the toplevel), and equality for all other types is judged by Gal_ObjectCaseEqual. The name of either frame can be *, indicating a wildcard match. Predicates associated with frames are not considered in this comparison.

Frame Name and Type Operations

Gal_Frame Gal_SetFrameName(Gal_Frame fr, const char *name);
Sets the name of the frame, fr, to name.

Memory management
The name is copied using strdup.

char *Gal_FrameName(Gal_Frame fr);
Returns the name of the frame, fr.

Memory management
The string which is returned is the string in the frame, not a copy.

int Gal_FrameNameEq(Gal_Frame fr, const char *name);
Returns 1 if the frame has name name.

int Gal_FrameNamesEq(Gal_Frame fr1, Gal_Frame fr2)
Returns 1 if the two frames have the same name.

Gal_Frame Gal_SetFrameType(Gal_Frame fr, Gal_FrameType type);
Sets the type of the frame, fr, to type.

Gal_FrameType Gal_GetFrameType(Gal_Frame fr);
Returns the type of the frame, fr.

int Gal_FrameIsType(Gal_Frame fr, Gal_FrameType type);
Returns 1 if the frame, fr, is of the specified type, type.

Property Lists

Frames contain property lists, or lists of key-value pairs which describe some knowledge about the domain. A key-value pair is a relation which maps domain elements to elements of a range. All keys are optional. Keys used in frames should not have global impact. Keys should begin with a colon and contain no spaces. Values of keys are typed objects as described below.

Property List Operations

int Gal_NumProperties(Gal_Frame fr);
Returns the number of properties in the property list. This function counts properties with NULL values.

int Gal_NumNonNullProperties(Gal_Frame fr);
Returns the number of properties in the property list. This function skips properties with NULL values.

Gal_Object Gal_SetProp(Gal_Frame fr, const char *key, Gal_Object obj);
Adds the object, obj, to the property list. The key, key, should begin with a colon (:) and contain no spaces. If the key is found in the property list, the associated object will be freed using Gal_FreeObject and replaced with the new object.

Memory management
The obj is not copied when stored in the frame, in spite of the fact that objects it replaces are freed. The key is copied using strdup, if the key is not yet present.

Gal_ObjectGal_GetObject(Gal_Frame fr, const char *key);
Returns the object associated with the key specified by key.

Memory management
The Gal_Object which is returned is not copied from the frame.

Gal_ObjectGal_RemProp(Gal_Frame fr, const char *key);
Removes the property, specified by key, from the property list and returns the object. The caller is responsible for freeing the object.

Memory management
The Gal_Object is returned, not freed.

int Gal_DelProp(Gal_Frame fr, const char *key)
Removes the property, specified by key, from the property list and calls Gal_FreeObject on it. Returns 1 if an element was found to free, 0 otherwise.

char **Gal_GetProperties(Gal_Frame fr, int *nkeys);
Returns a list of all the keys in the property list. If successful, nkeys will be set to the number of properties.

Memory management
The array of char * pointers is allocated using calloc, but each element in the array is a pointer to the actual name of the key, not a copy.

void Gal_DoProperties(Gal_Frame fr, int (*prop_fn)(const char *, Gal_Object , void *), void *caller_data)
Applies the function prop_fn to every key-value pair in the property list of the frame fr whose value is not NULL. The first argument of prop_fn is the key, the second is the Gal_Object value which would be returned by Gal_GetObject, and the third argument is the caller_data. The prop_fn should return 1 to continue, 0 to halt.

Miscellaneous Functions

The following functions are provided for convenience and compile time type checking.

Memory management
These functions have the same memory management properties as the object value extraction functions.

Gal_Frame Gal_GetFrame(Gal_Frame fr, const char *key);
Returns the frame value specified by the key, key, or NULL if the key is not present or its value is not a frame.

Gal_Frame Gal_GetTopicFrame(Gal_Frame fr, const char *key)
Returns the topic frame value specified by the key, key., or NULL if the key is not present or its value is not a topic frame.

char *Gal_GetString(Gal_Frame fr, const char *key);
Returns the string value specified by the key, key, or NULL if the key is not present or its value is not a string.

int Gal_GetInt(Gal_Frame fr, const char *key);
Returns the integer value specified by the key, key, or NULL if the key is not present or its value is not an integer.

float Gal_GetFloat(Gal_Frame fr, const char *key);
Returns the float value specified by the key, key, or NULL if the key is not present or its value is not a float.

Gal_Object *Gal_GetList(Gal_Frame fr, const char *key, int *length);
Returns the list value specified by the key, key. length is set to the length of the list object. If the key is not present, or the object is not a list, NULL is returned and length is not set.

void *Gal_GetBinary(Gal_Frame fr, const char *key, int *size);
Returns the binary object value specified by the key, key. size is set to the length of the binary object. If the key is not present, or the object is not a binary object, NULL is returned and size is not set.

void *Gal_GetInt16(Gal_Frame fr, const char *key, int *size)
Returns the GAL_INT_16 object value specified by the key, key. size is set to the number of elements in the object. If the key is not present, or the object is not a GAL_INT_16 object, NULL is returned and size is not set.

void *Gal_GetInt32(Gal_Frame fr, const char *key, int *size)
Returns the GAL_INT_32 object value specified by the key, key. size is set to the number of elements in the object. If the key is not present, or the object is not a GAL_INT_32 object, NULL is returned and size is not set.

void *Gal_GetInt64(Gal_Frame fr, const char *key, int *size)
Returns the GAL_INT_64 object value specified by the key, key. size is set to the number of elements in the object. If the key is not present, or the object is not a GAL_INT_64 object, NULL is returned and size is not set.

void *Gal_GetFloat32(Gal_Frame fr, const char *key, int *size)
Returns the GAL_FLOAT_32 object value specified by the key, key. size is set to the number of elements in the object. If the key is not present, or the object is not a GAL_FLOAT_32 object, NULL is returned and size is not set.

void *Gal_GetFloat64(Gal_Frame fr, const char *key, int *size)
Returns the GAL_FLOAT_64 object value specified by the key, key. size is set to the number of elements in the object. If the key is not present, or the object is not a GAL_FLOAT_64 object, NULL is returned and size is not set.

GalSS_BrokerProxy *Gal_GetProxy(Gal_Frame fr, const char *key)
Returns the GAL_PROXY object value specified by the key, key. If the key is not present, or the object is not a GAL_PROXY object, NULL is returned.

Typed Object Functions

For type checking, GAL_CLAUSE_FRAME, GAL_TOPIC_FRAME, GAL_PRED_FRAME, and GAL_FREE (for NULL frame) are valid.

Gal_ObjectType Gal_GetObjectType(Gal_Object to);
Returns the object type of the typed object, to.

Gal_ObjectType Gal_GetDetailedType(Gal_Object to);
Returns the object type of the typed object, to. If the object is of type GAL_FRAME, the detailed frame type is returned: one of GAL_CLAUSE_FRAME, GAL_TOPIC_FRAME, GAL_PRED_FRAME, or GAL_FREE.

char *Gal_ObjectTypeString(Gal_ObjectType object_type);
Returns a character string representing the name of the object type, object_type. This can be a Gal_Object type, a Gal_Frame type, or a binary data type.

Memory management
The string which is returned is a constant which should not be freed.

char *Gal_GetObjectTypeString(Gal_Object to)
Returns a character string representing the name of the type of the object to.

Memory management
The string which is returned is a constant which should not be freed.

Object Creation Functions

The following functions are for converting values into objects. They are most frequently used with Gal_SetProp, as in the following example:

void set_clause_topic(Gal_Frame clause, Gal_Frame topic)
{
Gal_SetProp(clause, ":topic", Gal_FrameObject(topic));
}

Gal_Object Gal_FrameObject(Gal_Frame val);
Converts the value, val, into a GAL_FRAME object.

Memory management

Creation: the frame argument is not copied; the Gal_Object which is returned contains a pointer to the frame passed in. The Gal_Object is allocated from an internal store of Gal_Objects.
Freeing: the frame which the Gal_Object points to is freed via Gal_FreeFrame, even though it was not copied when the object was created. The Gal_Object is returned to the internal store of Gal_Objects.
Copying: the frame is copied using Gal_CopyFrame. A new object is created using Gal_FrameObject.

Gal_Object Gal_CreateFrameObject(Gal_Frame value, int manage_memory)
Converts the value, value, into a GAL_FRAME object. If manage_memory is nonzero, the value will be freed when the object is freed, otherwise not.

Gal_Object Gal_StringObject(const char *val);
Converts the value, val, into a GAL_STRING object.

Memory management

Creation: the string is copied using strdup(). The Gal_Object is allocated from an internal store of Gal_Objects.
Freeing: the string is freed. The Gal_Object is returned to the internal store of Gal_Objects.
Copying: a new object is created using Gal_StringObject.
See Gal_CreateStringObject for memory management options.

Gal_Object Gal_CreateStringObject(char *cp, int manage_memory)
Converts the value, cp, into a GAL_STRING object. If manage_memory is nonzero, the value will be freed when the object is freed, otherwise not.

Gal_Object Gal_IntObject(int val);
Converts the value, val, into a GAL_INT object.

Memory management

Creation: the Gal_Object is allocated from an internal store of Gal_Objects.
Freeing: the Gal_Object is returned to the internal store of Gal_Objects.
Copying: a new object is created using Gal_IntObject.

Gal_Object Gal_FloatObject(float val);
Converts the value, val, into a GAL_FLOAT object.

Memory management

Creation: a placeholder for a float is allocated using calloc(), and the value passed in is stored in that location. The Gal_Object is allocated from an internal store of Gal_Objects.
Freeing: the float placeholder is freed. The Gal_Object is returned to the internal store of Gal_Objects.
Copying: a new object is created from the contents of the float placeholder using Gal_FloatObject.
See Gal_CreateFloatObject for memory management options.

Gal_Object Gal_CreateFloatObject(float *value, int manage_memory)
Converts the value, value, into a GAL_FLOAT object. The value must point to allocated memory. If manage_memory is nonzero, the allocated memory will be freed with the object is freed, otherwise not.

Gal_Object Gal_ListObject(Gal_Object *values, int n);
Converts the values, values, into a GAL_LIST object, where n is the number of objects in the list. The resulting object is not expandable using Gal_ListObjectAdd.

Memory management

Creation: an array of Gal_Objects (which are actually pointers to structs, not structs themselves) is allocated using calloc(), and the elements in that array are made to point to the elements in values; so the array is copied, but not its members. If n is 0 or values is NULL, no memory is allocated. The Gal_Object is allocated from an internal store of Gal_Objects.
Freeing: each object in the array is freed using Gal_FreeObject, even though the objects were not copied when the list was created. The array itself is freed. The Gal_Object is returned to the internal store of Gal_Objects.
Copying: an array of Gal_Objects is allocated using calloc(), and the elements of the internal array in the source object are copied using Gal_CopyObject. A new Gal_Object is allocated from an internal store of Gal_Objects; the Gal_ListObject function is not used directly.
See Gal_CreateListObject for explicit memory management options.

Gal_Object Gal_ListObjectFromElements(int n, ... )
Converts n values into a GAL_LIST object. Unlike Gal_ListObject, does not require the user to create an array of Gal_Objects first. The variable number of values must all be Gal_Objects. The same memory management comments apply.

Gal_Object Gal_CreateListObject(Gal_Object *values, int n, void (*free_fn)(void *), int manage_memory)
Converts the values, values, into a GAL_LIST object, where n is the number of objects in the list. The resulting list is expandable using the function Gal_ListObjectAdd. The free_fn is a function which can be used to free the elements of the list. There is no default freeing function, so unlike Gal_ListObject, the elements aren't automatically freed when the list object is freed. If the manage_memory argument is nonzero, the list of objects itself will be freed when the enclosing object is freed, otherwise not.

int Gal_ListObjectAdd(Gal_Object obj, Gal_Object elt)
Add object elt to the dynamic list object obj.

Gal_Object Gal_BinaryObject(void *data, int size);
Converts the data, data, into a GAL_BINARY object, where size is the size of the data in bytes. While frames allow binary data to be transported, brokering is a more flexible tool for transmitting audio data; binary data can be used for encoding arbitrary objects. The resulting object is not expandable using Gal_ArrayObjectAdd.

Memory management

Creation: an array the same size as data is allocated using malloc(), and the contents of data are copied using memcpy().
Freeing: the data memory is freed. The Gal_Object is returned to the internal store of Gal_Objects.
Copying: a new object is created from the data array using Gal_BinaryObject.
See Gal_CreateBinaryObject for explicit memory management options.

Gal_Object Gal_CreateBinaryObject(void *data, int size, int manage_memory)
Gal_Object Gal_CreateInt16Object(void *data, int num_int_16, int manage_memory)
Gal_Object Gal_CreateInt32Object(void *data, int num_int_32, int manage_memory)
Gal_Object Gal_CreateInt64Object(void *data, int num_int_64, int manage_memory)
Gal_Object Gal_CreateFloat32Object(void *data, int num_float_32, int manage_memory)
Gal_Object Gal_CreateFloat64Object(void *data, int num_float_64, int manage_memory)
Converts the data, data, into an array object of the appropriate type (GAL_BINARY, GAL_INT_16, GAL_INT_32, GAL_INT_64, GAL_FLOAT_32, GAL_FLOAT_64), where size is the size of the data in elements. The data must be of the appropriate type (array of bytes, array of 16-bit integers, etc.), coerced to a void *. The resulting object is expandable using Gal_ArrayObjectAdd. If manage_memory is nonzero, data will be freed when the object is freed, otherwise not.

int Gal_ArrayObjectAdd(Gal_Object obj, void *data, int size)
Adds the data to the array object obj, where size is the number of elements of data. The obj can be of type GAL_BINARY, GAL_INT_16, GAL_INT_32, GAL_INT_64, GAL_FLOAT_32, or GAL_FLOAT_64.

Gal_Object Gal_CreateProxyObject(GalSS_BrokerProxy *p, int manage_memory)
Converts the broker proxy p into a GAL_PROXY object. If manage_memory is nonzero, p will be freed using the function GalSS_FreeBrokerProxy.

Gal_Object Gal_ProxyObject(GalSS_BrokerProxy *p)
Converts the broker proxy p into a GAL_PROXY object.

Memory management

Freeing: p will be freed using the function GalSS_FreeBrokerProxy. The Gal_Object is returned to the internal store of Gal_Objects.
Copying: a new proxy object is created using object is created from the data array GalSS_CopyBrokerProxy.using Gal_BinaryObject.

Object Free and Copy Functions

void Gal_FreeObject(Gal_Object obj);
Frees the object, obj, and its value.

Memory management
See the object creation functions for the behavior of objects when they're freed.

void _gal_free_object(void *obj)
Wrapper for Gal_FreeObject for use with functions where memory management is required, such as Gal_CreateListObject.

Gal_Object Gal_CopyObject(Gal_Object obj);
Copies the object, obj, and its value.

Memory management
See the object creation functions for the behavior of objects when they're copied. If one of the Gal_Create... functions has been used to create obj, then a "deep copy" is performed, and the new object contains a copy of the underlying data.

Type Checking Predicates

int Gal_Framep(Gal_Object obj);
Returns 1 if the object, obj, is a frame, of type GAL_FRAME.

int Gal_Clausep(Gal_Object obj);
Returns 1 if the object, obj, is a clause frame, of type GAL_CLAUSE_FRAME.

int Gal_ClauseFramep(Gal_Frame fr)
Returns 1 if the frame is of type GAL_CLAUSE.

int Gal_Stringp(Gal_Object obj);
Returns 1 if the object, obj, is a string, of type GAL_STRING.

int Gal_Intp(Gal_Object obj);
Returns 1 if the object, obj, is an integer, of type GAL_INT.

int Gal_Floatp(Gal_Object obj);
Returns 1 if the object, obj, is a float, of type GAL_FLOAT.

int Gal_Listp(Gal_Object obj);
Returns 1 if the object, obj, is a list, of type GAL_LIST.

int Gal_Binaryp(Gal_Object obj);
Returns 1 if the object, obj, is binary data, of type GAL_BINARY.

int Gal_Int16p(Gal_Object to)
Returns 1 if the object, to, is binary data, of type GAL_INT_16.

int Gal_Int32p(Gal_Object to)
Returns 1 if the object, to, is binary data, of type GAL_INT_32.

int Gal_Int64p(Gal_Object to)
Returns 1 if the object, to, is binary data, of type GAL_INT_64.

int Gal_Float32p(Gal_Object to)
Returns 1 if the object, to, is binary data, of type GAL_FLOAT_32.

int Gal_Float64p(Gal_Object to)
Returns 1 if the object, to, is binary data, of type GAL_FLOAT_64.

int Gal_Proxyp(Gal_Object obj)
Returns 1 if the object, obj, is a broker proxy object, of type GAL_PROXY.

Object Comparison Predicates

int Gal_ObjectEqual(Gal_Object obj1, Gal_Object obj2);
Returns 1 if the objects, obj1 and obj2, are equivalent. The table below lists the functions used for equivalence testing of each object type:

object type	equivalence function
GAL_FRAME	Gal_FrameEqual
GAL_STRING	strcmp
GAL_INT, GAL_FLOAT	==
GAL_LIST	recursive comparison using Gal_ObjectEqual; must match one-to-one (not in order)
GAL_BINARY, etc.	memcmp

int Gal_ObjectCaseEqual(Gal_Object obj1, Gal_Object obj2);
The same as Gal_ObjectEqual except that strings are compared with strcasecmp.

Object Value Extraction

Each of the supported types has an extraction function. If the object is not of the expected type, a warning is printed and NULL or zero is returned, as appropriate.

Memory management
None of these functions copy or free the contents of the Gal_Object; they just return the pointer which the Gal_Object contains. This is also true of Gal_UnwrapValue, which returns the Gal_Object structure to its internal store, but does not free the contents.

Gal_Frame Gal_FrameValue(Gal_Object to);
Extracts a frame from the object to. If the object is not of type GAL_FRAME, a warning is printed and NULL is returned.

Gal_Frame Gal_ClauseValue(Gal_Object to)
Extracts a frame of type GAL_CLAUSE from the object to. If the object is not of the appropriate type, a warning is printed and NULL is returned.

char *Gal_StringValue(Gal_Object to)
Extracts a string from the object to. If the object is not of type GAL_STRING, a warning is printed and NULL is returned. Also works for objects of type GAL_TOKEN, as a special case.

int Gal_IntValue(Gal_Object to)
Extracts an integer from the object to. If the object is not of type GAL_INT, a warning is printed and 0 is returned.

float Gal_FloatValue(Gal_Object to)
Extracts a float from the object to. If the object is not of type GAL_FLOAT, a warning is printed and 0 is returned.

Gal_Object *Gal_ListValue(Gal_Object obj, int *n)
Extracts an array of Gal_Objects (that is, a list) from the object to, and stores the length in n. If the object is not of type GAL_LIST, a warning is printed and 0 is returned.

void *Gal_BinaryValue(Gal_Object obj, int *size)
void *Gal_Int16Value(Gal_Object obj, int *size)
void *Gal_Int32Value(Gal_Object obj, int *size)
void *Gal_Int64Value(Gal_Object obj, int *size)
void *Gal_Float32Value(Gal_Object obj, int *size)
void *Gal_Float64Value(Gal_Object obj, int *size)
Returns the array data and sets size to the size of the data in elements, if the object is of the appropriate type.

GalSS_BrokerProxy *Gal_ProxyValue(Gal_Object o)
Extracts a broker proxy from the object o. If the object is not of type GAL_PROXY, a warning is printed and NULL is returned.

void Gal_FreeWrapper(Gal_Object to)
This function returns the Gal_Object wrapper to its internal store and detaches it from its internal value. It only frees the contents if the contents are a float pointer. It does not return the value.

List Object Operations

The following additional functions are provided for accessing GAL_LIST object elements:

int Gal_ListLength(Gal_Object obj)
Returns the length of the list.

Gal_Object Gal_GetListObject(Gal_Object obj, int n)
Returns the nth object in the list (counting from 0). Returns NULL if n is out of range. Returns obj if it is not a list.

Memory management
A pointer to the object in the list is returned, not a pointer to a copy of the object.

int Gal_SetListObject(Gal_Object obj, int n, Gal_Object elt)

If obj is a list at least n elements long, sets the nth location in obj to elt. Returns 1 if successful, 0 if not.

Memory management
The element currently in position n is dispensed with according to the memory management policies of the list obj.

int Gal_ListObjectExpandable(Gal_Object obj)
Returns 1 if obj is a list and is expandable, 0 otherwise.

Binary Object Operations

The following additional functions are provided for manipulating binary data.

int Gal_BinarySize(Gal_Object to)
int Gal_Int16Size(Gal_Object to)
int Gal_Int32Size(Gal_Object to)
int Gal_Int64Size(Gal_Object to)
int Gal_Float32Size(Gal_Object to)
int Gal_Float64Size(Gal_Object to)
Returns the number of elements of the array object, to, assuming it is of the appropriate type.

int Gal_ObjectByteCount(Gal_Object obj)
Returns the actual byte count for the object, obj, which can be GAL_STRING, GAL_BINARY, GAL_INT_16, GAL_INT_32, GAL_INT_64, GAL_FLOAT_32, GAL_FLOAT_64.

int Gal_ArrayObjectExpandable(Gal_Object obj)
Returns 1 if obj is an array object of type GAL_BINARY, GAL_INT_16, GAL_INT_32, GAL_INT_64, GAL_FLOAT_32, or GAL_FLOAT_64 and it is expandable, 0 otherwise.

Broker Proxy Operations

GalIO_BrokerStruct *Gal_ProxyObjectBroker(Gal_Object obj)
If obj is of type GAL_PROXY, returns the underlying broker object associated with the broker proxy. Otherwise, returns NULL.

Gal_ObjectType Gal_ProxyObjectType(Gal_Object obj)
If obj is of type GAL_PROXY, returns the underlying object type associated with the broker proxy. The type may be -1, which means that no type requirements have been imposed on this broker proxy. If obj is not of type GAL_PROXY, this function returns the type of obj.

Gal_Object Gal_ProxyObjectObject(Gal_Object obj)
If obj is of type GAL_PROXY, returns the underlying object being brokered by the broker proxy. This value may be NULL, if the broker proxy is being treated as a stream. If obj is not of type GAL_PROXY, returns NULL.

Frame Utilities

Frame to String Conversion

These functions are for converting frames and objects to strings for printing and for HUB-server communications. There are three forms:

Pr (print) functions generate space-separated tokens.

{c a_clause :topic {q the_topic :name "topic_name" :number 3 } }

PP (pretty-print) functions generate a human-readable format with line breaks and indentation.

{c a_clause

topic {q the_topic

:name "topic_name"

:number 3 } }

The outline function truncates the frame:

{c a_clause

:topic {q the_topic ... } }

Both the Pr and PP formats can be converted back to the original frames with Gal_ReadFrameFromString.
char *Gal_PrFrameToString(Gal_Frame fr, char *buf, int *bufsizeptr);
Converts a frame to Pr format.

Memory management
This function expands the buffer as necessary or will create a buffer if buf is NULL. If the buffer isreallocated, the new buffer is returned. Otherwise, the original buffer is returned.

char *Gal_PPFrameToString(Gal_Frame fr, char *buf, int *bufsizeptr);
Converts a frame to PP format.

Memory management
This function expands the buffer as necessary or will create a buffer if buf is NULL. If the buffer is reallocated, the new buffer is returned. Otherwise the original buffer is returned.

char *Gal_ObjectToString(Gal_Object to)
Converts an object to Pr format.

Memory management
A new string is returned.

enum {GAL_PP_PRINT, GAL_PR_PRINT};

char *Gal_PrintFrameToString(Gal_Frame fr, char *irpbuf, int *bufsizeptr, int how)
Converts a frame to a string according to the format specified by how (either GAL_PP_PRINT or GAL_PR_PRINT). Other arguments are as for Gal_PPFrameToString or Gal_PrFrameToString.

void Gal_PrintFrameToFile(Gal_Frame fr, FILE *fp, int how)
Writes a frame to a file according to the format specified by how (either GAL_PP_PRINT or GAL_PR_PRINT).

void GalUtil_PrintObject(int gal_verbose_level, Gal_Object to, int how)
Prints a printable representation of the object on standard output according to the format specified by how (either GAL_PP_PRINT or GAL_PR_PRINT), if GAL_VERBOSE exceeds gal_verbose_level.

Frame Printing Functions

The following functions use Gal_PrFrameToString and Gal_PPFrameToString to convert the frame, then print to the specified output device, and analogously for objects.

void Gal_PrFrame(Gal_Frame fr);
Prints the contents of the frame, fr, to standard output.

void Gal_PrObject(Gal_Object obj);
Prints the object, obj, to standard out.

void Gal_PPFrame(Gal_Frame fr);
Pretty prints the contents of the frame, fr, to standard output.

void Gal_PPObject(Gal_Object to)
Pretty prints the contents of the object, to, to standard output.

voidGal_PrObjectToFile(Gal_Object obj, FILE *fp);
Prints the object, obj, to a file.

void Gal_PPObjectToFile(Gal_Object to, FILE *fp)
Pretty prints the contents of the object, to, to the file fp.

void GalUtil_PrObject(int sls_verbose_level, Gal_Object to)
Prints the object, to, using sls_verbose_level.

void GalUtil_PPFrame(int sls_verbose_level, Gal_Frame fr)
Pretty prints the frame, fr, using sls_verbose_level.

void GalUtil_PPObject(int sls_verbose_level, Gal_Object to)
Pretty prints the object, to, using sls_verbose_level.

void GalUtil_CPPFrame(int sls_verbose_level, int fore, int back, Gal_Frame fr)
Pretty prints the frame, fr, using sls_verbose_level, using embedded color Xterm directives.

void GalUtil_CPPObject(int sls_verbose_level, int fore, int back, Gal_Object to)
Pretty prints the object, to, using sls_verbose_level, using embedded color Xterm directives.

void Gal_PrFrameToFile(Gal_Frame fr, FILE *fp);
Prints the contents of the frame, fr, to a file or stream.

void Gal_PPFrameToFile(Gal_Frame fr, FILE *fp);
Pretty prints the contents of the frame, fr, to a file or stream.

void Gal_OutlineFrame(Gal_Frame fr, int sls_verbose_level);
Prints a truncated frame to standard output.

void Gal_OutlineObject(Gal_Object to, int sls_verbose_level)
Prints a truncated object to standard output.

Frame Reading Functions

These functions read frames or objects from strings and files.

Note: the keys :pred and :PRED are special to these functions when converting strings to frames. For unavoidable historical reasons, their values are treated as elements of the list of predicate frames associated with each frame. This list of predicates is used extensively by MIT, but has no function in the general Galaxy Communicator infrastructure. These two keys, therefore, should be avoided.

Gal_Frame Gal_ReadFrameFromString(const char *buf);
This function creates a frame from Pr or PP format.

Gal_Object Gal_ReadObjectFromString(const char *buf)
This function creates a Gal_Object from either format.

Gal_Frame Gal_ReadFrameFromFile(FILE *fp)
Reads a frame from the file pointed to by fp.

Gal_ObjectGal_ReadObjectFromFile(FILE *fp)
Reads an object from a file.

Gal_Frame Gal_VAReadVarFrameFromString(const char *buf, int num_pairs, ... )
This function reads a frame from a string. The frame may contain values of the form $..., which indicates a variable. These variables may be values of keys, or elements of lists, and may appear arbitrarily deep. The num_pairs are the number of variable mappings which appear as variable arguments. The first element of each pair is a string whose first character is $, and the second element is a Gal_Object. So for example, the invocation

Gal_Object o1 = Gal_StringObject("bar"); Gal_Object o2 =Gal_IntObject(5);

Gal_VAReadVarFrameFromString("{c foo :string $a :int ( $b ) }", 2,
"$a", o1, "$b", o2); Gal_FreeObject(o1); Gal_FreeObject(o2);

yields the frame

{c foo :string "bar" :int ( 5 ) }

Memory management
When variables are matched in the frame, the object value is copied and substituted. So there will never be multiple references to the same instance, and no assumption is made about whether a particular variable will match or not. This means that it's the programmer's responsibility to manage the memory for the elements passed in. As shown in the example, this can mean ensuring that all objects which are created are freed.

Gal_VarMapping * Gal_CreateVarMapping(int num_pairs, ... )
Gal_Frame Gal_ReadVarFrameFromString(const char *buf, Gal_VarMapping *map)
An alternative means of incorporating variables. The map should be freed after being created and used, using free. The memory management comments for Gal_VAReadVarFrameFromString still apply.

Gal_Object Gal_VAReadVarObjectFromString(const char *buf, int num_pairs, ... )
Identical to Gal_VAReadVarFrameFromString, but reads a Gal_Object from buf instead of a frame.

Gal_Object Gal_ReadVarObjectFromString(const char *buf, Gal_VarMapping *map)
Identical to Gal_ReadVarFrameFromString, but reads a Gal_Object from buf instead of a frame.

MIT Linguistic Frame Tools

In the MIT Galaxy system, frames are used as interpretations of natural language utterances as well as general-purpose attribute-value structures. As interpretations of natural language utterances, the different frame types have the following form and purpose:

Clause frames correspond to sentences, and typically have a :topic key-value pair (typically filled by a topic frame) and a :pred key-value pair (filled by a predicate frame). The topic corresponds to the subject of the sentence, and a single element in the predicate list which corresponds to the verb phrase. Manipulating the predicate list is different than setting the value of a key named :pred, but since the frame encoder/decoder treats these as the same thing, it only makes a difference within a single program.
Topic frames correspond to noun phrases. They may have one or more predicates, which correspond to modifiers (adjective phrases, prepositional phrases).
Predicate phrases correspond to predicates of all sorts: modifiers (adjective phrases, prepositional phrases, adverbial phrases) and verb phrases. These phrases may have predicates themselves, and may also have a :topic key-value pair (typically filled by a topic frame) which corresponds to the internal argument (the object of the verb or preposition, for instance).

General Utilities

Gal_Frame Gal_MakeTopicFrame(const char *name)
Gal_Frame Gal_MakePredFrame(const char *name)

Creates a frame of the specified type. See Gal_MakeFrame.

int Gal_Topicp(Gal_Object obj);
Returns 1 if the object, obj, is a topic frame, of type GAL_TOPIC_FRAME.

intGal_Predp(Gal_Object obj);
Returns 1 if the object, obj, is a predicate frame, of type GAL_PRED_FRAME.

int Gal_TopicFramep(Gal_Framefr)
int Gal_PredFramep(Gal_Frame fr)
Returns 1 if the frame is of the appropriate frame type.

Gal_Frame Gal_TopicValue(Gal_Object to)
Gal_Frame Gal_PredValue(Gal_Object to)
Extracts a frame of the appropriate type from the object to. If the object is not of the appropriate type, a warning is printed and NULL is returned.

Frame Searching Functions

Gal_Object Gal_FindKey(Gal_Frame fr, const char *key_name);
Recursively searches the frame and its contents for the key specified by key_name, using the normal property list and predicate list operations. If found, the corresponding object is returned.

Gal_Object Gal_MatchKeyValue(Gal_Frame fr, const char *key_name, Gal_Object match);
Recursively searches the frame and its contents for the key specified by key_name, using the normal property list and predicate list operations. If found, the object is compared with match using Gal_ObjectEqual. If the objects match, the corresponding object is returned.

Gal_Frame Gal_FindPred(Gal_Frame fr, const char *pred_name);
Recursively searches the frame for a predicate with name pred_name, using the normal property list and predicate list operations. If found, the predicate frame is returned.

Gal_Frame Gal_FindPredParent(Gal_Frame frame, const char *name, Gal_Frame parent, int findpar, int nth);
Recursively searches for a predicate with the specified name, name, using the normal property list and predicate list operations. The parent of the first predicate found is returned.

Gal_Frame Gal_FindTopic(Gal_Frame fr, const char *topic_name);
Recursively searches the frame for a topic with name topic_name, using the normal property list and predicate list operations. If found, the topic frame is returned.

void Gal_DeletePreds(Gal_Frame fr, const char *pred_name);
Recursively searches the frame for predicates with name pred_name , removes the predicate from the frame using Gal_RemPredByName, and deletes the predicate using Gal_FreeObject.

Predicate List Operations

int Gal_NumPreds(Gal_Frame fr);
Returns the number of predicates in the predicate list.

Gal_Frame Gal_AddPred(Gal_Frame fr, Gal_Frame pred);
Creates a Gal_Object from pred using Gal_FrameObject and adds the object to the predicate list in the frame, fr. The frame must be of type GAL_PRED.

Gal_Frame Gal_GetPred(Gal_Frame fr, int i);
Retrieves a predicate frame from the predicate list of fr by its index, specified by i.

Memory management
The retrieved element is the element in fr, not a copy.

Gal_Frame Gal_GetPredByName(Gal_Frame fr, const char *name);
Retrieves a predicate frame from the predicate list of fr by its name, specified by name.

Memory management
The retrieved element is the element in fr, not a copy.

Gal_ObjectGal_RemPred(Gal_Frame fr, int i);
Removes a predicate from the predicate list of fr by its index, i, and returns it.

Memory management
The retrieved element is the element from fr, not a copy.

Gal_Object Gal_RemPredByName(Gal_Frame fr, const char *name);
Removes a predicate from the predicate list by its name, name, and returns it.

Memory management
The retrieved element is the element from fr, not a copy.

void Gal_DelPred(Gal_Frame fr, int i);
Removes a predicate from the predicate list by its index, i, and frees it using Gal_FreeObject.

void Gal_DelPredByName(Gal_Frame fr, const char *name);
Removes a predicate from the predicate list by its name, name, and frees it using Gal_FreeObject.

void Gal_ClearPreds(Gal_Frame fr);
Clears the predicate list of fr and frees all predicate objects using Gal_FreeObject.

void Gal_DoPreds(Gal_Frame fr, int (*pred_fn)(Gal_Object , void *), void *caller_data)
Applies the function pred_fn to all the predicates in the frame fr. The first argument of pred_fn will be a Gal_Object containing a frame which is the predicate; caller_data is passed as the second argument of pred_fn. The pred_fn should return 1 to continue, 0 to halt.

Deprecated functions

These functions will be removed in the next major release.

void *Gal_GetListValue(Gal_Object to, int n, Gal_ObjectType type)
Calls Gal_GetListObject, ensures the result is of the type type, and returns the contents of the object as a void *. If the element is not of the appropriate type, NULL is returned. Use of this function is strongly discouraged.

License / Documentation home / Help and feedback

Last updated August 23, 2002

Galaxy Communicator Documentation: Frames, Property Lists, and Typed Objects

Frames and Objects

Frame Subtypes

Frame Syntax

Examples

Object Types

Object syntax

Examples

Frame Functions

Frame Create, Free, and Copy Functions

Memory management

Memory management

Memory management

Frame Comparison Predicates

Frame Name and Type Operations

Memory management

Memory management

Property Lists

Property List Operations

Memory management

Memory management

Memory management

Memory management

Miscellaneous Functions

Memory management

Typed Object Functions

Memory management

Memory management

Object Creation Functions

Memory management

Memory management

Memory management

Memory management

Memory management

Memory management

Memory management

Object Free and Copy Functions

Memory management

Memory management

Type Checking Predicates

Object Comparison Predicates

Object Value Extraction

Memory management

List Object Operations

Memory management

Memory management

Binary Object Operations

Broker Proxy Operations

Frame Utilities

Frame to String Conversion

Memory management

Memory management

Frame Printing Functions

Frame Reading Functions

Memory management

MIT Linguistic Frame Tools

General Utilities

Frame Searching Functions

Predicate List Operations

Memory management

Memory management

Memory management

Memory management

Deprecated functions

Galaxy Communicator Documentation:

Frames, Property Lists, and Typed Objects