standard_library.md

This document describes the functions defined by default by Anselme. These are accessible from any Anselme script.

This document is generated automatically from the source files in anselme/stdlib.

print (val)

Print a human-readable string representation (using format(val)) of val to the console.

defined at line 10 of anselme/stdlib/base.lua: "print", "(val)",

format (val)

Returns a human-readable string representation of val.

This function is called by string and text interpolations to convert the value returned by the interpolation to a string.

This generic version uses the internal Anselme formatter for all other values, which tries to generate a representation close to valid Anselme code.

defined at line 22 of anselme/stdlib/base.lua: "format", "(val)",

hash (val)

Returns a hash of val.

A hash is a string that uniquely represents the value. Two equal hashes mean the values are equal.

defined at line 31 of anselme/stdlib/base.lua: "hash", "(val)",

error (message="error")

Throw an error.

defined at line 38 of anselme/stdlib/base.lua: "error", "(message=\"error\")",

Variable assignment

identifier = value

Assign value to the variable identifier.

var = 42

defined at line 56 of anselme/stdlib/assignment.lua: "_=_", "(quote::is quoted(\"identifier\"), value)",

symbol::is symbol = value

Define the variable using the symbol symbol with the initial value value.

:var = 42

defined at line 68 of anselme/stdlib/assignment.lua: "_=_", "(quote::is quoted(\"symbol\"), value)",

variable tuple::is tuple = value tuple::is tuple

For each variable element of the variable tuple and associated value element of the value tuple, call variable = value.

(:a, :b) = (24, 42)
(a, b) = (b, a)

defined at line 86 of anselme/stdlib/assignment.lua: "_=_", "(quote::is quoted(\"tuple\"), value::is tuple)",

Value checking

See the language reference for information on how value checking functions works.

is (t)

Returns a function $(x) that returns true if x is of type t, false otherwise.

is equal (x)

Returns a function $(y) that returns true if x is equal to y, false otherwise.

is nil (x)

Returns a true if x is a nil, false otherwise.

is number (x)

Returns a true if x is a number, false otherwise.

is string (x)

Returns a true if x is a string, false otherwise.

is boolean (x)

Returns a true if x is a boolean, false otherwise.

is false (x)

Returns a true if x is false, false otherwise.

is true (x)

Returns a true if x is true, false otherwise.

is symbol (x)

Returns a true if x is a symbol, false otherwise.

is anchor (x)

Returns a true if x is an anchor, false otherwise.

is pair (x)

Returns a true if x is a pair, false otherwise.

is text (x)

Returns a true if x is a text, false otherwise.

is sequence (x)

Returns a true if x is a sequence (a tuple or a list), false otherwise.

is list (x)

Returns a true if x is a list, false otherwise.

is map (x)

Returns a true if x is a map (a struct or a table), false otherwise.

is struct (x)

Returns a true if x is a struct, false otherwise.

is table (x)

Returns a true if x is a table, false otherwise.

is environment (x)

Returns a true if x is an environment, false otherwise.

is function (x)

Returns a true if x is a function, false otherwise.

is overload (x)

Returns a true if x is an overload, false otherwise.

constant (exp)

Always return false. Can be used as variable value checking function to prevent any reassignment and thus make the variable constant.

:var::constant = 42

defined at line 15 of anselme/stdlib/assignment.lua: "constant", "(exp)",

is tuple (exp)

Returns true if the expression is a tuple, false otherwise.

defined at line 24 of anselme/stdlib/assignment.lua: "is tuple", "(exp)",

is range (val)

Returns true if val is a range, false otherwise.

is script (x)

Returns true if x is a script, false otherwise.

value :: check

Call check(value) and error if it returns a false value. This can be used to ensure a value checking function is verified on a value.

defined at line 12 of anselme/stdlib/typed.lua: "_::_", "(value, check)",

Boolean

true

A boolean true value.

defined at line 9 of anselme/stdlib/boolean.lua: { "true", Boolean:new(true) },

false

A boolean false value.

defined at line 11 of anselme/stdlib/boolean.lua: { "false", Boolean:new(false) },

a == b

Equality operator. Returns true if a and b are equal, false otherwise.

Mutable values are compared by reference, immutable values are compared by value.

defined at line 18 of anselme/stdlib/boolean.lua: "_==_", "(a, b)",

a != b

Inequality operator. Retrusn false if a and b are equal, true otherwise.

defined at line 29 of anselme/stdlib/boolean.lua: "_!=_", "(a, b)",

! a

Boolean not operator. Returns false if a is true, false otherwise.

defined at line 40 of anselme/stdlib/boolean.lua: "!_", "(a)",

left & right

