Struct lua::State

pub struct State { /* fields omitted */ }

An idiomatic, Rust wrapper around lua_State.

Function names adhere to Rust naming conventions. Most of the time, this means breaking up long C function names using underscores; however, there are some cases where different names are used. Typically, these are cases where the name itself is a reserved Rust keyword (such as ref in luaL_ref or where in luaL_where) or where the name is used in both the base Lua library and the auxiliary Lua library (such as lua_getmetatable and luaL_getmetatable). More descriptive names have been chosen for these functions. Finally, any reference to C functions has been replaced by the term native functions. lua_iscfunction is is_native_fn and lua_tocfunction is to_native_fn.

Methods

impl State

fn new() -> State

Initializes a new Lua state. This function does not open any libraries by default. Calls lua_newstate internally.

unsafe fn from_ptr(L: *mut lua_State) -> State

Constructs a wrapper State from a raw pointer. This is suitable for use inside of native functions that accept a lua_State to obtain a wrapper.

fn as_ptr(&self) -> *mut lua_State

Returns an unsafe pointer to the wrapped lua_State.

fn open_libs(&mut self)

Maps to luaL_openlibs.

fn preload_library(&mut self, lib: Library)

Preloads library, i.e. it's not exposed, but can be required

fn load_library(&mut self, lib: Library)

Loads a built-in library and exposes it into lua code

fn open_base(&mut self) -> c_int

Maps to luaopen_base.

fn open_coroutine(&mut self) -> c_int

Maps to luaopen_coroutine.

fn open_table(&mut self) -> c_int

Maps to luaopen_table.

fn open_io(&mut self) -> c_int

Maps to luaopen_io.

fn open_os(&mut self) -> c_int

Maps to luaopen_os.

fn open_string(&mut self) -> c_int

Maps to luaopen_string.

fn open_utf8(&mut self) -> c_int

Maps to luaopen_utf8.

fn open_bit32(&mut self) -> c_int

Maps to luaopen_bit32.

fn open_math(&mut self) -> c_int

Maps to luaopen_math.

fn open_debug(&mut self) -> c_int

Maps to luaopen_debug.

fn open_package(&mut self) -> c_int

Maps to luaopen_package.

fn do_file(&mut self, filename: &str) -> ThreadStatus

Maps to luaL_dofile.

fn do_string(&mut self, s: &str) -> ThreadStatus

Maps to luaL_dostring.

fn push<T: ToLua>(&mut self, value: T)

Pushes the given value onto the stack.

fn to_type<T: FromLua>(&mut self, index: Index) -> Option<T>

Converts the value on top of the stack to a value of type T and returns it.

fn close(self)

Maps to lua_close.

fn new_thread(&mut self) -> State

Maps to lua_newthread.

fn at_panic(&mut self, panicf: Function) -> Function

Maps to lua_atpanic.

fn version(state: Option<&mut State>) -> Number

Maps to lua_version.

fn abs_index(&mut self, idx: Index) -> Index

Maps to lua_absindex.

fn get_top(&mut self) -> Index

Maps to lua_gettop.

fn set_top(&mut self, index: Index)

Maps to lua_settop.

fn push_value(&mut self, index: Index)

Maps to lua_pushvalue.

fn rotate(&mut self, idx: Index, n: c_int)

Maps to lua_rotate.

fn copy(&mut self, from_idx: Index, to_idx: Index)

Maps to lua_copy.

fn check_stack(&mut self, extra: c_int) -> bool

Maps to lua_checkstack.

fn xmove(&mut self, to: &mut State, n: c_int)

Maps to lua_xmove.

fn is_number(&mut self, index: Index) -> bool

Maps to lua_isnumber.

fn is_string(&mut self, index: Index) -> bool

Maps to lua_isstring.

fn is_native_fn(&mut self, index: Index) -> bool

Maps to lua_iscfunction.

fn is_integer(&mut self, index: Index) -> bool

