Module auxlib 

Auxiliary library: helper functions for building Lua libraries.

C source: reference/lua-5.4.7/src/lauxlib.c (1127 lines, ~50 functions) Target crate: lua-stdlib

This module provides the high-level luaL_* API layer that sits on top of the raw lua_* C API. In Rust we translate each luaL_* function as a free function receiving &mut LuaState rather than a method, matching the structure of the other stdlib modules.

PORT NOTE: The C buffer system (luaL_Buffer) uses a small inline initial buffer backed by a Lua-stack userdata box on overflow. In Rust we replace this with a plain Vec<u8> (LuaBuffer), dropping all the C-internal UBox / resizebox / boxgc / boxmt / newbox / buffonstack machinery. The public interface remains compatible.

PORT NOTE: File-loading functions (load_filex) use the embedder-installed GlobalState::file_loader_hook; concrete filesystem access belongs in lua-cli or another host backend.

Structs

LuaBuffer

Growable byte-buffer used by the auxiliary library for building strings.

LuaReg

A function-registration entry for set_funcs.

LuaStream

File-stream handle used by the IO library.

Constants

LUA_ERRFILE

Extended error code: file-related I/O error from load_filex.

LUA_FILE_HANDLE

Metatable name / file-handle key for the IO library.

LUA_GNAME

Name of the global environment table.

LUA_LOADED_TABLE

Registry key for the table of loaded modules.

LUA_NOREF

Pseudo-reference meaning “no reference” (never created by lua_ref).

LUA_PRELOAD_TABLE

Registry key for the table of preloaded loaders.

LUA_REFNIL

Pseudo-reference returned by lua_ref when the pushed value was nil.

Functions

add_char

Append a single byte to buf.

add_gsub

Perform global byte-string substitution: replace all occurrences of pat with repl in s, appending results into buf.

add_lstring

Append s to buf.

add_size

Append sz to the length counter (used after writing directly into the buffer).

add_value

Pop the string at top of state’s stack and append it to buf.

arg_error

Push an error for argument arg with extra message extramsg. Attempts to enrich the message with the calling function’s name. Always returns Err.

buf_init

Initialize buf and associate it with state. Pushes a placeholder light-userdata onto state to anchor the buffer in C. In Rust the Vec is self-contained; we still push a placeholder for stack-slot compatibility with code that later calls add_value / push_result.

buf_init_size

Initialize buf, reserve sz bytes, and return the writable region.

call_meta

Call the metafield event of obj with obj as argument, pushing one result. Returns true if the meta-method existed and was called.

check_any

Assert that a value (not none) is present at arg.

check_integer

Return the integer at arg as i64; raise if not an integer-convertible number.

check_lstring

Return the string at arg as bytes; raise a type error if not a string.

check_number

Return the number at arg as f64; raise a type error if not a number.

check_option

Check that arg is one of the strings in lst and return its index. If def is Some it is used as default when arg is absent/nil.

check_stack

Ensure the stack has at least space extra slots; raise on failure.

check_type

Assert that the value at arg has Lua type t; raise type error otherwise.

check_udata

Like test_udata but raises a type error if the check fails.

check_version

Version-compatibility check: error if numeric type sizes or version mismatch.

exec_result

Push the result of a process-exit status onto the stack. Returns 3 values: success-bool-or-nil, exit-kind string, status code.

file_result

Push the result of a POSIX-style file operation onto the stack. On success pushes true; on failure pushes nil, errmsg, errno. Returns the number of pushed values.

get_metafield

Push the metafield event of obj onto the stack and return its type. If there is no metafield, nothing is pushed and LuaType::Nil is returned.

get_metatable

Push registry[tname] and return its type.

get_subtable

Ensure state[idx][fname] is a table; push it. Returns true if the table already existed, false if newly created.

gsub

Build a string from s by replacing pat with repl, push it on the stack, and return the bytes of the pushed string.

load_buffer

Load a buffer as a Lua chunk (no mode argument).

load_bufferx

Load a buffer as a Lua chunk.

load_filex

Load a file as a Lua chunk. Returns LUA_OK on success or an error code.

load_string

Load a NUL-terminated byte-string as a Lua chunk.

lua_error

Format a runtime error with source location and raise it. Always returns Err.

lua_len

Return the length of the value at idx as a i64, raising an error if the length is not an integer.

lua_ref

Store the value at the top of the stack in table t and return a unique integer reference. If the value is nil, returns LUA_REFNIL without modifying the table.

lua_unref

Release reference ref from table t, adding it to the free list.

new_metatable

Create a new metatable for type tname and register it in the registry. Returns true (and leaves new metatable on stack) if the table was created; returns false (and leaves existing table on stack) if already existed.

new_state

Create a new LuaState with the default allocator, a panic handler, and warnings disabled.

opt_integer

Return the integer at arg; if absent/nil return def.

opt_lstring

Return the string at arg; if absent/nil return def.

opt_number

Return the number at arg; if absent/nil return def.

prep_buff_size

Ensure at least sz free bytes are available in buf.

push_result

Push the buffer contents as a Lua string onto state’s stack.

push_result_size

Add sz bytes to the buffer count then call push_result.

push_where

Push a string describing the location of the call at level onto the stack. If no location is available, pushes an empty string.

requiref

Simplified require: open module modname via openf, register it in package.loaded, and (if glb) in the global table. Leaves the module on top of the stack.

set_funcs

Register the functions in l into the table at -(nup + 1), giving each closure the nup upvalues currently at the top of the stack.

set_metatable

Set the metatable of the value at stack top to the one registered as tname.

test_udata

Check whether the value at ud is a full userdata with metatable tname. Returns Some(userdata) if yes, None otherwise.

to_lua_string

Convert the value at idx to a byte-string representation (using __tostring if available) and push it onto the stack.

traceback

Build a stack traceback string from thread other starting at level. If msg is non-None it is prepended on its own line. Leaves the result string on top of state.

type_error_arg

Push a type-mismatch error for argument arg, stating tname was expected. Always returns Err.