Status codes returned by protected operations, and the functions that raise errors from C. tea_throw is the lowest-level primitive: it raises the value on top of the stack as the error object. tea_error builds a formatted message first, and the argument error functions produce standard “bad argument” messages for use inside C functions.

Errors raised outside of a protected call (see tea_pcall) reach the panic function set with tea_atpanic.

TEA_OK

Signature

enum
{
    TEA_OK,
    TEA_ERROR_SYNTAX,
    TEA_ERROR_RUNTIME,
    TEA_ERROR_MEMORY,
    TEA_ERROR_FILE,
    TEA_ERROR_ERROR
};

Description

Status codes returned by protected calls and by the functions that load code. TEA_OK means success; every other value is an error, and the error value is left on top of the stack.

CodeMeaning
TEA_OKNo error
TEA_ERROR_SYNTAXSyntax error while compiling
TEA_ERROR_RUNTIMERuntime error
TEA_ERROR_MEMORYMemory allocation error
TEA_ERROR_FILEError opening or reading a file
TEA_ERROR_ERRORError while running the error handling machinery

Example

int status = tea_pcall(T, 0);
switch(status)
{
    case TEA_OK:
        break;
    case TEA_ERROR_MEMORY:
        fprintf(stderr, "out of memory\n");
        break;
    default:
        fprintf(stderr, "error: %s\n", tea_get_string(T, -1));
        break;
}

See also

tea_pcall, tea_load_file, tea_eval

tea_throw

Signature

void tea_throw(tea_State* T);
[-1, +0, v]

Description

Raises an error using the value on top of the stack as the error object. The value may be of any type (typically a string) and is consumed.

This is the lowest-level error primitive: tea_error and the argument error functions are built on top of it. Use it to raise a non-string error object, or one that has already been prepared on the stack.

Parameters

T
Teascript state

Errors

Always raises an error; never returns normally.

Example

static void fail_with_map(tea_State* T)
{
    tea_new_map(T);
    tea_push_string(T, "unknown field");
    tea_set_key(T, -2, "message");     /* {message = "unknown field"} */
    tea_throw(T);
}

See also

tea_error, tea_pcall, tea_atpanic

tea_error

Signature

int tea_error(tea_State* T, const char* fmt, ...);
[-0, +0, v]

Description

Raises an error with a formatted message. fmt and the following arguments are processed like in tea_push_fstring to build the message, which is then raised with tea_throw.

The int return type exists only so the call can be written as return tea_error(...) or used in an expression; the function never returns normally.

Parameters

T
Teascript state
fmt
Format string, as in tea_push_fstring
...
Arguments for fmt

Errors

Always raises an error; never returns normally.

Example

static void divide(tea_State* T)
{
    tea_Number a = tea_check_number(T, 1);
    tea_Number b = tea_check_number(T, 2);
    if(b == 0.0)
        tea_error(T, "division by zero: %g / %g", a, b);
    tea_push_number(T, a / b);
}

See also

tea_throw, tea_arg_error, tea_push_fstring

tea_arg_error

Signature

int tea_arg_error(tea_State* T, int narg, const char* msg);
[-0, +0, v]

Description

Raises a “bad argument #narg” error that includes msg. This is the general-purpose argument error, for problems that are not type mismatches (for those, tea_type_error is more appropriate).

As with tea_error, the int return type only allows return tea_arg_error(...) or use inside tea_arg_check.

Parameters

T
Teascript state
narg
Number of the offending argument
msg
Message describing the problem

Errors

Always raises an error; never returns normally.

Example

static void set_name(tea_State* T)
{
    const char* name = tea_check_string(T, 1);
    if(name[0] == '\0')
        tea_arg_error(T, 1, "name must not be empty");
    /* ... */
}

See also

tea_type_error, tea_arglimit_error, tea_arg_check

tea_arglimit_error

Signature

int tea_arglimit_error(tea_State* T, int narg, const char* msg);
[-0, +0, v]

Description

Raises an error saying that argument narg is outside the acceptable range, for example when a number exceeds a permitted maximum. msg describes the limit. The message carries the same “bad argument #narg” prefix as tea_arg_error.

Parameters

T
Teascript state
narg
Number of the offending argument
msg
Message describing the violated limit

Errors

Always raises an error; never returns normally.

Example

static void set_quality(tea_State* T)
{
    tea_Integer q = tea_check_integer(T, 1);
    if(q < 0 || q > 100)
        tea_arglimit_error(T, 1, "quality must be in range [0, 100]");
    /* ... */
}

See also

tea_arg_error, tea_type_error

tea_type_error

Signature

int tea_type_error(tea_State* T, int narg, const char* xname);
[-0, +0, v]

Description

Raises a “bad argument #narg” error for a type mismatch. xname is the name of the expected type or userdata class, and is inserted into the message together with the actual type, as in string expected, got number.

Parameters

T
Teascript state
narg
Number of the offending argument
xname
Name of the expected type or class

Errors

Always raises an error; never returns normally.

Example

static void connect(tea_State* T)
{
    if(!tea_test_udata(T, 1, "Socket"))
        tea_type_error(T, 1, "Socket");
    /* ... */
}

See also

tea_arg_error, tea_arglimit_error, tea_test_udata

tea_arg_check

Signature

#define tea_arg_check(T, cond, narg, extramsg) ((void)((cond) || tea_arg_error(T, (narg), (extramsg))))
[-0, +0, v]

Description

Checks that cond is true and otherwise raises a bad argument error for argument narg with extramsg, by calling tea_arg_error. cond is evaluated exactly once.

Parameters

T
Teascript state
cond
Condition that must hold
narg
Number of the argument being checked
extramsg
Message used if the condition is false

Errors

Raises an error if cond is false.

Example

static void set_volume(tea_State* T)
{
    tea_Integer v = tea_check_integer(T, 1);
    tea_arg_check(T, v >= 0 && v <= 10, 1, "volume must be in range [0, 10]");
    /* ... */
}

See also

tea_arg_error, tea_arglimit_error