Globals

Iterates over async iterator, calling it with given arguments.

Example

---@async
---@return AsyncIterator<number>
local function count( from, to )
    for i = from, to do
        futures.yield( i )
    end
end

local function main()
    for i in futures.apairs( count, 1, 5 ) do
        print( i ) -- 1, 2, 3, 4, 5
    end
end

futures.run( main )

Throws an error if the value is false or nil, otherwise returns all its arguments, like assert.

The message can be:

• nil, which throws "assertion failed!";
• a string, formatted with the remaining arguments when there are any;
• an Error, which is thrown as is;
• an error class, created with the string formatted from the remaining arguments.

local file = assert( open( path ), "cannot open '%s'", path )
assert( size >= 0, ValueError, "size must be positive, got %d", size )

Checks that the local variable at the given stack index (in the calling function) matches one of the expected types/classes given in .... If the value's type/instance does not match any of the expected types, a TypeError is raised, otherwise the function returns without doing anything.

Validates a local variable of the calling function (typically one of its parameters) against one or more validator functions, raising a ValueError on the first failure.

index is the index of the local variable in the function that called checkvalue, as in debug.getlocal. Parameters come first, so 1 is the first parameter, 2 the second, and so on. The variable's current value is read at call time, so reassigning a parameter before the check changes what gets validated.

Each validator receives the value and must return true if it is valid, or false plus an error message if it isn't. Validators run in the order given and checking stops at the first failure. Only a strict false counts as a failure, so a validator that returns nil (or nothing) is treated as passing.

On failure, the error is raised with level 2, so it points at the function that called checkvalue rather than at checkvalue itself.

local function is_positive( value )
    if value > 0 then
        return true
    end

    return false, "must be positive"
end

local function set_speed( speed )
    checkvalue( 1, is_positive )
    -- ...
end

Cancels an interval created by setInterval, so its callback will not be called anymore.

Usage example:

local interval_id = setInterval( function()
    print( "Hello, world!" )
end, 1 )

clearInterval( interval_id )

Cancels a timeout created by setTimeout, so its callback will not be called.

Usage example:

local timeout_id = setTimeout( function()
    print( "This will never be printed." )
end, 5 )

clearTimeout( timeout_id )

Returns the copy of the value.

Builds a function that dispatches each call to one of several implementations, chosen by the Lua types of the call's arguments. The multi-signature counterpart to overload, which only supports a single alternative signature.

Each entry in inputs pairs a match signature (a type name, or an ordered list of type names) with a fn. On every call, the entries are checked in order, and the first one whose signature matches exactly (same argument count, same types in the same order) has its fn called with the arguments. If nothing matches, fallback_fn is called instead; if there is no fallback_fn, an error is raised at call time.

inputs is validated up front: every fn must be a function and every match must be a string or a table, otherwise a TypeError is raised at definition time (level 2, pointing at the caller of dispatch). A bare string match is shorthand for a single-type list.

NOTE: inputs is modified in place. The entry count is cached in inputs[0], each match list gets its own count in match[0], and string match values are replaced with table equivalents. Don't reuse or edit the table after passing it in.

NOTE: a signature with no types can never match. Zero-argument calls always fall through to fallback_fn.

local describe = dispatch( {
    { match = "string",             fn = function( str ) return "a string" end },
    { match = { "number", "number" }, fn = function( a, b ) return "two numbers" end },
}, function( ... ) return "something else" end )

describe( "hi" )     --> "a string"
describe( 1, 2 )     --> "two numbers"
describe( 1 )        --> "something else"  (no signature matches: fallback_fn)

Opens the named file and executes its content as a Lua chunk.

When called without arguments, dofile executes the content of the standard input (stdin).

Returns all values returned by the chunk. In case of errors, dofile propagates the error to its caller. (That is, dofile does not run in protected mode.)

View documents

Compares two values for equality.

Unlike Lua's == operator, this function invokes the __eq metamethod from either operand if one is available. If neither operand defines __eq, it falls back to the built-in equality operator.

Throws an error with the specified message and level.

Throws an error with a formatted message, blamed on the caller of the function that calls errorf.

Use error( string.format( fmt, ... ), stack_level ) to pick another level.

Returns the current environment in use by the function.

If object does not have a metatable, returns nil.

Otherwise, if the object's metatable has a __metatable field, returns the associated value.

