-
Notifications
You must be signed in to change notification settings - Fork 9
Tagha API Reference
bool value.
signed char value.
signed char[8] value.
signed short value.
signed short[4] value.
signed int value.
signed int[2] value.
signed long long value.
unsigned char value.
unsigned char[8] value.
unsigned short value.
unsigned short[4] value.
unsigned int value.
unsigned int[2] value.
unsigned long long value.
size_t value.
ssize_t value.
uintptr_t value.
intptr_t value.
32-bit float value. exists only if TAGHA_FLOAT32_DEFINED is defined.
32-bit float[2] value. exists only if TAGHA_FLOAT32_DEFINED is defined.
64-bit float value. exists only if TAGHA_FLOAT64_DEFINED is defined.
constant C string (const char *) of the name of the native function.
pointer to native C function.
The native must have the signature: union TaghaVal (*)(struct TaghaModule *ctxt, const union TaghaVal params[]);
integer code that defines execution was successful.
integer code that defines an out of bounds instruction error (only used during debugging).
integer code that defines either a NULL or invalid pointer dereference attempt.
integer code that defines a missing/NULL bytecode function.
integer code that defines a missing/unresolved/NULL native function.
integer code that defines a stack overflow.
integer code that defines a bad external call, whether the function owner is nil, the function wasn't linked, or the data was nil.
struct TaghaModule *tagha_module_new_from_file(const char filename[]);Allocates a struct TaghaModule pointer from a script file.
-
filename- filename string of the script to load.
pointer to a newly allocated struct TaghaModule pointer, returns NULL if an error occured or problems reading the script.
struct TaghaModule *tagha_module_new_from_buffer(uint8_t buffer[]);Allocates a struct TaghaModule pointer from an existing data buffer.
-
buffer- pointer to raw script data.
pointer to a newly allocated struct TaghaModule pointer, return NULL if an error occured or problem reading the buffer data.
bool tagha_module_clear(struct TaghaModule *module);Deallocates a struct TaghaModule pointer's data.
-
module- pointer to astruct TaghaModuleobject.
bool value whether the deallocation was successful or not.
bool tagha_module_free(struct TaghaModule **module_ref);Deallocates a struct TaghaModule pointer's data, deallocates the module pointer itself, and sets the pointer to NULL.
-
module_ref- reference to astruct TaghaModulepointer.
bool value whether the deallocation was successful or not.
const char *tagha_module_get_err(const struct TaghaModule *module);Returns a constant string of an error message to check what error had occurred. When an error or exception occurs in the VM portion of a module, a return value of -1 is returned and the module's error field is set.
-
module- pointer to astruct TaghaModuleobject.
constant C string (const char *) error message. Never returns NULL.
void tagha_module_link_natives(struct TaghaModule *module, const struct TaghaNative natives[]);Links the native C functions to a module for data communication between C code and the script's bytecode.
-
module- pointer to astruct TaghaModuleobject. -
natives- array ofstruct TaghaNative's to register.
None.
bool tagha_module_link_ptr(struct TaghaModule *module, const char name[], uintptr_t ptr);Registers a pointer to a script's global pointer variable by name. Example - registering 'stdin' standard input FILE*:
tagha_module_link_ptr(module, "stdin", ( uintptr_t )stdin);Will crash the program if the variable name given is not a pointer on the script's side.
-
module- pointer to astruct TaghaModuleobject. -
name- string name of the global ptr variable to register. -
ptr- uintptr_t value to link.
true or false if the operation was successful or not.
void *tagha_module_get_var(struct TaghaModule *module, const char name[]);Returns a pointer to a script-defined global variable. If the global variable is defined as a pointer in the script, then the returning pointer will be a pointer to that pointer.
-
module- pointer to astruct TaghaModuleobject. -
name- string name of the global variable to retrieve.
pointer to the global variable, NULL if the variable doesn't exist or the module doesn't have script data/memory.
TaghaFunc tagha_module_get_func(struct TaghaModule *module, const char name[]);Returns a pointer to a script-defined function.
-
module- pointer to astruct TaghaModuleobject. -
name- string name of the function to retrieve.
returns a TaghaFunc object, NULL if error occurred.
uint32_t tagha_module_get_flags(const struct TaghaModule *module);gets a script's flags.
-
module- pointer to astruct TaghaModuleobject.
a uint32_t of the script's flags
bool tagha_module_call(struct TaghaModule *module, const char name[], size_t args, const union TaghaVal params[], union TaghaVal *retval);Manually calls a script function from C by name.
-
module- pointer to astruct TaghaModuleobject. -
name- name of script function to invoke. -
args- amount of arguments to pass. -
params- function params to be passed, as an array ofunion TaghaVal. -
ret_val- pointer tounion TaghaValfor use as a return value buffer.
true if successful AND no errors occurred, false otherwise.
bool tagha_module_invoke(struct TaghaModule *module, TaghaFunc func, size_t args, const union TaghaVal params[], union TaghaVal *retval);Manually calls a script function from C by function pointer. Designed to be used for natives that use a function pointer from bytecode as a parameter.
-
module- pointer to astruct TaghaModuleobject. -
func-TaghaFuncobject. -
args- amount of arguments to pass. -
params- function params to be passed, as an array ofunion TaghaVal. -
ret_val- pointer tounion TaghaValfor use as a return value buffer.
true if successful AND no errors occurred, false otherwise.
bool tagha_module_run(struct TaghaModule *module, size_t argc, const union TaghaVal argv[], int32_t *retval);Executes a script by calling its main function.
-
module- pointer to astruct TaghaModuleobject. -
argc- length of theargvarray. -
argv- array ofunion TaghaVals of lengthargc. -
ret_val- pointer toint32_tfor use as a return value buffer.
true if successful AND no errors occurred, false otherwise.
void tagha_module_throw_err(struct TaghaModule *module, int32_t err);Allows a developer to manually throw a VM runtime exception. Only use within a native C or C++ function call that the script needs to stop running.
-
module- pointer to astruct TaghaModuleobject. -
err- value that's higher or lower than 0, can be either a user defined error or anenum TaghaErrCodevalue.
None.
void tagha_module_link_module(struct TaghaModule *module, const struct TaghaModule *lib);Resolves unlinked functions in module from lib. (NOTE: lib could possibly have its own unresolved linkage.)
Two modules can link to functions from one another and a "lib" module can have its own unresolved links. This API function is a helper to resolve unlinked functions that are in module.
-
module- pointer to astruct TaghaModuleobject. -
lib- const pointer to astruct TaghaModuleobject.
None.