TeaScript

TeaScript Core Library Documentation

Here you find the documentation of the TeaScript Core Library which is integrated into TeaScript and usable from within scripts.

Hence the API is not yet finalized, the documentation is provided in a simplified form. During time (and API finalization) the documentation will be enriched as well.

How to read an entry. Each entry shows a one-line signature followed by a short description. The signature follows the pattern name(arg: Type, …) -> ReturnType for functions, and name : Type for predefined variables. Common types are Bool, i64, f64, u8, u64, String, Tuple, Map, Buffer, Error, Any, and Number (any numeric type). A := after a parameter marks a default value; (in/out) marks a parameter passed via shared assign.

Predefined Types

These predefined names hold TypeInfo values, so they can be used in is / as checks (e.g. if (val is String) { … }) and as signature annotations throughout the rest of this page.

Bool : TypeInfo

The boolean type. Values are true and false.

i64 : TypeInfo

Signed 64-bit integer. TeaScript's only signed integral type.

u64 : TypeInfo

Unsigned 64-bit integer.

u8 : TypeInfo

Unsigned 8-bit integer. Most commonly seen with buffers (one byte at a time).

f64 : TypeInfo

64-bit floating-point number.

String : TypeInfo

UTF-8 string type.

Tuple : TypeInfo

Heterogeneous, ordered, optionally-named collection. Used as TeaScript's general-purpose container (records, arrays, stacks, …).

Map : TypeInfo

Key-value container with keys kept in sorted order; keys may be of mixed type as long as they are comparable. Available since 0.17.0 β€” see Map support for the full API.

Buffer : TypeInfo

Contiguous byte buffer β€” see Buffer support for the full API.

Error : TypeInfo

The error type returned by fallible Core Library functions (since API version 1).

Function : TypeInfo

The function type. Matches any TeaScript function value in is checks.

IntegerSequence : TypeInfo

The type of values produced by _seq. Usable in forall loops.

TypeInfo : TypeInfo

The type of every predefined type binding on this page, including itself.

Number : TypeInfo

Fake concept matching any numeric type (i64, u64, u8, f64). Useful in is checks when you want "any number" rather than a specific representation.

Const : TypeInfo

Fake concept matching const-qualified values. Useful in is checks to distinguish a constant from a mutable variable.

NaV : TypeInfo

"Not a Value" β€” the type of the void value. Used as a function return type when nothing meaningful is returned.

Predefined Variables

_version_major : i64

Major version of TeaScript.

_version_minor : i64

Minor version of TeaScript.

_version_patch : i64

Patch version of TeaScript.

_version_combined_number : i64

Combined version number for easy version comparisons.

_version_build_date_time : String

Build date and time as a string.

_api_version : i64

Version of the Core Library API.

features : Tuple

A named tuple describing which optional features were compiled into the Library / Host application. Elements: format, color, toml (all Bool), json (i64), and json_adapter (String, the name of the active JSON adapter).

_init_core_stamp : f64

Time stamp in fractional seconds from an unspecified time point during program start.

_core_config : i64

Combined enum teascript::config::eConfig value used to bootstrap the Core Library.

_exit_success : i64

Exit code indicating success (used especially with _exit).

_exit_failure : i64

Exit code indicating failure (used especially with _exit).

void : NaV

"Not a Value." Convenience so you can write return void when a function shall return nothing.

PI : f64

The constant number Ο€.

Core Functions

_out(s: String) -> void

Prints s to stdout.

_err(s: String) -> void

Prints s to stderr.

print(val: Any) -> void

Prints val to stdout, doing to-string conversion of the parameter.

println(val: Any) -> void

Prints val followed by a line feed to stdout, doing to-string conversion of the parameter.

_print_version() -> void

Prints the TeaScript version string (<name> X.Y.Z) followed by a line feed to stdout.

readline() -> String

Reads a line from stdin (blocking until the line is finished) and returns it without the trailing line feed.

_exit(code: Any) -> void

Exits the script (with stack unwinding / scope cleanup) using code as the return value. This function never returns.

_strtonum(s: String) -> i64 | Error

