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:
- Before the object is about to be destroyed.
- On sgs_ObjCallDtor
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:
- On A[B] (index) and A.B (property) reads in SGScript.
- Index/Property/Path function families in the C API.
Additional arguments:
- object argument (see sgs_ObjectArg) -- (0/1) whether this is a property read (1) or index read (0)
Stack frame:
- Item 0 - key variable to be used to find a sub-item.
- Expected to have at least one item on stack after a successful index/property read. The topmost one is used.
Return values:
- Non-negative value if successful, negative on error.
- Use SGS_ENOTFND if the specified index/property was not found.
Additional notes:
It is safe to use conversion functions on the key variable.
SETINDEX - index/property setting callback
When called:
- On A[B] (index) and A.B (property) writes in SGScript.
- Index/Property/Path function families in the C API.
Additional arguments:
- sgs_Variable* key -- key variable to be used to find a sub-item
- sgs_Variable* value -- value variable to be used in setting the value of the sub-item
- object argument (see sgs_ObjectArg) -- (0/1) whether this is a property read (1) or index read (0)
Stack frame:
- Item 0 - key variable to be used to find a sub-item.
- Item 1 - value variable to be used in setting the value of the sub-item.
Return values:
- Non-negative value if successful, negative on error.
- Use SGS_ENOTFND if the specified index/property was not found.
- Use SGS_EINVAL if the given value could not be used.
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:
- type conversion: to*** function families and other conversion triggers (like operators) in SGScript and the Get/To/Parse function families in the C API.
- SGS_CONVOP_CLONE: called on clone / sgs_Clone
- SGS_CONVOP_TOITER: called on foreach / sgs_PushIterator / sgs_GetIterator
Additional arguments:
- int type -- one of SGS_VT_[BOOL|STRING] or SGS_CONVOP_CLONE / SGS_CONVOP_TOITER
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:
- type conversions require a value of the right type.
- SGS_CONVOP_CLONE should return an exact copy of the same object
- SGS_CONVOP_TOITER should return an object with a GETNEXT callback
Return values:
- Non-negative value if successful, negative on error.
- Use SGS_ENOTSUP if specified conversion is not supported.
Additional notes:
- It should be safe to give the wrong variable type but errors may not be triggered in such cases.
SERIALIZE - serialization callback
When called:
- serialize in SGScript.
- sgs_Serialize(Ext) in the C API.
Additional arguments:
None.
Stack frame:
Empty.
Return values:
- Non-negative value if successful, negative on error.
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:
- printvar, dumpvar, printvar_ext, dumpvar_ext in SGScript.
- sgs_DumpVar in the C API.
Additional arguments:
- int maxdepth -- remaining recursion depth of dump to be passed on to sgs_DumpVar calls.
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:
- Non-negative value if successful, negative on error.
Additional notes:
- Callback expects a string variable on the top of the stack.
- sgs_DumpVar with maxdepth <= 0 returns "...", so it is not necessary to handle such cases beyond passing the parameter.
GCMARK - garbage collector marking callback
When called:
- gc_collect in SGScript.
- sgs_GCMark / sgs_GCExecute in the C API.
Additional arguments:
None.
Stack frame:
Empty.
Return values:
- Non-negative value if successful, negative on error.
Additional notes:
- Callback expects that sgs_GCMark is called on all of the owned variables.
- It is important to minimize the possibility of failure here. The system cannot help in any way if memory or ownership states are corrupted.
GETNEXT - iterator control callback
When called:
- foreach in SGScript.
- sgs_IterAdvance / sgs_IterPushData / sgs_IterGetData
Additional arguments:
- int act -- specifies the actions that should be taken in this call.
- if argument == 0, iterator's position must be increased by one step and the return value must contain whether iterator has not reached end (positive value if so, otherwise - 0) or an error if callback has failed
- otherwise, callback must push the data required (if SGS_GETNEXT_KEY is set, the key, and if SGS_GETNEXT_VALUE is set - the value, in exactly that order)
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:
- Non-negative value if successful, negative on error.
- if argument == 0, must return whether iterator has not reached end (positive value if so, otherwise - 0)
Additional notes:
None.
CALL - the "function call" callback
When called:
- when an object is used like a function
object_variable( .. )in SGScript- Call function family in the C API
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:
- Non-negative value if successful, negative on error.
- On success, the number returned is the number of variables returned by the function.
Additional notes:
None.
EXPR - expression callback
When called:
- On arithmetic operations with the object as one or both operands in SGScript.
- On sgs_ArithOp in the C API.
Additional arguments:
- sgs_Variable* A - the first (left side) operand or the only one in case of SGS_EOP_NEGATE
- sgs_Variable* B - the second (right side) operand or NULL in case of SGS_EOP_NEGATE
- int op - operation type, one of SGS_EOP_[ADD|SUB|MUL|DIV|MOD|COMPARE|NEGATE]
Stack frame:
Empty at beginning. Expects at least one variable on success (the topmost one will be used).
Return values:
- Non-negative value if successful, negative on error.
Additional notes:
- SGS_EOP_COMPARE expects int/real value: >0 if A > B, <0 if A < B, =0 if A = B
The full list of operators triggering the operations:
- SGS_EOP_ADD: binary +, +=
- SGS_EOP_SUB: binary -, -=
- SGS_EOP_MUL: *, *=
- SGS_EOP_DIV: /, /=
- SGS_EOP_MOD: %, %=
- SGS_EOP_COMPARE: <, <=, >, >=, ==, !=, ===, !==
- SGS_EOP_NEGATE: unary -