API reference

A global variable (not a function) that holds the global environment.

A global variable containing the running Lus version string.

Checks whether v is truthy. If so, returns all its arguments. Otherwise, raises an error with message (defaults to "assertion failed!").

Controls the garbage collector. The opt argument selects the operation:

• "collect" (the default) performs a full collection.
• "stop" and "restart" control the collector.
• "count" returns the memory in use, in kilobytes.
• "step" performs a collection step.
• "isrunning" returns whether the collector is running.
• "incremental" and "generational" set the GC mode.
• "param" queries or sets a GC parameter.

Opens and executes the contents of filename as a Lus chunk. When called without arguments, executes from standard input. Returns all values returned by the chunk.

Raises an error with message as the error object. The level argument specifies where the error position points: 1 (default) is the caller, 2 is the caller’s caller, and so on. Level 0 omits position information.

Parses a CSV string s and returns a table of rows. Each row is a sequential table of string values. When headers is true, the first row is used as column headers and subsequent rows are returned as tables keyed by those headers. The optional delimiter defaults to ",".

Parses a JSON string s and returns the corresponding Lus value. Tables become Lus tables, JSON null becomes nil.

Returns the metatable of object. If the metatable has a __metatable field, returns that value instead. Returns nil if the object has no metatable.

Returns an iterator function that traverses the integer keys of t in order, from t[1] up to the first absent index. Intended for use in for loops.

Loads a chunk. If chunk is a string, the chunk is that string. If it is a function, it is called repeatedly to get the chunk pieces. Returns the compiled chunk as a function, or nil plus an error message on failure.

The optional arguments refine the load:

• chunkname names the chunk for error messages.
• mode controls whether text ("t"), binary ("b"), or both ("bt", the default) are allowed.
• env sets the first upvalue as the chunk’s environment.

Loads a chunk from filename (or standard input if absent) without executing it. Returns the compiled chunk as a function, or nil plus an error message on failure. See load for the meaning of mode and env.

Returns the next key—value pair after key k in table t. When called with nil as the second argument, returns the first pair. Returns nil when there are no more pairs. The traversal order is undefined.

Returns an iterator function, the table t, and nil, so that the construction for k, v in pairs(t) iterates over all key—value pairs of t. If t has a __pairs metamethod, calls it with t as argument and returns its results.

Removed. Use the catch expression instead: local ok, result = catch f(...).

Grants or checks a permission. Returns true if the permission was granted, false if it was denied or the state is sealed.

The name arguments specify the permissions to grant or check.

Special permissions: "all" grants all permissions (CLI only), "seal" prevents future permission changes. The ~ prefix rejects a permission permanently.

pledge("fs")           -- grant filesystem access
pledge("fs:read=/tmp") -- grant read access to /tmp only
pledge("~network")     -- reject network permission
pledge("seal")         -- lock permissions

Prints its arguments to standard output, converting each to a string with tostring. Arguments are separated by tabs, followed by a newline.

Evaluates the query q and returns a fresh iterator over its result records, for use in a generic for. Each call to query(q) runs the query again, so a stored query value observes source changes on its next loop. Every result is a record: a projected field table, or the source row itself for a whole-row projection.

The logical pipeline is fixed. Every query runs these stages in order:

1. Fetch each source.
2. Join the sources.
3. Filter with where.
4. Group with group by, then filter groups with having.
5. Project with select, applying distinct.
6. Sort with order by.
7. Cut with limit and offset.

Sources come in three shapes. A plain table serves as an array of records through the built-in in-memory provider. A value whose metatable carries __query supplies its own row iterator. Native sources such as io.sqlite table references push accepted conjuncts down as parameterized SQL. All providers share the same semantics, so the same query text returns the same rows wherever it runs.

The following example filters an in-memory table and projects one field.

global query, print

local people = {
    { name = "Alice", age = 30 },
    { name = "Bob",   age = 17 },
}

for row in query(@people as p where p.age >= 18 select p.name) do
    print(row.name)
end

Checks equality of v1 and v2 without invoking the __eq metamethod. Returns true if they are primitively equal.

Gets the value of t[k] without invoking the __index metamethod.

Returns the length of v without invoking the __len metamethod. v must be a table or string.

Sets t[k] = v without invoking the __newindex metamethod. Returns t.

Loads and runs the module modname. Searches package.searchers in order to find a loader. Caches results in package.loaded so subsequent calls return the same value.

If index is a number, returns all arguments after argument number index. If index is the string "#", returns the total number of extra arguments.

