Standard Library

Decision

Modular implementation, one file per library, matching PUC-Rio Lua 5.1.1 standard library behavior.

Overview

Lua 5.1.1 ships with 9 standard libraries (base, coroutine, string, table, math, io, os, debug, package). The coroutine library is registered as part of luaopen_base() but occupies its own namespace. Each library is a collection of functions registered in a table (or as globals for the base library). Libraries can be loaded selectively — an embedded Lua environment may omit io and os for sandboxing.

Libraries

Base Library (stdlib/base.rs)

Global functions not in any table.

Base Library Behavioral Notes

assert(v [, message]) — if v is nil or false, calls error(message). Default message is "assertion failed!". Returns all arguments on success.

error(message [, level]) — level 0 means no position prefix. Level 1 (default) prefixes with the current function’s location. Level 2 uses the caller’s location, etc. If message is not a string, no position prefix is added.

getfenv(f) — f can be a function or a number (stack level). Level 0 returns the thread environment. Level 1 (default) returns the current function’s environment. getfenv(0) differs from getfenv() (the latter defaults to level 1).

getmetatable(object) — if the metatable has a __metatable field, returns that field’s value instead of the actual metatable. This protects metatables from user inspection.

ipairs(t) — returns an iterator function, the table, and 0. The iterator returns index, value pairs starting at 1 until t[index] is nil. Uses raw access (no metamethods).

pcall(f, ...) — calls f(...) in protected mode. Returns true, results... on success or false, error on failure. The error object can be any type, not just strings.

select(index, ...) — if index is "#", returns the count of remaining arguments. If index is negative, counts from the end. Error: "index out of range" if the resulting position is < 1.

setfenv(f, table) — level 0 changes the thread environment (returns nothing). Cannot change environments of C functions (error: "'setfenv' cannot change environment of given object").

setmetatable(table, metatable) — first arg must be a table (not userdata). If the existing metatable has a __metatable field, error: "cannot change a protected metatable".

tonumber(e [, base]) — base 10 uses lua_isnumber (handles strings, hex 0xff, whitespace). Other bases (2-36) use unsigned integer conversion only. Returns nil on failure.

tostring(e) — checks __tostring metamethod first. Without metamethod: numbers use "%.14g" format, booleans produce "true"/"false", nil produces "nil", other types produce "typename: pointer".

unpack(list [, i [, j]]) — i defaults to 1, j defaults to #list. Returns list[i] through list[j] using raw access. Error: "table too big to unpack" if the range exceeds stack space.

xpcall(f, err) — calls f() with zero arguments (extra args are discarded). The error handler receives the original error object and its return value becomes the error returned by xpcall.

Coroutine Library (stdlib/base.rs)

String Library (stdlib/string.rs)

Registered as the string table and as the string metatable’s __index.

Lua 5.1 patterns are NOT regular expressions. They support character classes (%a, %d, %w, etc.), anchors (^, $), quantifiers (*, +, -, ?), captures, and backreferences (%1 through %9 to match a previous capture). They do not support alternation.

String Library Behavioral Notes

string.byte(s [, i [, j]]) — i defaults to 1, j defaults to i. Negative positions count from end. Returns one integer per byte (0-255). Stack check: "string slice too long".

string.char(...) — each argument must be 0-255 (error: "invalid value"). No arguments returns empty string.

string.dump(function) — function must be a Lua function, not a C function (error: "unable to dump given function").

string.find(s, pattern [, init [, plain]]) — init defaults to 1 (negative counts from end). Plain mode does literal substring search. Returns start, end, captures... on match, nil on failure. Positions are 1-based.

string.format(formatstring, ...) — specifiers: c d i o u x X e E f g G q s and %%. Flags: - + (space) # 0. Width/precision max 2 digits each. %q produces a Lua-readable quoted string (escapes ", \, newlines, \r, \0). %s with no precision and string >= 100 chars pushes directly (no truncation).

string.gmatch(s, pattern) — returns an iterator. Each call returns the next match’s captures. Empty matches advance by 1 character to prevent infinite loops.

string.gsub(s, pattern, repl [, n]) — replacement can be string (%0=match, %1-%9=captures, %%=literal %), function (called with captures; falsy return keeps original), or table (first capture as key; falsy result keeps original). Returns the result string and substitution count.

string.sub(s, i [, j]) — j defaults to -1 (end of string). Negative positions count from end. Returns empty string if start > end.

Pattern Language Specification

Character classes (from match_class in lstrlib.c):

Bracket classes: [abc] matches any of a, b, c. [^abc] negated. [a-z] ranges. % classes work inside brackets.

Single character matchers: . matches any character. %x matches a class. [...] matches a bracket class. Anything else matches literally.

Quantifiers:

Anchors: ^ at pattern start anchors to beginning. $ at pattern end anchors to end. Elsewhere they are literal.

Captures: (...) captures matched text. () captures the position (1-based integer) instead of text. Maximum 32 captures (LUA_MAXCAPTURES). Backreferences: %1 through %9 match the same text as the corresponding capture.

Special patterns: %bxy matches balanced delimiters (e.g., %b() matches balanced parentheses). %f[set] is a frontier pattern — matches a position where the previous character does not match [set] and the current character does. At string start, the “previous character” is \0.

