lobster builtin function reference

lobster builtin functions:(file auto generated by compiler, do not modify) ### treesheets
`ts_goto_root()` | makes the root of the document the current cell. this is the default at the startof any script, so this function is only needed to return there.
`ts_goto_view()` | makes what the user has zoomed into the current cell.
`ts_has_selection() -> int` | wether there is a selection.
`ts_goto_selection()` | makes the current cell the one containing the selection, or does nothing on noselection.
`ts_has_parent() -> int` | wether the current cell has a parent (is the root cell).
`ts_goto_parent()` | makes the current cell the parent of the current cell, if any.
`ts_num_children() -> int` | returns the total number of children of the current cell (rows * columns).returns 0 if this cell doesn't have a sub-grid at all.
`ts_num_columns_rows() -> xy_i` | returns the number of columns & rows in the current cell.
`ts_selection() -> xy_i, xy_i` | returns the (x,y) and (xs,ys) of the current selection, or zeroes if none.
`ts_goto_child(n:int)` | makes the current cell the nth child of the current cell.
`ts_goto_column_row(col:int, row:int)` | makes the current cell the child at col / row.
`ts_get_text() -> string` | gets the text of the current cell.
`ts_set_text(text:string)` | sets the text of the current cell.
`ts_create_grid(cols:int, rows:int)` | creates a grid in the current cell if there isn't one yet.
`ts_insert_columns(c:int, n:int)` | insert n columns before column c in an existing grid.
`ts_insert_rows(r:int, n:int)` | insert n rows before row r in an existing grid.
`ts_delete(pos:xy_i, size:xy_i)` | clears the cells denoted by pos/size. also removes columns/rows if they becomecompletely empty, or the entire grid.
`ts_set_background_color(col:xyzw_f)` | sets the background color of the current cell
`ts_set_text_color(col:xyzw_f)` | sets the text color of the current cell
`ts_set_relative_size(s:int)` | sets the relative size (0 is normal, -1 is smaller etc.) of the current cell
`ts_set_style_bits(s:int)` | sets one or more styles (bold = 1, italic = 2, fixed = 4, underline = 8, strikethru = 16) on the current cell.
`ts_set_status_message(msg:string)` | sets the status message in TreeSheets.
`ts_get_filename_from_user(is_save:int) -> string` | gets a filename using a file dialog. empty string if cancelled.
### builtin
`print(x:string)` | output any value to the console (with linefeed).
`string(x:string) -> string` | convert any value to string
`set_print_depth(depth:int)` | for printing / string conversion: sets max vectors/objects recursion depth (default 10)
`set_print_length(len:int)` | for printing / string conversion: sets max string length (default 100000)
`set_print_quoted(quoted:bool)` | for printing / string conversion: if the top level value is a string, whether to convert it with escape codes and quotes (default false)
`set_print_decimals(decimals:int)` | for printing / string conversion: number of decimals for any floating point output (default -1, meaning all)
`set_print_indent(spaces:int)` | for printing / string conversion: number of spaces to indent with. default is 0: no indent / no multi-line
`get_line() -> string` | reads a string from the console if possible (followed by enter)
`if(cond, then:function, else:function = nil) -> any` | evaluates then or else depending on cond, else is optional
`while(cond:function, do:function) -> any` | evaluates body while cond (converted to a function) holds true, returns last body value
`for(iter, do:function)` | iterates over int/vector/string, body may take [ element [ , index ] ] arguments
`append(xs:[any], ys:[any]) -> [any]` | creates a new vector by appending all elements of 2 input vectors
`vector_reserve(typeid:typeid, len:int) -> [any]` | creates a new empty vector much like [] would, except now ensures it will have space for len push() operations without having to reallocate. pass "typeof return" as typeid.
`length(x:int) -> int` | length of int (identity function, useful in combination with string/vector version)
`length(s:string) -> int` | length of string
`length(xs:[any]) -> int` | length of vector
`equal(a, b) -> int` | structural equality between any two values (recurses into vectors/objects, unlike == which is only true for vectors/objects if they are the same object)
`push(xs:[any], x) -> [any]` | appends one element to a vector, returns existing vector
`pop(xs:[any]) -> any` | removes last element from vector and returns it
`top(xs:[any]) -> any` | returns last element from vector
`insert(xs:[any], i:int, x) -> [any]` | inserts a value into a vector at index i, existing elements shift upward, returns original vector
`remove(xs:[any], i:int, n:int = 0) -> any` | remove element(s) at index i, following elements shift down. pass the number of elements to remove as an optional argument, default 1. returns the first element removed.
`remove_obj(xs:[any], obj) -> any` | remove all elements equal to obj (==), returns obj.
`binary_search(xs:[int], key:int) -> int, int` | does a binary search for key in a sorted vector, returns as first return value how many matches were found, and as second the index in the array where the matches start (so you can read them, overwrite them, or remove them), or if none found, where the key could be inserted such that the vector stays sorted. This overload is for int vectors and keys.
`binary_search(xs:[float], key:float) -> int, int` | float version.
`binary_search(xs:[string], key:string) -> int, int` | string version.
`copy(xs) -> any` | makes a shallow copy of any object.
`slice(xs:[any], start:int, size:int) -> [any]` | returns a sub-vector of size elements from index start. size can be negative to indicate the rest of the vector.
`any(xs:vec_i) -> int` | returns wether any elements of the numeric struct are true values
`any(xs:[any]) -> int` | returns wether any elements of the vector are true values
`all(xs:vec_i) -> int` | returns wether all elements of the numeric struct are true values
`all(xs:[any]) -> int` | returns wether all elements of the vector are true values
`substring(s:string, start:int, size:int) -> string` | returns a substring of size characters from index start. size can be negative to indicate the rest of the string.
`string_to_int(s:string) -> int, int` | converts a string to an int. returns 0 if no numeric data could be parsed.second return value is true if all characters of the string were parsed
`string_to_float(s:string) -> float` | converts a string to a float. returns 0.0 if no numeric data could be parsed
`tokenize(s:string, delimiters:string, whitespace:string) -> [string]` | splits a string into a vector of strings, by splitting into segments upon each dividing or terminating delimiter. Segments are stripped of leading and trailing whitespace. Example: "; A ; B C; " becomes [ "", "A", "B C" ] with ";" as delimiter and " " as whitespace.
`unicode_to_string(us:[int]) -> string` | converts a vector of ints representing unicode values to a UTF-8 string.
`string_to_unicode(s:string) -> [int]?` | converts a UTF-8 string into a vector of unicode values, or nil upon a decoding error
`number_to_string(number:int, base:int, minchars:int) -> string` | converts the (unsigned version) of the input integer number to a string given the base (2..36, e.g. 16 for hex) and outputting a minimum of characters (padding with 0).
`lowercase(s:string) -> string` | converts a UTF-8 string from any case to lower case, affecting only A-Z
`uppercase(s:string) -> string` | converts a UTF-8 string from any case to upper case, affecting only a-z
`escape_string(s:string, set:string, prefix:string, postfix:string) -> string` | prefixes & postfixes any occurrences or characters in set in string s
`concat_string(v:[string], sep:string) -> string` | concatenates all elements of the string vector, separated with sep.
`repeat_string(s:string, n:int) -> string` | returns a string consisting of n copies of the input string.
`pow(a:float, b:float) -> float` | a raised to the power of b
`pow(a:int, b:int) -> int` | a raised to the power of b, for integers, using exponentiation by squaring
`pow(a:vec_f, b:float) -> vec_f` | vector elements raised to the power of b
`log(a:float) -> float` | natural logaritm of a
`sqrt(f:float) -> float` | square root
`ceiling(f:float) -> int` | the nearest int >= f
`ceiling(v:vec_f) -> vec_i` | the nearest ints >= each component of v
`floor(f:float) -> int` | the nearest int <= f
`floor(v:vec_f) -> vec_i` | the nearest ints <= each component of v
`int(f:float) -> int` | converts a float to an int by dropping the fraction
`int(v:vec_f) -> vec_i` | converts a vector of floats to ints by dropping the fraction
`round(f:float) -> int` | converts a float to the closest int. same as int(f + 0.5), so does not work well on negative numbers
`round(v:vec_f) -> vec_i` | converts a vector of floats to the closest ints
`fraction(f:float) -> float` | returns the fractional part of a float: short for f - int(f)
`fraction(v:vec_f) -> vec_f` | returns the fractional part of a vector of floats
`float(i:int) -> float` | converts an int to float
`float(v:vec_i) -> vec_f` | converts a vector of ints to floats
`sin(angle:float) -> float` | the y coordinate of the normalized vector indicated by angle (in degrees)
`cos(angle:float) -> float` | the x coordinate of the normalized vector indicated by angle (in degrees)
`tan(angle:float) -> float` | the tangent of an angle (in degrees)
`sincos(angle:float) -> xy_f` | the normalized vector indicated by angle (in degrees), same as xy { cos(angle), sin(angle) }
`asin(y:float) -> float` | the angle (in degrees) indicated by the y coordinate projected to the unit circle
`acos(x:float) -> float` | the angle (in degrees) indicated by the x coordinate projected to the unit circle
`atan(x:float) -> float` | the angle (in degrees) indicated by the y coordinate of the tangent projected to the unit circle
`radians(angle:float) -> float` | converts an angle in degrees to radians
`degrees(angle:float) -> float` | converts an angle in radians to degrees
`atan2(vec:vec_f) -> float` | the angle (in degrees) corresponding to a normalized 2D vector
`radians(angle:float) -> float` | converts an angle in degrees to radians
`degrees(angle:float) -> float` | converts an angle in radians to degrees
`normalize(vec:vec_f) -> vec_f` | returns a vector of unit length
`dot(a:vec_f, b:vec_f) -> float` | the length of vector a when projected onto b (or vice versa)
`magnitude(v:vec_f) -> float` | the geometric length of a vector
`manhattan(v:vec_i) -> int` | the manhattan distance of a vector
`cross(a:xyz_f, b:xyz_f) -> xyz_f` | a perpendicular vector to the 2D plane defined by a and b (swap a and b for its inverse)
`rnd(max:int) -> int` | a random value [0..max).
`rnd(max:vec_i) -> vec_i` | a random vector within the range of an input vector.
`rnd_float() -> float` | a random float [0..1)
`rnd_gaussian() -> float` | a random float in a gaussian distribution with mean 0 and stddev 1
`rnd_seed(seed:int)` | explicitly set a random seed for reproducable randomness
`div(a:int, b:int) -> float` | forces two ints to be divided as floats
`clamp(x:int, min:int, max:int) -> int` | forces an integer to be in the range between min and max (inclusive)
`clamp(x:float, min:float, max:float) -> float` | forces a float to be in the range between min and max (inclusive)
`clamp(x:vec_i, min:vec_i, max:vec_i) -> vec_i` | forces an integer vector to be in the range between min and max (inclusive)
`clamp(x:vec_f, min:vec_f, max:vec_f) -> vec_f` | forces a float vector to be in the range between min and max (inclusive)
`in_range(x:int, range:int, bias:int = 0) -> int` | checks if an integer is >= bias and < bias + range. Bias defaults to 0.
`in_range(x:float, range:float, bias:float = 0) -> int` | checks if a float is >= bias and < bias + range. Bias defaults to 0.
`in_range(x:vec_i, range:vec_i, bias:vec_i = nil) -> int` | checks if a 2d/3d integer vector is >= bias and < bias + range. Bias defaults to 0.
`in_range(x:vec_f, range:vec_f, bias:vec_f = nil) -> int` | checks if a 2d/3d float vector is >= bias and < bias + range. Bias defaults to 0.
`abs(x:int) -> int` | absolute value of an integer
`abs(x:float) -> float` | absolute value of a float
`abs(x:vec_i) -> vec_i` | absolute value of an int vector
`abs(x:vec_f) -> vec_f` | absolute value of a float vector
`sign(x:int) -> int` | sign (-1, 0, 1) of an integer
`sign(x:float) -> int` | sign (-1, 0, 1) of a float
`sign(x:vec_i) -> vec_i` | signs of an int vector
`sign(x:vec_f) -> vec_i` | signs of a float vector
`min(x:int, y:int) -> int` | smallest of 2 integers.
`min(x:float, y:float) -> float` | smallest of 2 floats.
`min(x:vec_i, y:vec_i) -> vec_i` | smallest components of 2 int vectors
`min(x:vec_f, y:vec_f) -> vec_f` | smallest components of 2 float vectors
`min(v:vec_i) -> int` | smallest component of a int vector.
`min(v:vec_f) -> float` | smallest component of a float vector.
`min(v:[int]) -> int` | smallest component of a int vector, or INT_MAX if length 0.
`min(v:[float]) -> float` | smallest component of a float vector, or FLT_MAX if length 0.
`max(x:int, y:int) -> int` | largest of 2 integers.
`max(x:float, y:float) -> float` | largest of 2 floats.
`max(x:vec_i, y:vec_i) -> vec_i` | largest components of 2 int vectors
`max(x:vec_f, y:vec_f) -> vec_f` | largest components of 2 float vectors
`max(v:vec_i) -> int` | largest component of a int vector.
`max(v:vec_f) -> float` | largest component of a float vector.
`max(v:[int]) -> int` | largest component of a int vector, or INT_MIN if length 0.
`max(v:[float]) -> float` | largest component of a float vector, or FLT_MIN if length 0.
`lerp(x:float, y:float, f:float) -> float` | linearly interpolates between x and y with factor f [0..1]
`lerp(a:vec_f, b:vec_f, f:float) -> vec_f` | linearly interpolates between a and b vectors with factor f [0..1]
`cardinal_spline(z:vec_f, a:vec_f, b:vec_f, c:vec_f, f:float, tension:float) -> xyz_f` | computes the position between a and b with factor f [0..1], using z (before a) and c (after b) to form a cardinal spline (tension at 0.5 is a good default)
`line_intersect(line1a:xy_f, line1b:xy_f, line2a:xy_f, line2b:xy_f) -> int, xy_f` | computes if there is an intersection point between 2 line segments, with the point as second return value
`circles_within_range(dist:float, positions:[xy_f], radiuses:[float], positions2:[xy_f], radiuses2:[float], gridsize:xy_i) -> [[int]]` | Given a vector of 2D positions (and same size vectors of radiuses), returns a vector of vectors of indices (to the second set of positions and radiuses) of the circles that are within dist of eachothers radius. If the second set are [], the first set is used for both (and the self element is excluded). gridsize optionally specifies the size of the grid to use for accellerated lookup of nearby points. This is essential for the algorithm to be fast, too big or too small can cause slowdown. Omit it, and a heuristic will be chosen for you, which is currently sqrt(num_circles) * 2 along each dimension, e.g. 100 elements would use a 20x20 grid. Efficiency wise this algorithm is fastest if there is not too much variance in the radiuses of the second set and/or the second set has smaller radiuses than the first.
`wave_function_collapse(tilemap:[string], size:xy_i) -> [string], int` | returns a tilemap of given size modelled after the possible shapes in the input tilemap. Tilemap should consist of chars in the 0..127 range. Second return value the number of failed neighbor matches, this should ideally be 0, but can be non-0 for larger maps. Simply call this function repeatedly until it is 0
`resume(coroutine:coroutine, return_value:any = nil) -> coroutine?` | resumes execution of a coroutine, passing a value back or nil
`return_value(coroutine:coroutine) -> any` | gets the last return value of a coroutine
`active(coroutine:coroutine) -> int` | wether the given coroutine is still active
`hash(x:function) -> int` | hashes a function value into an int
`hash(x) -> int` | hashes any value into an int
`program_name() -> string` | returns the name of the main program (e.g. "foo.lobster".
`vm_compiled_mode() -> int` | returns if the VM is running in compiled mode (Lobster -> C++).
`seconds_elapsed() -> float` | seconds since program start as a float, unlike gl_time() it is calculated every time it is called
`assert(condition) -> any` | halts the program with an assertion failure if passed false. returns its input
`trace_bytecode(mode:int)` | tracing shows each bytecode instruction as it is being executed, not very useful unless you are trying to isolate a compiler bug. Mode is off(0), on(1) or tail only (2)
`set_max_stack_size(max:int)` | size in megabytes the stack can grow to before an overflow error occurs. defaults to 1
`reference_count(val) -> int` | get the reference count of any value. for compiler debugging, mostly
`set_console(on:bool)` | lets you turn on/off the console window (on Windows)
`command_line_arguments() -> [string]` |
`thread_information() -> int, int` | returns the number of hardware threads, and the number of cores
`is_worker_thread() -> int` | wether the current thread is a worker thread
`start_worker_threads(numthreads:int)` | launch worker threads
`stop_worker_threads()` | only needs to be called if you want to stop the worker threads before the end of the program, or if you want to call start_worker_threads again. workers_alive will become false inside the workers, which should then exit.
`workers_alive() -> int` | wether workers should continue doing work. returns false after stop_worker_threads() has been called.
`thread_write(struct)` | put this struct in the thread queue
`thread_read(type:typeid) -> any?` | get a struct from the thread queue. pass the typeof struct. blocks if no suchstructs available. returns struct, or nil if stop_worker_threads() was called
`log_frame()` | call this function instead of gl_frame() or gl_log_frame() to simulate a frame based program from non-graphical code.
### compiler
`compile_run_code(code:string, args:[string]) -> string, string?` | compiles and runs lobster source, sandboxed from the current program (in its own VM). the argument is a string of code. returns the return value of the program as a string, with an error string as second return value, or nil if none. using parse_data(), two program can communicate more complex data structures even if they don't have the same version of struct definitions.
`compile_run_file(filename:string, args:[string]) -> string, string?` | same as compile_run_code(), only now you pass a filename.
### file
`scan_folder(folder:string, divisor:int) -> [string]?, [int]?` | returns two vectors representing all elements in a folder, the first vector containing all names, the second vector containing sizes (or -1 if a directory). Specify 1 as divisor to get sizes in bytes, 1024 for kb etc. Values > 0x7FFFFFFF will be clamped in 32-bit builds. Returns nil if folder couldn't be scanned.
`read_file(file:string, textmode:int = 0) -> string?` | returns the contents of a file as a string, or nil if the file can't be found. you may use either \ or / as path separators
`write_file(file:string, contents:string, textmode:int = 0) -> int` | creates a file with the contents of a string, returns false if writing wasn't possible
`ensure_size(string:string, size:int, char:int, extra:int = 0) -> string` | ensures a string is at least size characters. if it is, just returns the existing string, otherwise returns a new string of that size (with optionally extra bytes added), with any new characters set to char. You can specify a negative size to mean relative to the end, i.e. new characters will be added at the start.
`write_int64_le(string:string, i:int, val:int) -> string, int` | writes a value as little endian to a string at location i. Uses ensure_size to make the string twice as long (with extra 0 bytes) if no space. Returns new string if resized, and the index of the location right after where the value was written. The _back version writes relative to the end (and writes before the index)
`write_int32_le(string:string, i:int, val:int) -> string, int` | (see write_int64_le)
`write_int16_le(string:string, i:int, val:int) -> string, int` | (see write_int64_le)
`write_int8_le(string:string, i:int, val:int) -> string, int` | (see write_int64_le)
`write_float64_le(string:string, i:int, val:float) -> string, int` | (see write_int64_le)
`write_float32_le(string:string, i:int, val:float) -> string, int` | (see write_int64_le)
`write_int64_le_back(string:string, i:int, val:int) -> string, int` | (see write_int64_le)
`write_int32_le_back(string:string, i:int, val:int) -> string, int` | (see write_int64_le)
`write_int16_le_back(string:string, i:int, val:int) -> string, int` | (see write_int64_le)
`write_int8_le_back(string:string, i:int, val:int) -> string, int` | (see write_int64_le)
`write_float64_le_back(string:string, i:int, val:float) -> string, int` | (see write_int64_le)
`write_float32_le_back(string:string, i:int, val:float) -> string, int` | (see write_int64_le)
`write_substring(string:string, i:int, substr:string, nullterm:int) -> string, int` | writes a substring into another string at i (see also write_int64_le)
`write_substring_back(string:string, i:int, substr:string, nullterm:int) -> string, int` |
`compare_substring(string_a:string, i_a:int, string_b:string, i_b:int, len:int) -> int` | returns if the two substrings are equal (0), or a < b (-1) or a > b (1).
`read_int64_le(string:string, i:int) -> int, int` | reads a value as little endian from a string at location i. The value must be within bounds of the string. Returns the value, and the index of the location right after where the value was read. The _back version reads relative to the end (and reads before the index)
`read_int32_le(string:string, i:int) -> int, int` | (see read_int64_le)
`read_int16_le(string:string, i:int) -> int, int` | (see read_int64_le)
`read_int8_le(string:string, i:int) -> int, int` | (see read_int64_le)
`read_float64_le(string:string, i:int) -> float, int` | (see read_int64_le)
`read_float32_le(string:string, i:int) -> float, int` | (see read_int64_le)
`read_int64_le_back(string:string, i:int) -> int, int` | (see read_int64_le)
`read_int32_le_back(string:string, i:int) -> int, int` | (see read_int64_le)
`read_int16_le_back(string:string, i:int) -> int, int` | (see read_int64_le)
`read_int8_le_back(string:string, i:int) -> int, int` | (see read_int64_le)
`read_float64_le_back(string:string, i:int) -> float, int` | (see read_int64_le)
`read_float32_le_back(string:string, i:int) -> float, int` | (see read_int64_le)
`flatbuffers_field_int64(string:string, tablei:int, vo:int, def:int) -> int` | reads a flatbuffers field from a string at table location tablei, field vtable offset vo, and default value def. The value must be within bounds of the string. Returns the value (or default if the field was not present)
`flatbuffers_field_int32(string:string, tablei:int, vo:int, def:int) -> int` | (see flatbuffers_field_int64)
`flatbuffers_field_int16(string:string, tablei:int, vo:int, def:int) -> int` | (see flatbuffers_field_int64)
`flatbuffers_field_int8(string:string, tablei:int, vo:int, def:int) -> int` | (see flatbuffers_field_int64)
`flatbuffers_field_float64(string:string, tablei:int, vo:int, def:float) -> float` | (see flatbuffers_field_int64)
`flatbuffers_field_float32(string:string, tablei:int, vo:int, def:float) -> float` | (see flatbuffers_field_int64)
`flatbuffers_field_string(string:string, tablei:int, vo:int) -> string` | reads a flatbuffer string field, returns "" if not present
`flatbuffers_field_vector_len(string:string, tablei:int, vo:int) -> int` | reads a flatbuffer vector field length, or 0 if not present
`flatbuffers_field_vector(string:string, tablei:int, vo:int) -> int` | returns a flatbuffer vector field element start, or 0 if not present
`flatbuffers_field_table(string:string, tablei:int, vo:int) -> int` | returns a flatbuffer table field start, or 0 if not present
`flatbuffers_field_struct(string:string, tablei:int, vo:int) -> int` | returns a flatbuffer struct field start, or 0 if not present
`flatbuffers_indirect(string:string, index:int) -> int` | returns a flatbuffer offset at index relative to itself
`flatbuffers_string(string:string, index:int) -> string` | returns a flatbuffer string whose offset is at given index
`flatbuffers_binary_to_json(schemas:string, binary:string, includedirs:[string]) -> string, string?` | returns a JSON string generated from the given binary and corresponding schema.if there was an error parsing the schema, the error will be in the second returnvalue, or nil for no error
`flatbuffers_json_to_binary(schema:string, json:string, includedirs:[string]) -> string, string?` | returns a binary flatbuffer generated from the given json and corresponding schema.if there was an error parsing the schema, the error will be in the second returnvalue, or nil for no error
### parsedata
`parse_data(typeid:typeid, stringdata:string) -> any?, string?` | parses a string containing a data structure in lobster syntax (what you get if you convert an arbitrary data structure to a string) back into a data structure. supports int/float/string/vector and classes. classes will be forced to be compatible with their current definitions, i.e. too many elements will be truncated, missing elements will be set to 0/nil if possible. useful for simple file formats. returns the value and an error string as second return value (or nil if no error)