Boolean lazy and operator. If left is truthy, evaluate right and returns it. Otherwise, returns left.

defined at line 48 of anselme/stdlib/boolean.lua: "_&_", "(left, right)",

left | right

Boolean lazy or operator. If left is truthy, returns it. Otherwise, evaluate right and returns it.

defined at line 60 of anselme/stdlib/boolean.lua: "_|_", "(left, right)",

Control flow

if(5 > 3)
	print("called")

if(3 > 5)
	print("not called")
else if(1 > 5)
	print("not called")
else!
	print("called")

if (condition, expression=attached block(keep return=true))

Call expression if condition is true. Returns the result of the call to expression, or nil if the condition was false.

If we are currently resuming to an anchor contained in expression, expression is called regardless of the condition result.

defined at line 40 of anselme/stdlib/conditionals.lua: "if", "(condition, expression=attached block(keep return=true))", function(state, condition, expression)

if (condition, if true, if false)

Call if true if condition is true, if false otherwise. Return the result of the call.

If we are currently resuming to an anchor contained in if true or if false, if true or if false (respectively) is called regardless of the condition result.

defined at line 56 of anselme/stdlib/conditionals.lua: "if", "(condition, if true, if false)", function(state, condition, if_true, if_false)

else if (condition, expression=attached block(keep return=true))

Call expression if condition is true and the last if, else if or else's condition was false, or the last while loop was never entered. Returns the result of the call to expression, or nil if not called.

If we are currently resuming to an anchor contained in expression, expression is called regardless of the condition result.

defined at line 72 of anselme/stdlib/conditionals.lua: "else if", "(condition, expression=attached block(keep return=true))",

else (expression=attached block(keep return=true))

Call expression if the last if, else if or else's condition was false, or the last while loop was never entered. Returns the result of the call to expression, or nil if not called.

If we are currently resuming to an anchor contained in expression, expression is called regardless of the condition result.

defined at line 89 of anselme/stdlib/conditionals.lua: "else", "(expression=attached block(keep return=true))",

while (condition, expression=attached block(keep return=true))

Call condition, if it returns a true value, call expression, and repeat until condition returns a false value.

Returns the value returned by the the last loop. If condition returns a false value on its first call, returns nil.

If a continue happens in the loop, the current iteration is stopped and skipped. If a break happens in the loop, the whole loop is stopped.

:i = 1
while(i <= 5)
	print(i)
	i += 1
// 1, 2, 3, 4, 5

:i = 1
while(i <= 5)
	if(i == 3, break)
	print(i)
	i += 1
// 1, 2

:i = 1
while(i <= 5)
	if(i == 3, continue)
	print(i)
	i += 1
// 1, 2, 4, 5

:i = 10
while(i <= 5)
	print(i)
	i += 1
else!
	print("the while loop was never entered")
// the while loop was never entered

defined at line 145 of anselme/stdlib/conditionals.lua: "while", "(condition, expression=attached block(keep return=true))",

break (value=())

Returns a break return value, eventually with an associated value. This can be used to exit a loop.

defined at line 175 of anselme/stdlib/conditionals.lua: "break", "(value=())",

continue (value=())

Returns a continue return value, eventually with an associated value. This can be used to skip the current loop iteration.

defined at line 184 of anselme/stdlib/conditionals.lua: "continue", "(value=())",

For loops

for (symbol::is symbol, var, block=attached block(keep return=true))

Iterates over the elements of var: for each element, set the variable symbol in the function block's environment and call it.

In order to get the elements of var, this calls iter(var) to obtain an iterator over var. An iterator is a function that, each time it is called, returns the next value given to the for loop. When the iterator returns nil, the loop ends.

:l = [1,2,3]
// prints 1, 2, and 3
for(:x, l)
	print(x)

Ranges

range (stop::is number)

Returns a new range, going from 1 to stop with a step of 1.

range (start::is number, stop::is number, step::is number=1)

Returns a new range, going from start to stop with a step of step.

iter (t::is range)

Returns an iterator that iterates over the range. For a range going from start to stop with a step of step, this means this will iterate over all the numbers x such that x = start + n⋅step with n ∈ N and x ≤ stop, starting from n = 0.

Arithmetic and math functions

Comparaison operators are designed to be chained:

1 < 2 < 3
// is parsed as
(1 < 2) < 3
// (1 < 2) returns 2, 2 < 3 returns 3 which is true

pi

Pi.

defined at line 17 of anselme/stdlib/number.lua: { "pi", Number:new(math.pi) },

a::is number < b::is number

Returns b if a < b, false otherwise.

defined at line 21 of anselme/stdlib/number.lua: "_<_", "(a::is number, b::is number)",

a::is false < b::is number