Converts a string to i64. Returns an Error on failure. Works only with real String parameters. An alternative is +str.

_strtonumex(s: String) -> i64 | u8 | u64 | f64 | Error

Converts a string to i64, u8, u64 or f64. Returns an Error on failure. Works only with real String objects.

_numtostr(n: i64) -> String

Converts an i64 to a String. Works only with real i64 parameters. An alternative is num % "".

_f64toi64(n: f64) -> i64

Deprecated Converts an f64 to i64. Same effect as trunc() but yields an i64. Use a cast instead.

to_string(val: Any) -> String

Converts val to a string. If val is an integer, _numtostr is an alternative.

to_number(val: Any) -> i64 | u8 | u64 | f64 | Error

Converts val to a number. Returns an Error on failure. If val is a String, _strtonum / _strtonumex is an alternative.

to_f64(val: Any) -> f64 | Bool

Provisional Ensures val is used as f64. val must already be a number; returns an Error on failure. Will be replaced by a cast later. Typical use: to_f64(to_number(some_var)).

to_i64(val: Any) -> i64 | Bool

Provisional Ensures val is used as i64. val must already be a number; returns an Error on failure. Will be replaced by a cast later. Typical use: to_i64(to_number(some_var)).

_eval(code: String) -> Any

Parses and evaluates the string as TeaScript code and returns its result.

eval_file(path: String) -> Any

Parses and evaluates the content of the file and returns its result. All functions and variables defined in the top-level scope stay available.

print_error(e: Any) -> void

Prints e followed by a line feed to stderr, doing to-string conversion (usually e should be a String or Error).

fail() -> void

Exits the script (with stack unwinding / scope cleanup) with error code _exit_failure. Never returns.

fail_with_error(error_code: i64) -> void

Exits the script (with stack unwinding / scope cleanup) using the given error code. Never returns.

fail_with_message(err: Any, error_code: i64) -> void

Prints err to stderr (usually err should be a String or Error), then exits the script (with stack unwinding / scope cleanup) using the given error code. Never returns.

clock() -> f64

Returns the local wall-clock time of the current day in (fractional) seconds.

clock_utc() -> f64

Returns the UTC time of the current day in (fractional) seconds.

_timestamp() -> f64

Returns the elapsed time in (fractional) seconds from an unspecified time point during program start. Monotonically increasing.

sleep(seconds: i64) -> void

Sleeps for at least the given amount of seconds.

random(start: i64, end: i64) -> i64

Creates a random number in [start, end]. Both bounds must be >= 0 and <= UINT_MAX.

min(a: Any, b: Any) -> Any

Returns the smaller of a and b.

max(a: Any, b: Any) -> Any

Returns the larger of a and b.

clamp(val: Any, low: Any, high: Any) -> Any

Returns low if val is less than low, high if val is greater than high, otherwise val. Garbage in, garbage out.

swap(a: Any, b: Any) -> void

Swaps the values of a and b. Both parameters are passed via shared assign.

abs(n: Number) -> Number

Returns the absolute value of n (as the same type as n). n must be a number.

trunc(n: Number) -> f64
_trunc(n: f64) -> f64

Rounds the given number toward zero as f64. For example, 1.9 yields 1.0 and -2.9 yields -2.0. trunc does to-number conversion on input; _trunc is the lower-level primitive that requires n to already be an f64.

floor(n: Number) -> f64

Rounds the given number down to the next smaller integer as f64. For example, 1.9 yields 1.0 and -2.1 yields -3.0.

ceil(n: Number) -> f64

Rounds the given number up to the next greater integer as f64. For example, 1.1 yields 2.0 and -1.9 yields -1.0.

round(n: Number) -> f64

Rounds the given number to the nearest integer as f64. For example, 1.1 yields 1.0; both 1.6 and 1.5 yield 2.0.

pow(base: Any, exp: i64) -> f64

Computes base raised to the integer exponent exp. If exp is a float, it gets truncated. To-number conversion is applied to base. Returns an f64.

sqrt(n: Any) -> f64
_sqrt(n: f64) -> f64

Computes the square root of the given input. sqrt does to-number conversion on input; _sqrt is the lower-level primitive that requires n to already be an f64.

