API referencestd/script

std/script/lua

Public declarations, types, methods, and source contracts for std/script/lua.

On this page

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.

Alias Package Source file
mem core/mem api.dodo, auxlib.dodo, call.dodo, code.dodo, debuginfo.dodo, dump.dodo, errors.dodo, func.dodo, gc.dodo, lex.dodo, lib_base.dodo, lib_io.dodo, lib_os.dodo, lib_package.dodo, lib_string.dodo, lib_string_format.dodo, lib_string_pack.dodo, lib_utf8.dodo, mem.dodo, meta.dodo, object.dodo, parse.dodo, state.dodo, string.dodo, table.dodo, undump.dodo, vm.dodo
platform_native std/platform/native lib_package.dodo
ptr core/ptr api.dodo, auxlib.dodo, call.dodo, code.dodo, debuginfo.dodo, dump.dodo, errors.dodo, func.dodo, gc.dodo, lex.dodo, lib_base.dodo, lib_coroutine.dodo, lib_debug.dodo, lib_io.dodo, lib_math.dodo, lib_os.dodo, lib_package.dodo, lib_string.dodo, lib_string_format.dodo, lib_string_pack.dodo, lib_table.dodo, lib_utf8.dodo, mem.dodo, meta.dodo, number.dodo, object.dodo, parse.dodo, pattern.dodo, state.dodo, string.dodo, table.dodo, undump.dodo, vm.dodo
script_host std/script/native auxlib.dodo, lib_io.dodo, lib_os.dodo

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"

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 count instructions.

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 from into to.

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 name to 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 size bytes and nuv user 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 nargs arguments.

pub fn call(&mut self, nargs: i32, nresults: i32) -> void!Throw

Cx.call_k

Function · Source

Call with a continuation: if the callee yields, k is 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; msgh is 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 co with its top nargs values; 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 level levels 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 ar with the fields selected by what (‘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 ar and 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. mode is “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 of def when 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 event of 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 event of 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 tostring does: __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 nup upvalues 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 modname when 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: stores open as 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): exited tells whether the process terminated normally (with exit status code) or by a signal (number code). 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 tostring formats 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)

Search every guide, reference page, and API declaration.