SGScript - all C API functions (with some overlap)

# Context management [info]

@sgs_CreateEngine - create scripting engine context
@sgs_CreateEngineExt - create scripting engine context and pass a custom memory function
@sgs_DestroyEngine - validate memory statistics and destroy engine context
@sgs_DefaultMemFunc - example memory management callback
@sgs_GetOutputFunc - return the current output callback and its user data pointer
@sgs_SetOutputFunc - set the output callback and its user data pointer
@sgs_GetMsgFunc - return the current messaging callback and its user data pointer
@sgs_SetMsgFunc - set the messaging callback and its user data pointer
@sgs_Cntl - set and/or retrieve various states in the system


# Memory management [info]

@sgs_DefaultMemFunc - example memory management callback
@sgs_Memory - allocate/reallocate/free memory
@sgs_Malloc - allocate specified amount of memory
@sgs_Free - free a previously allocated memory pointer
@sgs_Realloc - allocate/reallocate/free memory (requires implicit sgs_Context* C)
@sgs_Alloc - allocate object (requires implicit sgs_Context* C)
@sgs_Alloc_n - allocate an array of objects (requires implicit sgs_Context* C)
@sgs_Alloc_a - allocate object + additional memory (requires implicit sgs_Context* C)
@sgs_Dealloc - free a previously allocated memory pointer (requires implicit sgs_Context* C)


# Input / output [info]

@sgs_GetOutputFunc - return the current output callback and its user data pointer
@sgs_SetOutputFunc - set the output callback and its user data pointer
@sgs_Write - pass a character buffer to the output callback
@sgs_Writef - pass a formatted string to the output callback
@sgs_WriteStr - pass a null-terminated string to the output callback
@sgs_GetMsgFunc - return the current messaging callback and its user data pointer
@sgs_SetMsgFunc - set the messaging callback and its user data pointer
@sgs_Msg - invoke the messaging system
@sgs_WriteErrorInfo - write message info to output callback
@sgs_PushErrorInfo - push message info to stack
@sgs_HasFuncName - check if current C function has a name set
@sgs_FuncName - set current C function name
@SGSFN - set current C function name
@SGSBASEFN - set current C function name if it's not already set
@sgs_Errno - copy errno to internal errno if 2nd argument is false, otherwise clear it
@sgs_SetErrno - set the internal errno value
@sgs_GetLastErrno - return the currently set internal errno value
@sgs_StdOutputFunc - example output callback
@sgs_StdMsgFunc_NoAbort - example messaging callback that does not abort on errors
@sgs_StdMsgFunc - example messaging callback
@sgs_Cntl - set and/or retrieve various states in the system
@sgs_ArgErrorExt - emit an argument type mismatch error with additional formatting options
@sgs_ArgError - emit an argument type mismatch error
@sgs_FuncArgError - emit an argument type mismatch error (alias for states where `this` variable is hidden)
@sgs_MethodArgError - emit an argument type mismatch error (alias for states where `this` variable is NOT hidden)


# Code handling [info]

@sgs_ExecBuffer - execute a character buffer
@sgs_EvalBuffer - execute a character buffer, keep returned variables on stack
@sgs_ExecFile - execute a file
@sgs_EvalFile - execute a file, keep returned variables on stack
@sgs_ExecString - execute a null-terminated string
@sgs_EvalString - execute a null-terminated string, keep returned variables on stack
@sgs_Include - include an item from the file system
@sgs_IncludeExt - include an item from the file system, optionally specifying a search path
@sgs_Compile - compile character buffer to bytecode buffer
@sgs_DumpCompiled - dump bytecode/constant info from a compiled bytecode buffer


# Introspection [info]

@sgs_Stat - retrieve or dump various parts of VM state
@sgs_StackFrameInfo - retrieve preprocessed info from stack frame
@sgs_GetFramePtr - return a stack frame pointer


# Execution control [info]

@sgs_FCallP - call variable as function
@sgs_CallP - call variable as function without `this` passed to it
@sgs_ThisCallP - call variable as function function with `this` passed to it
@sgs_FCall - call the topmost stack item as function
@sgs_Call - call the topmost stack item as function without `this` passed to it
@sgs_ThisCall - call the topmost stack item as function with `this` passed to it
@sgs_GlobalCall - call a global function
@sgs_Abort - abort the execution of the previous SGS functions up to the last C function before them
@sgs_Cntl - set and/or retrieve various states in the system


# Binding helpers [info]

@sgs_LoadLib_Fmt - load the formatting library
@sgs_LoadLib_IO - load the input/output library
@sgs_LoadLib_Math - load the math library
@sgs_LoadLib_OS - load the operating system library
@sgs_LoadLib_RE - load the regular expression library
@sgs_LoadLib_String - load the string library
@sgs_RegFuncConsts - register a list of global C function constants
@sgs_RegIntConsts - register a list of global integer constants
@sgs_RegRealConsts - register a list of global real value constants