Sets the metatable of table t to metatable. If metatable is nil, removes the metatable. Raises an error if the existing metatable has a __metatable field. Returns t.

Converts a table of rows t to a CSV string. Each row must be a sequential table of values. Non-string values are converted via tostring; nil values produce empty fields. Fields containing the delimiter, newlines, or double quotes are automatically quoted. The optional delimiter defaults to ",".

Converts a Lus value to a JSON string. The optional filter argument controls serialization. Objects with a __json metamethod use it for custom serialization.

Converts e to a number. If e is already a number, returns it. If e is a string, tries to parse it as a numeral. If e is an enum value, returns its 1-based index. The optional base (2—36) specifies the base for string conversion. Returns nil on failure.

Converts v to a human-readable string. If v has a __tostring metamethod, calls it with v as argument and returns the result.

Returns the type of v as a string: "nil", "number", "string", "boolean", "table", "function", "thread", "userdata", "vector", "enum", or "query".

Emits a warning by concatenating all arguments (which must be strings) and sending the result to the warning system. Warnings beginning with "@" are control messages: "@on" enables and "@off" disables warnings.

Removed. Use the catch expression instead, pairing it with debug.traceback when a traceback is needed.

Creates a copy of the table t. If deep is true, nested tables are recursively cloned. Deep copies preserve circular references.

local x = table.clone(t)        -- shallow copy
local y = table.clone(t, true)  -- deep copy

Shrinks the internal storage of t to fit its current contents and returns t. Removing keys from a table never shrinks its array or hash storage on its own, so a table that was once large keeps its capacity; table.compact releases that memory. Raises an error if t is readonly.

local cache = build_huge_table()
prune(cache)            -- removes most entries
table.compact(cache)    -- releases the now-unused capacity

Concatenate the string or number elements of table list, separated by sep (empty string by default), from index i to j.

Create a new table with pre-allocated space for narray array elements and nhash hash elements. Useful for performance when the final table size is known.

Returns a new table containing only elements of array for which predicate(element) returns a truthy value. The original table is not modified. The result is a dense sequence.

Groups elements of array by the result of keyfunc(element). Returns a new table where keys are the grouping results and values are tables of grouped elements.

Insert value at position pos in list, shifting up subsequent elements. If pos is omitted, appends to the end.

Applies func to each element of array, returning a new table of results. The function receives (element, index) as arguments. The original table is not modified.

Computes the arithmetic mean of numeric values in array. Strings naming a number count as numeric values and are coerced. Other non-numeric values are skipped. Returns NaN if no numeric values exist.

Computes the median of numeric values in array. Returns the middle value for odd-length arrays, or the average of the two middle values for even-length arrays. Strings naming a number count as numeric values and are coerced. Other non-numeric values are skipped. Does not modify the original table. Returns NaN if no numeric values exist.

Copy elements from table a1 positions f through e into table a2 (defaults to a1) starting at position t. Returns a2.

Return a new table with the given arguments as array elements, plus a field "n" set to the total number of arguments.

Reduces array to a single value by iteratively applying func(accumulator, element, index). If initial is not provided, the first element is used and iteration starts from the second. Raises an error if initial is not provided and the array is empty.

Remove the element at position pos from list, shifting down subsequent elements. Default pos is #list, so it removes the last element. Returns the removed value.

Reshapes a 1D array into a 2D matrix with the specified dimensions, filled in row-major order. The array length must equal rows * cols.

Sort list elements in place. If comp is given, it must be a function that takes two elements and returns true when the first is less than the second. The sort is not stable.

Sorts array in-place by the key returned by keyfunc(element). When asc is false, sorts in descending order. Default is ascending. Returns nothing.

Computes the standard deviation of numeric values in array. When sample is true, divides by n-1 (sample standard deviation). Otherwise divides by n (population standard deviation). Strings naming a number count as numeric values and are coerced. Other non-numeric values are skipped. Returns NaN if no numeric values exist.

Computes the sum of numeric values in array. Strings naming a number count as numeric values and are coerced. Other non-numeric values are skipped. Returns 0 for an empty table.

Transposes a 2D table (matrix) so that result[i][j] == matrix[j][i]. All rows must have the same length. Raises an error for non-rectangular matrices.

Return the elements from table list from index i to j. Defaults to i = 1 and j = #list.

Splits a table of tuples into separate tables (inverse of table.zip). Returns multiple tables, one per position in the tuples. All tuples must have the same length.