Returns false.

defined at line 29 of anselme/stdlib/number.lua: { "_<_", "(a::is false, b::is number)", function(state, a, b) return Boolean:new(false) end },

a::is number <= b::is number

Returns b if a <= b, false otherwise.

defined at line 32 of anselme/stdlib/number.lua: "_<=_", "(a::is number, b::is number)",

a::is false <= b::is number

Returns false.

defined at line 40 of anselme/stdlib/number.lua: { "_<=_", "(a::is false, b::is number)", function(state, a, b) return Boolean:new(false) end },

a::is number > b::is number

Returns b if a > b, false otherwise.

defined at line 43 of anselme/stdlib/number.lua: "_>_", "(a::is number, b::is number)",

a::is false > b::is number

Returns false.

defined at line 51 of anselme/stdlib/number.lua: { "_>_", "(a::is false, b::is number)", function(state, a, b) return Boolean:new(false) end },

a::is number >= b::is number

Returns b if a >= b, false otherwise.

defined at line 54 of anselme/stdlib/number.lua: "_>=_", "(a::is number, b::is number)",

a::is false >= b::is number

Returns false.

defined at line 62 of anselme/stdlib/number.lua: { "_>=_", "(a::is false, b::is number)", function(state, a, b) return Boolean:new(false) end },

a::is number + b::is number

Returns a + b.

defined at line 64 of anselme/stdlib/number.lua: { "_+_", "(a::is number, b::is number)", function(state, a, b) return Number:new(a.number + b.number) end },

a::is number - b::is number

Returns a - b.

defined at line 66 of anselme/stdlib/number.lua: { "_-_", "(a::is number, b::is number)", function(state, a, b) return Number:new(a.number - b.number) end },

a::is number * b::is number

Returns a * b.

defined at line 68 of anselme/stdlib/number.lua: { "_*_", "(a::is number, b::is number)", function(state, a, b) return Number:new(a.number * b.number) end },

a::is number / b::is number

Returns a / b.

defined at line 70 of anselme/stdlib/number.lua: { "_/_", "(a::is number, b::is number)", function(state, a, b) return Number:new(a.number / b.number) end },

div (a::is number, b::is number)

Returns the integer division of a by b.

defined at line 73 of anselme/stdlib/number.lua: "div", "(a::is number, b::is number)", function(state, a, b)

a::is number % b::is number

Returns the modulo of a by b.

defined at line 83 of anselme/stdlib/number.lua: { "_%_", "(a::is number, b::is number)", function(state, a, b) return Number:new(a.number % b.number) end },

a::is number ^ b::is number

Returns a to the power of b.

defined at line 85 of anselme/stdlib/number.lua: { "_^_", "(a::is number, b::is number)", function(state, a, b) return Number:new(a.number ^ b.number) end },

- a::is number

Returns the negative of a.

defined at line 87 of anselme/stdlib/number.lua: { "-_", "(a::is number)", function(state, a) return Number:new(-a.number) end },

+ a::is number

Returns a.

defined at line 89 of anselme/stdlib/number.lua: { "+_", "(a::is number)", function(state, a) return a end },

rand (min::is number, max::is number)

Returns a random integer number with uniform distribution in [min, max].

defined at line 92 of anselme/stdlib/number.lua: { "rand", "(min::is number, max::is number)", function(state, min, max) return Number:new(math.random(min.number, max.number)) end },

rand (max::is number)

Returns a random integer number with uniform distribution in [1, max].

defined at line 94 of anselme/stdlib/number.lua: { "rand", "(max::is number)", function(state, max) return Number:new(math.random(max.number)) end },

rand ()

Returns a random float number with uniform distribution in [0,1).

defined at line 96 of anselme/stdlib/number.lua: { "rand", "()", function(state) return Number:new(math.random()) end },

floor (x::is number)

Returns the largest integral value less than or equal to x.

defined at line 99 of anselme/stdlib/number.lua: { "floor", "(x::is number)", function(state, x) return Number:new(math.floor(x.number)) end },

ceil (x::is number)

Returns the smallest integral value greater than or equal to x.

defined at line 101 of anselme/stdlib/number.lua: { "ceil", "(x::is number)", function(state, x) return Number:new(math.ceil(x.number)) end },

round (x::is number, increment=1)

Returns x rounded to the nearest integer. If increment > 1, rounds to the nearest float with increment decimals.

defined at line 105 of anselme/stdlib/number.lua: "round", "(x::is number, increment=1)",

sqrt (x::is number)

Returns the square root of x.

defined at line 117 of anselme/stdlib/number.lua: { "sqrt", "(x::is number)", function(state, x) return Number:new(math.sqrt(x.number)) end },