timevals(t: f64,
         HH: i64, MM: i64, S: i64, ms: i64) -> Bool

Computes the hour, minute, second and (optionally) millisecond parts of the given time in seconds (e.g. from clock()). Note: hours can be greater than 23/24 β€” the value is not cut at the day boundary.

timetostr(t: f64, with_ms: Bool) -> String | Bool

Builds a 24-hour wall-clock string with format HH:MM:SS.mmm (milliseconds are optional). Note: if t exceeds 24 hours the result is not cut.

rolldice(eyes: i64) -> i64

Randomly rolls a die with eyes faces and returns the result.

inc(n: Number (in/out), step: Number := 1) -> Number

Increments n by step (default 1).

dec(n: Number (in/out), step: Number := 1) -> Number

Decrements n by step (default 1).

_seq(start: i64, end: i64, step: i64) -> Sequence

Creates an IntegerSequence of [start, end] with the given step. If end is smaller than start, step must be negative. The sequence starts at start and the next value is current + step. If end cannot be reached exactly by stepping, the value remains at the last current β€” for example, _seq(1, 10, 2) produces 1, 3, 5, 7, 9. Sequences can be used in forall loops.

_error_get_code(e: Error) -> i64

Returns the code of the Error as i64.

_error_get_name(e: Error) -> String

Returns the name of the Error as a string.

_error_get_message(e: Error) -> String

Returns the message of the Error as a string.

make_runtime_error(message: String) -> Error

Creates a runtime Error with the given message. An alternative is "str" as Error.

Tuple helper functions

_tuple_create(...) -> Tuple

Creates a tuple from the passed parameters. Parameter count is variable; each parameter can be of any type.

_tuple_named_create(...) -> Tuple

Creates a named tuple from the given parameters. Each parameter must be a 2-element tuple whose first element is a String (the name) and whose second element can be any type. Example: _tuple_named_create(("name", "John"), ("age", 31)).

_tuple_size(tup: Tuple) -> i64

Returns the element count of the tuple.

_tuple_same_types(a: Tuple, b: Tuple) -> Bool

Checks whether the two tuples have the same types in exactly the same order (and with the same names).

_tuple_val(tup: Tuple, idx: i64) -> Any

Returns the value at the given index.

_tuple_named_val(tup: Tuple, name: String) -> Any

Returns the value with the given name, or throws if it does not exist.

_tuple_set(tup: Tuple, idx: i64, val: Any) -> void

Sets the value at the given index, or throws if the index does not exist.

_tuple_named_set(tup: Tuple, name: String, val: Any) -> void

Sets the value with the given name, or throws if the name does not exist.

_tuple_append(tup: Tuple, val: Any) -> void

Appends a new value to the end as a new element.

_tuple_named_append(tup: Tuple, name: String, val: Any) -> Bool

Appends a new value with the given name to the end as a new element if that name does not exist yet.

_tuple_insert(tup: Tuple, idx: i64, val: Any) -> void

Inserts a new value at the given index.

_tuple_named_insert(tup: Tuple, idx: i64,
                    name: String, val: Any) -> void

Inserts a value with the given name at the given index.

_tuple_remove(tup: Tuple, idx: i64) -> Bool

Removes the element at the given index; returns whether an element has been removed.

_tuple_named_remove(tup: Tuple, name: String) -> Bool

Removes the element with the given name; returns whether an element has been removed.

_tuple_index_of(tup: Tuple, name: String) -> i64

Returns the index of the element with the given name, or -1 if not found.

_tuple_name_of(tup: Tuple, idx: i64) -> String

Returns the name of the element at the given index, or throws if the index does not exist.

_tuple_swap(tup: Tuple, a: i64, b: i64) -> void

Swaps the elements at the given indices.

tuple_print(tup: Tuple, root_name: String,
            max_nesting: i64) -> void

Recursively prints all (named) elements of tup for debugging. root_name is used as the printed root name; max_nesting caps recursion depth.

tuple_contains(tup: Tuple, idx_or_name: Any) -> Bool