Combines multiple tables element-wise into a table of tuples. The result length equals the length of the shortest input table. Each tuple is a table {table1[i], table2[i], ...}.

Return the byte values of characters s[i] through s[j]. Defaults to i = 1 and j = i.

Return a string of characters from the given byte values.

Return a binary string containing a serialized representation of function, so that a later load on this string returns a copy of the function. If strip is true, debug information is omitted.

Look for the first match of pattern in string s. Returns the start and end indices of the match, plus any captures. Returns nil if no match is found. If init is given, the search starts at that position. If plain is true, performs a plain substring search with no pattern matching.

Return a formatted string following the description in formatstring, which follows printf-style directives. Accepts %d, %i, %u, %f, %e, %g, %x, %o, %s, %q, %c, and %%.

Return an iterator function that, each time it is called, returns the next captures from pattern in string s. If pattern has no captures, the whole match is returned. If init is given, the search starts at that position.

Return a copy of s where all (or the first n) occurrences of pattern are replaced by repl. The replacement repl can be a string, table, or function. Also returns the total number of substitutions as a second value.

Joins elements of table t into a single string with delimiter between each element. Non-string values are converted via tostring. Empty table returns an empty string.

Return the length of string s in bytes.

Return a copy of s with all uppercase letters changed to lowercase, according to the current locale.

Removes leading characters from string s. If chars is not provided, removes whitespace (space, tab, newline, carriage return). Otherwise removes all contiguous characters present in chars from the left.

Look for the first match of pattern in string s. Returns the captures from the match, or the whole match if there are no captures. Returns nil if no match is found.

Return a binary string containing the values packed according to format string fmt. See string.unpack for format codes.

Return the size of the string that would result from string.pack with format fmt. The format must not contain variable-length options.

Return a string consisting of n copies of s, separated by sep (empty string by default).

Return a string with the bytes of s in reverse order.

Removes trailing characters from string s. If chars is not provided, removes whitespace (space, tab, newline, carriage return). Otherwise removes all contiguous characters present in chars from the right.

Splits string s on the literal delimiter, returning a table of substrings. An empty delimiter splits into individual characters. Consecutive delimiters produce empty string entries.

Return the substring of s from position i to j (inclusive). Negative indices count from the end of the string. Default for j is -1 (end of string).

Transcodes string s from encoding from to encoding to. Supported encodings depend on the platform.

Removes leading and trailing characters from string s. If chars is not provided, removes whitespace (space, tab, newline, carriage return). Otherwise removes all contiguous characters present in chars from both ends.

Return the values packed in string s according to format fmt, starting at position pos (default 1). Also returns the position after the last read byte.

Return a copy of s with all lowercase letters changed to uppercase, according to the current locale.

Returns the absolute value of x.

Returns the arc cosine of x in radians.

Returns the arc sine of x in radians.

Returns the arc tangent of y/x in radians, using the signs of both arguments to determine the quadrant. x defaults to 1.

Returns the smallest integer not less than x.

Returns the cosine of angle x (in radians).

Converts angle x from radians to degrees.

Returns e raised to the power x.

Returns the largest integer not greater than x.

Returns the remainder of the division of x by y, rounding the quotient towards zero.

Returns m and e such that x = m * 2^e, where m is in [0.5, 1) and e is an integer.

The float value HUGE_VAL, greater than any other numeric value.

Returns m * 2^e.

Returns the logarithm of x in the given base. The default base is e (natural logarithm).

Returns the maximum value among its arguments.

The maximum value for an integer.

Returns the minimum value among its arguments.

The minimum value for an integer.

Returns the integral part and the fractional part of x.

The value of pi.

Converts angle x from degrees to radians.

When called without arguments, returns a uniform pseudo-random float in [0,1). With one integer m, returns an integer in [1, m]. With two integers m and n, returns an integer in [m, n].

Sets x as the seed for the pseudo-random generator. When called without arguments, seeds with a system-dependent value. Equal seeds produce equal sequences.

Returns the sine of angle x (in radians).

Returns the square root of x.

Returns the tangent of angle x (in radians).

Converts x to an integer if its value is convertible to one, meaning a number with an integer value or a string naming such a number. Returns nil when x cannot be converted.

Returns "integer" if x is an integer, "float" if it is a float, or nil if x is not a number.

Returns true if integer m is below integer n when compared as unsigned integers.

Closes file, or the default output file if no argument is given. Returns the status from the file close operation. For files opened with io.popen, returns the exit status.

Flushes the write buffer of the default output file.

