LibObj/Reference

LibObj Base - Object Handles

Interface

integer objNew()
objDelete(integer id)

Guarantees

• The handle returned by objNew is positive (> 0).
• The handle returned by objNew is unique among all handles existing at the moment the function is called.
• objDelete does nothing if the given handle id does not exist.

Assumptions

• The implementation of objDelete should include calls to suitable functions of any used extensions to delete data associated with the given object.

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

• objSetName returns the given object handle, even if invalid.
• objSetName removes the name if name == "".
• If a name for the given object already exists, objSetName replaces that name.
• objByName returns 0 if an object with the given name does not exist.

Assumptions

• No particular 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

• objSetPath returns the given object handle, even if invalid.
• objSetPath removes the path if path == [].
• If a path for the given object already exists, objSetPath replaces it.
• objByPath returns 0 if the given path does not match any object.

Assumptions

• All elements of paths are automatically converted to the string data type.
• No element of valid paths should contain the newline character ("\n").

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

• objSetData returns the given object handle, even if invalid.
• objSetData removes any existing data for the given object if data == "".
• objGetData returns the empty string ("") if no data is associated with the given object.

Assumptions

• No particular 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

• objSetProp returns the given object handle, even if invalid.
• objSetProp removes all properties of the given object if prop == "".
• objSetProp removes a given property "X" if prop == "X" and data == "".
• objGetProp returns the empty string ("") if the given object or property does not exist.

Assumptions

• No particular 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

• objSetParent returns the given object handle, even if invalid.
• objSetParent removes the parent relation for the given object if parent == 0.
• objGetChild returns 0 if the given object has no children.
• objGetChildren returns the empty list ([]) if the given object has no children.

Assumptions

• If non-zero, the parent object given to objSetParent shall be a handle to an existing object.
• The objDelete function should take care of setting the parent of children of the object being deleted to 0.

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

• objSetTimeout returns the given object handle, even if invalid.
• Timeout is removed by objSetTimeout if time <= 0

Assumptions

• The temporal resolution of timeouts are relatively coarse (seconds).
• The timeout mechanism should not be used for high frequency timers.

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.