Maps to lua_isinteger.

fn is_userdata(&mut self, index: Index) -> bool

Maps to lua_isuserdata.

fn type_of(&mut self, index: Index) -> Option<Type>

Maps to lua_type.

fn typename_of(&mut self, tp: Type) -> &'static str

Maps to lua_typename.

fn to_numberx(&mut self, index: Index) -> Option<Number>

Maps to lua_tonumberx.

fn to_integerx(&mut self, index: Index) -> Option<Integer>

Maps to lua_tointegerx.

fn to_bool(&mut self, index: Index) -> bool

Maps to lua_toboolean.

fn raw_len(&mut self, index: Index) -> size_t

Maps to lua_rawlen.

fn to_native_fn(&mut self, index: Index) -> Function

Maps to lua_tocfunction.

fn to_userdata(&mut self, index: Index) -> *mut c_void

Maps to lua_touserdata.

unsafe fn to_userdata_typed<'a, T>(
    &'a mut self,
    index: Index
) -> Option<&'a mut T>

Convenience function that calls to_userdata and performs a cast.

fn to_thread(&mut self, index: Index) -> Option<State>

Maps to lua_tothread.

fn to_pointer(&mut self, index: Index) -> *const c_void

Maps to lua_topointer.

fn arith(&mut self, op: Arithmetic)

Maps to lua_arith.

fn raw_equal(&mut self, idx1: Index, idx2: Index) -> bool

Maps to lua_rawequal.

fn compare(&mut self, idx1: Index, idx2: Index, op: Comparison) -> bool

Maps to lua_compare.

fn push_nil(&mut self)

Maps to lua_pushnil.

fn push_number(&mut self, n: Number)

Maps to lua_pushnumber.

fn push_integer(&mut self, i: Integer)

Maps to lua_pushinteger.

fn push_string(&mut self, s: &str)

Maps to lua_pushlstring.

fn push_closure(&mut self, f: Function, n: c_int)

Maps to lua_pushcclosure.

fn push_bool(&mut self, b: bool)

Maps to lua_pushboolean.

unsafe fn push_light_userdata<T>(&mut self, ud: *mut T)

Maps to lua_pushlightuserdata. The Lua state will receive a pointer to the given value. The caller is responsible for cleaning up the data. Any code that manipulates the userdata is free to modify its contents, so memory safety is not guaranteed.

fn push_thread(&mut self) -> bool

Maps to lua_pushthread.

fn get_global(&mut self, name: &str) -> Type

Maps to lua_getglobal.

fn get_table(&mut self, index: Index) -> Type

Maps to lua_gettable.

fn get_field(&mut self, index: Index, k: &str) -> Type

Maps to lua_getfield.

fn geti(&mut self, index: Index, i: Integer) -> Type

Maps to lua_geti.

fn raw_get(&mut self, index: Index) -> Type

Maps to lua_rawget.

fn raw_geti(&mut self, index: Index, n: Integer) -> Type

Maps to lua_rawgeti.

fn raw_getp<T>(&mut self, index: Index, p: *const T) -> Type

Maps to lua_rawgetp.

fn create_table(&mut self, narr: c_int, nrec: c_int)

Maps to lua_createtable.

fn new_userdata(&mut self, sz: size_t) -> *mut c_void

Maps to lua_newuserdata. The pointer returned is owned by the Lua state and it will be garbage collected when it is no longer in use or the state is closed. To specify custom cleanup behavior, use a __gc metamethod.

fn new_userdata_typed<T>(&mut self) -> *mut T

Convenience function that uses type information to call new_userdata and perform a cast.

Example

unsafe { *state.new_userdata_typed() = MyStruct::new(...); }
state.set_metatable_from_registry("MyStruct");

fn get_metatable(&mut self, objindex: Index) -> bool

Maps to lua_getmetatable.

fn get_uservalue(&mut self, idx: Index) -> Type

