Class: Frame

Frame provides two basic capabilities: structure and inheritance. The synergy between these two features, as well as their use within the Livelink Scripting Framework, provides developers with many powerful capabilities.

In its most basic form, a Frame consists of a set of named slots. Each slot can contain a single value and can be referenced with the dot operator. Thus, a Frame is the equivalent of a structure in most programming languages. A frame's slots are identified with a String and cannot be accidentally created (e.g., due to a typo) during an assignment. In addition, referencing a slot that does not exist will produce a runtime exception, rather than returning an Undefined value. There are operations in the Frame class that permit a Frame's structure to be examined and even modified.

In addition to the structuring mechanisms described above, Frame has the additional ability to have special slots, parent slots, which affect how slots are looked up within a Frame. A parent slot acts like a normal slot, except that it cannot be assigned to. In addition, when a Frame's slot is referenced with a dot operator (e.g., myFrame.someSlot), the presence of one or more parent slots can affect how and where the slot is used.

When a frame dot expression occurs on the left side of an assignment (i.e., an lvalue), then the following steps occur:

1. If the slot exists in the Frame, then its value is replaced with the result of the assigned value.

2. If the slot does not exist in the Frame, then the parent slots are searched in definition order for the specified slot name.

   1. If not found, then an error is reported in the same way that any nonexistent slot would be handled.
   2. If the slot does exist in a parent frame, then a slot with the specified name is created in the lvalue frame and is assigned the value of the right-hand-side of the assignment expression.

When a frame dot expression occurs in any other context where its value is desired (i.e., an rvalue), then the following steps occur:

1. If the slot exists in the Frame, then its value is returned as the result of the expression.

2. If the slot does not exist in the Frame, then the parent slots are searched in definition order for the specified slot name.

   1. If not found, then an error is reported in the same way that any nonexistent slot would be handled.
   2. If the slot does exist in a parent frame, then the value of the parent's is returned as the result of the expression.

In other words, Frame behaves as a prototype-based object (similar to OSpace's ObjRef datatype). Frame has the following advantages compared to ObjRef:

• The ability to have a Destructor slot which is executed prior to deleting the object.
• Multiple, ordered parents, instead of just a single one.
• More efficient at performing feature lookups.
• Parents can be any OScript datatype that can be dotted.

Frame has some shortcomings with respect to ObjRef:

• Persistence is not built in.
• Circular references can possibly lead to memory leaks.

If inheritance is ignored, both Frame and Assoc share certain features that make them amenable to being used to build structures within the OScript environment. Assoc values can have arbitrary keys of any datatype, whereas Frames must have named slots of type String. In addition, Assoc is most useful when the structure is extremely dynamic and where keys may need to be added at any time. Frame is more useful for safety and debugging because references to incorrectly typed slot names will be cause an error during testing and debugging, rather than continuing with possibly erroneous results. Of course, Assoc is also very useful when it is used for the purpose for which it was designed, as an Associative array. Assoc can efficiently map between arbitrary keys (of any datatype) and their associated values.

Using Destructor

If a slot named "Destructor" is available on the Frame or its parents, and that slot's value is executable, then the slot will be invoked when the Frame is destroyed. Note that the Frame will still exist during the execution of Destructor(), and if the refcount of the Frame has increased during Destructor(), then the frame will NOT be deleted. Be careful with this feature.

Circular References

Livelink values use a simple reference-counting scheme to determine when an unused value can be deleted. Powerful datatypes such as Assoc and Frame both share the unfortunate characteristic that it is possible to create cyclic data structures whose values can never be deleted automatically. Please be careful, as this can result in memory leaks and other even nastier side effects.

Example

Here is an example of using Frame.New() to create a frame representing a 3D coordinate:

    Frame   coordinateProto = Frame.New( {}, { { "x", 0 }, { "y", 0 }, { "z", 0 } } )
    Frame   aCoordinate = Frame.New( { { "parentCoordinate", coordinateProto } }, \
                { { "x", 5 } } )

    echo( coordinateProto.x )
    echo( coordinateProto.y )
    echo( coordinateProto.z )
    echo( aCoordinate.x )
    aCoordinate.x = 55
    echo( aCoordinate.x )
    coordinateProto.x = 10
    echo( aCoordinate.x )
    coordinateProto.y = 10
    echo( aCoordinate.y )
    aCoordinate.y = 100
    echo( aCoordinate.y )
    echo( coordinateProto.zzzz )        // runtime error. feature not found exception.

The output from the above is:

    0
    0
    0
    5
    55
    55      // Changing the value of the proto slot doesn't change the child's slot
    10      // Changing the value of the parent slot does change the child's inherited slot
    100 // Child's override hides parent's value.