Otherwise, returns the metatable of the given object.

Use debug.getmetatable to get the real metatable regardless of a __metatable field.

View documents

Returns the hash of the given value.

Returns the next value in the table t, with the given index.

Returns three values (an iterator function, the table t, and 0) so that the construction

    for i,v in ipairs(t) do body end

will iterate over the key–value pairs (1,t[1]), (2,t[2]), ..., up to the first absent index.

View documents

Checks whether the value is a BigFixed.

Checks whether the value is a BigInteger.

Checks whether the value type is boolean.

Checks if the value is callable, basically it's a function or a table with a callable __call metamethod.

Checks if the value is a class.

Returns whether the given value is an error.

Checks whether the value type is a function.

Checks whether the value type is a HTMLNode.

Checks if the value is an instance of the given parent.

Checks whether the value type is a integer.

Checks whether the value type is nil.

Checks whether the value type is a number.

Checks if the value is an object created by a class.

Objects of a base that was never passed to class.create are not considered objects.

Checks whether the value type is a string.

Checks if a value is a symbol.

Checks whether the value is a table.

Checks whether the value type is a thread.

Checks if the value is an instance of the given parent.

Checks if the given value is a URL.

Checks if the given value is a URL.SearchParams.

Checks if the value is valid.

Checks whether the value type is a XMLNode.

Creates a function that accepts a variable number of arguments and returns them in the order of the specified indices.

Returns the next non-integer key–value pair in the table tbl.

Integer keys (the array part) are skipped; only hash/map keys are yielded.

Returns two values (an iterator function and the table tbl) so that the construction

    local t = { "a", "b", foo = 1, bar = 2 }

    for k, v in kpairs( t ) do
        print( k, v )
    end

    -- foo    1
    -- bar    2

will iterate over the non-integer key–value pairs of table t (the hash/map part).

Integer keys are skipped; use ipairs for the array part.

Returns the length of the given value.

Compares two values, returning whether the first is less than or equal to the second.

Unlike Lua's <= operator, this function invokes the __le metamethod from either operand if one is available. If neither operand defines __le, it falls back to the built-in less-than-or-equal operator.

Compares two values, returning whether the first is less than the second.

Unlike Lua's < operator, this function invokes the __lt metamethod from either operand if one is available. If neither operand defines __lt, it falls back to the built-in less-than operator.

Loads a binary module if available.

Loads a string as a bytecode chunk in the specified environment and returns function as a compile result.

Loads a file as a lua code chunk in the specified environment and returns function as a compile result.

Loads a string as a lua code chunk in the specified environment and returns new function as a compile result.

Checks if a binary module is available and can be loaded.

If t has a metamethod __pairs, calls it with t as argument and returns the first three results from the call.

Otherwise, returns three values: the next function, the table t, and nil, so that the construction

    for k,v in pairs(t) do body end

will iterate over all key–value pairs of table t.

See function next for the caveats of modifying the table during its traversal.

Wraps main_fn so that calls whose arguments match a specific type signature are routed to overload_fn instead, while every other call falls through to main_fn unchanged.

match describes the signature to intercept, as the exact list of Lua type names (as returned by type, e.g. "string", "number", "table") the arguments must have, in order. A call goes to overload_fn only if the number of arguments equals the number of entries in match and every argument's type matches its entry; any extra or missing arguments, or any type mismatch, calls main_fn instead. Trailing nil arguments count toward the argument total, and are matched as "nil".

A single type may be given as a bare string rather than a one-element array. An empty match array has nothing to intercept, so main_fn is returned as-is without wrapping.

local describe = overload(
    function( ... ) return "generic" end,
    { "string", "number" },
    function( str, num ) return "string + number" end
)

describe( "a", 1 )   --> "string + number"  (types and count match: overload_fn)
describe( "a" )      --> "generic"           (argument count differs: main_fn)
describe( 1, "a" )   --> "generic"           (order matters, types differ: main_fn)

If t has a metamethod __pairs, calls it with t as argument and returns the first three results from the call.

Otherwise, returns three values: the next function, the table t, and nil, so that the construction

    for k,v in pairs(t) do body end

will iterate over all key–value pairs of table t.

See function next for the caveats of modifying the table during its traversal.

View documents

Prints the given arguments to the console.

Prints the difference between two strings to the console.

The difference is computed with string.diff and printed inline as a single colored line, terminated with a newline:

• unchanged parts are printed in gray;
• parts inserted in b are printed in green;
• parts removed from a are printed in red.

Prints a formatted string to the console.

Basically the same as print( string.format( fmt, ... ) )

Prints the contents of a table to the engine console as a colorized, indented, pseudo-Lua literal, recursing into any nested tables.

String keys are printed as escaped bare keys, non-string keys are printed as [ key ], and values are rendered with represent.

Nested tables are expanded as { ... } blocks and indented one level deeper for each level of nesting; if a nested table has already been visited higher up the current branch (a cycle back to an ancestor, including tbl itself), it is printed inline followed by a -- RECURSION comment instead of being expanded again.

If expanding a nested table would exceed max_depth, it is likewise printed inline followed by a -- TOO DEEP comment instead of being walked further.

Creates a stateless numeric for-loop iterator that steps from from to to (inclusive), incrementing (or decrementing) by step each iteration.

Intended to be used directly in a generic for loop, e.g. for i in range( 1, 10, 2 ) do ... end.

Returns a string representation of the given value.

Loads the given module, returns any value returned by the searcher(true when nil). Besides that value, also returns as a second result the loader data returned by the searcher, which indicates how require found the module. (For instance, if the module came from a file, this loader data is the file path.)

View documents

Sets the environment of the specified function.

Calls the fn function every delay seconds, until the interval is cancelled with clearInterval.

Usage example:

local interval_id = setInterval( function()
    print( "Hello, world!" )
end, 1 ) -- Calls the function every second.

setTimeout( function()
    clearInterval( interval_id )
end, 5 ) -- Stops it after 5 seconds.

Calls the fn function after delay seconds.

Usage example:

setTimeout( function()
    print( "Hello, world!" )
end, 5 ) -- Calls the function after 5 seconds.

Returns binary size of the value as integer of bit/bytes.

Puts current thread to sleep for given amount of seconds.

CAUTION: This function could pause the main thread.

Gets or creates the symbol with the given name.

Symbols are interned: calling this repeatedly with the same name returns the same object as long as it is still referenced somewhere.

Creates a BigFixed object from the given value.

If value is already a BigFixed at the requested scale, it is returned unchanged.

Creates a BigInteger object from the given value.

If value is already a BigInteger, it is returned unchanged.

Creates a BigInteger object from the given value.

If value is already a BigInteger, it is returned unchanged.

If e has a metamethod __toboolean, calls it with e as argument and returns its result.

Otherwise, returns nil.

If e has a metamethod __toboolean, calls it with e as argument and returns its result.

Otherwise, returns nil.

If value has a metamethod __tocolor, calls it with value as argument and returns its result.

Otherwise, returns nil.

Converts any error value into an Error and captures its call stack if it has none yet.

Can be passed to xpcall directly as a message handler.

Returns a hexadecimal string identifying the given value.

If value's metatable defines a __hash metamethod, that function is called on value and its integer result is formatted as hex. Otherwise the value's raw memory address is used (via %p), which is stable for the lifetime of the value but has no meaning beyond identifying it — this is mainly useful for tables, functions, threads, and userdata.

If desired_length is given, the resulting string is padded with leading zeros to reach that length, or truncated from the left if it's already longer.

If e has a metamethod __tonumber, calls it with e and base as arguments and returns its result.

When called with no base, tonumber tries to convert its argument to a number. If the argument is already a number or a string convertible to a number, then tonumber returns this number; otherwise, it returns fail.

The conversion of strings can result in integers or floats, according to the lexical conventions of Lua (see §3.1). The string may have leading and trailing spaces and a sign.

View documents

Receives a value of any type and converts it to a string in a human-readable format.

If the metatable of v has a __tostring field, then tostring calls the corresponding value with v as argument, and uses the result of the call as its result.

Otherwise, if the metatable of v has a __name field with a string value, tostring may use that string in its final result.

For complete control of how numbers are converted, use string.format.

View documents

Calls the function in protected mode, converting a raised error into an Error.

Unlike pcall, the error value is always an Error with the call stack of the place it was raised, signals like ACTION_CANCEL are converted too, use xpcall with dreamwork.exceptions.catch to keep them.

Returns a string representing the name of the type of the passed object.

Displays the error with its call stack without throwing it, the current code keeps running.

Yields given arguments to the apairs listener.