When called with a filename, opens that file and sets it as the default input. When called with a file handle, sets it as the default input. When called with no arguments, returns the current default input file.

Returns an iterator function that reads from filename (or the default input if absent) according to the given formats. The file is automatically closed when the iterator finishes. Default format reads lines.

Opens filename in the given mode and returns a file handle, or nil plus an error message on failure.

Modes follow C fopen conventions: "r" (read, the default), "w" (write), "a" (append), plus an optional "b" suffix for binary. A read mode requires only fs:read. Any write or append mode requires fs:write.

When called with a filename, opens that file and sets it as the default output. When called with a file handle, sets it as the default output. When called with no arguments, returns the current default output file.

Starts the program prog in a separated process and returns a file handle for reading or writing, depending on mode ("r" for reading, default; "w" for writing).

Reads from the default input file according to the given formats. Formats: "n" reads a number, "a" reads the whole file, "l" reads a line (default, strips newline), "L" reads a line keeping the newline, or an integer n reads n bytes.

Opens the SQLite database at path and returns a database handle. SQLite is embedded in the runtime, so no external library or system package is involved. Passing ":memory:" opens a private in-memory database that needs no filesystem pledge at all. The optional mode is "rw" (the default, which reads, writes, and creates) or "r" (read-only).

A file-backed open pledge-checks the database path together with its -journal, -wal, and -shm sidecar files: fs:read always, and fs:write too under "rw". Writable file-backed databases run in WAL mode, which supports concurrent readers alongside a single writer.

The handle runs statements and queries through six methods:

• db:exec(sql) runs one or more statements for their side effects.
• db:run(sql, ...) runs a single statement with bound parameters and returns the affected row count and the last inserted row id.
• db:query(sql, ...) runs a single statement and returns an iterator over the result rows, where each row is a table keyed by column name.
• db:prepare(sql) compiles a reusable statement. The statement’s stmt:run(...) and stmt:query(...) execute it with fresh bindings, and stmt:close() releases it early.
• db:transaction(fn) runs fn inside a transaction. It commits when fn returns, passing through all of fn’s return values, and rolls back when fn raises.
• db:close() closes the handle.

Placeholders carry every value into a statement, so interpolated or concatenated text reaches the database as data. Positional ? placeholders bind from the extra arguments in order. Named placeholders (:name, @name, or $name) bind from a single table argument keyed by the bare name. Numbered ?NNN placeholders are not supported, and one statement never mixes named and positional styles.

Values map between Lus and SQLite types in both directions:

• nil binds as NULL, and NULL reads back as an absent row field.
• boolean binds as 1 or 0.
• integer binds as INTEGER, and INTEGER reads back as an integer.
• float binds as REAL, and REAL reads back as a float. Binding NaN stores NULL, following SQLite.
• string binds as TEXT, and TEXT reads back as a string.
• vector binds as BLOB, and BLOB reads back as a vector.

The handle manages its native resources the same way io.open file objects do. It carries a __close metamethod, so local db <close> = io.sqlite(path) closes the database when its block exits, including through an error, and a __gc finalizer releases any handle a program leaves open. Closing a database finalizes its live statements first. Prepared statements and query iterations follow the same lifetime rules with their own __close and __gc.

Indexing the handle with a key that is not a method yields a table reference for use as a query source, so @db.users as u where u.age > 18 select u.name pushes down as a parameterized SELECT. The reference anchors its database, and the push-down makes the same injection-safety guarantee as a hand-written statement.

SQLite never touches a path outside the pledged set: temp structures live in memory, ATTACH and VACUUM INTO are denied, and URI filenames are rejected at open. A database handle lives in the interpreter state that opened it and cannot be sent to a worker, so a worker uses a database by opening the path itself.

The following example pledges the database files, creates a table, and reads matching rows back with a named placeholder.

global io, pledge

pledge("fs:read=./app.db*", "fs:write=./app.db*", "seal")

