UnQLite C/C++ API Reference - Constant Expansion Mechanism.

Syntax

int unqite_create_constant(

unqlite_vm *pVm,

const char *zName,

void (*xExpand)(unqlite_value *pValue,void *pUserData),

void *pUserData

);

Constant Expansion Mechanism - Expand a constant to the desired value via user installable callbacks.

Description

This routine is used to register constants which are expanded later to the desired value when invoked from the running Jx9 script. The constant expansion mechanism under UnQLite is extremely powerful yet simple and work as follows:

Each registered constant have a C procedure associated with it. This procedure known as the constant expansion callback is responsible of expanding the invoked constant to the desired value. For example the C procedure associated with the “__PI__” constant expands to 3.14 (the value of PI), the “__OS__” constant expands to the name of the host Operating System (Windows, Linux) and so on.

The third and most important parameter this function takes is an application-defined procedure responsible of expanding the constant to the desired value. This procedure must accept two arguments. The first argument is a pointer to a unqlite_value that the procedure must fill with the desired value for example 3.14 (value of PI) is stored in this pointer. Use the following interfaces to populate this object with the desired value:

unqlite_value_int()

unqlite_value_int64()

unqlite_value_bool()

unqlite_value_null()

unqlite_value_double()

unqlite_value_string()

unqlite_value_string_format()

unqlite_value_resource()

The second argument is a copy of the fourth argument to this function which is forwarded verbatim by engine.

Built-in constants may be overloaded by new application-defined constants. Note that Jx9 is shipped with more than 142 built-in constants installed using exactly this interface.

A valid constant name starts with a letter or underscore, followed by any number of letters, numbers or underscores. Also note that constants names are case-sensitive.

This function must be called before Jx9 program execution via unqlite_vm_exec().

You can refer to the following guide for an introductory course to this interface and the constant expansion mechanism in general.

Parameters

pVm	A pointer to a UnQLite Virtual Machine.
zName	A pointer to a null terminated string holding the name of the constant to be expanded for example __PI__, __OS__, __EOL__.
xExpand	Host-application defined procedure responsible of expanding the constant to the desired value.
pUserDara	Arbitrary user pointer which is forwarded verbatim by the engine to the callback as its second argument.

Return value

UNQLITE_OK is returned on success. Any other return value typically (UNQLITE_NOMEM) indicates failure

Example

Compile this C file for a smart introduction to this interface.