Functions for creating, configuring and destroying a Teascript state. A tea_State represents the entire interpreter context and must exist before any other function of the C API can be called. This section covers creating a state, providing a custom memory allocator, storing command-line arguments for scripts to access, and installing a panic handler for unprotected errors. Creating a state at startup and closing it at shutdown ensures that all resources, including userdata with finalizers, are released cleanly.

tea_State

Signature

typedef struct tea_State tea_State;

Description

An opaque structure that holds the whole interpreter context: the stack, the garbage collector, the global and module environments, and the allocator. Every function of the C API takes a pointer to a tea_State as its first argument (named T throughout this documentation).

A state is created with tea_new_state or tea_open and destroyed with tea_close. Its contents are private and must only be accessed through the API.

Example

tea_State* T = tea_open();
/* ... pass T to every other API function ... */
tea_close(T);

See also

tea_new_state, tea_open, tea_close

tea_new_state

Signature

tea_State* tea_new_state(tea_Alloc allocf, void* ud);

Description

Creates a new Teascript state. This is the first function to call when embedding Teascript into an application. The state holds the entire interpreter context, including the stack, the garbage collector, and the global and module environments.

If allocf is NULL, the default allocator is used. Use tea_open for the common case of a state with the default allocator.

Parameters

allocf
A custom memory allocator function, or NULL to use the default allocator
ud
An opaque pointer passed as the first argument to allocf; may be NULL

Returns

A pointer to the new state, or NULL if the allocation of the state fails.

Example

tea_State* T = tea_new_state(NULL, NULL);
if(T == NULL)
{
    fprintf(stderr, "Failed to create Tea state\n");
    return 1;
}
/* ... use the state ... */
tea_close(T);

See also

tea_open, tea_close, tea_set_allocf

tea_open

Signature

#define tea_open() tea_new_state(NULL, NULL)

Description

Creates a new Teascript state with the default allocator. Equivalent to tea_new_state(NULL, NULL).

Returns

A pointer to the new state, or NULL if the allocation of the state fails.

Example

tea_State* T = tea_open();
if(T == NULL)
    return 1;
tea_close(T);

See also

tea_new_state, tea_close

tea_close

Signature

void tea_close(tea_State* T);

Description

Closes and destroys the state, releasing all memory associated with it. Any userdata finalizers are called during this process.

After calling this function, the state pointer must not be used again.

Parameters

T
Teascript state to close

Example

tea_State* T = tea_open();
tea_do_file(T, "script.tea");
tea_close(T);   /* T is no longer valid */

See also

tea_new_state, tea_open, tea_set_finalizer

tea_set_argv

Signature

void tea_set_argv(tea_State* T, int argc, char** argv, int argf);

Description

Stores command-line arguments in the state, making them accessible to scripts. argf is the index in argv of the first non-option argument, or 0 if there is none. Scripts typically use this to parse their own options.

The array is stored by reference, not copied: argv and the strings it points to must stay valid for the lifetime of the state.

Parameters

T
Teascript state
argc
Number of command-line arguments
argv
Array of C strings holding the arguments
argf
Index of the first non-option argument, or 0 if none

Example

int main(int argc, char** argv)
{
    tea_State* T = tea_open();
    /* argv[1] is the script, so the first non-option argument is at 1 */
    tea_set_argv(T, argc, argv, 1);
    tea_do_file(T, argv[1]);
    tea_close(T);
    return 0;
}

See also

tea_get_argv

tea_get_argv

Signature

int tea_get_argv(tea_State* T, char*** argv, int* argf);

Description

Retrieves the command-line arguments previously stored with tea_set_argv. argv and argf may be NULL if only the argument count is needed.

Parameters

T
Teascript state
argv
Receives the argument array, or NULL
argf
Receives the index of the first non-option argument, or NULL

Returns

The number of command-line arguments.

Example

char** argv;
int argf;
int argc = tea_get_argv(T, &argv, &argf);
printf("Script received %d arguments\n", argc);
for(int i = argf; i < argc; i++)
    printf("  arg[%d] = %s\n", i, argv[i]);

See also

tea_set_argv

tea_atpanic

Signature

tea_CFunction tea_atpanic(tea_State* T, tea_CFunction panicf);

Description

Sets a new panic function and returns the old one. The panic function is called when an unprotected error occurs (for example, an error raised outside of any tea_pcall). It receives the state with the error value on top of the stack.

The default panic function prints a message to stderr and aborts the program. A custom panic function must not return normally: it must terminate the process or recover by other means, such as a long jump.

Parameters

T
Teascript state
panicf
The new panic function, or NULL to keep the current one

Returns

The previous panic function.

Example

static void my_panic(tea_State* T)
{
    const char* msg = tea_to_string(T, -1);
    fprintf(stderr, "PANIC: %s\n", msg ? msg : "(no message)");
    exit(EXIT_FAILURE);
}

tea_atpanic(T, my_panic);

See also

tea_error, tea_throw, tea_pcall

tea_get_allocf

Signature

tea_Alloc tea_get_allocf(tea_State* T, void** ud);

Description

Returns the memory allocator function currently used by the state and, optionally, its user data pointer. Use it when you need allocations that are tracked by the same allocator.

Parameters

T
Teascript state
ud
Receives the allocator user data, or NULL

Returns

The current allocator function.

Example

void* ud;
tea_Alloc alloc = tea_get_allocf(T, &ud);
char* buf = (char*)alloc(ud, NULL, 0, 256);   /* allocate 256 bytes */
/* ... use buf ... */
alloc(ud, buf, 256, 0);                       /* free it */

See also

tea_set_allocf, tea_new_state, tea_alloc

tea_set_allocf

Signature

void tea_set_allocf(tea_State* T, tea_Alloc f, void* ud);

Description

Changes the memory allocator used by the state. This is only safe when no other Teascript resources are live, typically right after creating the state.

If f is NULL, the allocator is left unchanged. Likewise, if ud is NULL, the user data is left unchanged, so it cannot be reset to NULL with this function.

Parameters

T
Teascript state
f
The new allocator function, or NULL to keep the current one
ud
The allocator user data, or NULL to keep the current one

Example

static void* my_alloc(void* ud, void* ptr, size_t osize, size_t nsize)
{
    (void)ud; (void)osize;
    if(nsize == 0)
    {
        free(ptr);
        return NULL;
    }
    return realloc(ptr, nsize);
}

tea_State* T = tea_open();
tea_set_allocf(T, my_alloc, NULL);

See also

tea_get_allocf, tea_new_state