-
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.
int main(void)
{
struct TaghaModule *m = tagha_module_new_from_file("test_fib.tbc");
...;
tagha_module_free(&m);
}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.
int main(void)
{
struct TaghaModGen module_generator = ...;
...;
struct TaghaModule *m = tagha_module_new_from_buffer(tagha_mod_gen_raw(&module_generator));
...;
tagha_module_free(&m);
}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.
int main(void)
{
/// useful if you have to free a restrict and/or const qualified pointer.
struct TaghaModule *const restrict ctxt = tagha_module_new_from_file("test_fib.tbc");
...;
tagha_module_clear(ctxt), ctxt = NULL;
}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.
int main(void)
{
/// cannot use const or restricted pointers on 'tagha_module_free' or compiler will discard those qualifiers.
struct TaghaModule *ctxt = tagha_module_new_from_file("test_fib.tbc");
...;
tagha_module_free(&ctxt);
}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.
result typical_function(struct TaghaModule *const ctxt, ...)
{
if( tagha_module_run(ctxt, 0, NULL) != 0 || ctxt->err ) {
prog_log_error("result => %i | err? '%s'\n", main_result, tagha_module_get_err(ctxt));
}
}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.
/// int puts(const char *str);
static NO_NULL union TaghaVal native_puts(struct TaghaModule *const restrict ctxt, const union TaghaVal params[const static 1])
{
( void )ctxt;
return ( union TaghaVal ){ .int32 = puts(( const char* )params[0].uintptr) };
}
bool setup_rt_natives(void *const restrict sys, struct TaghaModule *const restrict ctxt)
{
return tagha_module_link_natives(ctxt, ( const struct TaghaNative[] ){
{"puts", &native_puts},
{NULL, NULL}
});
}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.
/// int puts(const char *str);
static NO_NULL union TaghaVal native_puts(struct TaghaModule *const restrict module, const union TaghaVal params[const static 1])
{
( void )module;
return ( union TaghaVal ){ .int32 = puts(( const char* )params[0].uintptr) };
}
bool setup_rt_natives(void *const restrict sys, struct TaghaModule *const restrict ctxt)
{
tagha_module_link_ptr(ctxt, "stdin", ( uintptr_t )stdin);
tagha_module_link_ptr(ctxt, "stdout", ( uintptr_t )stdout);
tagha_module_link_ptr(ctxt, "g_sys", ( uintptr_t )sys);
return tagha_module_link_natives(ctxt, ( const struct TaghaNative[] ){
{"puts", &native_puts},
{NULL, NULL}
});
}void *tagha_module_get_var(const 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 aconst struct 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.
const char *get_ctxt_name(struct TaghaModule *const restrict ctxt)
{
const char *restrict name = tagha_module_get_var(ctxt, "g_name");
return ( name != NULL ) ? name : "unknown";
}TaghaFunc tagha_module_get_func(const struct TaghaModule *module, const char name[]);Returns a pointer to a script-defined function.
-
module- pointer to aconst struct TaghaModuleobject. -
name- string name of the function to retrieve.
returns a TaghaFunc object, NULL if error occurred.
void invoke_startup(struct TaghaModule *ctxts[const restrict static 1], const size_t num_ctxts)
{
for( size_t i=0; i<num_ctxts; i++ ) {
const TaghaFunc on_start = tagha_module_get_func(ctxts[i], "on_start");
/// void on_start(void);
tagha_module_invoke(ctxts[i], on_start, 0, NULL, NULL);
}
}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.
size_t count_extensions(struct TaghaModule *ctxts[const restrict static 1], const size_t num_ctxts)
{
size_t count = 0;
for( size_t i=0; i<num_ctxts; i++ ) {
const uint32_t ctxt_flags = tagha_module_get_flags(ctxts[i]);
/// ignore if module contains no 'main' or 'on_start'.
if( ctxt_flags & LIBRARY )
continue;
else count++;
}
return count;
}uintptr_t tagha_module_heap_alloc(struct TaghaModule *module, size_t size);allocates memory from the script's heap.
-
module- pointer to astruct TaghaModuleobject. -
size- how many bytes to allocate.
a pointer allocated from a module's runtime casted to uintptr_t, NIL if script heap is exhausted.
void invoke_startup_with_argv(struct TaghaModule *ctxts[const restrict static 1], const size_t num_ctxts)
{
for( size_t i=0; i<num_ctxts; i++ ) {
const TaghaFunc on_start = tagha_module_get_func(ctxts[i], "on_start");
/// void on_start_args(const char *titles[static MAX_TITLES]);
union TaghaVal script_argv = { .uintptr = tagha_module_heap_alloc(ctxts[i], sizeof(union TaghaVal) * MAX_TITLES + 1) };
union TaghaVal *strs = ( union TaghaVal* )script_argv.uintptr;
for( size_t i=0; i<MAX_TITLES; i++ ) {
const size_t len = strlen(g_app_sys->titles[i]);
strs[i].uintptr = tagha_module_heap_alloc(ctxts[i], len + 1);
char *restrict title = ( char* )strs[i].uintptr;
strcpy(title, g_app_sys->titles[i]);
}
strs[MAX_TITLES].uintptr = NIL;
union TaghaVal main_args[2] = {
{.size = 2},
{.uintptr = script_argv.uintptr}
};
tagha_module_invoke(ctxts[i], on_start, 2, main_args, NULL);
}
}bool tagha_module_heap_free(struct TaghaModule *module, uintptr_t ptr);returns memory back to a script's heap.
-
module- pointer to astruct TaghaModuleobject. -
ptr-uintptr_tof a pointer that was allocated from the script's heap.
true if operation was successful, false otherwise.
const uintptr_t ctxt_mem = tagha_module_heap_alloc(ctxt, 256);
...;
tagha_module_heap_free(ctxt, ctxt_mem);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.
int invoke_startup(struct TaghaModule *ctxts[const restrict static 1], const size_t num_ctxts)
{
for( size_t i=0; i<num_ctxts; i++ ) {
tagha_module_call(ctxts[i], "on_start", 0, NULL, NULL);
}
}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.
/** void array_destroy(array *a, void dtor(void *item)); */
union TaghaVal native_array_destroy(struct TaghaModule *const restrict ctxt, const union TaghaVal params[const restrict static 1])
{
(void)args;
array_type *const array = ( array_type* )params[0].uintptr;
const TaghaFunc dtor = ( TaghaFunc )params[1].uintptr;
if( dtor != NULL ) {
tagha_module_invoke(ctxt, dtor, 2, ( union TaghaVal[] ){ {.uintptr = ( uintptr_t )array->table}, {.size = array->len} }, NULL);
}
array_type_destroy(array);
return ( union TaghaVal ){ 0 };
}int tagha_module_run(struct TaghaModule *module, size_t argc, const 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.
true if successful AND no errors occurred, false otherwise as an int.
int main(void)
{
struct TaghaModule *ctxt = tagha_module_new_from_file(argv[1]);
const int result = tagha_module_run(ctxt, 0, NULL);
...;
tagha_module_free(&ctxt);
}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 abort(void); */
union TaghaVal native_abort(struct TaghaModule *const restrict ctxt, const union TaghaVal params[const restrict static 1])
{
(void)args; (void)params;
tagha_module_throw_err(ctxt, 0xff);
return ( union TaghaVal ){ 0 };
}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- pointer to a conststruct TaghaModuleobject.
None.
bool load_extension_to_sys(const char ctxt_name[restrict static 1])
{
if( g_app_sys.num_ctxts >= MAX_CTXTS || app_sys_ctxt_exists(ctxt_name) )
return false;
struct TaghaModule *ctxt = tagha_module_new_from_file(ctxt_name);
const size_t curr_ctxts = g_app_sys.num_ctxts;
g_app_sys.ctxts[g_app_sys.num_ctxts++] = ctxt;
for( size_t i=0; i<curr_ctxts; i++ ) {
tagha_module_link_module(ctxt, g_app_sys.ctxts[i]);
}
return true;
}