Maps to lua_getuservalue.

fn set_global(&mut self, var: &str)

Maps to lua_setglobal.

fn set_table(&mut self, idx: Index)

Maps to lua_settable.

fn set_field(&mut self, idx: Index, k: &str)

Maps to lua_setfield.

fn seti(&mut self, idx: Index, n: Integer)

Maps to lua_seti.

fn raw_set(&mut self, idx: Index)

Maps to lua_rawset.

fn raw_seti(&mut self, idx: Index, n: Integer)

Maps to lua_rawseti.

fn raw_setp<T>(&mut self, idx: Index, p: *const T)

Maps to lua_rawsetp.

fn set_metatable(&mut self, objindex: Index)

Maps to lua_setmetatable.

fn set_uservalue(&mut self, idx: Index)

Maps to lua_setuservalue.

fn callk<F>(&mut self, nargs: c_int, nresults: c_int, continuation: F) where
    F: FnOnce(&mut State, ThreadStatus) -> c_int, 

Maps to lua_callk.

fn call(&mut self, nargs: c_int, nresults: c_int)

Maps to lua_call.

fn pcallk<F>(
    &mut self,
    nargs: c_int,
    nresults: c_int,
    msgh: c_int,
    continuation: F
) -> c_int where
    F: FnOnce(&mut State, ThreadStatus) -> c_int, 

Maps to lua_pcallk.

fn pcall(&mut self, nargs: c_int, nresults: c_int, msgh: c_int) -> ThreadStatus

Maps to lua_pcall.

fn load<F>(&mut self, reader: F, source: &str, mode: &str) -> ThreadStatus where
    F: FnMut(&mut State) -> &[u8], 

Maps to lua_load.

fn dump<F>(&mut self, writer: F, strip: bool) -> c_int where
    F: FnMut(&mut State, &[u8]) -> c_int, 

Maps to lua_dump.

fn co_yieldk<F>(&mut self, nresults: c_int, continuation: F) -> ! where
    F: FnOnce(&mut State, ThreadStatus) -> c_int, 

Maps to lua_yieldk.

fn co_yield(&mut self, nresults: c_int) -> !

Maps to lua_yield. This function is not called yield because it is a reserved keyword.

fn resume(&mut self, from: Option<&mut State>, nargs: c_int) -> ThreadStatus

Maps to lua_resume.

fn status(&mut self) -> ThreadStatus

Maps to lua_status.

fn is_yieldable(&mut self) -> bool

Maps to lua_isyieldable.

fn gc(&mut self, what: GcOption, data: c_int) -> c_int

Maps to lua_gc.

fn error(&mut self) -> !

Maps to lua_error.

fn next(&mut self, idx: Index) -> bool

Maps to lua_next.

fn concat(&mut self, n: c_int)

Maps to lua_concat.

fn len(&mut self, idx: Index)

Maps to lua_len.

fn string_to_number(&mut self, s: &str) -> size_t

Maps to lua_stringtonumber.

fn get_alloc_fn(&mut self) -> (Allocator, *mut c_void)

Maps to lua_getallocf.

fn set_alloc_fn(&mut self, f: Allocator, ud: *mut c_void)

Maps to lua_setallocf.

fn set_extra(&mut self, extra: Option<Extra>) -> Option<Extra>

Set extra data. Return previous value if it was set.

fn with_extra<F, R>(&mut self, closure: F) -> R where
    F: FnOnce(&mut Option<Extra>) -> R, 

Do some actions with mutable extra.

fn with_extra_typed<T, F, R>(&mut self, closure: F) -> R where
    T: Any,
    F: FnOnce(&mut T) -> R, 

Unwrap and downcast extra to typed.

Panics

Panics if state has no attached Extra or it's impossible to downcast to T.

fn to_number(&mut self, index: Index) -> Number

Maps to lua_tonumber.

fn to_integer(&mut self, index: Index) -> Integer

