Functions for loading Teascript source or precompiled bytecode, serializing compiled functions, evaluating strings and importing modules. Loading never runs the code: a successful load pushes the compiled chunk as a function, which you then run with tea_call or tea_pcall. Each loader comes in two forms: the x variant takes a mode argument selecting text or binary input, and the plain variant accepts both.
Calling a loaded chunk is covered in the Calls section.
TEA_SIGNATURE
Signature
#define TEA_SIGNATURE "\x1bTea"Description
<esc>Tea) that start every precompiled chunk produced by tea_dump. The loaders use it to tell binary chunks from source text.tea_Reader
Signature
typedef const char* (*tea_Reader)(tea_State* T, void* ud, size_t* sz);Description
Type of the function that tea_load and tea_loadx call repeatedly to get successive pieces of a chunk. Each call returns a pointer to the next piece and stores its size in *sz. To signal the end of the chunk, return NULL and set *sz to 0.
The returned piece must stay valid until the next call to the reader.
Parameters
T- Teascript state
ud- User data given to the loader
sz- Receives the size of the returned piece
Example
typedef struct Source
{
const char* text;
int done;
} Source;
static const char* string_reader(tea_State* T, void* ud, size_t* sz)
{
Source* s = (Source*)ud;
(void)T;
if(s->done)
{
*sz = 0;
return NULL;
}
s->done = 1;
*sz = strlen(s->text);
return s->text;
}
tea_Writer
Signature
typedef int (*tea_Writer)(tea_State* T, void* ud, const void* p, size_t sz);Description
tea_dump calls with each successive piece of the serialized chunk. p points to sz bytes. Return 0 to continue; any other value stops the dump and is returned by tea_dump.Parameters
T- Teascript state
ud- User data given to
tea_dump p- Pointer to the piece of data
sz- Size of the piece in bytes
Example
static int file_writer(tea_State* T, void* ud, const void* p, size_t sz)
{
(void)T;
return fwrite(p, 1, sz, (FILE*)ud) == sz ? 0 : 1;
}
See also
tea_loadx
Signature
int tea_loadx(tea_State* T, tea_Reader reader, void* data, const char* name, const char* mode);Description
Loads a chunk using the reader function reader, which is called repeatedly to supply successive pieces of it. data is passed through to the reader.
name is the chunk’s name, used in error messages and as the module environment name. mode controls what is accepted: "t" for text source, "b" for binary bytecode, and "bt" for both. NULL is the same as "bt".
On success the compiled chunk is pushed as a function, ready to be called. On failure an error code is returned and the error message is pushed instead.
Parameters
T- Teascript state
reader- Callback that returns the next piece of the chunk
data- User data passed to
reader name- Chunk name, used in error messages and as the module environment name
mode- Accepted input:
"t","b","bt"orNULL
Returns
TEA_OK on success; otherwise an error code.
Example
Source src = { "return 1 + 2", 0 }; /* Source and string_reader: see tea_Reader */
if(tea_loadx(T, string_reader, &src, "=inline", "t") == TEA_OK)
{
tea_pcall(T, 0); /* run it: the result replaces the function */
printf("%g\n", tea_get_number(T, -1)); /* 3 */
tea_pop(T, 1);
}
See also
tea_load
Signature
int tea_load(tea_State* T, tea_Reader reader, void* data, const char* name);Description
tea_loadx with mode set to NULL, accepting both text and binary chunks.Parameters
T- Teascript state
reader- Callback that returns the next piece of the chunk
data- User data passed to
reader name- Chunk name, used in error messages and as the module environment name
Returns
TEA_OK on success; otherwise an error code.
Example
Source src = { "return 'hello'", 0 }; /* Source and string_reader: see tea_Reader */
if(tea_load(T, string_reader, &src, "=greeting") == TEA_OK
&& tea_pcall(T, 0) == TEA_OK)
{
printf("%s\n", tea_get_string(T, -1));
}
tea_pop(T, 1); /* the result, or the error message */
See also
tea_load_filex
Signature
int tea_load_filex(tea_State* T, const char* filename, const char* name, const char* mode);Description
filename. name is used in error messages and as the module environment name; if it is NULL, filename is used instead. mode has the same meaning as in tea_loadx.Parameters
T- Teascript state
filename- Path of the file to load
name- Chunk name used in error messages; may be
NULL mode- Accepted input:
"t","b","bt"orNULL
Returns
TEA_OK on success; otherwise an error code.
Example
if(tea_load_filex(T, "script.tea", "=script", "t") == TEA_OK)
{
tea_pcall(T, 0);
tea_pop(T, 1);
}
See also
tea_load_file
Signature
int tea_load_file(tea_State* T, const char* filename, const char* name);Description
tea_load_filex with mode set to NULL.Parameters
T- Teascript state
filename- Path of the file to load
name- Chunk name used in error messages; may be
NULL
Returns
TEA_OK on success; otherwise an error code.
Example
if(tea_load_file(T, "config.tea", "=config") == TEA_OK)
tea_pcall(T, 0);
See also
tea_load_bufferx
Signature
int tea_load_bufferx(tea_State* T, const char* buffer, size_t size, const char* name, const char* mode);Description
buffer of size bytes. name and mode behave as in tea_loadx. The buffer may contain embedded NUL bytes.Parameters
T- Teascript state
buffer- Pointer to the chunk data
size- Size of the buffer in bytes
name- Chunk name used in error messages; may be
NULL mode- Accepted input:
"t","b","bt"orNULL
Returns
TEA_OK on success; otherwise an error code.
Example
const char* src = "return 6 * 7";
if(tea_load_bufferx(T, src, strlen(src), "=answer", "t") == TEA_OK
&& tea_pcall(T, 0) == TEA_OK)
{
printf("%d\n", (int)tea_get_integer(T, -1)); /* 42 */
}
tea_pop(T, 1);
See also
tea_load_buffer
Signature
int tea_load_buffer(tea_State* T, const char* buffer, size_t size, const char* name);Description
tea_load_bufferx with mode set to NULL.Parameters
T- Teascript state
buffer- Pointer to the chunk data
size- Size of the buffer in bytes
name- Chunk name used in error messages; may be
NULL
Returns
TEA_OK on success; otherwise an error code.
Example
const char* src = "return 'buffered'";
if(tea_load_buffer(T, src, strlen(src), "=buf") == TEA_OK)
tea_pcall(T, 0);
tea_pop(T, 1);
See also
tea_dump
Signature
int tea_dump(tea_State* T, tea_Writer writer, void* data);Description
Serializes the function on top of the stack into bytecode, calling writer with successive pieces of the output. data is passed through to the writer. The function is not popped.
This is the counterpart of tea_loadx: use it to precompile chunks or to save compiled code. The output starts with TEA_SIGNATURE.
Parameters
T- Teascript state
writer- Callback invoked with each piece of output
data- User data passed to
writer
Returns
TEA_OK on success; otherwise the non-zero value returned by the writer.
Example
/* a compiled function is on top of the stack; file_writer: see tea_Writer */
FILE* fp = fopen("out.tbc", "wb");
int status = tea_dump(T, file_writer, fp);
fclose(fp);
tea_pop(T, 1);
See also
tea_eval
Signature
int tea_eval(tea_State* T, const char* s);Description
Loads the NUL-terminated string s, runs it, and leaves the result on the stack. On failure an error code is returned and the error value is left on the stack instead.
Unlike tea_load_buffer, the source is a C string and cannot contain embedded NUL bytes.
Parameters
T- Teascript state
s- Source code to evaluate
Returns
TEA_OK on success; otherwise an error code.
Example
if(tea_eval(T, "1 + 2 * 3") == TEA_OK)
{
printf("%g\n", tea_get_number(T, -1)); /* 7 */
}
tea_pop(T, 1); /* the result, or the error value */
See also
tea_import
Signature
void tea_import(tea_State* T, const char* name);Description
name, loading and running it first if it has not been loaded yet, and pushes the module onto the stack. This is the C counterpart of the import statement in Teascript.Parameters
T- Teascript state
name- Logical name of the module
Example
tea_import(T, "math");
if(tea_get_key(T, -1, "sqrt"))
{
tea_push_number(T, 16.0);
tea_call(T, 1);
printf("%g\n", tea_get_number(T, -1)); /* 4 */
tea_pop(T, 1); /* the result */
}
tea_pop(T, 1); /* the module */
See also
tea_do_file
Signature
#define tea_do_file(T, fn) (tea_load_file(T, fn, NULL) || tea_pcall(T, 0))Description
fn and runs it in protected mode. Leaves exactly one value on the stack: the chunk’s result on success, or the error value on failure.Parameters
T- Teascript state
fn- Path of the file to run
Returns
TEA_OK on success; otherwise an error code.
Example
if(tea_do_file(T, "script.tea") != TEA_OK)
fprintf(stderr, "%s\n", tea_get_string(T, -1));
tea_pop(T, 1);