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
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
NULLto use the default allocator ud- An opaque pointer passed as the first argument to
allocf; may beNULL
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
Signature
#define tea_open() tea_new_state(NULL, NULL)Description
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_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_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
0if 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
Signature
int tea_get_argv(tea_State* T, char*** argv, int* argf);Description
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_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
NULLto 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);
tea_get_allocf
Signature
tea_Alloc tea_get_allocf(tea_State* T, void** ud);Description
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
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
NULLto keep the current one ud- The allocator user data, or
NULLto 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);