Maps to lua_tointeger.

fn pop(&mut self, n: c_int)

Maps to lua_pop.

fn new_table(&mut self)

Maps to lua_newtable.

fn register(&mut self, n: &str, f: Function)

Maps to lua_register.

fn push_fn(&mut self, f: Function)

Maps to lua_pushcfunction.

fn is_fn(&mut self, index: Index) -> bool

Maps to lua_isfunction.

fn is_table(&mut self, index: Index) -> bool

Maps to lua_istable.

fn is_light_userdata(&mut self, index: Index) -> bool

Maps to lua_islightuserdata.

fn is_nil(&mut self, index: Index) -> bool

Maps to lua_isnil.

fn is_bool(&mut self, index: Index) -> bool

Maps to lua_isboolean.

fn is_thread(&mut self, index: Index) -> bool

Maps to lua_isthread.

fn is_none(&mut self, index: Index) -> bool

Maps to lua_isnone.

fn is_none_or_nil(&mut self, index: Index) -> bool

Maps to lua_isnoneornil.

fn push_global_table(&mut self)

Maps to lua_pushglobaltable.

fn insert(&mut self, idx: Index)

Maps to lua_insert.

fn remove(&mut self, idx: Index)

Maps to lua_remove.

fn replace(&mut self, idx: Index)

Maps to lua_replace.

fn get_stack(&mut self, level: c_int) -> Option<lua_Debug>

Maps to lua_getstack.

fn get_info(&mut self, what: &str) -> Option<lua_Debug>

Maps to lua_getinfo.

fn get_local(&mut self, ar: &lua_Debug, n: c_int) -> Option<&str>

Maps to lua_getlocal.

fn set_local(&mut self, ar: &lua_Debug, n: c_int) -> Option<&str>

Maps to lua_setlocal.

fn get_upvalue(&mut self, funcindex: Index, n: c_int) -> Option<&str>

Maps to lua_getupvalue.

fn set_upvalue(&mut self, funcindex: Index, n: c_int) -> Option<&str>

Maps to lua_setupvalue.

fn upvalue_id(&mut self, funcindex: Index, n: c_int) -> *mut c_void

Maps to lua_upvalueid.

fn upvalue_join(&mut self, fidx1: Index, n1: c_int, fidx2: Index, n2: c_int)

Maps to lua_upvaluejoin.

fn set_hook(&mut self, func: Hook, mask: HookMask, count: c_int)

Maps to lua_sethook.

fn get_hook(&mut self) -> Hook

Maps to lua_gethook.

fn get_hook_mask(&mut self) -> HookMask

Maps to lua_gethookmask.

fn get_hook_count(&mut self) -> c_int

Maps to lua_gethookcount.

fn check_version(&mut self)

Maps to luaL_checkversion.

fn get_metafield(&mut self, obj: Index, e: &str) -> bool

Maps to luaL_getmetafield.

fn call_meta(&mut self, obj: Index, e: &str) -> bool

Maps to luaL_callmeta.

fn to_str(&mut self, index: Index) -> Option<&str>

Maps to luaL_tolstring. This function is not called to_string because that method name is used for the ToString trait. This function returns a reference to the string at the given index, on which to_owned may be called.

fn to_str_in_place(&mut self, index: Index) -> Option<&str>

Maps to lua_tolstring. This function is not called to_string because that method name is used for the ToString trait. This function returns a reference to the string at the given index, on which to_owned may be called.

fn arg_error(&mut self, arg: Index, extramsg: &str) -> !

Maps to luaL_argerror.

fn check_number(&mut self, arg: Index) -> Number

Maps to luaL_checknumber.

fn opt_number(&mut self, arg: Index, def: Number) -> Number

Maps to luaL_optnumber.

fn check_integer(&mut self, arg: Index) -> Integer

Maps to luaL_checkinteger.

fn opt_integer(&mut self, arg: Index, def: Integer) -> Integer