Error conditions: "malformed pattern (ends with '%%')", "malformed pattern (missing ']')", "invalid capture index", "unfinished capture", "invalid pattern capture", "too many captures", "missing '[' after '%%f' in pattern".

Table Library (stdlib/table.rs)

Table Library Behavioral Notes

table.concat(list [, sep [, i [, j]]]) — sep defaults to "", i defaults to 1, j defaults to #list. Each element must be a string or number (error: "table contains non-strings"). Uses raw access. Returns empty string if i > j.

table.insert(list, [pos,] value) — 2 args appends at end. 3 args inserts at pos, shifting elements up. Error: "wrong number of arguments to 'insert'" for other counts.

table.maxn(list) — scans ALL keys (both parts) via next(). Returns the largest positive numeric key (including non-integer keys like 1.5). Returns 0 if no positive numeric keys exist.

table.remove(list [, pos]) — pos defaults to #list (remove from end). Shifts elements down, sets last element to nil. Returns the removed element, or nothing if the table was empty.

table.sort(list [, comp]) — Quicksort with median-of-three pivot. Tail recursion on the larger partition. Default comparison uses < (invokes __lt metamethods). Error: "invalid order function for sorting" if the comparison is inconsistent (e.g., NaN values break strict weak ordering). Not stable.

table.setn(table, n) — error: "'setn' is obsolete".

Math Library (stdlib/math.rs)

Math Library Behavioral Notes

All single-argument functions use f64 methods from Rust’s standard library. Each takes one number argument and returns one number.

math.random([m [, n]]) — 0 args: float in [0, 1). 1 arg: integer in [1, m]. 2 args: integer in [m, n]. Error: "interval is empty" if the range is invalid. Uses C rand() equivalent (deterministic for a given seed).

math.randomseed(x) — seeds the random generator. Argument must be convertible to integer.

math.min(...) / math.max(...) — requires at least 1 argument. NaN asymmetry: if NaN is the first argument, it is returned. If NaN appears later, it is skipped (since NaN < x and NaN > x are both false).

math.frexp(x) — returns 2 values: mantissa m and integer exponent e where x = m * 2^e and 0.5 <= |m| < 1.

math.modf(x) — returns 2 values: integer part and fractional part.

math.log(x) — natural logarithm only (no base parameter in 5.1). Base-10 is math.log10.

Lua % vs math.fmod: the Lua % operator uses a - floor(a/b)*b (result has same sign as b), while math.fmod uses C fmod (result has same sign as a). Example: -1 % 5 is 4 in Lua but math.fmod(-1, 5) is -1.

I/O Library (stdlib/io.rs)

OS Library (stdlib/os.rs)

Debug Library (stdlib/debug.rs)

Package Library (stdlib/package.rs)

Native Module Loading

PUC-Rio Lua’s package.loadlib loads C modules via lua_CFunction (int (*)(lua_State *)). rilua cannot load PUC-Rio C modules because:

• Rust has no stable ABI. The internal types (LuaState, Val) change layout between compiler versions.
• rilua’s function signature (fn(&mut LuaState) -> LuaResult<u32>) differs from PUC-Rio’s extern "C" fn(*mut lua_State) -> c_int.
• Building a C API compatibility shim (lua.h-compatible) would require reimplementing the entire PUC-Rio stack API (~120 functions) with extern "C" wrappers, plus maintaining ABI stability guarantees that Rust does not provide.

Instead, rilua defines its own native module ABI. Modules are Rust cdylib crates compiled against the same rilua version and rustc version as the host. This is gated behind the dynmod Cargo feature (default off). Without the feature, package.loadlib returns (nil, msg, "absent").

When dynmod is enabled:

• package.loadlib(path, funcname) loads a shared library, validates a RILUA_MODULE_INFO descriptor (magic bytes, version, struct sizes), and looks up the named entry point.
• The C module loaders (package.loaders[3] and [4]) search package.cpath for modules named rilua_open_<modname>.
• Library handles are stored as userdata with a __gc metamethod that calls dlclose/FreeLibrary on collection.

See src/dynmod.rs for the ABI contract and examples/native_module/ for a working example.

Loading

Libraries are loaded via Lua::new() (all standard libraries) or selectively via Lua::new_with(StdLib).

Mirrored at examples/selective_stdlib.rs.

use rilua::{Lua, StdLib};

fn main() -> rilua::LuaResult<()> {
    let mut lua = Lua::new_with(
        StdLib::BASE | StdLib::STRING | StdLib::TABLE | StdLib::MATH,
    )?;
    // io, os, debug, package omitted (sandboxed)
    lua.exec(r#"print(string.upper("ok"))"#)?;
    Ok(())
}

Error Message Formats

All luaL_error messages are prefixed by source location ("source:line: " or empty string).

Argument errors: "bad argument #N to 'funcname' (message)". For methods, narg is decremented by 1 (implicit self). If narg becomes 0: "calling 'name' on bad self (message)".

Type errors: "bad argument #N to 'funcname' (expected expected, got actual)".

Key format constants:

Implementation Priority

1. Base library (with coroutine) — required for any Lua program
2. String library — heavily used, pattern matching is complex
3. Table library — common operations
4. Math library — straightforward wrappers around f64 methods
5. I/O library — file operations
6. OS library — system operations
7. Package library — module system
8. Debug library — introspection, lowest priority