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 wi_foreign_fn_t signature.

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_t

Wi's number type

wi_object_t

Opaque Wi object handle

wi_run_result_t

The result of running Wi code

• WI_RUN_OK: No errors occurred
• WI_RUN_ERROR: A runtime error or a compile error occurred
• WI_RUN_ABORT: Execution was aborted early via wi_state_abort

wi_state_t

Opaque Wi state handle

wi_foreign_fn_t

Foreign (C) function pointer, called from Wi scripts

wi_userdata_finalizer_fn_t

Userdata finalizer - function called when the state is deleted (freed)

Functions

wi_def_std

Define the standard library in a state
Parameters:

• wi_state_t* state: Wi state instance

wi_def_foreign

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

• wi_state_t* state: Wi state instance
• const char* name: Function name
• wi_foreign_fn_t fn: Pointer to the C function implementation
• int arity: Function's arity (number of arguments it expects), use -1 for variable arguments

wi_def_object

Define an object in the state (global)
Parameters:

• wi_state_t* state: Wi state instance
• const char* name: Object name

Returns: Pointer to the created object

wi_set_field_real

Set a real field on an object
Parameters:

• wi_state_t* state: Wi state instance
• wi_object_t* object: Target object
• const char* name: Field name
• wi_real_t real: Value to set

wi_set_field_bool

Set a boolean field on an object
Parameters:

• wi_state_t* state: Wi state instance
• wi_object_t* object: Target object
• const char* name: Field name
• bool boolean: Value to set

wi_set_field_string

Set a string field on an object
Parameters:

• wi_state_t* state: Wi state instance
• wi_object_t* object: Target object
• const char* name: Field name
• char* string: Value to set

wi_set_field_userdata

Set userdata as a field on an object
Parameters:

• wi_state_t* state: Wi state instance
• wi_object_t* object: Target object
• const char* name: Field name
• void* userdata: Pointer to userdata
• wi_userdata_finalizer_fn_t finalizer: Userdata finalizer

wi_set_field_foreign

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

• wi_state_t* state: Wi state instance
• wi_object_t* object: Target object
• const char* name: Field name
• wi_foreign_fn_t fn: Pointer to the C function implementation
• int arity: Function's arity (number of arguments it expects)

wi_new_state

Create a new Wi state instance
Parameters:

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

Returns: Created Wi state instance

wi_delete_state

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

• wi_state_t* state: Wi state instance

wi_state_print_backtrace

Print the current call stack backtrace to stderr
Parameters:

• wi_state_t* state: Wi state instance

wi_state_error

Throw a runtime error in the state
Parameters:

• wi_state_t* 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_t* 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_t* state: Wi state instance

wi_state_run

Execute Wi code
Parameters:

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

Returns: Run result

wi_slot_is_real

Slot functions are 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. / / Check if a slot contains a real value
Parameters:

• wi_state_t* 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_t* 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_t* 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_t* 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_t* 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_t* 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_t* 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_t* 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_t* state: Wi state instance
• int slot: Slot index (0-[arg_count])

wi_slot_set_userdata

Store userdata in a slot
Parameters:

• wi_state_t* 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_t finalizer: Userdata finalizer

wi_slot_get_real

Get a real value from a slot
Parameters:

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

Returns: Real stored in a slot

wi_slot_get_bool

Get a boolean value from a slot
Parameters:

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

Returns: Boolean stored in a slot

wi_slot_get_string

Get a string value from a slot
Parameters:

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

Returns: String stored in a slot

wi_slot_get_userdata

Get userdata from a slot
Parameters:

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

Returns: Userdata stored in a slot

wi_slot_check_real

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

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

Returns: Real stored in a slot

wi_slot_check_bool

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

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

Returns: Boolean stored in a slot

wi_slot_check_string

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

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

Returns: String stored in a slot

wi_slot_check_userdata

Get userdata from a slot with type-checking
Parameters:

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

Returns: 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: "1.0.0"
Wi version as a string

Constants

WI_VERSION_MAJOR

Value: 1

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: 1048576
Initial heap size before first collection

WI_GC_HEAP_GROW_FACTOR

Value: 2
Heap growth factor per garbage collection run

WI_GC_TEMP_ROOTS_MAX

Value: 15
Maximum number of temporary GC root references

WI_CALL_FRAMES_COUNT

Value: 16384
Maximum number of call frames

WI_STACK_COUNT

Value: 65535
Maximum number of values on the VM stack

Types

wi_conf_flag_t

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_t

Configuration bitmask type

Functions

wi_conf_set

Set a configuration flag
Parameters:

• wi_conf_t* conf: Configuration bitmask
• wi_conf_flag_t flag: Configuration flag

wi_conf_is_set

Check if a configuration flag is set
Parameters:

• wi_conf_t* conf: Configuration bitmask
• wi_conf_flag_t flag: Configuration flag

Returns: true if the flag is set, false otherwise