# Object type storage [info]

@sgs_RegisterType - register an object interface pointer by name
@sgs_UnregisterType - unregister an object interface pointer by name
@sgs_FindType - find a registered object interface pointer by name
@sgs_IsType - check if variable on stack is of specified registered type


# Variable initialization [info]

@sgs_InitNull - initialize variable to a null variable
@sgs_InitBool - initialize variable to a boolean variable
@sgs_InitInt - initialize variable to an integer
@sgs_InitReal - initialize variable to a real value
@sgs_InitStringBuf - initialize variable to a new char buffer
@sgs_InitString - initialize variable to a new string
@sgs_InitCFunction - initialize variable to C function
@sgs_InitObject - initialize variable to a new object
@sgs_InitObjectIPA - initialize variable to a new object with additional memory allocated in-place for the internal data pointer
@sgs_InitPtr - initialize variable to a pointer variable
@sgs_InitObjectPtr - initialize variable to an existing object and acquire it
@sgs_InitArray - initialize variable to a new array, optionally using the specified number of pushed items on stack
@sgs_InitDict - initialize variable to a new dict, optionally using the specified number of pushed items on stack
@sgs_InitMap - initialize variable to a new map, optionally using the specified number of pushed items on stack


# Stack primary interface [info]

@sgs_PushNull - push a null variable
@sgs_PushBool - push a boolean variable
@sgs_PushInt - push an integer
@sgs_PushReal - push a real value
@sgs_PushStringBuf - push a new string from char buffer
@sgs_PushString - push a new string
@sgs_PushCFunction - push a C function
@sgs_PushObject - push a new object
@sgs_PushObjectIPA - push a new object with additional memory allocated in-place for the internal data pointer
@sgs_PushPtr - push a pointer
@sgs_PushObjectPtr - push an object pointer
@sgs_PushArray - push a new array variable, optionally using the specified number of pushed items on stack
@sgs_PushDict - push a new dict variable, optionally using the specified number of pushed items on stack
@sgs_PushMap - push a new map variable, optionally using the specified number of pushed items on stack
@sgs_PushVariable - push the specified variable
@sgs_StoreVariable - retrieve, acquire and pop the topmost variable on stack
@sgs_PushItem - retrieve and push the specified variable on stack
@sgs_StoreItem - store and pop the topmost variable to the specified position after removal in stack
@sgs_InsertVariable - insert a variable on stack in the specified position
@sgs_Pop - pop the specified number of items from stack
@sgs_PopSkip - pop the specified number of items from stack, skipping some topmost items
@sgs_StackSize - return the size of the current stack frame
@sgs_SetStackSize - resize the current stack frame
@sgs_AbsIndex - convert stack index to positive if possible (if it's <0 or >=StackSize, then it's invalid)
@sgs_IsValidIndex - check if specified stack index is valid
@sgs_PeekStackItem - retrieve without acquisition the specified variable on stack
@sgs_GetStackItem - retrieve and acquire the specified variable on stack
@sgs_SetStackItem - assign variable to the specified variable on stack
@sgs_ItemType - return the variable type of the specified variable on stack
@sgs_LoadArgsExtVA - parse the stack as an argument list with additional options (for custom wrapper functions)
@sgs_LoadArgsExt - parse the stack as an argument list with additional options
@sgs_LoadArgs - parse the stack as an argument list
@sgs_ParseMethod - the `this` object variable handling function, using the macro is preferred to this
@SGS_PARSE_METHOD - automagically handle a `this` object variable regardless of the way its passed
@sgs_Method - unhide the first variable on stack if there is a hidden `this` variable
@sgs_HideThis - hide the first variable on stack if the stack already doesn't contain a hidden `this` variable
@sgs_ForceHideThis - hide the first variable even if it wasn't previously hidden before unhiding


# Sub-item usage [info]

@sgs_GetIndex*** - retrieve a sub-item
@sgs_SetIndex*** - set a sub-item
@sgs_PushIndex** - retrieve and push a sub-item
@sgs_StoreIndex** - store and pop a sub-item
@sgs_GetGlobalPP - retrieve a global variable
@sgs_SetGlobalPP - set a global variable
@sgs_PushProperty - retrieve and push the string property of a variable on stack
@sgs_StoreProperty - store and pop the topmost stack item to a string property of a variable on stack
@sgs_PushNumIndex - retrieve and push the integer index of a variable on stack
@sgs_StoreNumIndex - store and pop the topmost stack item to an integer index of a variable on stack
@sgs_PushGlobal - retrieve and push the global variable, specified by a string
@sgs_StoreGlobal - store and pop the topmost stack item as a global variable, specified by a string
@sgs_GetEnv - retrieve the global environment hash table (dict)
@sgs_SetEnv - set the variable as the global environment hash table (dict), if possible
@sgs_PushEnv - push the global environment hash table (dict)
@sgs_StoreEnv - store and pop the topmost stack item as the global environment hash table (dict), if possible
@sgs_PushPath - retrieve and push a variable from a path of sub-items
@sgs_StorePath - store and pop the topmost stack item into a path of sub-items


