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);Description
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_opt_bool
Signature
bool tea_opt_bool(tea_State* T, int index, bool def);Description
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
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_opt_number
Signature
tea_Number tea_opt_number(tea_State* T, int index, tea_Number def);Description
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
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_opt_integer
Signature
tea_Integer tea_opt_integer(tea_State* T, int index, tea_Integer def);Description
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
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_opt_pointer
Signature
const void* tea_opt_pointer(tea_State* T, int index, void* def);Description
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
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_opt_lstring
Signature
const char* tea_opt_lstring(tea_State* T, int index, const char* def, size_t* len);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
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_opt_string
Signature
const char* tea_opt_string(tea_State* T, int index, const char* def);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
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_opt_userdata
Signature
void* tea_opt_userdata(tea_State* T, int index, void* def);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
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_opt_cfunction
Signature
tea_CFunction tea_opt_cfunction(tea_State* T, int index, tea_CFunction def);Description
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
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 */
}