Object interface

Every interface function has the type int ObjCallback ( sgs_Context* C, sgs_VarObj* data, ... ). Not every of them has to be implemented (none of them are required) but for all non-pointer objects it helps to have at least one of them.

Interface is a structure that contains of an array and 10 function pointers in the following order: destruct, gcmark, getindex, setindex, convert, serialize, dump, getnext, call, expr. This is how interfaces are usually defined in code:

sgs_ObjInterface object_interface[1] =
{{
    "object_type_name",
    object_destruct, NULL,  /* destruct, gcmark */
    object_getindex, NULL,  /* getindex, setindex */
    NULL, NULL, NULL, NULL, /* convert, serialize, dump, getnext */
    NULL, NULL              /* call, expr */
}};

The interface is defined as an array with size=1 to later be able to use it in code without prepending "&" to the name.

DESTRUCT - destruction callback

When called:
Additional arguments:

None.

Stack frame:

Empty.

Return values:

Non-negative value if successful, negative on error.

Additional notes:

It is important to minimize the possibility of failure here. The system cannot help in any way if memory or ownership states are corrupted.

GETINDEX - index/property retrieval callback

When called:
Additional arguments:
Stack frame:
Return values:
Additional notes:

It is safe to use conversion functions on the key variable.

SETINDEX - index/property setting callback

When called:
Additional arguments:
Stack frame:
Return values:
Additional notes:

It is safe to use conversion functions on both variables.

CONVERT - conversion callback

When called:

Depending on the argument, it is called by different sources:

Additional arguments:
Stack frame:

Empty at beginning. Expected to have at least one item on stack after a successful conversion. The topmost one is used.

Depending on the argument, it requires different variable types on stack:

Return values:
Additional notes:

SERIALIZE - serialization callback

When called:
Additional arguments:

None.

Stack frame:

Empty.

Return values:
Additional notes:

Callback requires no data but expects that sgs_Serialize / sgs_SerializeObject is successfully called once. In the case of sgs_SerializeObject, the necessary number (equal to argument count, passed to the function) of sgs_Serialize calls must be made before it.

DUMP - debug dump callback

When called:
Additional arguments:
Stack frame:

Empty at beginning. Expected to have at least one item on stack after a successful conversion. The topmost one is used.

Return values:
Additional notes:

GCMARK - garbage collector marking callback

When called:
Additional arguments:

None.

Stack frame:

Empty.

Return values:
Additional notes:

GETNEXT - iterator control callback

When called:
Additional arguments:
Stack frame:

Empty at beginning. Expects at least one (if either flag is set, but not both) or two (if both flags are set) variables on success. Key first, value second.

Return values:
Additional notes:

None.

CALL - the "function call" callback

When called:
Additional arguments:

None.

Stack frame:

Contains all the same things as any C function call would: optional this variable and optional argument list. Expects at least the returned number of items after the call to be used as return values.

Return values:
Additional notes:

None.

EXPR - expression callback

When called:

Additional arguments:
Stack frame:

Empty at beginning. Expects at least one variable on success (the topmost one will be used).

Return values:
Additional notes:

The full list of operators triggering the operations: