Library guide · API index and notation
This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.
import "std/script/lua"
Names used in signatures
Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.
version
Function · Source
Lua 5.4 version strings.
pub fn version() -> &str from(static)
VERSION_NUM
Constant · Source
Version number (major * 100 + minor).
pub const VERSION_NUM: i32 = 504
RELEASE
Constant · Source
Release string of the implemented reference version.
pub const RELEASE: &str = "Lua 5.4.9"
COPYRIGHT
Constant · Source
Banner printed by the standalone interpreter (-v). It names the language version first, like PUC Lua’s banner, but credits this implementation: the code is Dodo’s own, not Lua.org’s. It still ends in “Lua.org, PUC-Rio” (naming the language’s authors), as scripts and the official test suite (main.lua) check the banner for that ending.
pub const COPYRIGHT: &str = "Lua 5.4.9 Dodo std/script/lua, implementing Lua by Lua.org, PUC-Rio"
NativeFn
Type alias · Source
Signature of native functions callable from Lua. The function receives its arguments on the stack (1..get_top()) and returns the number of results it pushed (taken from the top).
pub type NativeFn = fn(&mut Cx) -> i32!Throw
OK
Constant · Source
Status codes.
pub const OK: i32 = 0
YIELD
Constant · Source
The thread is suspended (yielded).
pub const YIELD: i32 = 1
ERRRUN
Constant · Source
Runtime error.
pub const ERRRUN: i32 = 2
ERRSYNTAX
Constant · Source
Syntax error while loading a chunk.
pub const ERRSYNTAX: i32 = 3
ERRMEM
Constant · Source
Memory allocation error.
pub const ERRMEM: i32 = 4
ERRERR
Constant · Source
Error while running the message handler.
pub const ERRERR: i32 = 5
ERRFILE
Constant · Source
Extra status of loadfile: the file could not be opened/read.
pub const ERRFILE: i32 = 6
TNONE
Constant · Source
Basic types (type_of results).
pub const TNONE: i32 = -1
TNIL
Constant · Source
nil
pub const TNIL: i32 = 0
TBOOLEAN
Constant · Source
boolean
pub const TBOOLEAN: i32 = 1
TLIGHTUSERDATA
Constant · Source
light userdata (a raw pointer)
pub const TLIGHTUSERDATA: i32 = 2
TNUMBER
Constant · Source
number (integer or float)
pub const TNUMBER: i32 = 3
TSTRING
Constant · Source
string
pub const TSTRING: i32 = 4
TTABLE
Constant · Source
table
pub const TTABLE: i32 = 5
TFUNCTION
Constant · Source
function (Lua or native)
pub const TFUNCTION: i32 = 6
TUSERDATA
Constant · Source
full userdata
pub const TUSERDATA: i32 = 7
TTHREAD
Constant · Source
thread (coroutine)
pub const TTHREAD: i32 = 8
MULTRET_ALL
Constant · Source
“All results” for calls.
pub const MULTRET_ALL: i32 = -1
REGISTRY_INDEX
Constant · Source
Pseudo-index of the registry, and of the upvalues of the running native closure (upvalue_index(1) is the first upvalue).
pub const REGISTRY_INDEX: i32 = -1001000
upvalue_index
Function · Source
Pseudo-index of upvalue i (1-based) of the running native closure.
pub fn upvalue_index(i: i32) -> i32
RIDX_MAINTHREAD
Constant · Source
Registry slots.
pub const RIDX_MAINTHREAD: i64 = 1
RIDX_GLOBALS
Constant · Source
Registry slot of the globals table.
pub const RIDX_GLOBALS: i64 = 2
OPADD
Constant · Source
Arithmetic operators for Cx.arith: addition (+).
pub const OPADD: i32 = 0
OPSUB
Constant · Source
Subtraction (-).
pub const OPSUB: i32 = 1
OPMUL
Constant · Source
Multiplication (*).
pub const OPMUL: i32 = 2
OPMOD
Constant · Source
Floor modulo (%).
pub const OPMOD: i32 = 3
OPPOW
Constant · Source
Exponentiation (^).
pub const OPPOW: i32 = 4
OPDIV
Constant · Source
Float division (/).
pub const OPDIV: i32 = 5
OPIDIV
Constant · Source
Floor division (//).
pub const OPIDIV: i32 = 6
OPBAND
Constant · Source
Bitwise and (&).
pub const OPBAND: i32 = 7
OPBOR
Constant · Source
Bitwise or (|).
pub const OPBOR: i32 = 8
OPBXOR
Constant · Source
Bitwise exclusive or (~).
pub const OPBXOR: i32 = 9
OPSHL
Constant · Source
Left shift (<<).
pub const OPSHL: i32 = 10
OPSHR
Constant · Source
Right shift (>>).
pub const OPSHR: i32 = 11
OPUNM
Constant · Source
Negation (unary -).
pub const OPUNM: i32 = 12
OPBNOT
Constant · Source
Bitwise not (unary ~).
pub const OPBNOT: i32 = 13
OPEQ
Constant · Source
Comparison operators for Cx.compare: equality (==).
pub const OPEQ: i32 = 0
OPLT
Constant · Source
Less than (<).
pub const OPLT: i32 = 1
OPLE
Constant · Source
Less or equal (<=).
pub const OPLE: i32 = 2
MASKCALL
Constant · Source
Hook masks and events.
pub const MASKCALL: i32 = 1
MASKRET
Constant · Source
Hook mask bit: function returns.
pub const MASKRET: i32 = 2
MASKLINE
Constant · Source
Hook mask bit: new source lines.
pub const MASKLINE: i32 = 4
MASKCOUNT
Constant · Source
Hook mask bit: every
countinstructions.
pub const MASKCOUNT: i32 = 8
HOOKCALL
Constant · Source
Hook event: call.
pub const HOOKCALL: i32 = 0
HOOKRET
Constant · Source
Hook event: return.
pub const HOOKRET: i32 = 1
HOOKLINE
Constant · Source
Hook event: new line.
pub const HOOKLINE: i32 = 2
HOOKCOUNT
Constant · Source
Hook event: instruction count.
pub const HOOKCOUNT: i32 = 3
HOOKTAILCALL
Constant · Source
Hook event: tail call.
pub const HOOKTAILCALL: i32 = 4
NOREF
Constant · Source
Reference values of Cx.reference.
pub const NOREF: i32 = -2
REFNIL
Constant · Source
Reference returned for nil values.
pub const REFNIL: i32 = -1
LuaStr
Struct · Source
A view of a Lua string’s bytes. It stays valid while the string is reachable (for strings obtained from a stack slot: while that slot keeps the string), independently of later Cx operations.
pub struct LuaStr {
// Private implementation fields omitted.
}
LuaStr.bytes
Function · Source
The bytes (without the terminating NUL the runtime keeps after them).
pub fn bytes(&self) -> &[u8]
LuaStr.size
Function · Source
Number of bytes.
pub fn size(&self) -> usize
LuaStr.as_ptr
Function · Source
Pointer to the bytes, which are followed by a NUL byte.
pub fn as_ptr(&self) -> *const u8
Lua
Struct · Source
A Lua universe: global state and main thread.
pub struct Lua {
// Private implementation fields omitted.
}
Lua.new
Function · Source
Create a new state with no libraries loaded (Throw.Memory if the allocation fails).
pub fn new() -> Lua!Throw
Lua.cx
Function · Source
Handle on the main thread.
pub fn cx(&mut self) -> Cx
Lua.open_libs
Function · Source
Open every standard library available in this build into the globals.
pub fn open_libs(&mut self) -> void!Throw
Lua.preload_module
Function · Source
Register a native module for
require(see Cx.preload_module).
pub fn preload_module(&mut self, name: &str, open: NativeFn) -> void!Throw
Lua.memory_in_use
Function · Source
Bytes currently allocated by the state.
pub fn memory_in_use(&self) -> usize
Lua.set_warn_fn
Function · Source
Install a warning function (replacing the default one, which writes “Lua warning: …” to stderr when warnings are on).
pub fn set_warn_fn(&mut self, f: WarnFn)
Lua.set_memory_limit
Function · Source
Limit the memory the state may allocate (0: unlimited). Allocations beyond the limit first trigger an emergency collection, then raise “not enough memory”.
pub fn set_memory_limit(&mut self, limit: usize)
Lua.set_gc_stress
Function · Source
Testing aid: make the collector work at every check point (where it may run), not only when the allocation debt asks for it. Level 0 turns this off, 1 runs one incremental step and 2 a full collection at each check point. Programs behave the same, only (much) slower; this shakes out missing write barriers and unanchored objects in native code.
pub fn set_gc_stress(&mut self, level: i32)
Lua.close
Function · Source
Close the state now (running pending finalizers) and return the number of bytes that were not released (0 when nothing leaked).
pub fn close(&mut self) -> usize
Cx
Struct · Source
Handle on one Lua thread; native functions receive one for the calling thread. A Cx is only valid while its thread is alive (the main thread: while the Lua value lives).
pub struct Cx {
// Private implementation fields omitted.
}
Cx.get_top
Function · Source
Index of the top element (= number of elements in the frame).
pub fn get_top(&self) -> i32
Cx.set_top
Function · Source
Set the top (non-negative: absolute; negative: relative). New slots are nil. Does not run __close (see close_slot).
pub fn set_top(&mut self, idx: i32)
Cx.pop
Function · Source
Pop n elements.
pub fn pop(&mut self, n: i32)
Cx.abs_index
Function · Source
Absolute version of an index.
pub fn abs_index(&self, idx: i32) -> i32
Cx.check_stack
Function · Source
Ensure room for n more elements; false if impossible.
pub fn check_stack(&mut self, n: i32) -> bool
Cx.push_value
Function · Source
Push a copy of the element at idx.
pub fn push_value(&mut self, idx: i32)
Cx.rotate
Function · Source
Rotate the elements between idx and the top by n positions (towards the top for positive n).
pub fn rotate(&mut self, idx: i32, n: i32)
Cx.copy
Function · Source
Copy the element at
fromintoto.
pub fn copy(&mut self, fromidx: i32, toidx: i32)
Cx.insert
Function · Source
Move the top element into position idx, shifting up.
pub fn insert(&mut self, idx: i32)
Cx.remove
Function · Source
Remove the element at idx, shifting down.
pub fn remove(&mut self, idx: i32)
Cx.replace
Function · Source
Pop the top element into position idx.
pub fn replace(&mut self, idx: i32)
Cx.xmove
Function · Source
Move n values from this thread to
to(same universe).
pub fn xmove(&mut self, to: &mut Cx, n: i32)
Cx.push_nil
Function · Source
Push nil.
pub fn push_nil(&mut self)
Cx.push_boolean
Function · Source
Push a boolean.
pub fn push_boolean(&mut self, b: bool)
Cx.push_integer
Function · Source
Push an integer.
pub fn push_integer(&mut self, n: i64)
Cx.push_number
Function · Source
Push a float.
pub fn push_number(&mut self, n: f64)
Cx.push_bytes
Function · Source
Push a string with these bytes.
pub fn push_bytes(&mut self, b: &[u8]) -> void!Throw
Cx.push_str
Function · Source
Push a string from UTF-8 text.
pub fn push_str(&mut self, s: &str) -> void!Throw
Cx.push_raw_bytes
Function · Source
Push a string from raw bytes (ptr, len).
pub fn push_raw_bytes(&mut self, p: *const u8, n: usize) -> void!Throw
Cx.push_light_userdata
Function · Source
Push a light userdata (a raw pointer value).
pub fn push_light_userdata(&mut self, p: *mut u8)
Cx.push_native
Function · Source
Push a native function (no upvalues).
pub fn push_native(&mut self, f: NativeFn) -> void!Throw
Cx.push_closure
Function · Source
Push a native closure taking its n upvalues from the top of the stack.
pub fn push_closure(&mut self, f: NativeFn, n: i32) -> void!Throw
Cx.push_thread
Function · Source
Push this thread; true if it is the main thread.
pub fn push_thread(&mut self) -> bool
Cx.push_global_table
Function · Source
Push the globals table.
pub fn push_global_table(&mut self)
Cx.push_fail
Function · Source
Push the “fail” value (nil).
pub fn push_fail(&mut self)
Cx.type_of
Function · Source
Type of the value at idx (TNONE for an invalid index).
pub fn type_of(&self, idx: i32) -> i32
Cx.type_name
Function · Source
Name of a type code (“no value” for TNONE).
pub fn type_name(&self, t: i32) -> &str from(static)
Cx.is_none
Function · Source
The index is not valid (above the top).
pub fn is_none(&self, idx: i32) -> bool
Cx.is_nil
Function · Source
The value is nil.
pub fn is_nil(&self, idx: i32) -> bool
Cx.is_none_or_nil
Function · Source
The index is not valid (above the top).
pub fn is_none_or_nil(&self, idx: i32) -> bool
Cx.is_boolean
Function · Source
The value is a boolean.
pub fn is_boolean(&self, idx: i32) -> bool
Cx.is_table
Function · Source
The value is a table.
pub fn is_table(&self, idx: i32) -> bool
Cx.is_function
Function · Source
The value is a function.
pub fn is_function(&self, idx: i32) -> bool
Cx.is_thread
Function · Source
The value is a thread.
pub fn is_thread(&self, idx: i32) -> bool
Cx.is_light_userdata
Function · Source
The value is a light userdata.
pub fn is_light_userdata(&self, idx: i32) -> bool
Cx.is_userdata
Function · Source
Full or light userdata.
pub fn is_userdata(&self, idx: i32) -> bool
Cx.is_native_function
Function · Source
The value is a native (Dodo) function.
pub fn is_native_function(&self, idx: i32) -> bool
Cx.is_number
Function · Source
A number or a string convertible to a number.
pub fn is_number(&self, idx: i32) -> bool
Cx.is_string
Function · Source
A string or a number (numbers convert to strings).
pub fn is_string(&self, idx: i32) -> bool
Cx.is_integer
Function · Source
An integer value (not a float).
pub fn is_integer(&self, idx: i32) -> bool
Cx.is_yieldable
Function · Source
The thread can yield here.
pub fn is_yieldable(&self) -> bool
Cx.to_integer
Function · Source
Integer value (strings and integral floats convert), or none.
pub fn to_integer(&self, idx: i32) -> Option<i64>
Cx.to_number
Function · Source
Float value (strings convert), or none.
pub fn to_number(&self, idx: i32) -> Option<f64>
Cx.to_boolean
Function · Source
Truth value (false only for nil and false).
pub fn to_boolean(&self, idx: i32) -> bool
Cx.to_lstr
Function · Source
String value (numbers are converted in place, like lua_tolstring), or none for other types.
pub fn to_lstr(&mut self, idx: i32) -> Option<LuaStr>!Throw
Cx.raw_len
Function · Source
Raw length: string length, table border without __len, userdata size.
pub fn raw_len(&self, idx: i32) -> u64
Cx.to_userdata
Function · Source
Address of a full userdata’s block or a light userdata, else null.
pub fn to_userdata(&self, idx: i32) -> *mut u8
Cx.to_pointer
Function · Source
Generic pointer identifying the value (for “%p” style output).
pub fn to_pointer(&self, idx: i32) -> *const u8
Cx.to_thread
Function · Source
Handle on the thread at idx.
pub fn to_thread(&self, idx: i32) -> Option<Cx>
Cx.to_native
Function · Source
The native function at idx, if any.
pub fn to_native(&self, idx: i32) -> Option<NativeFn>
Cx.raw_equal
Function · Source
Primitive equality (no __eq).
pub fn raw_equal(&self, i1: i32, i2: i32) -> bool
Cx.compare
Function · Source
Compare two values with metamethods (OPEQ, OPLT, OPLE).
pub fn compare(&mut self, i1: i32, i2: i32, op: i32) -> bool!Throw
Cx.arith
Function · Source
Arithmetic over the top two values (one for OPUNM/OPBNOT), replaced by the result.
pub fn arith(&mut self, op: i32) -> void!Throw
Cx.concat
Function · Source
Concatenate the top n values (n = 0 pushes “”).
pub fn concat(&mut self, n: i32) -> void!Throw
Cx.len
Function · Source
Push the length of the value at idx (with __len).
pub fn len(&mut self, idx: i32) -> void!Throw
Cx.string_to_number
Function · Source
Convert a numeral string and push its value; returns the string size plus one on success, 0 otherwise.
pub fn string_to_number(&mut self, s: &[u8]) -> usize
Cx.new_table
Function · Source
Push a new empty table.
pub fn new_table(&mut self) -> void!Throw
Cx.create_table
Function · Source
Push a new table with preallocated space.
pub fn create_table(&mut self, narr: i32, nrec: i32) -> void!Throw
Cx.get_table
Function · Source
Push t[k] (t at idx, k popped from the top), with metamethods.
pub fn get_table(&mut self, idx: i32) -> i32!Throw
Cx.get_field
Function · Source
Push t[name].
pub fn get_field(&mut self, idx: i32, name: &str) -> i32!Throw
Cx.get_field_bytes
Function · Source
Push t[name] for a byte-string name.
pub fn get_field_bytes(&mut self, idx: i32, name: &[u8]) -> i32!Throw
Cx.set_field_bytes
Function · Source
t[name] = v (v popped) for a byte-string name.
pub fn set_field_bytes(&mut self, idx: i32, name: &[u8]) -> void!Throw
Cx.get_global_bytes
Function · Source
Push the global with a byte-string name.
pub fn get_global_bytes(&mut self, name: &[u8]) -> i32!Throw
Cx.set_global_bytes
Function · Source
Set the global with a byte-string name to the popped value.
pub fn set_global_bytes(&mut self, name: &[u8]) -> void!Throw
Cx.get_i
Function · Source
Push t[n].
pub fn get_i(&mut self, idx: i32, n: i64) -> i32!Throw
Cx.get_global
Function · Source
Push the global
name.
pub fn get_global(&mut self, name: &str) -> i32!Throw
Cx.set_table
Function · Source
t[k] = v with t at idx, k and v on top (both popped).
pub fn set_table(&mut self, idx: i32) -> void!Throw
Cx.set_field
Function · Source
t[name] = v (v popped).
pub fn set_field(&mut self, idx: i32, name: &str) -> void!Throw
Cx.set_i
Function · Source
t[n] = v (v popped).
pub fn set_i(&mut self, idx: i32, n: i64) -> void!Throw
Cx.set_global
Function · Source
Set global
nameto the popped value.
pub fn set_global(&mut self, name: &str) -> void!Throw
Cx.raw_get
Function · Source
Raw t[k] (k popped, value pushed); t must be a table.
pub fn raw_get(&mut self, idx: i32) -> i32
Cx.raw_get_i
Function · Source
Push raw t[n].
pub fn raw_get_i(&mut self, idx: i32, n: i64) -> i32
Cx.raw_get_p
Function · Source
Push raw t[p] for a light userdata key.
pub fn raw_get_p(&mut self, idx: i32, p: *mut u8) -> i32
Cx.raw_set
Function · Source
Raw t[k] = v (k, v popped).
pub fn raw_set(&mut self, idx: i32) -> void!Throw
Cx.raw_set_i
Function · Source
Raw t[n] = v (v popped).
pub fn raw_set_i(&mut self, idx: i32, n: i64) -> void!Throw
Cx.raw_set_p
Function · Source
Raw t[p] = v for a light userdata key (v popped).
pub fn raw_set_p(&mut self, idx: i32, p: *mut u8) -> void!Throw
Cx.get_metatable
Function · Source
Push the metatable of the value at idx; false (nothing pushed) if none.
pub fn get_metatable(&mut self, idx: i32) -> bool
Cx.set_metatable
Function · Source
Pop a table (or nil) and make it the metatable of the value at idx.
pub fn set_metatable(&mut self, idx: i32)
Cx.next
Function · Source
Table traversal: pops a key and pushes the next key and value (returns false, pushing nothing, at the end).
pub fn next(&mut self, idx: i32) -> bool!Throw
Cx.new_userdata
Function · Source
Push a new full userdata with
sizebytes andnuvuser values; returns its block address (16-byte aligned).
pub fn new_userdata(&mut self, size: usize, nuv: i32) -> (*mut u8)!Throw
Cx.get_iuservalue
Function · Source
Push user value n of the userdata at idx; returns its type (TNONE if there is no such value, pushing nil).
pub fn get_iuservalue(&mut self, idx: i32, n: i32) -> i32
Cx.set_iuservalue
Function · Source
Pop a value into user value n of the userdata at idx (false if none).
pub fn set_iuservalue(&mut self, idx: i32, n: i32) -> bool
Cx.call
Function · Source
Call the function below the top
nargsarguments.
pub fn call(&mut self, nargs: i32, nresults: i32) -> void!Throw
Cx.call_k
Function · Source
Call with a continuation: if the callee yields,
kis called (with status YIELD) when the coroutine resumes, instead of returning here.
pub fn call_k(&mut self, nargs: i32, nresults: i32, ctx: isize, k: ContinuationFn) -> void!Throw
Cx.pcall
Function · Source
Protected call;
msghis the stack index of a message handler (0: none). Returns the status; on error the error object is on top.
pub fn pcall(&mut self, nargs: i32, nresults: i32, msgh: i32) -> i32
Cx.pcall_k
Function · Source
Protected call with continuation (see call_k). The Throw is only ever Yield, which the native function must propagate.
pub fn pcall_k(&mut self, nargs: i32, nresults: i32, msgh: i32, ctx: isize, k: ContinuationFn) -> i32!Throw
Cx.error
Function · Source
Raise the value on top of the stack as an error:
return err(cx.error()).
pub fn error(&mut self) -> Throw
Cx.yield_
Function · Source
Yield from a native function:
return err(cx.yield_(n)).
pub fn yield_(&mut self, nresults: i32) -> Throw
Cx.yield_k
Function · Source
Yield with a continuation called on resume.
pub fn yield_k(&mut self, nresults: i32, ctx: isize, k: ContinuationFn) -> Throw
Cx.resume
Function · Source
Resume the coroutine
cowith its topnargsvalues; returns the status and stores the number of results (on co’s stack) in nres.
pub fn resume(&mut self, co: &mut Cx, nargs: i32, nres: &mut i32) -> i32
Cx.status
Function · Source
Thread status (OK, YIELD or an error status).
pub fn status(&self) -> i32
Cx.new_thread
Function · Source
Push a new coroutine; returns its handle.
pub fn new_thread(&mut self) -> Cx!Throw
Cx.close_thread
Function · Source
Reset a thread (coroutine.close): close pending to-be-closed variables and return the status (the error object is on top on error).
pub fn close_thread(&mut self, caller: &mut Cx) -> i32
Cx.thread_handle
Function · Source
Another handle on the same thread (for APIs that take a thread argument, such as traceback, applied to the current thread).
pub fn thread_handle(&self) -> Cx
Cx.open_libs
Function · Source
Open every standard library available in this build into the globals.
pub fn open_libs(&mut self) -> void!Throw
Cx.same_thread
Function · Source
Same universe check: whether two handles are the same thread.
pub fn same_thread(&self, other: &Cx) -> bool
Cx.to_close
Function · Source
Mark the slot at idx as to-be-closed (closed by close_slot or when the native function returns).
pub fn to_close(&mut self, idx: i32) -> void!Throw
Cx.close_slot
Function · Source
Close the to-be-closed slot at idx (and set it to nil).
pub fn close_slot(&mut self, idx: i32) -> void!Throw
Cx.gc_collect
Function · Source
Full collection.
pub fn gc_collect(&mut self)
Cx.gc_stop
Function · Source
Stop the collector (emergency collections still run).
pub fn gc_stop(&mut self)
Cx.gc_restart
Function · Source
Restart the collector.
pub fn gc_restart(&mut self)
Cx.gc_is_running
Function · Source
Whether the collector is running.
pub fn gc_is_running(&self) -> bool
Cx.gc_count_bytes
Function · Source
Memory in use, in bytes.
pub fn gc_count_bytes(&self) -> usize
Cx.gc_step
Function · Source
One step (
kb: extra kilobytes of debt, 0 for a basic step); true if a cycle finished.
pub fn gc_step(&mut self, kb: i64) -> bool
Cx.gc_incremental
Function · Source
Switch to incremental mode (parameters <= 0 keep the current value); returns the previous mode name.
pub fn gc_incremental(&mut self, pause: i32, stepmul: i32, stepsize: i32) -> &str from(static)
Cx.gc_generational
Function · Source
Switch to generational mode; returns the previous mode name.
pub fn gc_generational(&mut self, minormul: i32, majormul: i32) -> &str from(static)
Cx.gc_set_pause
Function · Source
Set the pause (percent); returns the previous value.
pub fn gc_set_pause(&mut self, v: i32) -> i32
Cx.gc_set_stepmul
Function · Source
Set the step multiplier; returns the previous value.
pub fn gc_set_stepmul(&mut self, v: i32) -> i32
Cx.warning
Function · Source
Emit a warning piece (
tocont: more pieces follow).
pub fn warning(&mut self, msg: &[u8], tocont: bool)
Cx.get_upvalue
Function · Source
Push upvalue n of the function at funcindex; returns its name (“” for native closures) or none if there is no such upvalue.
pub fn get_upvalue(&mut self, funcindex: i32, n: i32) -> Option<LuaStr>
Cx.set_upvalue
Function · Source
Pop a value into upvalue n of the function at funcindex.
pub fn set_upvalue(&mut self, funcindex: i32, n: i32) -> Option<LuaStr>
Cx.upvalue_id
Function · Source
Identity of upvalue n of the function at funcindex (null if none).
pub fn upvalue_id(&self, funcindex: i32, n: i32) -> *mut u8
Cx.upvalue_join
Function · Source
Make upvalue n1 of Lua closure f1 refer to upvalue n2 of closure f2.
pub fn upvalue_join(&mut self, f1: i32, n1: i32, f2: i32, n2: i32)
Cx.get_stack
Function · Source
Activation record of the function
levellevels up the stack (0 = current). False if the level is out of range.
pub fn get_stack(&mut self, level: i32, ar: &mut Debug) -> bool
Cx.get_info
Function · Source
Fill
arwith the fields selected bywhat(‘n’, ‘S’, ‘l’, ‘u’, ‘t’, ‘r’; ‘f’ pushes the function, ‘L’ pushes the table of active lines). A leading ‘>’ takes the function from the top of the stack (popped) instead of the record’s frame. Returns false for invalid options.
pub fn get_info(&mut self, what: &str, ar: &mut Debug) -> bool!Throw
Cx.get_local
Function · Source
Push local variable n of the frame described by
arand return its name; none (nothing pushed) if there is no such local.
pub fn get_local(&mut self, ar: &Debug, n: i32) -> Option<LuaStr>
Cx.get_param_name
Function · Source
Name of parameter n of the Lua function on top of the stack (not popped), for get_local with a function instead of a frame.
pub fn get_param_name(&mut self, n: i32) -> Option<LuaStr>
Cx.set_local
Function · Source
Pop a value into local n of the frame described by
ar; returns the name or none (the value is popped either way).
pub fn set_local(&mut self, ar: &Debug, n: i32) -> Option<LuaStr>
Cx.watch_interrupt
Function · Source
While
on, the first SIGINT (Ctrl-C) makes the Lua code running in this thread raise “interrupted!” at its next jump, loop or call; the handler then restores the default action, so a second SIGINT ends a program stuck in native code. This is what the standalone interpreter does around each chunk it runs. Turn it off before the thread is closed.
pub fn watch_interrupt(&mut self, on: bool)
Cx.set_hook
Function · Source
Install (or remove, with mask 0) the debug hook of this thread.
pub fn set_hook(&mut self, f: HookFn, mask: i32, count: i32)
Cx.clear_hook
Function · Source
Remove the debug hook.
pub fn clear_hook(&mut self)
Cx.get_hook
Function · Source
The installed hook function (lua_gethook), or none.
pub fn get_hook(&self) -> Option<HookFn>
Cx.get_hook_mask
Function · Source
Current hook mask.
pub fn get_hook_mask(&self) -> i32
Cx.get_hook_count
Function · Source
Current hook count.
pub fn get_hook_count(&self) -> i32
Cx.has_hook
Function · Source
Whether a hook is installed.
pub fn has_hook(&self) -> bool
Cx.load_buffer
Function · Source
Load a chunk (text or binary) and push it as a function; on error push the message.
modeis “b”, “t” or “bt”.
pub fn load_buffer(&mut self, chunk: &[u8], chunkname: &str, mode: &str) -> i32
Cx.load_bytes
Function · Source
Same with byte-string chunk name and mode.
pub fn load_bytes(&mut self, chunk: &[u8], chunkname: &[u8], mode: &[u8]) -> i32
Cx.dump
Function · Source
Push the binary chunk of the Lua function on top (stripping debug information if asked). False if the value is not a Lua function.
pub fn dump(&mut self, strip: bool) -> bool!Throw
Cx.arg_error
Function · Source
Raise “bad argument #arg to ‘fname’ (msg)”.
pub fn arg_error(&mut self, arg: i32, msg: &str) -> Throw
Cx.arg_error_bytes
Function · Source
arg_error with a byte-string message.
pub fn arg_error_bytes(&mut self, arg: i32, msg: &[u8]) -> Throw
Cx.type_error
Function · Source
Raise “bad argument … (tname expected, got <type>)”.
pub fn type_error(&mut self, arg: i32, tname: &str) -> Throw
Cx.arg_check
Function · Source
Check a condition on an argument.
pub fn arg_check(&mut self, cond: bool, arg: i32, msg: &str) -> void!Throw
Cx.arg_expected
Function · Source
Check an argument’s type condition (raising a type error with tname).
pub fn arg_expected(&mut self, cond: bool, arg: i32, tname: &str) -> void!Throw
Cx.check_integer
Function · Source
Integer argument (integral floats and numeric strings convert).
pub fn check_integer(&mut self, arg: i32) -> i64!Throw
Cx.opt_integer
Function · Source
Optional integer argument.
pub fn opt_integer(&mut self, arg: i32, def: i64) -> i64!Throw
Cx.check_number
Function · Source
Number argument (numeric strings convert).
pub fn check_number(&mut self, arg: i32) -> f64!Throw
Cx.opt_number
Function · Source
Optional number argument.
pub fn opt_number(&mut self, arg: i32, def: f64) -> f64!Throw
Cx.check_lstr
Function · Source
String argument (numbers are converted in place).
pub fn check_lstr(&mut self, arg: i32) -> LuaStr!Throw
Cx.opt_lstr
Function · Source
Optional string argument with a static default.
pub fn opt_lstr(&mut self, arg: i32, def: &[u8]) -> LuaStr!Throw
Cx.check_any
Function · Source
Raise “value expected” if the argument is absent.
pub fn check_any(&mut self, arg: i32) -> void!Throw
Cx.check_type
Function · Source
Raise a type error unless the argument has type t.
pub fn check_type(&mut self, arg: i32, t: i32) -> void!Throw
Cx.check_option
Function · Source
Index of the string argument in
list(or ofdefwhen the argument is absent and def is non-empty); raises “invalid option ‘x’”.
pub fn check_option(&mut self, arg: i32, def: &str, list: &[&str]) -> i32!Throw
Cx.check_stack_msg
Function · Source
Grow the stack or raise “stack overflow (msg)”.
pub fn check_stack_msg(&mut self, n: i32, msg: &str) -> void!Throw
Cx.error_msg
Function · Source
Raise an error with position information of the caller (luaL_error):
return err(cx.error_msg("...")).
pub fn error_msg(&mut self, msg: &str) -> Throw
Cx.error_bytes
Function · Source
error_msg with a byte-string message.
pub fn error_bytes(&mut self, msg: &[u8]) -> Throw
Cx.error_buffer
Function · Source
Raise the contents of a Buffer as an error with position information.
pub fn error_buffer(&mut self, buf: &mut Buffer) -> Throw
Cx.where_
Function · Source
Push “short_src:line: “ of the function at
level(or “”).
pub fn where_(&mut self, level: i32) -> void!Throw
Cx.get_metafield
Function · Source
Push field
eventof the metatable of obj; returns its type (TNIL, pushing nothing, when absent).
pub fn get_metafield(&mut self, obj: i32, event: &str) -> i32!Throw
Cx.call_meta
Function · Source
Call metamethod
eventof obj with obj as argument, pushing its result; false (nothing pushed) if there is no such metamethod.
pub fn call_meta(&mut self, obj0: i32, event: &str) -> bool!Throw
Cx.to_lstring_meta
Function · Source
Push the string form of any value (as
tostringdoes: __tostring, __name, numbers, “type: 0x…”), returning a view of it.
pub fn to_lstring_meta(&mut self, idx0: i32) -> LuaStr!Throw
Cx.len_of
Function · Source
Length of the value at idx (with __len) as an integer.
pub fn len_of(&mut self, idx: i32) -> i64!Throw
Cx.new_metatable
Function · Source
Create (or find) registry[tname] as a metatable with __name = tname and push it; true if it was created.
pub fn new_metatable(&mut self, tname: &str) -> bool!Throw
Cx.get_metatable_by_name
Function · Source
Push registry[tname]; returns its type.
pub fn get_metatable_by_name(&mut self, tname: &str) -> i32!Throw
Cx.set_metatable_by_name
Function · Source
Set registry[tname] as the metatable of the value on top.
pub fn set_metatable_by_name(&mut self, tname: &str) -> void!Throw
Cx.test_udata
Function · Source
Block of the userdata at arg if its metatable is registry[tname], else null.
pub fn test_udata(&mut self, arg: i32, tname: &str) -> (*mut u8)!Throw
Cx.check_udata
Function · Source
Like test_udata, raising a type error on mismatch.
pub fn check_udata(&mut self, arg: i32, tname: &str) -> (*mut u8)!Throw
Cx.set_funcs
Function · Source
Register functions into the table below the
nupupvalues on top; each function gets copies of the upvalues (which are then popped).
pub fn set_funcs(&mut self, funcs: &[(&str, NativeFn)], nup: i32) -> void!Throw
Cx.new_lib
Function · Source
Push a new table with the given functions.
pub fn new_lib(&mut self, funcs: &[(&str, NativeFn)]) -> void!Throw
Cx.get_subtable
Function · Source
Push t[fname] (t at idx), creating it as a table if needed; true if it already existed.
pub fn get_subtable(&mut self, idx0: i32, fname: &str) -> bool!Throw
Cx.require_lib
Function · Source
luaL_requiref: if package.loaded[modname] is not true, call openf(modname) and store its result there; push the module, and also set it as global
modnamewhen glb.
pub fn require_lib(&mut self, modname: &str, openf: NativeFn, glb: bool) -> void!Throw
Cx.preload_module
Function · Source
Register a native module for
require: storesopenas package.preload[name] (the registry table “_PRELOAD”, so this works before or after the standard libraries are opened).require(name)then calls open with the arguments (name, “:preload:”), stores its first result in package.loaded[name] (true when it returns nothing or nil) and returns it, like any Lua module. Example:fn open_greet(cx: &mut lua.Cx) -> i32!lua.Throw { let funcs = [(“hello”, greet_hello)] cx.new_lib(&funcs)? return ok(1) } … cx.preload_module(“greet”, open_greet)? // Lua: require “greet”
pub fn preload_module(&mut self, name: &str, open: NativeFn) -> void!Throw
Cx.traceback
Function · Source
Push a traceback of thread L1 (luaL_traceback), starting at
level, preceded by msg (if any).
pub fn traceback(&mut self, L1: &mut Cx, msg: Option<&[u8]>, level: i32) -> void!Throw
Cx.reference
Function · Source
Store the value on top in table t (popped) and return a fresh integer reference to it (REFNIL for nil).
pub fn reference(&mut self, t0: i32) -> i32!Throw
Cx.unreference
Function · Source
Release reference r of table t.
pub fn unreference(&mut self, t0: i32, r: i32) -> void!Throw
Cx.load_file
Function · Source
Load a file (or standard input when filename is none) as a chunk: skips a first line starting with ‘#’, accepts binary chunks. Pushes the function or an error message; returns the status (ERRFILE when the file cannot be read).
pub fn load_file(&mut self, filename: Option<&[u8]>, mode: &[u8]) -> i32
Cx.do_string
Function · Source
Load and run a string chunk; returns the status.
pub fn do_string(&mut self, s: &[u8]) -> i32
Cx.gsub
Function · Source
Push a copy of s with every occurrence of pattern p (plain text) replaced by r.
pub fn gsub(&mut self, s: &[u8], p: &[u8], r: &[u8]) -> void!Throw
Cx.exec_result
Function · Source
Results of a process operation (luaL_execresult):
exitedtells whether the process terminated normally (with exit statuscode) or by a signal (numbercode). Pushes true|fail, “exit”|“signal”, code.
pub fn exec_result(&mut self, exited: bool, code: i64) -> i32!Throw
Cx.file_result
Function · Source
Results of a file operation (luaL_fileresult): true, or fail, “fname: message”, errno.
pub fn file_result(&mut self, success: bool, fname: Option<&[u8]>) -> i32!Throw
c_stdin
Function · Source
C stream (FILE*) for standard input, shared by all states of the process.
pub fn c_stdin() -> *mut u8
c_stdout
Function · Source
C stream for standard output (used by print and io.stdout).
pub fn c_stdout() -> *mut u8
c_stderr
Function · Source
C stream for standard error (warnings, interpreter messages).
pub fn c_stderr() -> *mut u8
write_stdout
Function · Source
Write bytes to standard output (buffered).
pub fn write_stdout(b: &[u8])
flush_stdout
Function · Source
Flush the shared standard output stream.
pub fn flush_stdout()
write_stderr
Function · Source
Write bytes to standard error (flushed immediately).
pub fn write_stderr(b: &[u8])
last_os_error_message
Function · Source
Message of the last C library error (errno).
pub fn last_os_error_message() -> &[u8] from(static)
Buffer
Struct · Source
Growable byte buffer for building strings (the analogue of luaL_Buffer). Its memory is accounted to the state; it does not use stack slots.
pub struct Buffer {
// Private implementation fields omitted.
}
Buffer.new
Function · Source
An empty buffer accounted to the state of cx.
pub fn new(cx: &Cx) -> Buffer
Buffer.add_bytes
Function · Source
Append bytes.
pub fn add_bytes(&mut self, s: &[u8]) -> void!Throw
Buffer.add_str
Function · Source
Append UTF-8 text.
pub fn add_str(&mut self, s: &str) -> void!Throw
Buffer.add_char
Function · Source
Append one byte.
pub fn add_char(&mut self, c: u8) -> void!Throw
Buffer.add_raw
Function · Source
Append n bytes from a pointer.
pub fn add_raw(&mut self, p: *const u8, n: usize) -> void!Throw
Buffer.add_integer
Function · Source
Append an integer in decimal.
pub fn add_integer(&mut self, v: i64) -> void!Throw
Buffer.add_number
Function · Source
Append a float as
tostringformats it.
pub fn add_number(&mut self, v: f64) -> void!Throw
Buffer.add_value
Function · Source
Append the string form of the value on top of the stack (with __tostring/__name, like tostring) and pop it.
pub fn add_value(&mut self, cx: &mut Cx) -> void!Throw
Buffer.prepare
Function · Source
Make room for n bytes and return a pointer to them; commit with add_size(n) after writing.
pub fn prepare(&mut self, n: usize) -> (*mut u8)!Throw
Buffer.add_size
Function · Source
Commit n bytes written after
prepare.
pub fn add_size(&mut self, n: usize)
Buffer.shrink
Function · Source
Remove the last n bytes.
pub fn shrink(&mut self, n: usize)
Buffer.bytes
Function · Source
Current contents.
pub fn bytes(&self) -> &[u8]
Buffer.size
Function · Source
Number of bytes in the buffer.
pub fn size(&self) -> usize
Buffer.push_result
Function · Source
Push the contents as a string.
pub fn push_result(&mut self, cx: &mut Cx) -> void!Throw
LibFn
Type alias · Source
Library entry: name and function.
pub type LibFn = (&str, NativeFn)
Debug
Struct · Source
Activation record filled by Cx.get_stack / Cx.get_info and passed to hooks. Text fields are exposed through methods (they view strings owned by the Lua state, valid while the described function is alive).
pub struct Debug {
// Hook event (HOOK_* constants) when passed to a hook.
pub event: i32
// Current line of the function (-1 when unknown or native).
pub currentline: i32
pub linedefined: i32
pub lastlinedefined: i32
// Number of upvalues and fixed parameters.
pub nups: u8
pub nparams: u8
pub isvararg: bool
pub istailcall: bool
// Transfer information for call/return hooks ('r').
pub ftransfer: i32
pub ntransfer: i32
// Private implementation fields omitted.
}
Debug.new
Function · Source
An empty record.
pub fn new() -> Debug
Debug.name
Function · Source
Function name (‘n’), if known.
pub fn name(&self) -> Option<&[u8]>
Debug.namewhat
Function · Source
How the name was found (‘n’): “global”, “local”, “method”, “field”, “upvalue”, “metamethod”, “for iterator”, “hook” or “”.
pub fn namewhat(&self) -> &[u8]
Debug.what
Function · Source
“Lua”, “C” or “main” (‘S’).
pub fn what(&self) -> &[u8]
Debug.source
Function · Source
Chunk source (‘S’), e.g. “@file.lua” or “=[C]”.
pub fn source(&self) -> &[u8]
Debug.short_src
Function · Source
Printable source name (‘S’), as used in messages.
pub fn short_src(&self) -> &[u8]
open_base
Function · Source
Open the basic library into the globals table (pushes it).
pub fn open_base(cx: &mut Cx) -> i32!Throw
open_coroutine
Function · Source
Open the coroutine library (pushes it).
pub fn open_coroutine(cx: &mut Cx) -> i32!Throw
open_debug
Function · Source
pub fn open_debug(cx: &mut Cx) -> i32!Throw
open_io
Function · Source
Open the io library (pushes the io table).
pub fn open_io(cx: &mut Cx) -> i32!Throw
open_math
Function · Source
pub fn open_math(cx: &mut Cx) -> i32!Throw
open_os
Function · Source
Open the os library (pushes the os table).
pub fn open_os(cx: &mut Cx) -> i32!Throw
open_package
Function · Source
pub fn open_package(cx: &mut Cx) -> i32!Throw
open_string
Function · Source
pub fn open_string(cx: &mut Cx) -> i32!Throw
open_table
Function · Source
pub fn open_table(cx: &mut Cx) -> i32!Throw
open_utf8
Function · Source
pub fn open_utf8(cx: &mut Cx) -> i32!Throw
set_string_arith_metamethods
Function · Source
Register the string arithmetic metamethods (__add … __unm) into the table on top of the stack (the string metatable).
pub fn set_string_arith_metamethods(cx: &mut Cx) -> void!Throw
Throw
Enum · Source
Outcome of a raised Lua error or a coroutine yield, propagated through every internal function that can raise (
T!Throw). The error object itself is stored by the raiser as described in DESIGN.md (“Errors”).
pub enum Throw {
// LUA_ERRRUN: runtime error (error(), failed operation).
Runtime,
// LUA_ERRSYNTAX: compilation error.
Syntax,
// LUA_ERRMEM: allocation failure.
Memory,
// LUA_ERRERR: error while running a message handler.
Handler,
// A coroutine yield unwinding the native stack.
Yield,
}
ContinuationFn
Type alias · Source
Continuation of a native function that called or yielded with a continuation (see Cx.call_k / Cx.pcall_k / Cx.yield_k).
pub type ContinuationFn = fn(&mut Cx, i32, isize) -> i32!Throw
HookFn
Type alias · Source
Debug hook installed with Cx.set_hook.
pub type HookFn = fn(&mut Cx, &mut Debug) -> void!Throw
WarnFn
Type alias · Source
Warning function installed with Lua.set_warn_fn: receives one piece of a (possibly multi-part) message and whether more pieces follow.
pub type WarnFn = fn(&mut Cx, &[u8], bool)