SGScript docs - object interface

# Object interface [info]

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:

- sgs_Variable* key -- key variable to be used to find a sub-item
- int isprop -- (0/1) whether this is a property read (1) or index read (0)

==== Stack frame:

Empty at beginning. 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
- int isprop -- (0/1) whether this is a property read (1) or index read (0)

==== Stack frame:

Empty.

==== 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_TYPEOF: called on @typeof / @sgs_TypeOf
- SGS_CONVOP_TOITER: called on foreach / @sgs_PushIterator(P) / @sgs_GetIterator(P)

==== Additional arguments:

- int type -- one of SGS_VT_[BOOL|INT|REAL|STRING|PTR] or SGS_CONVOP_CLONE / SGS_CONVOP_TYPEOF / 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_TYPEOF should return a string containing the type name
- 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 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(P) / @sgs_IterPushData(P) / @sgs_IterGetData(P)

==== 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 -