local db <close> = io.sqlite("app.db")
db:exec("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
db:run("INSERT INTO users (name) VALUES (?)", "Alice")
for row in db:query("SELECT id, name FROM users WHERE name = :name",
                    { name = "Alice" }) do
    print(row.id, row.name)
end

Standard error file handle.

Standard input file handle.

Standard output file handle.

Returns a handle for a temporary file, opened in update mode. The file is automatically removed when the program ends.

Returns "file" if obj is an open file handle, "closed file" if it is a closed file handle, or nil if it is not a file handle.

Writes each argument to the default output file. Arguments must be strings or numbers. Returns the file handle on success, or nil plus an error message on failure.

Returns the CPU time used by the program, in seconds.

Returns a string or table with the date and time, formatted according to format. If format starts with "!", the time is formatted in UTC. If format is "*t", the result is a table with fields year, month, day, hour, min, sec, wday, yday, and isdst.

The optional time argument specifies the time to format and defaults to the current time.

Returns the difference t2 - t1 in seconds, where t1 and t2 are values returned by os.time.

Passes command to the operating system shell for execution. Returns true (or nil on failure), an exit type string ("exit" or "signal"), and the exit or signal number.

Terminates the program. The optional code argument is the exit code (true means success, false means failure, default is true). If close is true, closes the Lua state before exiting.

Returns the value of the environment variable varname, or nil if the variable is not defined.

The env pledge can be scoped to individual variables, e.g. pledge("env=HOME").

Returns a string identifying the current platform (e.g., "linux", "darwin", "windows"). The names are the lowercase uname -s style identifiers, so Apple platforms report "darwin".

Removed. Use fs.remove instead.

Removed. Use fs.move instead.

Sets the program’s current locale. The category selects which category to set (e.g., "all", "collate", "ctype", "monetary", "numeric", "time"). If locale is nil, returns the current locale for the given category. Returns the locale name, or nil on failure.

Returns the current time as a number (seconds since epoch) when called without arguments. When called with a table argument t, returns the time represented by that table (with fields year, month, day, hour, min, sec).

Returns a temporary file name suitable for use as a temporary file.

Enters interactive debugging mode. Prompts for commands from standard input. Not available in all environments.

Formats Lus source code. Returns the formatted source string.

The optional chunkname specifies the name used in error messages. The optional indent_width sets the indentation width (defaults to 2).

Returns the current hook function, hook mask (a string), and hook count for the given thread (or the current thread).

Returns a table with information about a function or stack level. The what string selects which fields to fill: "n" (name), "S" (source), "l" (line), "t" (tail call), "u" (upvalues), "f" (function), "L" (valid lines). Default is all.

Returns the name and value of local variable local at stack level f. Returns nil if there is no local variable with that index. Negative indices access vararg arguments.

Returns the metatable of value without checking __metatable.

Returns the registry table.

Returns the name and value of upvalue up of function f. Returns nil for invalid indices.

Returns the n-th user value associated with userdata u, plus a boolean indicating whether the userdata has that value.

Parses a Lus source string and returns its AST (Abstract Syntax Tree) as a nested table structure. Returns nil if parsing fails.

The optional chunkname argument specifies the name used in error messages (defaults to "=(parse)").

local ast = debug.parse("local x = 1 + 2")
-- Returns: {type = "chunk", line = 1, children = {...}}

Each AST node is a table with at minimum type (node type string) and line (source line number).

Renders the execution plan of the query q as a human-readable string without running it. The string gives tests and programs a direct observable for push-down decisions.

The plan lists each source with its provider (in-memory, __query, or native) and the number of conjuncts pushed down to it. It then reports the disposition of every where conjunct: pushed down, kept in memory as a host closure, or kept in memory as a translatable expression.

Sets the given function as a debug hook. The mask string may contain "c" (call), "r" (return), "l" (line). The count argument sets a count hook. Call with no arguments to remove the hook.

Sets the value of local variable local at stack level level to value. Returns the variable name, or nil if the index is invalid.

Sets the metatable of value to t (which can be nil). Returns value.

Sets the value of upvalue up of function f to value. Returns the upvalue name, or nil for invalid indices.

Sets the n-th user value associated with userdata u to value. Returns u.

Returns a traceback string of the call stack. The optional message is prepended. The level argument specifies where to start the traceback (default 1).

Returns a unique identifier (light userdata) for upvalue n of function f. This can be used to check whether different closures share upvalues.

Makes upvalue n1 of closure f1 refer to the same upvalue as n2 of closure f2.

Closes coroutine co, putting it in a dead state. If the coroutine was suspended with pending to-be-closed variables, those variables are closed. Returns true on success, or false plus an error message if closing a variable raises an error.

Creates a new coroutine from function f and returns it. Does not start execution; use coroutine.resume to begin.

Returns true if the running coroutine can yield. A coroutine is not yieldable when it is the main thread or inside a non-yieldable C function.

Starts or resumes execution of coroutine co. On the first resume, the extra arguments are passed to the coroutine body function. On subsequent resumes, the extra arguments become the results of the yield that suspended the coroutine.

Returns true plus any values passed to yield or returned by the body, or false plus an error message on failure.

Returns the running coroutine and a boolean. The boolean is true if the running coroutine is the main thread.

Returns the status of coroutine co as a string: "running", "suspended", "normal", or "dead".

Creates a coroutine from function f and returns a function that resumes it each time it is called. Arguments to the wrapper are passed as extra arguments to resume. Returns the values passed to yield, excluding the first boolean. Raises an error on failure (unlike resume).

Suspends the running coroutine. Arguments to yield become the extra return values of the resume that restarted this coroutine.

A string describing some compile-time configurations for packages.

The path used by require to search for a C loader.

A table used by require to control which modules are already loaded.

Dynamically loads C library libname. If funcname is "*", links the library globally. Otherwise, returns the C function funcname from the library. Returns nil plus an error message on failure.

The path used by require to search for a Lus loader.

A table to store loaders for specific modules.

A table holding the sequence of searcher functions used by require.

Searches for name in the given path string, replacing each "?" with name (with "." replaced by sep). Returns the first file that exists, or nil plus a string listing all files tried.

Return a string containing the UTF-8 encoding of the given codepoints.

The pattern which matches exactly one UTF-8 byte sequence.

Return the codepoints of all characters in s from position i to j (default i = 1, j = i).

Return an iterator function that traverses s, returning the byte position and codepoint of each UTF-8 character.

Return the number of UTF-8 characters in s from position i to j. Returns nil plus the position of the first invalid byte on failure.

Return the byte position of the n-th UTF-8 character, counting from byte position i (default 1 for positive n, #s + 1 for non-positive).

Copies the file at source to dest. Returns true on success, or nil plus an error message on failure.

Creates a directory at path. Returns true on success, or nil plus an error message on failure.

Creates a symbolic link at link pointing to target. Returns true on success, or nil plus an error message on failure.

Resolves a symbolic link at path and returns the target path. Returns nil plus an error message on failure.

Returns a table of filenames in the directory at path. Returns nil plus an error message on failure.

Moves (renames) the file or directory at source to dest. Returns true on success, or nil plus an error message on failure.

The fs.path sub-module.

The platform path list delimiter (: on POSIX, ; on Windows).

Joins path components into a single path using the platform path separator.

Returns the final component (filename) of path.

Returns the parent directory of path, or nil if path has no parent.

The platform path separator (/ on POSIX, \ on Windows).

Splits path into a table of its components.

Removes the file or directory at path. Returns true on success, or nil plus an error message on failure.

Returns the type of the filesystem entry at path as a string: "file", "directory", "link", or nil if it does not exist.

Performs an HTTP(S) request to url. The optional options table may specify method, headers, and body. Returns the response body as a string, plus the HTTP status code and a response headers table.

The network.tcp sub-module.

Binds a TCP server to host and port. Returns a server object that can accept incoming connections.

Connects to a TCP server at host and port. Returns a connection object for reading and writing.

The network.udp sub-module.

Opens a UDP socket, optionally bound to port and address. Returns a socket object for sending and receiving datagrams.

Creates a copy of the vector v.

Creates a new vector with the given capacity in bytes. If fast is true, the buffer is not zero-initialized (faster but contents are undefined).

local v = vector.create(1024)        -- zero-initialized
local v = vector.create(1024, true)  -- fast, uninitialized

Packs values into the vector v starting at offset. Uses the same format string as string.pack.

local v = vector.create(16)
vector.pack(v, 0, "I4I4I4", 1, 2, 3)

Resizes the vector to newsize bytes. New bytes are zero-initialized. Existing data within the new size is preserved.

Returns the size of the vector in bytes. Equivalent to #v.

Unpacks values from the vector v starting at offset. Uses the same format string as string.unpack. Returns unpacked values followed by the next offset.

local a, b, c, nextpos = vector.unpack(v, 0, "I4I4I4")

Returns an iterator that repeatedly unpacks values from v using the format fmt. Optional count limits the number of iterations.

for a, b in vector.unpackmany(v, 0, "I4I4") do
  print(a, b)
end

Compresses data using Brotli format (RFC 7932). The optional quality (0-11, default 11) controls compression quality. The optional lgwin (10-24, default 22) sets the LZ77 window size. Returns the same type as the input.

Decompresses Brotli-compressed data. Returns the same type as the input.

Compresses data using raw deflate format (RFC 1951) without headers. The optional level (0-9, default 6) controls the compression ratio. Returns the same type as the input.

Decompresses raw deflate-compressed data. No header or checksum validation is performed. Returns the same type as the input.

Compresses data using gzip format. The optional level (0-9, default 6) controls the compression ratio. Returns the same type as the input.

Decompresses gzip-compressed data. Validates the gzip header and CRC32 checksum. Returns the same type as the input.

Compresses data using LZ4 frame format. The optional level (1-12, default 1) controls the speed-ratio trade-off. Returns the same type as the input.

Decompresses LZ4 frame-compressed data. Validates the frame header and optional checksum. Returns the same type as the input.

Decompresses data written in the legacy LZ4 frame format, identified by the magic number 0x184C2102. Older LZ4 tools produced this format, so decompress_hc reads archives written by them. New code should compress with compress and decompress with decompress, which use the current LZ4 frame format. Returns the same type as the input.

Compresses data using Zstandard format (RFC 8878). The optional level (-7 to 22, default 3) controls the speed-ratio trade-off. Returns the same type as the input.

Decompresses Zstandard-compressed data. Validates the frame header and optional content checksum. Returns the same type as the input.

Spawns a new worker running the script at path. Optional varargs are serialized and can be received by the worker via worker.peek(). Returns a worker handle. Requires load and fs:read pledges.

local w = worker.create("worker.lus", "hello", 42)
-- worker can receive "hello" and 42 via worker.peek()

(Worker-side only) Sends value to the worker’s outbox for the parent to receive via worker.receive().

(Worker-side only) Blocking receive from the worker’s inbox. Blocks until a message from the parent (via worker.send()) is available.

Blocking select-style receive from one or more workers. Blocks until at least one worker has a message. Returns one value per worker: the message if available, or nil if that worker has no message. Propagates worker errors.

local msg = worker.receive(w)
-- or multi-worker select:
local m1, m2 = worker.receive(w1, w2)

Sends value to worker w’s inbox. The worker can receive it via worker.peek(). Values are deep-copied.

Returns the status of worker w: "running" if the worker is still executing, or "dead" if it has finished or errored.

The time module: date, time, and duration handling. It provides three immutable value types:

• instant - an absolute point on the UTC timeline (second + nanosecond precision).
• duration - a signed span of time.
• zoned - a civil (wall-clock) date and time observed at a particular zone offset.

Arithmetic on an instant is exact SI-seconds (instant + duration), while calendar arithmetic on a zoned value is a separate, DST-aware operation (zoned:add), so the two can never be confused. Distinct from os.time/os.date, which work in raw integer epochs: bridge them with time.instant(os.time()) and instant:epoch().

Returns a duration of n days. A concise alternative to time.duration{ days = n } for single-unit spans.

local timeout = time.days(5)

Constructs a duration from a table summing any of days, hours, minutes, seconds, millis, micros, nanos (each optional, may be negative).

A duration supports d:seconds(), d:millis(), d:parts() (a normalized {negative, days, hours, minutes, seconds, nanos} breakdown), the operators +, -, unary -, and duration * integer, and the comparisons ==, <, <=. See also the scalar helpers time.days, time.hours, time.minutes, time.seconds, time.millis.

Returns a duration of n hours. A concise alternative to time.duration{ hours = n } for single-unit spans.

local timeout = time.hours(5)

Constructs an instant from epoch_seconds (Unix seconds since 1970-01-01 UTC) and an optional nanos fraction. Use this to lift an os.time() value into the time type system.

An instant supports: i:epoch(), i:nanos(), i:format(fmt), i:iso(), i:at(zone) (render as a zoned in a zone or a fixed offset in seconds), the operators i + duration, i - duration, i - instant (a duration), and the comparisons ==, <, <=.

Returns the system’s local zone, detected from the environment: $TZ, then /etc/localtime//etc/timezone on Unix, or the current Windows time-zone mapped to its IANA name. Falls back to UTC when detection fails. The resolved zone is looked up in the embedded tzdata, so it carries full DST history.

print(time.now():at(time.localzone()):iso())

Returns a duration of n millis. A concise alternative to time.duration{ millis = n } for single-unit spans.

local timeout = time.millis(5)

Returns a duration of n minutes. A concise alternative to time.duration{ minutes = n } for single-unit spans.

local timeout = time.minutes(5)

Returns a monotonic instant for timing durations. Monotonic instants never move backwards and are immune to wall-clock adjustments (NTP, DST), but they have no calendar meaning: they may only be subtracted from another monotonic reading to yield a duration. Formatting one or calling :epoch() raises an error.

local start = time.monotonic()
do_work()
print(`took {time.monotonic() - start}`)

A first-class enum of the months, january = 1 through december = 12. It may be used wherever a month integer is expected (e.g. the month field of time.zoned, zoned:with, and zoned:add), taking its 1-based index. The month field of a zoned returns a plain integer, for arithmetic and parity with os.date.

local z = time.zoned{ year = 2026, month = time.month.july, day = 2 }
print(z.month)                      -- 7

Returns an instant for the current point in time, read from the system wall clock (UTC).

local n = time.now()
print(n:iso())          -- "2026-07-02T15:04:05Z"
print(n:epoch())        -- integer Unix seconds

Returns a fixed-offset zone at seconds east of UTC (negative for west), for cases where a full IANA zone is unnecessary or unavailable. Its :name() is the formatted offset, e.g. "-04:00". Unlike a named zone, a fixed offset never varies with the instant.

local z = time.offset(-5 * 3600)   -- UTC-05:00

Parses a date/time string s. Returns a zoned when the input carries an explicit numeric offset (e.g. -04:00 or -0400), or an instant when it is in UTC (Z) or offset-free (assumed UTC).

Without a format, s is read as ISO 8601: a date alone (2026-07-02, midnight UTC), a date and time separated by T or a space, optional seconds, and fractional seconds to nanosecond precision.

With a format, s is matched against an explicit pattern using the specifiers %Y %y %m %d %e %H %M %S %z and %%. A space in the pattern matches a run of whitespace; any other literal must match exactly. Parsing is portable and does not depend on the platform’s strptime.

local i = time.parse("2026-07-02T13:15:00Z")            -- ISO -> instant
local z = time.parse("02/07/2026 09:15 -0400",
                     "%d/%m/%Y %H:%M %z")               -- pattern -> zoned

Returns a duration of n seconds. A concise alternative to time.duration{ seconds = n } for single-unit spans.

local timeout = time.seconds(5)

Returns the IANA tzdata release string embedded in this build, e.g. "2026b". Regenerate the embedded database with scripts/update-tzdata.sh.

A first-class enum of the days of the week, following ISO 8601 numbering: monday = 1 through sunday = 7. The weekday field of a zoned returns one of these values.

local z = time.zoned{ year = 2026, month = 7, day = 2 }
assert(z.weekday == time.weekday.thursday)
print(tonumber(z.weekday))          -- 4

Returns a zone for an IANA name such as "America/New_York" or "Europe/Paris". Raises if the name is unknown.

Names resolve from an embedded, zstd-compressed copy of the IANA tzdata database, and time.tzdata_version() reports the release. No filesystem access or fs pledge is required: the database is compiled into the runtime, so named zones behave identically on every platform, including ones without a system tz database.

A zone supports z:name() and z:offset(instant), which returns the offset east of UTC, in seconds, that the zone observes at that instant, honouring historical DST transitions. Pass a zone to instant:at(zone) to render a civil time, or to time.zoned(fields, zone) to interpret wall-clock fields.

The following example renders the current time on the New York wall clock.

local ny = time.zone("America/New_York")
print(time.now():at(ny):iso())   -- current time as New York wall clock

Constructs a zoned civil datetime from a table of fields (year, month, day, hour, minute, second, nanosecond). Missing fields default to the start of 1970-01-01. The second argument selects how the wall-clock fields are interpreted: pass a zone (from time.zone, time.offset, or time.localzone) for a DST-aware resolution, an integer for a fixed offset east of UTC, or omit it for UTC.

A zoned exposes read-only fields year, month, day, hour, minute, second, nanosecond, weekday, yearday, and offset, plus the methods z:instant(), z:format(fmt), and z:iso(). month is an integer (1-12). weekday is a time.weekday enum value (monday through sunday).

Two methods derive new values:

• z:with{...} returns a copy with the named civil fields replaced.
• z:add{...} returns a copy advanced by calendar amounts (years, months, weeks, days, hours, minutes, seconds, nanos, negative allowed).

Both operate on the wall clock and re-resolve the offset through the originating zone. z:add{days = 1} keeps the same wall-clock time the next day even across a DST transition, and adding months clamps the day to the target month’s length (Jan 31 plus one month is Feb 28 or 29).

The following example builds a fixed-offset civil time and reads it back.

local z = time.zoned({ year = 2026, month = 7, day = 2, hour = 9 }, -4 * 3600)
print(z:iso())          -- "2026-07-02T09:00:00-04:00"
print(z.weekday)        -- 4  (Thursday)