-
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.
inptr_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, size_t args, const union TaghaVal params[]);
integer code that defines an out of bounds error. Value of -1.
integer code that defines execution was successful. Value of 0.
integer code that defines either a NULL or invalid pointer dereference attempt. Value of 1.
integer code that defines a missing/NULL bytecode function. Value of 2.
integer code that defines a missing/unresolved/NULL native function. Value of 3.
integer code that defines an invalid script during loading. Value of 4.
integer code that defines an invalid stack size given. Value of 5.
integer code that defines a stack overflow. Value of 6.
int code that defines a bad external call, whether the function owner is nil, the function wasn't linked, or the data was nil. Value of 7.
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_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.
struct TaghaModule tagha_module_create_from_file(const char filename[]);builds a module from a file.
-
filename- filename string of the script to load.
usable module structure if building the module from the file was a success, empty module structure otherwise.
struct TaghaModule tagha_module_create_from_buffer(uint8_t buffer[]);builds a module from an existing data buffer.
-
buffer- pointer to raw script data.
usable module structure if building the module from buffer was a success, empty module structure otherwise.
bool tagha_module_clear(struct TaghaModule *module);Deallocates a struct TaghaModule's stored script data. The module pointer itself is NOT freed. Do NOT use this if you're using a buffer made from scratch.
-
module- pointer to astruct TaghaModuleobject.
bool value whether the deallocation was successful or not.
void tagha_module_print_vm_state(const struct TaghaModule *module, bool hex);Prints the registers and condition flag of a Tagha module object.
-
module- pointer to astruct TaghaModuleobject. -
hex- option bool to print general-purpose register data as hexadecimal instead of decimal.
None.
const char *tagha_module_get_error(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. Returns NULL if the module object was NULL.
bool tagha_module_register_natives(struct TaghaModule *module, const struct TaghaNative natives[]);Registers 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.
true or false if the operation was successful or not.
bool tagha_module_register_ptr(struct TaghaModule *module, const char varname[], void *ptr);Registers a pointer to a script's global pointer variable by name. Example - registering 'stdin' standard input FILE *:
tagha_module_register_ptr(module, "stdin", stdin);Will crash the program if the variable name given is not a pointer on the script's side.
-
module- pointer to astruct TaghaModuleobject. -
varname- string name of the global ptr variable to register. -
ptr- ptr value to register.
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.
void *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.
pointer to bytecode function, NULL if the function doesn't exist or the module doesn't have script data/memory.
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
int32_t tagha_module_call(struct TaghaModule *module, const char name[], size_t args, union TaghaVal params[], union TaghaVal *ret_val);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.
returns a status int32_t value, returns -1 if an error occurred. Use ret_val to get a proper return value.
int32_t tagha_module_invoke(struct TaghaModule *module, const void *func, size_t args, union TaghaVal params[], union TaghaVal *ret_val);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- const pointer to script function. -
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.
returns a status int32_t value, returns -1 if an error occurred. Use ret_val to get a proper return value.
int32_t tagha_module_run(struct TaghaModule *module, size_t argc, union TaghaVal argv[]);Executes a script by calling its main function.
-
module- pointer to astruct TaghaModuleobject. -
argc- length of theargvarray. -
argv- array ofunion TaghaVals of lengthargc.
returns a status int32_t value, returns -1 if an error occurred.
void tagha_module_throw_error(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_jit_compile(struct TaghaModule *module, TaghaCFunc *jitfunc(uintptr_t, size_t, void*), void *userdata)JIT compiles an entire module to native code.
-
module- pointer to astruct TaghaModuleobject. -
jitfunc- function pointer that is given auint8_t*casted as auintptr_t, the instruction len, and avoid*to userdata necessary to carry out the JIT compilation process. -
userdata- pointer to user data to pass the jit function pointer.
None.
void tagha_module_resolve_links(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.