# Argument handling [info]

@sgs_ArgErrorExt - emit an argument type mismatch error with additional formatting options
@sgs_ArgError - emit an argument type mismatch error
@sgs_FuncArgError - emit an argument type mismatch error (alias for states where `this` variable is hidden)
@sgs_MethodArgError - emit an argument type mismatch error (alias for states where `this` variable is NOT hidden)
@sgs_LoadArgsExtVA - parse the stack as an argument list with additional options (for custom wrapper functions)
@sgs_LoadArgsExt - parse the stack as an argument list with additional options
@sgs_LoadArgs - parse the stack as an argument list
@sgs_ParseMethod - the `this` object variable handling function, using the macro is preferred to this
@SGS_PARSE_METHOD - automagically handle a `this` object variable regardless of the way its passed
@sgs_Method - unhide the first variable on stack if there is a hidden `this` variable
@sgs_HideThis - hide the first variable on stack if the stack already doesn't contain a hidden `this` variable
@sgs_ForceHideThis - hide the first variable even if it wasn't previously hidden before unhiding


# Virtual machine operations [info]

@sgs_Assign - release the current variable and acquire-assign to it from the source
@sgs_ArithOp - run an arithmetic operation (+,-,*,/,%) on two variables to generate a third one
@sgs_Compare - check if both variables compare equal to each other
@sgs_EqualTypes - check if both variables have the same type and object interface (if both are objects)
@sgs_IncDec - increment or decrement the specified variable
@sgs_TypeOf - convert the topmost variable on stack to a type name string
@sgs_DumpVar - convert the topmost variable on stack to a string that contains detailed info about its contents
@sgs_GCExecute - run the garbage collection system to remove all unreachable objects
@sgs_StringConcat - concatenate two or more variables into a string
@sgs_CloneItem - clone the topmost stack item if it's mutable
@sgs_ObjectAction - execute actions on object variable on stack
@sgs_Serialize - serialize the topmost variable on stack by converting it recursively to an instruction stream
@sgs_SerializeObject - emit a call to the specified function to the serialized stream
@sgs_Unserialize - unserialize the topmost variable on stack by running its serialized instruction stream


# String helpers [info]

@sgs_PadString - return a string with two spaces appended to all newline characters
@sgs_ToPrintSafeString - return a string with all non-printable (except space), non-ASCII characters converted to a character hex code
@sgs_StringConcat - concatenate two or more variables into a string


# Closures [info]

@sgs_ClPushNulls - push a number of empty closures to the closure stack
@sgs_ClPushItem - push a variable on stack as a closure to the closure stack
@sgs_ClPop - pop a number of closures from the closure stack
@sgs_MakeClosure - make a callable closure object from the specified callable and number of closures on stack
@sgs_ClGetItem - retrieve the variable from a closure on stack
@sgs_ClSetItem - set the variable to a closure on stack


# Data retrieval & conversion [info]

