Functions for reading optional arguments in a C function. Each tea_opt_* function returns the argument at index converted to a C value, exactly as the matching tea_check_* function would, or the default def if the argument is absent. If the argument is present but has the wrong type, a type error is raised.

The number of optional arguments a function accepts is declared when the function is pushed (the nopts parameter of tea_push_cfunction).

tea_opt_nil

Signature

void tea_opt_nil(tea_State* T, int index);
[-0, +(1|0), -]

Description

If the argument at index is absent, pushes nil in its place. Otherwise does nothing. This normalizes an optional argument slot so that later stack operations can count on a concrete value being there.

Parameters

T
Teascript state
index
Stack index of the argument

Example

tea_opt_nil(T, 2);   /* argument 2 is now at least nil */

See also

tea_check_any, tea_push_nil, tea_is_nonenil

tea_opt_bool

Signature

bool tea_opt_bool(tea_State* T, int index, bool def);
[-0, +0, v]

Description

Returns the boolean at index, or def if the argument is absent.

Parameters

T
Teascript state
index
Stack index of the argument
def
Value returned if the argument is absent

Returns

The boolean at index, or def.

Errors

Raises a type error if the argument is present but is not a boolean.

Example

static void greet(tea_State* T)
{
    const char* name = tea_check_string(T, 1);
    bool loud = tea_opt_bool(T, 2, false);
    if(loud)
        tea_push_fstring(T, "HELLO, %s!", name);
    else
        tea_push_fstring(T, "Hello, %s.", name);
}

See also

tea_check_bool, tea_get_bool

tea_opt_number

Signature

tea_Number tea_opt_number(tea_State* T, int index, tea_Number def);
[-0, +0, v]

Description

Returns the number at index, or def if the argument is absent.

Parameters

T
Teascript state
index
Stack index of the argument
def
Value returned if the argument is absent

Returns

The number at index, or def.

Errors

Raises a type error if the argument is present but is not a number.

Example

static void scale(tea_State* T)
{
    tea_Number dx = tea_opt_number(T, 1, 1.0);
    tea_Number dy = tea_opt_number(T, 2, 1.0);
    tea_push_number(T, dx * dy);
}

See also

tea_check_number, tea_opt_integer

tea_opt_integer

Signature

tea_Integer tea_opt_integer(tea_State* T, int index, tea_Integer def);
[-0, +0, v]

Description

Returns the number at index truncated to a tea_Integer, or def if the argument is absent.

Parameters

T
Teascript state
index
Stack index of the argument
def
Value returned if the argument is absent

Returns

The integer at index, or def.

Errors

Raises a type error if the argument is present but is not a number.

Example

static void repeat(tea_State* T)
{
    const char* s = tea_check_string(T, 1);
    tea_Integer n = tea_opt_integer(T, 2, 1);   /* once by default */
    for(tea_Integer i = 0; i < n; i++)
        tea_push_string(T, s);
    tea_concat(T, (int)n);
}

See also

tea_check_integer, tea_opt_number

tea_opt_pointer

Signature

const void* tea_opt_pointer(tea_State* T, int index, void* def);
[-0, +0, v]

Description

Returns the raw C pointer at index, or def if the argument is absent.

Parameters

T
Teascript state
index
Stack index of the argument
def
Pointer returned if the argument is absent

Returns

The pointer at index, or def.

Errors

Raises a type error if the argument is present but is not a pointer.

Example

static void open(tea_State* T)
{
    const char* path = tea_check_string(T, 1);
    const void* ctx = tea_opt_pointer(T, 2, NULL);
    /* ... open path, using ctx if one was given ... */
}

See also

tea_check_pointer, tea_get_pointer

tea_opt_lstring

Signature

const char* tea_opt_lstring(tea_State* T, int index, const char* def, size_t* len);
[-0, +0, v]

Description

Returns the string at index, with its length stored in *len, or def if the argument is absent. In that case the length is strlen(def), or 0 if def is NULL.

Use this variant when the string may contain embedded zero bytes.

Parameters

T
Teascript state
index
Stack index of the argument
def
String returned if the argument is absent; may be NULL
len
Receives the string length, or NULL

Returns

A pointer to the string data, or def.

Errors

Raises a type error if the argument is present but is not a string.

Example

size_t len;
const char* sep = tea_opt_lstring(T, 2, ", ", &len);
/* sep is ", " and len is 2 if argument 2 is absent */

See also

tea_check_lstring, tea_opt_string

tea_opt_string

Signature

const char* tea_opt_string(tea_State* T, int index, const char* def);
[-0, +0, v]

Description

Returns the string at index, or def if the argument is absent.

Use tea_opt_lstring if the string may contain embedded zero bytes.

Parameters

T
Teascript state
index
Stack index of the argument
def
String returned if the argument is absent; may be NULL

Returns

A pointer to the string data, or def.

Errors

Raises a type error if the argument is present but is not a string.

Example

static void log_message(tea_State* T)
{
    const char* msg = tea_check_string(T, 1);
    const char* prefix = tea_opt_string(T, 2, "[info]");
    tea_push_fstring(T, "%s %s", prefix, msg);
}

See also

tea_check_string, tea_opt_lstring

tea_opt_userdata

Signature

void* tea_opt_userdata(tea_State* T, int index, void* def);
[-0, +0, v]

Description

Returns a pointer to the data block of the userdata at index, or def if the argument is absent or nil.

The userdata’s class is not checked. When a particular class is required, use tea_test_udata or tea_check_udata.

Parameters

T
Teascript state
index
Stack index of the argument
def
Pointer returned if the argument is absent or nil

Returns

A pointer to the userdata’s data block, or def.

Errors

Raises a type error if the argument is present but is not a userdata.

Example

static void attach(tea_State* T)
{
    void* widget = tea_check_userdata(T, 1);
    void* parent = tea_opt_userdata(T, 2, NULL);
    attach_widget(widget, parent);   /* parent may be NULL */
}

See also

tea_check_userdata, tea_opt_pointer, tea_test_udata

tea_opt_cfunction

Signature

tea_CFunction tea_opt_cfunction(tea_State* T, int index, tea_CFunction def);
[-0, +0, v]

Description

Returns the C function at index, or def if the argument is absent.

Parameters

T
Teascript state
index
Stack index of the argument
def
Function returned if the argument is absent

Returns

The tea_CFunction at index, or def.

Errors

Raises a type error if the argument is present but is not a C function.

Example

static void walk(tea_State* T)
{
    tea_CFunction visit = tea_opt_cfunction(T, 1, NULL);
    /* call visit on each element if it is not NULL */
}

See also

tea_check_cfunction, tea_to_cfunction