Maps to luaL_optinteger.

fn check_stack_msg(&mut self, sz: c_int, msg: &str)

Maps to luaL_checkstack.

fn check_type(&mut self, arg: Index, t: Type)

Maps to luaL_checktype.

fn check_any(&mut self, arg: Index)

Maps to luaL_checkany.

fn new_metatable(&mut self, tname: &str) -> bool

Maps to luaL_newmetatable.

fn set_metatable_from_registry(&mut self, tname: &str)

Maps to luaL_setmetatable.

fn test_userdata(&mut self, arg: Index, tname: &str) -> *mut c_void

Maps to luaL_testudata.

unsafe fn test_userdata_typed<'a, T>(
    &'a mut self,
    arg: Index,
    tname: &str
) -> Option<&'a mut T>

Convenience function that calls test_userdata and performs a cast.

fn check_userdata(&mut self, arg: Index, tname: &str) -> *mut c_void

Maps to luaL_checkudata.

unsafe fn check_userdata_typed<'a, T>(
    &'a mut self,
    arg: Index,
    tname: &str
) -> &'a mut T

Convenience function that calls check_userdata and performs a cast.

fn location(&mut self, lvl: c_int)

Maps to luaL_where. where is a reserved keyword.

fn check_option(&mut self, arg: Index, def: Option<&str>, lst: &[&str]) -> usize

Maps to luaL_checkoption.

fn file_result(&mut self, stat: c_int, fname: &str) -> c_int

Maps to luaL_fileresult.

fn exec_result(&mut self, stat: c_int) -> c_int

Maps to luaL_execresult.

fn reference(&mut self, t: Index) -> Reference

Maps to luaL_ref.

fn unreference(&mut self, t: Index, reference: Reference)

Maps to luaL_unref.

fn load_filex(&mut self, filename: &str, mode: &str) -> ThreadStatus

Maps to luaL_loadfilex.

fn load_file(&mut self, filename: &str) -> ThreadStatus

Maps to luaL_loadfile.

fn load_bufferx(&mut self, buff: &[u8], name: &str, mode: &str) -> ThreadStatus

Maps to luaL_loadbufferx.

fn load_string(&mut self, source: &str) -> ThreadStatus

Maps to luaL_loadstring.

fn len_direct(&mut self, index: Index) -> Integer

Maps to luaL_len.

fn gsub(&mut self, s: &str, p: &str, r: &str) -> &str

Maps to luaL_gsub.

fn set_fns(&mut self, l: &[(&str, Function)], nup: c_int)

Maps to luaL_setfuncs.

fn get_subtable(&mut self, idx: Index, fname: &str) -> bool

Maps to luaL_getsubtable.

fn traceback(&mut self, state: &mut State, msg: &str, level: c_int)

Maps to luaL_traceback.

fn requiref(&mut self, modname: &str, openf: Function, glb: bool)

Maps to luaL_requiref.

fn new_lib_table(&mut self, l: &[(&str, Function)])

Maps to luaL_newlibtable.

fn new_lib(&mut self, l: &[(&str, Function)])

Maps to luaL_newlib.

fn arg_check(&mut self, cond: bool, arg: Index, extramsg: &str)

Maps to luaL_argcheck.

fn check_string(&mut self, n: Index) -> &str

Maps to luaL_checklstring.

fn opt_string<'a>(&'a mut self, n: Index, default: &'a str) -> &'a str

Maps to luaL_optlstring.

fn typename_at(&mut self, n: Index) -> &'static str

Maps to luaL_typename.

fn get_metatable_from_registry(&mut self, tname: &str)

Maps to luaL_getmetatable.

fn load_buffer(&mut self, buff: &[u8], name: &str) -> ThreadStatus

Maps to luaL_loadbuffer.

Trait Implementations

impl Send for State

impl Drop for State

fn drop(&mut self)

A method called when the value goes out of scope.