Returns whether tup contains the given name (String) or index (i64).

stack_push(stack: Tuple, val: Any) -> void

Pushes val to the end of the tuple, treating it as a stack. Equivalent to _tuple_append.

stack_pop(stack: Tuple) -> Any

Removes the last element of the tuple and returns its value, treating the tuple as a stack. Returns void if the tuple is empty.

Map support

A Map is a distinct key-value container type, available since TeaScript 0.17.0. Create one with _map_create; the forall loop can iterate over it (see The map iterator tuple).

Keys may be of mixed type as long as they are mutually comparable β€” e.g. i64, u64, u8, f64 and String. Values can be of any type, including Tuple, Function and Map. Entries are kept in sorted key order, not insertion order, and every function that hands out the contents (_map_keys, _map_values, _map_kv_tuple) as well as the forall loop traverse in that same order. Numeric keys of the same kind sort numerically; with mixed key types the relative order is decided by the internal comparison, so do not rely on a particular ordering across types.

The subscript operator works on maps: reading map[key] returns the value for key and raises an error if the key does not exist β€” use _map_at when you would rather get an Error value back that can be handled with try / catch. Assigning map[key] := val inserts the entry when key is not present yet and assigns to it otherwise.

If a key cannot be compared with the keys already in the map (e.g. a Buffer), the querying functions report the miss (_map_contains returns false, _map_remove returns false) while the modifying functions return an Error and leave the map unchanged.

def map := _map_create( (2, 7), (5, "Hello"), (9, (1,2,3) ) )

println( _map_size( map ) )        // 3
println( map[5] )                  // Hello

map[2] := 23                       // assign, key exists
map[3] := 42                       // insert, key is new
println( _map_size( map ) )        // 4

_map_create(...) -> Map

Creates a map from the passed parameters. Parameter count is variable; each parameter must be a 2-element tuple of the form (key, value). Called without parameters it creates an empty map. Raises an error if a parameter is not a tuple with exactly 2 elements. Example: _map_create(("name", "John"), ("age", 31)).

_map_size(map: Map) -> i64

Returns the element count of the map.

_map_contains(map: Map, key: Any) -> Bool

Returns whether an entry for key exists in the map. Also returns false if key is not comparable with the keys already present.

_map_at(map: Map, key: Any) -> Any | Error

Returns the value stored for key, or an Error if the key does not exist or is not comparable with the existing keys. This is the error-returning counterpart to the subscript operator, which raises instead β€” so it combines well with try: def v := try _map_at( map, key ).

_map_insert(map: Map, key: Any, val: Any) -> Bool | Error

Inserts val for key if no entry for key exists yet. Returns true when the entry was inserted, false when key was already present (the existing value is kept), or an Error if key is not comparable with the existing keys.

_map_assign(map: Map, key: Any, val: Any) -> Bool | Error

Assigns val to an already existing entry for key. Returns true when the value was assigned, false when key is not present (nothing is inserted), or an Error if key is not comparable with the existing keys.

_map_insert_or_assign(map: Map, key: Any, val: Any) -> Bool | Error

Stores val for key, inserting the entry when key is not present yet and assigning to it otherwise. Returns an Error if key is not comparable with the existing keys. Note the return value: it is true for an insert and false for an assign β€” it reports whether a new entry was created, not whether the call succeeded.

_map_remove(map: Map, key: Any) -> Bool

Removes the entry for key and returns whether an entry has actually been removed. Also returns false if key is not comparable with the keys already present.

_map_keys(map: Map) -> Tuple

Returns all keys of the map as a Tuple, in sorted key order. The keys are copies, so the keys inside the map cannot be modified through the returned tuple.

_map_values(map: Map) -> Tuple

Returns all values of the map as a Tuple, ordered by their corresponding keys. Unlike the keys returned by _map_keys, the values are shared with the map rather than copied.

_map_kv_tuple(map: Map) -> Tuple

Returns all entries as a Tuple of 2-element (key, value) tuples, in sorted key order β€” the same shape _map_create accepts. As above, the keys are copies while the values are shared with the map.

The map iterator tuple

