The types and functions used to expose C code to Teascript. A C function has the type tea_CFunction. To register many at once, describe them in an array of tea_Reg (for module functions) or tea_Methods (for class methods), terminated by an entry whose name is NULL, and register the array with tea_set_funcs or tea_set_methods. The tea_create_module and tea_create_class functions do both steps in one call.

tea_CFunction

Signature

typedef void (*tea_CFunction)(tea_State* T);

Description

The type of a C function that Teascript can call. It receives the state, with its arguments on the stack, and leaves its result on top of the stack when it returns.

The number of required and optional arguments is not part of the function itself: it is given when the function is pushed (tea_push_cfunction) or registered (tea_Reg, tea_Methods).

Example

static void add(tea_State* T)
{
    tea_Number a = tea_check_number(T, 1);
    tea_Number b = tea_check_number(T, 2);
    tea_push_number(T, a + b);   /* the result */
}

See also

tea_push_cfunction, tea_Reg, tea_Methods

tea_Reg

Signature

typedef struct tea_Reg
{
    const char* name;
    tea_CFunction fn;
    int nargs;
    int nopts;
} tea_Reg;

Description

Describes one C function to register in a module: its name, the C function fn, the number of required arguments nargs (or TEA_VARG) and the number of optional arguments nopts.

An array of tea_Reg ends with an entry whose name is NULL. In tea_create_module, an entry with a NULL fn stores nil under its name, as a placeholder.

Example

static const tea_Reg mathlib[] =
{
    {"add", math_add, 2, 0},
    {"sub", math_sub, 2, 0},
    {NULL, NULL, 0, 0}
};

See also

tea_set_funcs, tea_create_module, tea_Methods

tea_Methods

Signature

typedef struct tea_Methods
{
    const char* name;
    const char* type;
    tea_CFunction fn;
    int nargs;
    int nopts;
} tea_Methods;

Description

Describes one C method to register in a class: its name, its type, the C function fn, and the argument counts nargs and nopts. Note that type comes before fn. The type is one of:

TypeMeaning
"method"Instance method
"static"Static function
"getter"Attribute getter
"setter"Attribute setter

An array of tea_Methods ends with an entry whose name is NULL. A getter and a setter may share a name.

Example

static const tea_Methods point_methods[] =
{
    {"new",  "method", point_new,  2, 0},
    {"x",    "getter", point_getx, 0, 0},
    {"x",    "setter", point_setx, 1, 0},
    {"zero", "static", point_zero, 0, 0},
    {NULL, NULL, NULL, 0, 0}
};

See also

tea_set_methods, tea_create_class, tea_Reg

TEA_VARG

Signature

#define TEA_VARG (-255)

Description

Pass it as the nargs of a function to declare it variadic, accepting any number of arguments.

Example

tea_push_cfunction(T, path_join, TEA_VARG, 0);

See also

tea_push_cfunction, tea_push_cclosure, tea_Reg

tea_set_funcs

Signature

void tea_set_funcs(tea_State* T, const tea_Reg* reg, int nup);
[-nup, +0, m]

Description

Registers the functions in the tea_Reg array reg into the module (or other object) on the stack. For each entry, a C closure is created with nup upvalues, copied from the nup values on top of the stack, and stored under the entry’s name. When all entries are done, the nup upvalues are popped.

The object that receives the functions is the value just below the upvalues, which is the top of the stack when nup is 0. The array must end with an entry whose name is NULL.

Parameters

T
Teascript state
reg
Array of tea_Reg descriptors, ending with a NULL name
nup
Number of upvalues shared by every function

Example

static const tea_Reg mathlib[] =
{
    {"add", math_add, 2, 0},
    {"sub", math_sub, 2, 0},
    {NULL, NULL, 0, 0}
};

/* stack: [module] */
tea_set_funcs(T, mathlib, 0);

/* with one upvalue shared by every function: [module, 42] */
tea_push_integer(T, 42);
tea_set_funcs(T, mathlib, 1);   /* the upvalue is captured, then popped */

See also

tea_set_methods, tea_create_module, tea_push_cclosure

tea_set_methods

Signature

void tea_set_methods(tea_State* T, const tea_Methods* reg, int nup);
[-nup, +0, v]

Description

Registers the methods in the tea_Methods array reg into the class on the stack. The type of each entry decides how the method is bound: as an instance method, a static function, a getter or a setter. For each entry, a C closure is created with nup upvalues, copied from the nup values on top of the stack, and bound under the entry’s name. When all entries are done, the nup upvalues are popped.

The class is the value just below the upvalues, which is the top of the stack when nup is 0. The array must end with an entry whose name is NULL.

Parameters

T
Teascript state
reg
Array of tea_Methods descriptors, ending with a NULL name
nup
Number of upvalues shared by every method

Errors

Raises an error if an entry has an unrecognized type string.

Example

static const tea_Methods point_methods[] =
{
    {"new",  "method", point_new,  2, 0},
    {"x",    "getter", point_getx, 0, 0},
    {"x",    "setter", point_setx, 1, 0},
    {"zero", "static", point_zero, 0, 0},
    {NULL, NULL, NULL, 0, 0}
};

/* stack: [class Point] */
tea_set_methods(T, point_methods, 0);

/* with one upvalue shared by every method: [class Point, 100] */
tea_push_integer(T, 100);
tea_set_methods(T, point_methods, 1);   /* the upvalue is captured, then popped */

See also

tea_set_funcs, tea_create_class, tea_push_cclosure