abs (x::is number)

Returns the absolute value of x.

defined at line 120 of anselme/stdlib/number.lua: { "abs", "(x::is number)", function(state, x) return Number:new(math.abs(x.number)) end },

exp (x::is number)

Returns the exponential of x.

defined at line 123 of anselme/stdlib/number.lua: { "exp", "(x::is number)", function(state, x) return Number:new(math.exp(x.number)) end },

log (x::is number)

Returns the natural logarithm of x.

defined at line 125 of anselme/stdlib/number.lua: { "log", "(x::is number)", function(state, x) return Number:new(math.log(x.number)) end },

log (x::is number, base::is number)

Returns the logarithm in base base of x.

defined at line 127 of anselme/stdlib/number.lua: { "log", "(x::is number, base::is number)", function(state, x, base) return Number:new(math.log(x.number, base.number)) end },

deg (x::is number)

Convert x from radian to degrees.

defined at line 130 of anselme/stdlib/number.lua: { "deg", "(x::is number)", function(state, x) return Number:new(math.deg(x.number)) end },

rad (x::is number)

Convert x from degrees to radians.

defined at line 132 of anselme/stdlib/number.lua: { "rad", "(x::is number)", function(state, x) return Number:new(math.rad(x.number)) end },

Trigonometric functions

All triginometric functions take and return angles in radians.

cos (x::is number)

Returns the cosinus of x.

defined at line 139 of anselme/stdlib/number.lua: { "cos", "(x::is number)", function(state, x) return Number:new(math.cos(x.number)) end },

sin (x::is number)

Returns the sinus of x.

defined at line 141 of anselme/stdlib/number.lua: { "sin", "(x::is number)", function(state, x) return Number:new(math.sin(x.number)) end },

tan (x::is number)

Returns the tagent of x.

defined at line 143 of anselme/stdlib/number.lua: { "tan", "(x::is number)", function(state, x) return Number:new(math.tan(x.number)) end },

acos (x::is number)

Returns the arc cosinus of x.

defined at line 145 of anselme/stdlib/number.lua: { "acos", "(x::is number)", function(state, x) return Number:new(math.acos(x.number)) end },

asin (x::is number)

Returns the arc sinus of x.

defined at line 147 of anselme/stdlib/number.lua: { "asin", "(x::is number)", function(state, x) return Number:new(math.asin(x.number)) end },

atan (x::is number)

Returns the arc tangent of x.

defined at line 149 of anselme/stdlib/number.lua: { "atan", "(x::is number)", function(state, x) return Number:new(math.atan(x.number)) end },

atan (y::is number, x::is number)

Returns the arc tangent of x / y, taking the signs of both arguments into account to find the correct quandrant (see atan2).

defined at line 151 of anselme/stdlib/number.lua: { "atan", "(y::is number, x::is number)", function(state, y, x) return Number:new((math.atan2 or math.atan)(y.number, x.number)) end },

Strings

a::is string + b::is string

Concatenate two strings and return the result as a new string.

defined at line 10 of anselme/stdlib/string.lua: { "_+_", "(a::is string, b::is string)", function(state, a, b) return String:new(a.string .. b.string) end },

len (s::is string)

Returns the length of the string s.

defined at line 13 of anselme/stdlib/string.lua: "len", "(s::is string)",

format (val::is string)

Return the same string. See format for details on the format function.

defined at line 21 of anselme/stdlib/string.lua: "format", "(val::is string)",

Text

a::is text + b::is text

Concatenate two texts, returning a new text value.

defined at line 16 of anselme/stdlib/text.lua: "_+_", "(a::is text, b::is text)",

txt::is text !

Write a text event in the event buffer using this text.

defined at line 30 of anselme/stdlib/text.lua: "_!", "(txt::is text)",

tag (txt::is text, tags::is struct)

Create and return a new text from text, with the tags from tags added.

defined at line 38 of anselme/stdlib/text.lua: "tag", "(txt::is text, tags::is struct)",

write choice (text::is text, fn=attached block(keep return=true, default=($()())))

Write a choice event to the event buffer using this text and fn as the function to call if the choice is selected.

The same function is also defined in the *_ operator:

*| Choice
	42
// is the same as
write choice(| Choice |, $42)

If we are currently resuming to an anchor contained in fn, fn is directly called and the current choice event buffer will be discarded on flush, simulating the choice event buffer being sent to the host game and this choice being selected.

defined at line 57 of anselme/stdlib/text.lua: "write choice", "(text::is text, fn=attached block(keep return=true, default=($()())))",

original -> translated

Add a translation so original is replaced with translated.

defined at line 74 of anselme/stdlib/text.lua: "_->_", "(original::is(\"quote\"), translated::is(\"quote\"))",