When a Map appears on the right-hand side of the in keyword of a forall loop, the loop identifier is not an i64 index as it is for a Tuple or an Integer Sequence. Instead the loop creates and advances an iterator for the current position, realized as a named Tuple with these members:

Field Type Description
idx i64 The current iterator position, counting up from 0.
key Any The key at the current position. Use it to reach the value, e.g. map[it.key]. Not present while the map is empty β€” but then the loop body does not execute at all.
_all_keys Tuple Internal. A copy of the list of all keys present in the map, taken once when the loop starts. May change in a future version β€” do not rely on it. 
def map := _map_create( (2, 6), (5, "Hello"), (9, (1,2,3) ) )

forall( it in map ) {
    println( "at idx %(it.idx): key=%(it.key), value=%(map[ it.key ])" )
}

Because _all_keys is captured once at loop start, the set of keys the loop visits is fixed when the loop begins. Inserting entries during the loop will not make them appear in the current run, and removing an entry does not skip it β€” the loop still yields that key, and looking the value up with map[it.key] would then raise an error. Iterating over an empty map executes the loop body zero times.

Minimalistic string support

_strlen(s: String) -> i64

Returns the length of the string in bytes (excluding the trailing 0).

_strglyphs(s: String) -> i64

Returns the UTF-8 (Unicode) glyph count of the string (excluding the trailing 0).

_strglyphtobytepos(s: String, glyph: i64) -> i64

Returns the byte position of the given glyph in the string, or -1 if out of range.

_strat(s: String, pos: i64) -> String

Returns a substring consisting of one complete UTF-8 code point where pos points into. Returns an empty string if out of range.

_substr(s: String, from: i64, count: i64) -> String

Returns the substring [from, from + count). count of -1 means "until end of string". Returns an empty string on invalid arguments.

_strfind(s: String, substring: String, offset: i64) -> i64

Searches for substring starting at offset and returns the position of the first occurrence, or -1 if not found.

strfind(s: String, substring: String, offset: i64 := 0) -> i64

Convenience wrapper around _strfind with a default offset of 0.

_strfindreverse(s: String, substring: String,
                offset: i64) -> i64

Searches for substring from the back (starting at offset) and returns the position of the first occurrence, or -1 if not found.

_strreplacepos(str: String, start: i64, count: i64,
               new: String) -> Bool

Replaces the section [start, start + count) in str with new. Returns false on error, e.g. when start is out of range.

strreplacefirst(str: String, what: String, new: String,
                offset: i64 := 0) -> Bool

Replaces the first occurrence of what with new starting from offset. Returns true if a replacement happened.

strreplacelast(str: String, what: String, new: String,
               offset: i64 := 0) -> Bool

Replaces the last occurrence of what with new starting from offset. Returns true if a replacement happened.

strtrim(str: String, set: String,
        leading: Bool, trailing: Bool) -> Bool

Trims the string if it starts or ends with characters in the given set.

strsplit(str: String, sep: String,
         skip_empty: Bool := false) -> Tuple

Splits the given string at every occurring separator and returns a tuple with the elements.

strjoin(tup: Tuple, sep: String,
        add_leading: Bool := false,
        add_trailing: Bool := false) -> String

Joins all elements of a tuple to a string using the given separator.

_strfromascii(char: Number) -> String | Error

Returns a string built from the given ASCII character. For invalid chars (>127) an Error is returned.

utf8_begin(s: String) -> UTF8_Iterator

Creates a UTF-8 iterator for the given string and sets .cur to the first UTF-8 glyph. See the UTF8_Iterator tuple for details.

utf8_end(it: UTF8_Iterator) -> Bool

Returns whether the given UTF-8 iterator is already at the end.

utf8_next(it: UTF8_Iterator) -> UTF8_Iterator

Advances the UTF-8 iterator (.cur) to the next UTF-8 glyph or to the end of the string.

The UTF8_Iterator tuple

utf8_begin builds the iterator as a plain Tuple; utf8_next advances it in place. It has the following elements:

Field Type Description
cur String The current UTF-8 glyph. utf8_begin sets it to the first glyph and utf8_next advances it; once iteration is finished it points to the end of the string (\0).
_pos i64 Internal: the byte offset of the current glyph within the string.
_base String Internal: a reference to the iterated string.
_size i64 Internal: the length of the string in bytes.

Only cur is meant to be read; the underscore-prefixed fields are internal bookkeeping. Use utf8_end to test for the end rather than inspecting them.

Minimalistic (text) file I/O support

Text files must be UTF-8 encoded. Paths can be relative to the current working directory or absolute.

cwd() -> String

Returns the current working directory.

change_cwd(path: String) -> Bool

Changes the current working directory.

tempdir() -> String

Returns the configured temp directory as a string.

path_exists(path: String) -> Bool

Returns whether path exists as a directory or a file.

file_exists(file: String) -> Bool

Returns whether the given file exists.

file_size(file: String) -> i64

Returns the file size in bytes. Returns -1 on error, when the file does not exist, or when the path is not a file.

last_modified(path: String) -> String

Returns the last-modified time as a string for the given path, or an empty string if the path does not exist or on error.

create_dir(path: String, recursive: Bool) -> Bool

Creates directories for the given path. recursive == true creates intermediate directories.

path_delete(path: String) -> Bool

Deletes a file or an (empty) directory.

file_copy(file: String, dest_dir: String,
          overwrite: Bool) -> Bool

Copies file to dest_dir if it does not exist there, or if overwrite is true.

file_copy_newer(file: String, dest_dir: String) -> Bool

Copies file to dest_dir if it does not exist there, or if file is newer than the one already in dest_dir.

readtextfile(file: String) -> String | Error

Reads the content of a UTF-8 text file and returns it in a string. An optional BOM is removed.

writetextfile(file: String, str: String,
              overwrite: Bool, bom: Bool) -> Bool

Writes the content of str to a text file. An optional UTF-8 BOM can be written (last parameter). overwrite indicates whether a prior existing file shall be overwritten (old content is destroyed).

readfile(file: String) -> Buffer | Error

Reads the binary content of the file into a buffer. Returns an Error on failure.

writefile(file: String, content: Buffer,
          overwrite: Bool) -> Bool

Writes the content of the buffer to the file. overwrite indicates whether a prior existing file shall be overwritten (old content is destroyed).

readdirfirst(path: String) -> Tuple

Returns the first directory entry of the given path. See the direntry tuple for details.

readdirnext(entry: Tuple) -> Tuple

Returns the next directory entry. See the direntry tuple for details.

The direntry tuple

On error, when the directory is empty, or when there are no more entries to iterate over, the tuple has the following elements:

Field Type Description
valid Bool Always false.
error i64 If greater than 0, the reported error code from std::filesystem / the OS.
path String The path which was investigated.

In all other states the tuple has the following elements:

Field Type Description
valid Bool Always true.
name String The name of the entry.
size i64 The file size (always 0 for directories).
last_modified String Last-modified date/time as a string with format %F %T (perfectly sortable).
is_file Bool true if the entry is a file, false otherwise.
is_dir Bool true if the entry is a directory, false otherwise.
path String The absolute and canonical path of the entry.
_handle Passthrough Instance of std::filesystem::directory_iterator as a Passthrough value.

JSON support

readjsonstring(s: String) -> Any

Creates a corresponding object from the given JSON-formatted string. Returns an Error on failure.

readjsonfile(file: String) -> Any

Creates a corresponding object from the given JSON-formatted file. Returns an Error on failure.

writejsonstring(val: Any) -> String | Error

Creates a JSON-formatted string from the object, or an Error on failure.

writejsonfile(val: Any) -> Bool

Writes a JSON-formatted file from the object. Returns true on success.

json_is_object(val: Any) -> Bool

Checks whether val is a JSON-compatible object.

json_is_array(val: Any) -> Bool

Checks whether val is a JSON-compatible array.

json_object_size(obj: Tuple) -> i64

Returns the element count of the object.

json_array_size(arr: Tuple) -> i64

Returns the element count of the array.

json_make_object(...) -> Tuple

Creates a JSON-compatible object from the passed parameters.

json_make_array(...) -> Tuple

