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() -> intwether there is a selection.
ts_goto_selection()makes the current cell the one containing the selection, or does nothing on noselection.
ts_has_parent() -> intwether 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() -> intreturns 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_ireturns the number of columns & rows in the current cell.
ts_selection() -> xy_i, xy_ireturns 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() -> stringgets 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) -> stringgets a filename using a file dialog. empty string if cancelled.

builtin

print(x) -> anyoutput any value to the console (with linefeed). returns its argument.
string(x) -> stringconvert 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 10000)
set_print_quoted(quoted:int)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)
getline() -> stringreads a string from the console if possible (followed by enter)
if(cond, then:function [, else:function]) -> anyevaluates then or else depending on cond, else is optional
while(cond:function, do:function) -> anyevaluates 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) -> intlength of int (identity function, useful in combination with string/vector version)
length(s:string) -> intlength of string
length(s:xy_z_w_f) -> intnumber of fields in a numerical struct
length(s:xy_z_w_i) -> intnumber of fields in a numerical struct
length(xs:[any]) -> intlength of vector
equal(a, b) -> intstructural 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]) -> anyremoves last element from vector and returns it
top(xs:[any]) -> anyreturns last element from vector
replace(xs:xy_z_w_f, i:int, x:float) -> xy_z_w_freturns a copy of a numeric struct with the element at i replaced by x
replace(xs:xy_z_w_i, i:int, x:int) -> xy_z_w_ireturns a copy of a numeric struct with the element at i replaced by x
replace(xs:[any], i:int, x) -> [any]returns a copy of a vector with the element at i replaced by x
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]) -> anyremove 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.
removeobj(xs:[any], obj) -> anyremove all elements equal to obj (==), returns obj.
binarysearch(xs:[int], key:int) -> int, intdoes 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.
binarysearch(xs:[float], key:float) -> int, intfloat version.
binarysearch(xs:[string], key:string) -> int, intstring version.
copy(xs) -> anymakes a shallow copy of any object.
slice(xs:[any], start:int, size:int) -> [any]returns a sub-vector of size elements from index start. start & size can be negative to indicate an offset from the vector length.
any(xs:xy_z_w_i) -> intreturns wether any elements of the numeric struct are true values
any(xs:[any]) -> intreturns wether any elements of the vector are true values
all(xs:xy_z_w_i) -> intreturns wether all elements of the numeric struct are true values
all(xs:[any]) -> intreturns wether all elements of the vector are true values
substring(s:string, start:int, size:int) -> stringreturns a substring of size characters from index start. start & size can be negative to indicate an offset from the string length.
string2int(s:string) -> intconverts a string to an int. returns 0 if no numeric data could be parsed
string2float(s:string) -> floatconverts 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.
unicode2string(us:[int]) -> stringconverts a vector of ints representing unicode values to a UTF-8 string.
string2unicode(s:string) -> [int]?converts a UTF-8 string into a vector of unicode values, or nil upon a decoding error
number2string(number:int, base:int, minchars:int) -> stringconverts 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) -> stringconverts a UTF-8 string from any case to lower case, affecting only A-Z
uppercase(s:string) -> stringconverts a UTF-8 string from any case to upper case, affecting only a-z
escapestring(s:string, set:string, prefix:string, postfix:string) -> stringprefixes & postfixes any occurrences or characters in set in string s
concatstring(v:[string], sep:string) -> stringconcatenates all elements of the string vector, separated with sep.
pow(a:float, b:float) -> floata raised to the power of b
log(a:float) -> floatnatural logaritm of a
sqrt(f:float) -> floatsquare root
ceiling(f:float) -> intthe nearest int >= f
ceiling(v:xy_z_w_f) -> xy_z_w_ithe nearest ints >= each component of v
floor(f:float) -> intthe nearest int <= f
floor(v:xy_z_w_f) -> xy_z_w_ithe nearest ints <= each component of v
int(f:float) -> intconverts a float to an int by dropping the fraction
int(v:xy_z_w_f) -> xy_z_w_iconverts a vector of floats to ints by dropping the fraction
round(f:float) -> intconverts a float to the closest int. same as int(f + 0.5), so does not work well on negative numbers
round(v:xy_z_w_f) -> xy_z_w_iconverts a vector of floats to the closest ints
fraction(f:float) -> floatreturns the fractional part of a float: short for f - int(f)
fraction(v:xy_z_w_f) -> xy_z_w_freturns the fractional part of a vector of floats
float(i:int) -> floatconverts an int to float
float(v:xy_z_w_i) -> xy_z_w_fconverts a vector of ints to floats
sin(angle:float) -> floatthe y coordinate of the normalized vector indicated by angle (in degrees)
cos(angle:float) -> floatthe x coordinate of the normalized vector indicated by angle (in degrees)
tan(angle:float) -> floatthe tangent of an angle (in degrees)
sincos(angle:float) -> xy_fthe normalized vector indicated by angle (in degrees), same as [ cos(angle), sin(angle) ]
arcsin(y:float) -> floatthe angle (in degrees) indicated by the y coordinate projected to the unit circle
arccos(x:float) -> floatthe angle (in degrees) indicated by the x coordinate projected to the unit circle
atan2(vec:xy_z_w_f) -> floatthe angle (in degrees) corresponding to a normalized 2D vector
radians(angle:float) -> floatconverts an angle in degrees to radians
degrees(angle:float) -> floatconverts an angle in radians to degrees
normalize(vec:xy_z_w_f) -> xy_z_w_freturns a vector of unit length
dot(a:xy_z_w_f, b:xy_z_w_f) -> floatthe length of vector a when projected onto b (or vice versa)
magnitude(v:xy_z_w_f) -> floatthe geometric length of a vector
manhattan(v:xy_z_w_i) -> intthe manhattan distance of a vector
cross(a:xyz_f, b:xyz_f) -> xyz_fa perpendicular vector to the 2D plane defined by a and b (swap a and b for its inverse)
rnd(max:int) -> inta random value [0..max).
rnd(max:xy_z_w_i) -> xy_z_w_ia random vector within the range of an input vector.
rndfloat() -> floata random float [0..1)
rndseed(seed:int)explicitly set a random seed for reproducable randomness
div(a:int, b:int) -> floatforces two ints to be divided as floats
clamp(x:int, min:int, max:int) -> intforces an integer to be in the range between min and max (inclusive)
clamp(x:float, min:float, max:float) -> floatforces a float to be in the range between min and max (inclusive)
clamp(x:xy_z_w_i, min:xy_z_w_i, max:xy_z_w_i) -> xy_z_w_iforces an integer vector to be in the range between min and max (inclusive)
clamp(x:xy_z_w_f, min:xy_z_w_f, max:xy_z_w_f) -> xy_z_w_fforces a float vector to be in the range between min and max (inclusive)
inrange(x:int, range:int [, bias:int]) -> intchecks if an integer is >= bias and < bias + range. Bias defaults to 0.
inrange(x:xy_z_w_i, range:xy_z_w_i [, bias:xy_z_w_i]) -> intchecks if a 2d/3d integer vector is >= bias and < bias + range. Bias defaults to 0.
inrange(x:xy_z_w_f, range:xy_z_w_f [, bias:xy_z_w_f]) -> intchecks if a 2d/3d float vector is >= bias and < bias + range. Bias defaults to 0.
abs(x:int) -> intabsolute value of an integer
abs(x:float) -> floatabsolute value of a float
abs(x:xy_z_w_i) -> xy_z_w_iabsolute value of an int vector
abs(x:xy_z_w_f) -> xy_z_w_fabsolute value of a float vector
min(x:int, y:int) -> intsmallest of 2 integers.
min(x:float, y:float) -> floatsmallest of 2 floats.
min(x:xy_z_w_i, y:xy_z_w_i) -> xy_z_w_ismallest components of 2 int vectors
min(x:xy_z_w_f, y:xy_z_w_f) -> xy_z_w_fsmallest components of 2 float vectors
min(v:xy_z_w_i) -> intsmallest component of a int vector.
min(v:xy_z_w_f) -> floatsmallest component of a float vector.
min(v:[int]) -> intsmallest component of a int vector, or INT_MAX if length 0.
min(v:[float]) -> floatsmallest component of a float vector, or FLT_MAX if length 0.
max(x:int, y:int) -> intlargest of 2 integers.
max(x:float, y:float) -> floatlargest of 2 floats.
max(x:xy_z_w_i, y:xy_z_w_i) -> xy_z_w_ilargest components of 2 int vectors
max(x:xy_z_w_f, y:xy_z_w_f) -> xy_z_w_flargest components of 2 float vectors
max(v:xy_z_w_i) -> intlargest component of a int vector.
max(v:xy_z_w_f) -> floatlargest component of a float vector.
max(v:[int]) -> intlargest component of a int vector, or INT_MIN if length 0.
max(v:[float]) -> floatlargest component of a float vector, or FLT_MIN if length 0.
lerp(x:float, y:float, f:float) -> floatlinearly interpolates between x and y with factor f [0..1]
lerp(a:xy_z_w_f, b:xy_z_w_f, f:float) -> xy_z_w_flinearly interpolates between a and b vectors with factor f [0..1]
cardinalspline(z:xy_z_w_f, a:xy_z_w_f, b:xy_z_w_f, c:xy_z_w_f, f:float, tension:float) -> xyz_fcomputes 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) -> xy_f?computes the intersection point between 2 line segments, or nil if no intersection
circles_within_range(dist:float, positions:[xy_f], radiuses:[float], prefilter:[int]) -> [[int]]given a vector of 2D positions (an same size vectors of radiuses and pre-filter), returns a vector of vectors of indices of the circles that are within dist of eachothers radius. pre-filter indicates objects that should appear in the inner vectors.
resume(coroutine:coroutine [, returnvalue:any]) -> anyresumes execution of a coroutine, passing a value back or nil
returnvalue(coroutine:coroutine) -> anygets the last return value of a coroutine
active(coroutine:coroutine) -> intwether the given coroutine is still active
hash(x:function) -> inthashes a function value into an int
hash(x) -> inthashes any value into an int
program_name() -> stringreturns the name of the main program (e.g. "foo.lobster".
vm_compiled_mode() -> intreturns if the VM is running in compiled mode (Lobster -> C++).
seconds_elapsed() -> floatseconds since program start as a float, unlike gl_time() it is calculated every time it is called
assert(condition) -> anyhalts the program with an assertion failure if passed false. returns its input
trace_bytecode(on:int, tail:int)tracing shows each bytecode instruction as it is being executed, not very useful unless you are trying to isolate a compiler bug
collect_garbage() -> intforces a garbage collection to re-claim cycles. slow and not recommended to be used. instead, write code to clear any back pointers before abandoning data structures. Watch for a "LEAKS FOUND" message in the console upon program exit to know when you've created a cycle. returns number of objects collected.
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) -> intget the reference count of any value. for compiler debugging, mostly
set_console(on:int)lets you turn on/off the console window (on Windows)
command_line_arguments() -> [string]

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) -> 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) -> intcreates a file with the contents of a string, returns false if writing wasn't possible

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 structs. structs 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)