@sgs_GetBoolP - return the boolean version of the variable
@sgs_GetIntP - return the integer version of the variable
@sgs_GetRealP - return the real value version of the variable
@sgs_GetPtrP - return the pointer version of the variable
@sgs_ToBoolP - convert variable to a boolear value and return it
@sgs_ToIntP - convert variable to an integer and return it
@sgs_ToRealP - convert variable to a real value and return it
@sgs_ToPtrP - convert variable to a pointer and return it
@sgs_ToStringBufP - convert variable to a string, returning size
@sgs_ToStringP - convert variable to a string
@sgs_ToStringBufFastP - convert variable to a string, preventing possible recursion and returning size
@sgs_ToStringFastP - convert variable to a string, preventing possible recursion
@sgs_IsObjectP - check if variable is an object and has the specified interface pointer
@sgs_IsTypeP - check if variable is of specified registered type
@sgs_IsCallableP - check if variable is callable (SGS function, C function or object with CALL impl.)
@sgs_ParseBoolP - validate conversion, optionally return boolean value from variable, if possible
@sgs_ParseIntP - validate conversion, optionally return integer value from variable, if possible
@sgs_ParseRealP - validate conversion, optionally return real value from variable, if possible
@sgs_ParseStringP - validate conversion, optionally return string or buffer from variable, if possible
@sgs_ParseObjectPtrP - validate conversion, optionally return object pointer from variable, if possible
@sgs_ParsePtrP - validate conversion, optionally return pointer from variable, if possible
@sgs_ArraySizeP - retrieve size of array variable, if possible
@sgs_GetBool - return the boolean version of the variable on stack
@sgs_GetInt - return the integer version of the variable on stack
@sgs_GetReal - return the real value version of the variable on stack
@sgs_GetPtr - return the pointer version of the variable on stack
@sgs_ToBool - convert variable on stack to a boolear value and return it
@sgs_ToInt - convert variable on stack to an integer and return it
@sgs_ToReal - convert variable on stack to a real value and return it
@sgs_ToPtr - convert variable on stack to a pointer and return it
@sgs_ToStringBuf - convert variable on stack to a string, returning size
@sgs_ToString - convert variable on stack to a string
@sgs_ToStringBufFast - convert variable on stack to a string, preventing possible recursion and returning size
@sgs_ToStringFast - convert variable on stack to a string, preventing possible recursion
@sgs_IsObject - check if variable on stack is an object and has the specified interface pointer
@sgs_IsType - check if variable on stack is of specified registered type
@sgs_IsCallable - check if variable on stack is callable (SGS function, C function or object with CALL impl.)
@sgs_ParseBool - validate conversion, optionally return boolean value from variable on stack, if possible
@sgs_ParseInt - validate conversion, optionally return integer value from variable on stack, if possible
@sgs_ParseReal - validate conversion, optionally return real value from variable on stack, if possible
@sgs_ParseString - validate conversion, optionally return string or buffer from variable on stack, if possible
@sgs_ParseObjectPtr - validate conversion, optionally return object pointer from variable on stack, if possible
@sgs_ParsePtr - validate conversion, optionally return pointer from variable on stack, if possible
@sgs_ArraySize - retrieve size of array variable on stack, if possible
@sgs_GlobalBool - retrieve global by name as bool
@sgs_GlobalInt - retrieve global by name as integer
@sgs_GlobalReal - retrieve global by name as real
@sgs_GlobalStringBuf - retrieve global by name as string buffer
@sgs_GlobalString - retrieve global by name as string
@sgs_GetStringPtrP - get string pointer from variable pointer
@sgs_GetStringSizeP - get string size from variable pointer
@sgs_GetObjectStructP - get object pointer from variable pointer
@sgs_GetObjectDataP - get data pointer of object variable pointer
@sgs_GetObjectIfaceP - get interface pointer of object variable pointer
@sgs_SetObjectDataP - set data pointer of object variable pointer
@sgs_SetObjectIfaceP - set interface pointer of object variable pointer
@sgs_GetStringPtr - get string pointer from variable on stack
@sgs_GetStringSize - get string size from variable on stack
@sgs_GetObjectStruct - get object pointer from variable on stack
@sgs_GetObjectData - get data pointer of object variable on stack
@sgs_GetObjectIface - get interface pointer of object variable on stack
@sgs_SetObjectData - set data pointer of object variable on stack
@sgs_SetObjectIface - set interface pointer of object variable on stack


# Iterators [info]

@sgs_PushIteratorP - create and push iterator from variable pointer
@sgs_GetIteratorP - create iterator from variable pointer
@sgs_IterAdvanceP - advance iterator, specified by its variable pointer
@sgs_IterPushDataP - extract and push data of current iteration of the iterator, specified by its variable pointer
@sgs_IterGetDataP - extract data of current iteration of the iterator, specified by its variable pointer
@sgs_PushIterator - create and push iterator from variable on stack
@sgs_GetIterator - create iterator from variable on stack
@sgs_IterAdvance - advance iterator, specified by its stack index
@sgs_IterPushData - extract and push data of current iteration of the iterator variable on stack
@sgs_IterGetData - extract data of current iteration of the iterator variable on stack


# Variable ownership [info]

@sgs_Acquire - increment reference count of a variable if the type implements reference counting
@sgs_Release - decrement reference count and possibly destroy a variable if the type implements ref.counting
@sgs_ReleaseArray - release an array of variables
@sgs_GCMark - mark a variable as available to prevent GC from removing it
@sgs_GCMarkArray - mark an array of variables as available
@sgs_ObjAcquire - acquire an object variable by its sgs_VarObj pointer
@sgs_ObjRelease - release an object variable by its sgs_VarObj pointer
@sgs_ObjGCMark - mark an object variable by its sgs_VarObj pointer
@sgs_ObjCallDtor - call the destruction function of an object variable if it's defined


# String32 optimization interface [info]

@sgs_PushStringBuf32 - initialize and push string32 object on stack
@sgs_PushString32 - initialize and push string32 object on stack
@sgs_CheckString32 - trigger a breakpoint if string32 object is not freed
@sgs_IsFreedString32 - check if string32 object is freed


# Utility functions [info]

@sgs_CodeString - retrieve a name string for the specified constant
@sgs_IsNumericString - check if string is going to be parsed as a number by the internal parser