Creates a JSON-compatible array from the passed parameters. Parameter count is variable; each parameter can be any type.

json_array_empty(arr: Tuple) -> Bool

Checks whether the given tuple is an empty JSON array.

json_array_append(arr: Tuple, val: Any) -> void

Appends val to a JSON-compatible array. The tuple must be compatible (i.e. json_is_array returned true).

json_array_insert(arr: Tuple, idx: i64, val: Any) -> Bool

Inserts val at index idx of a JSON-compatible array. The tuple must be compatible (i.e. json_is_array returned true).

json_array_remove(arr: Tuple, idx: i64) -> Bool

Removes the value at index idx from a JSON-compatible array. The tuple must be compatible (i.e. json_is_array returned true).

readbsonbuffer(buf: Buffer) -> Any

Creates a value of appropriate type from the given BSON buffer, or an Error on failure.

writebsonbuffer(val: Any) -> Buffer | Error

Creates a BSON buffer, or an Error on failure.

TOML support

readtomlstring(s: String) -> Tuple | Error

Creates a named tuple from the given TOML-formatted string, or an Error on failure.

readtomlfile(file: String) -> Tuple | Error

Creates a named tuple from the given TOML-formatted file, or an Error on failure.

writetomlstring(tup: Tuple) -> String | Error

Creates a TOML-formatted string from the named tuple, or an Error on failure.

writetomlfile(tup: Tuple) -> Bool

Writes a TOML-formatted file from the named tuple. Returns true on success.

toml_is_table(val: Any) -> Bool

Checks whether val is a TOML-compatible table.

toml_is_array(val: Any) -> Bool

Checks whether val is a TOML-compatible array.

toml_table_size(tab: Tuple) -> i64

Returns the element count of the table.

toml_array_size(arr: Tuple) -> i64

Returns the element count of the array.

toml_make_table(...) -> Tuple

Creates a TOML-compatible table from the passed parameters.

toml_make_array(...) -> Tuple

Creates a TOML-compatible array from the passed parameters. Parameter count is variable; each parameter can be any type.

toml_array_empty(arr: Tuple) -> Bool

Checks whether the given tuple is an empty TOML array.

toml_array_append(arr: Tuple, val: Any) -> void

Appends val to a TOML-compatible array. The tuple must be compatible (i.e. toml_is_array returned true).

toml_array_insert(arr: Tuple, idx: i64, val: Any) -> Bool

Inserts val at index idx of a TOML-compatible array. The tuple must be compatible (i.e. toml_is_array returned true).

toml_array_remove(arr: Tuple, idx: i64) -> Bool

Removes the value at index idx from a TOML-compatible array. The tuple must be compatible (i.e. toml_is_array returned true).

Color output support

make_rgb(r: i64, g: i64, b: i64) -> i64

Builds a 32-bit RGB color (garbage in, garbage out).

cprint(rgb: i64, s: String) -> void

Prints the text in the given RGB color. Only available when the library is built with libfmt.

cprintln(rgb: i64, s: String) -> void

Same as cprint but adds a line feed at the end.

Format string support

format(fmt: String, ...) -> String

Formats the string with libfmt the same way as known from C++.

Buffer support

Buffers are represented as contiguous memory and can be accessed and modified byte-wise at byte boundaries (1 byte = 8 bit). It is not possible to share-assign from a single byte of a buffer.

The subscript operator can be used to access and modify an existing byte. Buffers will not grow beyond their original capacity automatically (use _buf_resize), but their size will grow up to that capacity. Memory is freed automatically when the last reference goes out of scope or is undef'ed.

Because TeaScript has only one signed integral type (i64), all setters and getters for signed types operate with i64. Because TeaScript has only u8 and u64 as unsigned integral types, all getters and setters using a larger type than u8 operate with u64. All getters and setters operate in host byte order.

_buf(size: Number) -> Buffer

Creates an empty buffer (size == 0) with the given capacity.

_buf_size(buf: Buffer) -> u64

Returns the actual amount of used / filled bytes in the buffer.

_buf_capacity(buf: Buffer) -> u64

Returns the amount of allocated memory in bytes for the buffer.

