LibObj/Reference

LibObj Base - Object Handles

Interface 

integer objNew()
objDelete(integer id)

Guarantees

Assumptions

Description

LibObj has a simple representation of "objects" as handles which are of type integer. Objects may be created and deleted using the "Object Base" module consisting of the functions objNew and objDelete. All handles returned by objNew() are unique within the script at any given point in time and positive (> 0). By themself, handles have little use but are instead intended to be used in combination with any of the extensions described below to associate additional data with the objects.

Important: In addition to deleting the object handle, the objDelete function also needs to call additional functions to delete any data associated with the object managed by the used extensions. Keep this in mind and make sure that all deletion function calls corresponding to the extensions you're using are included in the implementation of objDelete.

Example 

integer a = objNew(); // Create a new object.
objDelete(a); // Delete it again.

"Names" Extension

Interface 

integer objSetName(integer id, string name)
string  objGetName(integer id)
integer objByName(string name)

Guarantees

Assumptions

Description

The purpose of this extension is to address objects by name. Using the objSetName function of the names extension you can assign a name to an object. The main use of this extension is to look up objects by name using objByName. Once an object handle is retrieved, further operations may be performed on it. The objByName function returns 0 if an object with the given name is not found. Note that arbitrary data should generally not be stored as an object name; use the "data" or "properties" extensions for that purpose.

Example 

integer a = objNew(); // Create a new object.
objSetName(a, "A"); // Assign name to object.
llOwnerSay(objGetName(a)); // Says "A".
integer b = objByName("A"); // b == a.
objDelete(b); // Deletes the object.

"Paths" Extension

Interface 

integer objSetPath(integer id, list path)
list    objGetPath(integer id)
string  objGetPathItem(integer id, integer item)
integer objByPath(list path)

Guarantees

Assumptions

Description

The purpose of this extension is to address objects in a hierarchical (tree-like) manner. It is a generalization of the "names" extensions with more possibilities. Instead of assigning an object a single string as name, a multi-element list ("path") of names may be given. This principle may be used to group objects of a specific "type" by giving them a common prefix (for instance the first item in the path list). The objByPath function to retrieve an object handle by path does not require the whole path to match but instead returns the first object whose path prefix matches the given list.

Note: All elements of a given path are converted to strings and no path element shall contain a newline ("\n") character.

Example 

integer a = objNew(); // Create a new object.
integer b = objNew(); // Create another object.
objSetPath(a, ["X"]); // Assigns path to object a.
objSetPath(b, ["X", "Y"]); // Assigns path to object b.
integer x = objByPath(["X"]); // x == a.
integer y = objByPath(["X", "Y"]); // y == b.
llOwnerSay(objGetPathItem(x, 0)); // Says "X".
llOwnerSay(objGetPathItem(y, 1)); // Says "Y".
objDelete(x); // Deletes x (and a).
objDelete(y); // Deletes y (and b).

"Data" Extension

Interface 

integer objSetData(integer id, string data)
string  objGetData(integer id)

Guarantees

Assumptions

Description

The purpose of this extension is to assign a (string) payload to an object. It is similar to the "names" extension but does not include the capability to retrieve objects given a string. It is suitable to store possibly unsafe user data related to an object.

Example 

integer a = objNew(); // Create a new object.
objSetData(a, "Payload"); // Assign string data to object.
llOwnerSay(objGetData(a)); // Says "Payload".
objDelete(a); // Deletes the object.

"Properties" Extension

Interface 

integer objSetProp(integer id, string prop, string data)
string  objGetProp(integer id, string prop)

Guarantees

Assumptions

Description

The purpose of this extension is to assign named properties to an object. It is a generalization of the "data" extension in that it allows to assign multiple separate string payloads to a single object. The idea is to simulate the concept of e.g. "structs" or "dictionaries" in other languages.

Example 

integer a = objNew(); // Creates a new object.
objSetProp(a, "A", "X"); // Add property "A" with content "X".
objSetProp(a, "B", "Y"); // Add property "B" with content "Y".
objSetProp(a, "A", "Z"); // Replace content of property "A" with "Z".
llOwnerSay(objGetProp(a, "A")); // Says "Z".
objDelete(a); // Delete the object.

"Hierarchy" Extension

Interface 

integer objSetParent(integer id, integer parent)
integer objGetParent(integer id)
integer objGetChild(integer id)
list    objGetChildren(integer id)

Guarantees

Assumptions

Description

The purpose of this extension is to define "child-parent" relationships between objects which allows to build object hierarchies (without common, redundant name prefixes as with the "path" extension). An object may have one parent object specified using the objSetParent function. Conversely, an object obj may have multiple (implicitly defined) children which is the set of objects whose parent is obj. The function objGetChild returns the first child for a given object; the function objGetChildren may be used to get a list of all children of an object (a list of object handles).

Example 

integer a = objNew(); // Create object a.
integer b = objNew(); // Create object b.
integer c = objNew(); // Create object c.
objSetParent(b, a); // Set parent of object b to a.
objSetParent(c, a); // Set parent of object c to a.
list children = objGetChildren(a); // children == [b, c].
integer child = objGetChild(a); // x == b or x == c, implementation dependent.
while (child = objGetChild(a)) {objDelete(child);} // Delete children (b, c).
objDelete(a); // Delete remaining object.

Object Timeouts

Interface 

integer objSetTimeout(integer id, integer time)
integer objCheckTimeout()

// Minimal timer event for handling timeouts:
timer() {
    integer obj;
    while (obj = objCheckTimeout()) {
        // Do something with obj.
        
        // Finally, you should either disable the timeout for the object
        // by calling objSetTimeout(obj, 0) or delete the object.
        objDelete(obj);
    }
}

Guarantees

Assumptions

Description

The purpose of this extension is to set independent timeouts for objects which are handled asynchronously by a timer event at a later point in time.

Example 

integer a = objNew(); // Create a new object.
objSetTimeout(a, 5); // Timeout handle will trigger in approximately 5 seconds in timer event.