Symbols

to string (symbol::is symbol)

Return a string of the symbol name.

defined at line 7 of anselme/stdlib/symbol.lua: "to string", "(symbol::is symbol)",

Pairs

name : value

Returns a new pair with name name and value value.

Note that if the left expression is an identifier, it is parsed as a string.

name: 42
// is the same as
"name": 42

defined at line 16 of anselme/stdlib/pair.lua: { "_:_", "(name, value)", function(state, a, b) return Pair:new(a,b) end },

name (pair::is pair)

Returns the pair pair's name.

defined at line 20 of anselme/stdlib/pair.lua: "name", "(pair::is pair)",

value (pair::is pair)

Returns the pair pair's value.

defined at line 27 of anselme/stdlib/pair.lua: "value", "(pair::is pair)",

Structures

Anselme offers:

• indexed structures: tuple (immutable) and list (mutable)
• dictionary structures: struct (immutable) and table (mutable)

:tuple = ["a","b",42]
tuple(2) // "b"

:list = *["a","b",42]
list(2) = "c"

:struct = { a: 42, 2: "b" }
struct("a") // 42

:table = *{ a: 42, 2: "b" }
table(2) = "c"

* t::is tuple

Create a list from the tuple.

defined at line 30 of anselme/stdlib/structures.lua: "*_", "(t::is tuple)",

l::is tuple, i::is number !

Returns the i-th element of the tuple.

defined at line 37 of anselme/stdlib/structures.lua: "_!", "(l::is tuple, i::is number)",

len (l::is tuple)

Returns the length of the tuple.

defined at line 44 of anselme/stdlib/structures.lua: "len", "(l::is tuple)",

find (l::is tuple, value)

Returns the index of the value element in the tuple. If value is not in the tuple, returns nil.

defined at line 51 of anselme/stdlib/structures.lua: "find", "(l::is tuple, value)",

l::is list, i::is number !

Returns the i-th element of the list.

defined at line 65 of anselme/stdlib/structures.lua: "_!", "(l::is list, i::is number)",

l::is list, i::is number ! = value

Set the i-th element of the list to value.

defined at line 72 of anselme/stdlib/structures.lua: "_!", "(l::is list, i::is number) = value",

len (l::is list)

Returns the length of the list.

defined at line 80 of anselme/stdlib/structures.lua: "len", "(l::is list)",

find (l::is list, value)

Returns the index of the value element in the list. If value is not in the list, returns nil.

defined at line 87 of anselme/stdlib/structures.lua: "find", "(l::is list, value)",

insert (l::is list, value)

Insert a new value value at the end of the list.

defined at line 99 of anselme/stdlib/structures.lua: "insert", "(l::is list, value)",

insert (l::is list, i::is number, value)

Insert a new value value at the i-th position in list, shifting the i, i+1, etc. elements by one.

defined at line 107 of anselme/stdlib/structures.lua: "insert", "(l::is list, i::is number, value)",

remove (l::is list)

Remove the last element of the list.

defined at line 115 of anselme/stdlib/structures.lua: "remove", "(l::is list)",

remove (l::is list, i::is number)

Remove the i-th element of the list, shifting the i, i+1, etc. elements by minus one.

defined at line 123 of anselme/stdlib/structures.lua: "remove", "(l::is list, i::is number)",

to tuple (l::is list)

Returns a tuple with the same content as this list.

defined at line 131 of anselme/stdlib/structures.lua: "to tuple", "(l::is list)",

* s::is struct

Create a table from the struct.

defined at line 140 of anselme/stdlib/structures.lua: "*_", "(s::is struct)",

s::is struct, key !

Returns the value associated with key in the struct.

defined at line 147 of anselme/stdlib/structures.lua: "_!", "(s::is struct, key)",

s::is struct, key, default !

Returns the value associated with key in the struct. If the key is not present in the struct, returns default instead.

defined at line 155 of anselme/stdlib/structures.lua: "_!", "(s::is struct, key, default)",

has (s::is struct, key)

Returns true if the struct contains the key key, false otherwise.

defined at line 166 of anselme/stdlib/structures.lua: "has", "(s::is struct, key)",

iter (s::is struct)

Returns an iterator over the keys of the struct.

defined at line 173 of anselme/stdlib/structures.lua: "iter", "(s::is struct)",

t::is table, key !

Returns the value associated with key in the table.

defined at line 187 of anselme/stdlib/structures.lua: "_!", "(t::is table, key)",

t::is table, key, default !

Returns the value associated with key in the table. If the key is not present in the table, returns default instead.

defined at line 195 of anselme/stdlib/structures.lua: "_!", "(t::is table, key, default)",