buf_zero(buf: Buffer) -> void

Fills the complete capacity of the buffer with zeroes. Postcondition: size == capacity.

_buf_fill(buf: Buffer, pos: Number,
          count: Number, val: u8) -> Bool

Fills the buffer from pos up to pos + count with val.

_buf_fill32(buf: Buffer, pos: Number,
            count: Number, val: u64) -> Bool

Fills the buffer from pos up to pos + count with val as u32. The passed range must be divisible by 4 (sizeof u32).

_buf_resize(buf: Buffer, size: Number) -> Bool

Resizes the buffer (shrink or grow). New values are added as zero. See also _buf_fill.

_buf_copy(dst: Buffer, dst_off: Number,
          src: Buffer, src_off: Number,
          len: Number) -> Bool

Copies the src buffer into the dst buffer.

_buf_at(buf: Buffer, pos: Number) -> u8

Returns the byte at the given position. Throws on out-of-range.

Buffer getters

_buf_get_u8(buf: Buffer, pos: Number) -> u8 | Error

Gets a u8 from the buffer at the given position. Returns an Error on failure.

_buf_get_u16(buf: Buffer, pos: Number) -> u64 | Error

Gets a u16 as u64 from the buffer at the given position. Returns an Error on failure.

_buf_get_u32(buf: Buffer, pos: Number) -> u64 | Error

Gets a u32 as u64 from the buffer at the given position. Returns an Error on failure.

_buf_get_u64(buf: Buffer, pos: Number) -> u64 | Error

Gets a u64 from the buffer at the given position. Returns an Error on failure.

_buf_get_i8(buf: Buffer, pos: Number) -> i64 | Error

Gets an i8 as i64 from the buffer at the given position. Returns an Error on failure.

_buf_get_i16(buf: Buffer, pos: Number) -> i64 | Error

Gets an i16 as i64 from the buffer at the given position. Returns an Error on failure.

_buf_get_i32(buf: Buffer, pos: Number) -> i64 | Error

Gets an i32 as i64 from the buffer at the given position. Returns an Error on failure.

_buf_get_i64(buf: Buffer, pos: Number) -> i64 | Error

Gets an i64 from the buffer at the given position. Returns an Error on failure.

Buffer setters

For all setters: if pos == size, the buffer will grow if the capacity is big enough.

_buf_set_u8(buf: Buffer, pos: Number, val: u8) -> Bool

Sets val as u8 in the buffer at the given position. Returns true on success.

_buf_set_u16(buf: Buffer, pos: Number, val: u64) -> Bool

Sets val as u16 in the buffer at the given position. Returns true on success.

_buf_set_u32(buf: Buffer, pos: Number, val: u64) -> Bool

Sets val as u32 in the buffer at the given position. Returns true on success.

_buf_set_u64(buf: Buffer, pos: Number, val: u64) -> Bool

Sets val as u64 in the buffer at the given position. Returns true on success.

_buf_set_i8(buf: Buffer, pos: Number, val: i64) -> Bool

Sets val as i8 in the buffer at the given position. Returns true on success.

_buf_set_i16(buf: Buffer, pos: Number, val: i64) -> Bool

Sets val as i16 in the buffer at the given position. Returns true on success.

_buf_set_i32(buf: Buffer, pos: Number, val: i64) -> Bool

Sets val as i32 in the buffer at the given position. Returns true on success.

_buf_set_i64(buf: Buffer, pos: Number, val: i64) -> Bool

Sets val as i64 in the buffer at the given position. Returns true on success.

Buffer string accessors

_buf_set_string(buf: Buffer, pos: Number,
                val: String) -> Bool

Writes the string val (without the trailing 0) into the buffer at the given position. Returns true on success.

_buf_get_string(buf: Buffer, pos: Number,
                len: Number) -> String | Error

Reads a string from the buffer at the given position. Bytes must form valid UTF-8. Returns an Error on failure.

_buf_get_ascii(buf: Buffer, pos: Number,
               len: Number) -> String | Error

Reads a string from the buffer at the given position. All values must be in the range [0, 127]. Returns an Error on failure.