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" (default) performs a full collection, "stop" and "restart" control the collector, "count" returns memory in use (in KB), "step" performs a collection step, "isrunning" returns whether the collector is running, "incremental" and "generational" set the GC mode, and "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. Requires load and fs:read pledges.

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 chunkname names the chunk for error messages, mode controls whether text ("t"), binary ("b"), or both ("bt", default) are allowed, and env sets the first upvalue as the chunk’s environment. Requires the load pledge.

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. Requires load and fs:read pledges.

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.

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", or "enum".

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; pair 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. 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. 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). Non-numeric values are skipped. Returns NaN if no numeric values exist.

Computes the sum of numeric values in array. 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 it is a number with an integer value. Returns nil if x is not an integer or not a number.

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, default), "w" (write), "a" (append), plus optional "b" for binary.

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). Requires exec pledge.

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.

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 "!", uses UTC. If format is "*t", returns a table with fields year, month, day, hour, min, sec, wday, yday, isdst. The optional time argument specifies the time to format (defaults to 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. Requires exec pledge.

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.

Returns a string identifying the current platform (e.g., "macos", "linux", "windows").

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

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. Requires fs:read and fs:write pledges.

Creates a directory at path. Returns true on success, or nil plus an error message on failure. Requires fs:write pledge.

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

Resolves a symbolic link at path and returns the target path. Returns nil plus an error message on failure. Requires fs:read pledge.

Returns a table of filenames in the directory at path. Returns nil plus an error message on failure. Requires fs:read pledge.

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

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. Requires fs:write pledge.

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

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. Requires network pledge.

The network.tcp sub-module.

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

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

The network.udp sub-module.

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

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 LZ4 HC (legacy high-compression) format data. Provided for backward compatibility with older LZ4 HC implementations. Prefer decompress for new code. 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.