t::is table, key ! = value

Sets the value associated with key in the table to value, creating it if not present If value is nil, deletes the entry in the table.

defined at line 207 of anselme/stdlib/structures.lua: "_!", "(t::is table, key) = value",

t::is table, key, default ! = value

Sets the value associated with key in the table to value, creating it if not present If value is nil, deletes the entry in the table.

defined at line 216 of anselme/stdlib/structures.lua: "_!", "(t::is table, key, default) = value",

has (t::is table, key)

Returns true if the table contains the key key, false otherwise.

defined at line 224 of anselme/stdlib/structures.lua: "has", "(t::is table, key)",

to struct (t::is table)

Returns a struct with the same content as this table.

defined at line 231 of anselme/stdlib/structures.lua: "to struct", "(t::is table)",

iter (t::is sequence)

Returns an iterator that iterates over the elements of the sequence (a list or tuple).

iter (t::is table)

Returns an iterator that iterates over the keys of the table.

Function

defined (fn::is function, var::is string, search parent::is boolean=false)

Returns true if the variable named var is defined in in the function fn's scope, false otherwise.

If search parent is true, this will also search in parent scopes of the function scope.

defined at line 13 of anselme/stdlib/function.lua: "defined", "(fn::is function, var::is string, search parent::is boolean=false)",

overload (l::is sequence)

Creates and returns a new overload containing all the callables in sequence l.

defined at line 25 of anselme/stdlib/function.lua: "overload", "(l::is sequence)",

keep return (f::is function)

Returns a copy of the function that keeps return values intact when returned, instead of only returning the associated value.

defined at line 38 of anselme/stdlib/function.lua: "keep return", "(f::is function)",

call (func, args::is tuple)

Call func with the arguments in args, and returns the result. If pairs with a string name appear in args, they are interpreted as named arguments.

defined at line 47 of anselme/stdlib/function.lua: "call", "(func, args::is tuple)",

call (func, args::is tuple) = v

Call func with the arguments in args and assignment argument v, and returns the result. If pairs with a string name appear in args, they are interpreted as named arguments.

defined at line 55 of anselme/stdlib/function.lua: "call", "(func, args::is tuple) = v",

can dispatch (func, args::is tuple)

Returns true if func can be called with arguments args. If pairs with a string name appear in args, they are interpreted as named arguments.

defined at line 65 of anselme/stdlib/function.lua: "can dispatch", "(func, args::is tuple)",

can dispatch (func, args::is tuple) = v

Returns true if func can be called with arguments args and assignment argument v. If pairs with a string name appear in args, they are interpreted as named arguments.

defined at line 73 of anselme/stdlib/function.lua: "can dispatch", "(func, args::is tuple) = v",

fn::is function . var::is string

Returns the value of the variable var defined in the function fn's scope.

defined at line 83 of anselme/stdlib/function.lua: "_._", "(fn::is function, var::is string)",

fn::is function . var::is string = v

Sets the value of the variable var defined in the function fn's scope to v.

defined at line 92 of anselme/stdlib/function.lua: "_._", "(fn::is function, var::is string) = v",

fn::is function . var::is symbol = v

Define a variable var in the function fn's scope with the value v.

defined at line 102 of anselme/stdlib/function.lua: "_._", "(fn::is function, var::is symbol) = v",

return (value=())

Returns a return value with an associated value value. This can be used to exit a function.

defined at line 114 of anselme/stdlib/function.lua: "return", "(value=())",

Resuming functions

Instead of starting from the beginning of the function expression each time, functions can be started from any anchor anchor literal present in the function expression using the functions resuming functions described below.

:$f
	print(1)
	#anchor
	print(2)
