Wi API Reference

Using Wi API to create a library

If you're using Wi API to create a library, your library must have a wi_foreign_init function marked as WI_FOREIGN_INIT with 1 parameter being wi_state* state.

`wi.h`

Macros

`WI_API`

Expands to:

#ifdef _WIN32: __declspec(dllexport)
#else:

Used to mark all public API functions

`WI_FOREIGN_INIT`

Expands to:

#ifdef _WIN32: __declspec(dllexport)
#else:

Used to mark foreign library entry point (wi_foreign_init)

Types

`wi_real`

Wi's number type

`wi_object`

Opaque Wi object handle

`wi_run_result`

The result of running Wi code

WI_RUN_OK: No errors occurred
WI_RUN_ERROR: A runtime error or a compile error occurred, also used when out of memory
WI_RUN_ABORT: Execution was aborted early via wi_state_abort

`wi_state`

Opaque Wi state handle

`wi_foreign_fn`

Foreign (C) function pointer, called from Wi scripts

`wi_userdata_finalizer_fn`

Userdata finalizer - function called when the userdata gets collected by GC

`wi_load_require_fn`

Function called in the require statement. Use this in a custom virtual filesystem (your app, for example).
Must return Wi code

`wi_require_exists_fn`

Function used to check whether a required file exists, called at compile time.
Must return whether a file exists

Functions

`wi_def_std`

Define the standard library in a state
Parameters:

wi_state* state: Wi state instance

`wi_def_foreign`

Define a foreign (C) function in the state
Parameters:

wi_state* state: Wi state instance
const char* name: Function name
wi_foreign_fn fn: Pointer to the C function implementation
int arity: Function's arity (number of arguments it expects)
bool is_variadic: Whether function is variadic or not

`wi_def_object`

Define an object in the state (global)
Parameters:

wi_state* state: Wi state instance
const char* name: Object name

Returns: wi_object* Pointer to the created object

`wi_object_set_field_real`

Set a real field on an object
Parameters:

wi_state* state: Wi state instance
wi_object* object: Target object
const char* name: Field name
wi_real real: Value to set

`wi_object_set_field_bool`

Set a boolean field on an object
Parameters:

wi_state* state: Wi state instance
wi_object* object: Target object
const char* name: Field name
bool boolean: Value to set

`wi_object_set_field_string`

Set a string field on an object
Parameters:

wi_state* state: Wi state instance
wi_object* object: Target object
const char* name: Field name
char* string: Value to set

`wi_object_set_field_userdata`

Set userdata as a field on an object
Parameters:

wi_state* state: Wi state instance
wi_object* object: Target object
const char* field_name: Field name
const char* name: Userdata name, used for type-checking
void* userdata: Pointer to userdata
wi_userdata_finalizer_fn finalizer: Userdata finalizer

`wi_object_set_field_foreign`

Set a foreign (C) function as a field on an object
Parameters:

wi_state* state: Wi state instance
wi_object* object: Target object
const char* name: Field name
wi_foreign_fn fn: Pointer to the C function implementation
int arity: Function's arity (number of arguments it expects)
bool is_variadic: Whether function is variadic or not

`wi_new_state`

Create a new Wi state instance
Parameters:

wi_conf conf: Wi configuration, see wi_conf.h for more

Returns: wi_state* Created Wi state instance

`wi_delete_state`

Delete a Wi state instance and free all associated memory
Parameters:

wi_state* state: Wi state instance

`wi_state_get_error`

Get the error message from the last compile or runtime error
Parameters:

wi_state* state: Wi state instance

Returns: const char* Error message, NULL if none occurred

`wi_state_set_require_load_fn`

Set the require load callback
Parameters:

wi_state* state: Wi state instance
wi_load_require_fn fn: Load callback function

`wi_state_set_require_exists_fn`

Set the require existence check callback
Parameters:

wi_state* state: Wi state instance
wi_require_exists_fn fn: Existence check callback function

`wi_state_set_args`

Set the command line arguments that will be available to Wi scripts via os.args
Parameters:

wi_state* state: Wi state instance
int argc: Number of arguments
const char** argv: Array of argument strings

`wi_state_error`

Throw a runtime error in the state
Parameters:

wi_state* state: Wi state instance
const char* format: printf format string
...: Format arguments