f!from(#anchor) // 2
f! // 1, 2

To execute a function from an anchor, or resuming a function, Anselme, when evaluating a block, simply skip any line that does not contain the anchor literal (either in the line itself or its attached block) until we reach the anchor.

:$f
	print("not run")
	(print("run"), _)
		print("not run")
		#anchor
		print("run")
	print("run")
f!from(#anchor)

from (function::is function, anchor::is anchor)

Call the function function with no arguments, starting from the anchor anchor.

defined at line 38 of anselme/stdlib/resume.lua: "from", "(function::is function, anchor::is anchor)",

from (function::is function, anchor::is nil=())

Call the function function with no arguments, starting from the beginning.

defined at line 45 of anselme/stdlib/resume.lua: "from", "(function::is function, anchor::is nil=())",

resuming (level::is number=0)

Returns true if we are currently resuming the function call (i.e. the function started from a anchor instead of its beginning).

level indicates the position on the call stack where the resuming status should be checked. 0 is where resuming was called, 1 is where the function calling resuming was called, 2 is where the function calling the function that called resuming is called, etc.

defined at line 54 of anselme/stdlib/resume.lua: "resuming", "(level::is number=0)",

resume target ()

Returns the current resuming target (an anchor).

defined at line 65 of anselme/stdlib/resume.lua: "resume target", "()",

merge branch (complete flush=true)

Merge all variables defined or changed in the branch back into the parent branch.

If complete flush is true, all waiting events will be flushed until no events remain before merging the state.

defined at line 74 of anselme/stdlib/resume.lua: "merge branch", "(complete flush=true)",

Scripts

Scripts extends on functions to provide tracking and persistence features useful for game dialogs:

• checkpoints allow scripts to be restarted from specific points when they are interrupted or restarted;
• tracking of reached status of anchors to be able to know what has already been shown to the player;
• helper functions to call scripts in common patterns.

:hello = "hello"!script
	| Hello...
	#midway!checkpoint
		| Let's resume. Hello...
	| ...world!
hello! // Hello..., ...world!
hello! // Let's resume. Hello..., ...world!
print(hello.reached(#midway)) // 1
print(hello.run) // 2
print(hello.current checkpoint) // #midway

script (name, fn=attached block!)

Creates and returns a new script.

name is the script identifier (typically a string), which is used as a prefix for the persistent storage keys of the script variables. This means that for the script variables to be stored and retrieved properly from a game save, the script name must stays the same and be unique for each script.

fn is the function that will be run when the script is called.

Some variables are defined into the script/fn scope. They are all stored from persistent storage, using the script name as part of their persistent key:

• current checkpoint is the currently set checkpoint (an anchor);
• reached is a table of *{ #anchor = number, ... } which associates to an anchor the number of times it was reached (see check and checkpoint);
• run is the number of times the script was successfully called.

As well as functions defined in the script scope:

• check (anchor::is anchor) increment by 1 the number of times anchor was reached in reached;
• checkpoint (anchor::is anchor, on resume=attached block(default=())) sets the current checkpoint to anchor, increment by 1 the number of times anchor was reached in reached, and merge the current branch state into the parent branch. If we are currently resuming to anchor, instead this only calls on resume! and keep resuming the script from the anchor.

s::is script !

Run the script s.

If a checkpoint is set, resume the script from this checkpoint. Otherwise, run the script from the beginning. s.run is incremented by 1 after it is run.

s::is script . k::is string

Returns the value of the variable k defined in the scripts s's scope.

s::is script . k::is string = val

Sets the value of the variable k defined in the scripts s's scope to val.

s::is script . k::is symbol = val

Define the variable k in the scripts s's scope with the value val.

from (s::is script, a::is anchor)

Resume the script s from anchor a, setting it as the current checkpoint.

from (s::is script, anchor::is nil=())

Run the script s from its beginning, discarding any current checkpoint.

cycle (l::is tuple)

Run the first script in the the tuple l with a run variable strictly lower than the first element, or the first element if it has the lowest run.

This means that, if the scripts are only called through cycle, the scripts in the tuple l will be called in a cycle: when cycle is first called the 1st script is called, then the 2nd, ..., then the last, and then looping back to the 1st.

next (l::is tuple)

Run the first script in the tuple l with a run that is 0, or the last element if there is no such script.

This means that, if the scripts are only called through next, the scripts in the tuple l will be called in order: when next is first called the 1st script is called, then the 2nd, ..., then the last, and then will keep calling the last element.

random (l::is tuple)

Run a random script from the typle l.

Environment

defined (env::is environment, var::is string, search parent::is boolean=false)

Returns true if the variable named var is defined in in the environment env, false otherwise.

If search parent is true, this will also search in parent scopes of the environment env.

defined at line 14 of anselme/stdlib/environment.lua: "defined", "(env::is environment, var::is string, search parent::is boolean=false)",

c::is environment . s::is string

Gets the variable named s defined in the environment c.

defined at line 26 of anselme/stdlib/environment.lua: "_._", "(c::is environment, s::is string)",

c::is environment . s::is string = v

Sets the variable named s defined in the environment c to v.

defined at line 35 of anselme/stdlib/environment.lua: "_._", "(c::is environment, s::is string) = v",

c::is environment . s::is symbol = v

Define a new variable s in the environment c with the value v.

defined at line 45 of anselme/stdlib/environment.lua: "_._", "(c::is environment, s::is symbol) = v",

import (env::is environment, symbol tuple::is tuple)

Get all the variables indicated in the tuple symbol typle from the environment env, and define them in the current scope.

import(env, [:a, :b])
// is the same as
:a = env.a
:b = env.b

defined at line 63 of anselme/stdlib/environment.lua: "import", "(env::is environment, symbol tuple::is tuple)",

import (env::is environment, symbol::is symbol)

Get the variable symbol from the environment env, and define it in the current scope.

import(env, :a)
// is the same as
:a = env.a

defined at line 79 of anselme/stdlib/environment.lua: "import", "(env::is environment, symbol::is symbol)",

load (path::is string)

Load an Anselme script from a file and run it. Returns the environment containing the exported variables from the file.

defined at line 89 of anselme/stdlib/environment.lua: "load", "(path::is string)",

Typed values

is typed (value)

Returns true if value is a typed value, false otherwise.

defined at line 25 of anselme/stdlib/typed.lua: "is typed", "(value)",

type (value)

Returns the type of value.

If value is a typed value, returns its associated type. Otherwise, returns a string of its type ("string", "number", etc.).

defined at line 35 of anselme/stdlib/typed.lua: "type", "(value)",

type (value, type)

Returns a new typed value with value value and type type.

defined at line 46 of anselme/stdlib/typed.lua: "type", "(value, type)",

value (value)

Returns the value of value.

If value is a typed value, returns its associated value. Otherwise, returns a value directly.

defined at line 56 of anselme/stdlib/typed.lua: "value", "(value)",

Persistence helpers

Theses functions store and retrieve data from persistent storage. Persistent storage is a key-value store intended to be saved and loaded alongside the host game's save files. See the relatied Lua API methods for how to retrieve and load the persistent data.

A persistent value can be accessed like a regular variable using aliases and the warp operator:

:&var => persist("name", "Hero") // persistent value with key "name" and default value "Hero"
print(var) // gets persistent value "name": "Hero"
var = "Link" // sets persistent value "name" to "Link"

persist (key, default)

Returns the value associated with the key key in persistent storage. If the key is not defined, returns default.

defined at line 24 of anselme/stdlib/persist.lua: "persist", "(key, default)",

persist (key, default) = value

Sets the value associated with the key key in persistent storage to value.

defined at line 31 of anselme/stdlib/persist.lua: "persist", "(key, default) = value",

persist (key)

Returns the value associated with the key key in persistent storage. If the key is not defined, raise an error.

defined at line 40 of anselme/stdlib/persist.lua: "persist", "(key)",

persist (key) = value

Sets the value associated with the key key in persistent storage to value.

defined at line 47 of anselme/stdlib/persist.lua: "persist", "(key) = value",

Attached block

The attached block can usually be accessed using the _ variable. However, _ is only defined in the scope of the line the block is attached to. These functions are intended to be used to retrieve an attached block where _ can not be used directly.

// `if` use `attached block!` in order to obtain the attached block without needing to pass `_` as an argument
if(true)
	print("hello")

attached block (level::is number=1, keep return=false)

Return the attached block (as a function).

level indicates the position on the call stack where the attached block should be searched. 0 is where attached block was called, 1 is where the function calling attached block was called, 2 is where the function calling the function that called attached block is called, etc.

// level is 1, `attached block` is called from `call attached block`: the attached block will be searched from where `call attached block` was called
:$call attached block()
	:fn = attached block!
	fn!
call attached block!
	print("hello")

// level is 0: the attached block is searched where `attached block` was called, i.e. the current scope
:block = attached block(level=0)
	print("hello")
block! // hello
// which is the same as
:block = $_
	print("hello")

if keep return is true, if the attached block function returns a return value when called, it will be returned as is (instead of unwrapping only the value associated with the return), and will therefore propagate the return to the current block.

defined at line 46 of [anselme/stdlib/attached block.lua](../anselme/stdlib/attached block.lua): "attached block", "(level::is number=1, keep return=false)",

attached block (level::is number=1, keep return=false, default)

Same as the above function, but returns default if there is no attached block instead of throwing an error.

defined at line 65 of [anselme/stdlib/attached block.lua](../anselme/stdlib/attached block.lua): "attached block", "(level::is number=1, keep return=false, default)",

Tagging

tags # expression

Add the tags from tags to the tag stack while calling expression.

tags can be:

• a tuple of tags
• a struct of tags
• a table of tags
• nil, for no new tags
• any other value, for a single tag

defined at line 20 of anselme/stdlib/tag.lua: "_#_", "(tags, expression)",

Wrap operator

> expression

Returns a new function or overload with expression as the function expression.

If expression is a function call or an identifier, this returns instead an overload of two functions, defined like $<expression> and $() = v; <expression> = v, where <expression> is replaced by expression.

defined at line 14 of anselme/stdlib/wrap.lua: ">_", "(q::is(\"quote\"))",

---

file generated at 2024-06-04T14:22:53Z