`wi_state_abort`

Request the state to stop execution, returning WI_RUN_ABORT from wi_state_run. Must only be called while a script is running (e.g., from a foreign (C) function). Calling it outside wi_state_run is undefined behavior
Parameters:

wi_state* state: Wi state instance

`wi_state_interrupt`

Request the state to stop execution as soon as possible, returning WI_RUN_ABORT from wi_state_run. In contrast to wi_state_abort, this function is safe to call asynchronously (e.g., from a signal handler or another thread)
Parameters:

wi_state* state: Wi state instance

`wi_state_run`

Execute Wi code
Parameters:

wi_state* state: Wi state instance
const char* file_path: Path to the script, used for error messages
const char* src: Code string

Returns: wi_run_result Run result

Function calling API

Example:

wi_find_function(state, "sum"); /* Find the global function "sum" and push it onto the stack */

wi_push_real(state, 10); /* Push argument 1 */ wi_push_real(state, 20); /* Push argument 2 */
wi_call(state, 2); /* Call function with `2` arguments, is protected */

wi_real sum = wi_check_real(state); /* Get the function result, with type-checking */
printf("%g\n", sum); /* Print it */

`wi_find_function`

Find a global function and push it onto the stack
Parameters:

wi_state* state: Wi state instance
const char *name: Function name

Returns: bool

`wi_is_real`

Check if the value at the stack top is a real value
Parameters:

wi_state* state: Wi state instance

Returns: bool

`wi_is_null`

Check if the value at the stack top is a null value
Parameters:

wi_state* state: Wi state instance

Returns: bool

`wi_is_bool`

Check if the value at the stack top is a boolean value
Parameters:

wi_state* state: Wi state instance

Returns: bool

`wi_is_string`

Check if the value at the stack top is a string value
Parameters:

wi_state* state: Wi state instance

Returns: bool

`wi_is_userdata`

Check if the value at the stack top is userdata
Parameters:

wi_state* state: Wi state instance
const char* name: Userdata name, used for type-checking

Returns: bool

`wi_push_real`

Push a real value onto the stack
Parameters:

wi_state* state: Wi state instance
wi_real real: Real

`wi_push_null`

Push a null value onto the stack
Parameters:

wi_state* state: Wi state instance

`wi_push_bool`

Push a boolean value onto the stack
Parameters:

wi_state* state: Wi state instance
bool boolean: Boolean

`wi_push_string`

Push a string value onto the stack
Parameters:

wi_state* state: Wi state instance
const char* string: String

`wi_push_userdata`

Push userdata onto the stack
Parameters:

wi_state* state: Wi state instance
const char* name: Userdata name, used for type-checking
void* userdata: Pointer to userdata
wi_userdata_finalizer_fn finalizer: Userdata finalizer

`wi_pop_real`

Pop a real value from the stack
Parameters:

wi_state* state: Wi state instance

Returns: wi_real

`wi_pop_null`

Pop a null value from the stack
Parameters:

wi_state* state: Wi state instance

`wi_pop_bool`

Pop a boolean value from the stack
Parameters:

wi_state* state: Wi state instance

Returns: bool

`wi_pop_string`

Pop a string value from the stack
Parameters:

wi_state* state: Wi state instance
int* len: Optional pointer to store the string length, can be NULL

Returns: char*

`wi_pop_userdata`

Pop userdata from the stack
Parameters:

wi_state* state: Wi state instance

Returns: void*

`wi_check_real`

Pop a real value from the stack with type-checking
Parameters:

wi_state* state: Wi state instance

Returns: wi_real

`wi_check_bool`

Pop a boolean value from the stack with type-checking
Parameters:

wi_state* state: Wi state instance

Returns: bool

`wi_check_string`

Pop a string value from the stack with type-checking
Parameters:

wi_state* state: Wi state instance
int* len: Optional pointer to store the string length, can be NULL

Returns: char*

`wi_check_userdata`

Pop userdata from the stack with type-checking
Parameters:

wi_state* state: Wi state instance
const char* name: Userdata name, used for type-checking

Returns: void*

`wi_call`

Call a Wi function, is protected.

Leaves the result on the stack top, which needs to be explicitly popped via one of wi_pop_X or wi_check_X functions
Parameters:

wi_state* state: Wi state instance
uint8_t arg_count: Argument count
char** error: Optional pointer to store the error message (if any), can be NULL, must be freed manually

Returns: bool

Slot functions

Used in C functions to get arguments from the Wi caller and to set the return value. Slot 0 is reserved for the return value.

`wi_slot_is_real`

Check if a slot contains a real value
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])

Returns: bool

`wi_slot_is_null`

Check if a slot contains a null value
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])

Returns: bool

`wi_slot_is_bool`

Check if a slot contains a boolean value
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])

Returns: bool

`wi_slot_is_string`

Check if a slot contains a string value
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])

Returns: bool

`wi_slot_is_userdata`

Check if a slot contains userdata
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])

Returns: bool

`wi_slot_set_real`

Store a real value in a slot
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])

`wi_slot_set_null`

Store a null value in a slot
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])

`wi_slot_set_bool`

Store a boolean value in a slot
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])

`wi_slot_set_string`

Store a string value in a slot
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])

`wi_slot_set_userdata`

Store userdata in a slot
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])
const char* name: Userdata name, used for type-checking
void* userdata: Pointer to userdata
wi_userdata_finalizer_fn finalizer: Userdata finalizer

`wi_slot_get_real`

Get a real value from a slot
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])

Returns: wi_real Real stored in a slot

`wi_slot_get_bool`

Get a boolean value from a slot
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])

Returns: bool Boolean stored in a slot

`wi_slot_get_string`

Get a string value from a slot
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])
int* len: Optional pointer to store the string length, can be NULL

Returns: char* String stored in a slot

`wi_slot_get_userdata`

Get userdata from a slot
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])

Returns: void* Userdata stored in a slot

`wi_slot_check_real`

Get a real value from a slot with type-checking
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])

Returns: wi_real Real stored in a slot

`wi_slot_check_bool`

Get a boolean value from a slot with type-checking
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])

Returns: bool Boolean stored in a slot

`wi_slot_check_string`

Get a string value from a slot with type-checking
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])
int* len: Optional pointer to store the string length, can be NULL

Returns: char* String stored in a slot

`wi_slot_check_userdata`

Get userdata from a slot with type-checking
Parameters:

wi_state* state: Wi state instance
int slot: Slot index (0-[arg_count])
const char* name: Userdata name, used for type-checking

Returns: void* Userdata stored in a slot

`wi_conf.h`

Macros

`WI_DEFAULT_CONF`

Expands to: 0
Default configuration (all flags disabled)

`WI_VERSION_STRING`

Expands to: "6.0.0-beta"
Wi version as a string

Constants

`WI_VERSION_MAJOR`

Value: 6

`WI_VERSION_MINOR`

Value: 0

`WI_VERSION_PATCH`

Value: 0

`WI_CONSTANT_MAX`

Value: 65535
Maximum number of constants in a function

`WI_JUMP_MAX`

Value: 65535
Maximum jump offset

`WI_LOOP_MAX`

Value: 65535
Maximum loop offset

`WI_LOCALS_MAX`

Value: 255
Maximum number of local variables in a function

`WI_UPVALUES_MAX`

Value: 255
Maximum number of upvalues in a function (closure)

`WI_GC_MIN_HEAP`

Value: 10485760
Initial heap size before first collection (10MB)

`WI_GC_HEAP_GROW_FACTOR`

Value: 2
Heap growth factor per garbage collection run

`WI_CSTACK_MAX`

Value: 200
Maximum depth of nested wi_state_call and of recoveries

`WI_STACK_MIN`

Value: 20
Minimum number of values on the VM stack

`WI_STACK_MAX`

Value: 1000000
Maximum number of values on the VM stack

Types

`wi_conf_flag`

Configuration flags for the Wi state

WI_CONF_PRINT_CODE: Print bytecode after compilation
WI_CONF_STRESS_GC: Run garbage collection on every allocation
WI_CONF_LOG_GC: Log garbage collection

`wi_conf`

Configuration bitmask type

Functions

`wi_conf_set`

Set a configuration flag
Parameters:

wi_conf* conf: Configuration bitmask
wi_conf_flag flag: Configuration flag

`wi_conf_is_set`

Check if a configuration flag is set
Parameters:

wi_conf* conf: Configuration bitmask
wi_conf_flag flag: Configuration flag

Returns: bool