Struct tlua::Lua

pub struct Lua<OnDrop>
where
    OnDrop: OnDrop,
{ /* private fields */ }

Main object of the library.

The type parameter OnDrop specifies what happens with the underlying lua state when the instance gets dropped. There are currently 3 supported cases:

• on_drop::Ignore: nothing happens
• on_drop::Close: ffi::lua_close is called
• on_drop::Unref: ffi::luaL_unref is called with the associated value

About panic safety

This type isn’t panic safe. This means that if a panic happens while you were using the Lua, then it will probably stay in a corrupt state. Trying to use the Lua again will most likely result in another panic but shouldn’t result in unsafety.

Implementations

impl Lua<Close>

pub fn new() -> Self

Builds a new empty TempLua context.

There are no global variables and the registry is totally empty. Even the functions from the standard library can’t be used.

If you want to use the Lua standard library in the scripts of this context, see the openlibs method

Example

use tlua::Lua;
let lua = Lua::new();

Panic

The function panics if the underlying call to lua_newstate fails (which indicates lack of memory).

pub unsafe fn from_existing<T>(lua: *mut T) -> Self

Takes an existing lua_State and build a TemplLua object from it.

lua_close will be called on the lua_State in drop.

Safety

A pointer to a valid lua context must be provided which is ok to be closed.

impl Lua<Ignore>

pub unsafe fn from_static<T>(lua: *mut T) -> Self

Takes an existing lua_State and build a StaticLua object from it.

lua_close is NOT called in drop.

Safety

A pointer to a valid lua context must be provided.

pub fn new_thread(&self) -> LuaThread

Creates a new Lua thread with an independent stack and runs the provided function within it. The new state has access to all the global objects available to self.

impl<OnDrop> Lua<OnDrop>

where OnDrop: OnDrop,

pub fn openlibs(&self)

Opens all standard Lua libraries.

See the reference for the standard library here: https://www.lua.org/manual/5.2/manual.html#6

This is done by calling luaL_openlibs.

Example

use tlua::Lua;
let lua = Lua::new();
lua.openlibs();

pub fn open_base(&self)

Opens base library.

https://www.lua.org/manual/5.2/manual.html#pdf-luaopen_base

pub fn open_bit(&self)

Opens bit32 library.

https://www.lua.org/manual/5.2/manual.html#pdf-luaopen_bit32

pub fn open_debug(&self)

Opens debug library.

https://www.lua.org/manual/5.2/manual.html#pdf-luaopen_debug

pub fn open_io(&self)

Opens io library.

https://www.lua.org/manual/5.2/manual.html#pdf-luaopen_io

pub fn open_math(&self)

Opens math library.

https://www.lua.org/manual/5.2/manual.html#pdf-luaopen_math

pub fn open_os(&self)

Opens os library.

https://www.lua.org/manual/5.2/manual.html#pdf-luaopen_os

pub fn open_package(&self)

Opens package library.

https://www.lua.org/manual/5.2/manual.html#pdf-luaopen_package

pub fn open_string(&self)

Opens string library.

https://www.lua.org/manual/5.2/manual.html#pdf-luaopen_string

pub fn open_table(&self)

Opens table library.

https://www.lua.org/manual/5.2/manual.html#pdf-luaopen_table

pub fn eval<'lua, T>(&'lua self, code: &str) -> Result<T, LuaError>

where T: LuaRead<PushGuard<LuaFunction<PushGuard<&'lua Self>>>>,

Executes some Lua code in the context.

The code will have access to all the global variables you set with methods such as set. Every time you execute some code in the context, the code can modify these global variables.

The template parameter of this function is the return type of the expression that is being evaluated. In order to avoid compilation error, you should call this function either by doing lua.eval::<T>(...) or let result: T = lua.eval(...); where T is the type of the expression. The function will return an error if the actual return type of the expression doesn’t match the template parameter.

The return type must implement the LuaRead trait. See the documentation at the crate root for more information.

Examples

use tlua::Lua;
let lua = Lua::new();

let twelve: i32 = lua.eval("return 3 * 4;").unwrap();
let sixty = lua.eval::<i32>("return 6 * 10;").unwrap();

pub fn eval_with<'lua, A, T>( &'lua self, code: &str, args: A ) -> Result<T, CallError<A::Err>>

where A: PushInto<LuaState>, T: LuaRead<PushGuard<LuaFunction<PushGuard<&'lua Self>>>>,

Executes some Lua code in the context passing the arguments in place of ....

use tlua::Lua;
let lua = Lua::new();
let two: i32 = lua.eval_with("return 1 + ...", 1).unwrap();
assert_eq!(two, 2);

See also Lua::eval

pub fn exec(&self, code: &str) -> Result<(), LuaError>

Executes some Lua code in the context.

The code will have access to all the global variables you set with methods such as set. Every time you execute some code in the context, the code can modify these global variables.

Examples

use tlua::Lua;
let lua = Lua::new();
lua.exec("function multiply_by_two(a) return a * 2 end").unwrap();
lua.exec("twelve = multiply_by_two(6)").unwrap();

pub fn exec_with<A>(&self, code: &str, args: A) -> Result<(), CallError<A::Err>>

where A: PushInto<LuaState>,

Executes some Lua code in the context passing the arguments in place of ....

Examples

use tlua::Lua;
let lua = Lua::new();
lua.exec_with("a, b = ...; c = a * b", (3, 4)).unwrap();
let c: i32 = lua.get("c").unwrap();
assert_eq!(c, 12);

See also Lua::exec

pub fn eval_from<'lua, T>(&'lua self, code: impl Read) -> Result<T, LuaError>

where T: LuaRead<PushGuard<LuaFunction<PushGuard<&'lua Self>>>>,

Executes some Lua code on the context.

This does the same thing as the eval method, but the code to evaluate is loaded from an object that implements Read.

Use this method when you potentially have a large amount of code (for example if you read the code from a file) in order to avoid having to put everything in memory first before passing it to the Lua interpreter.

Example

use std::fs::File;
use tlua::Lua;

let mut lua = Lua::new();
let script = File::open("script.lua").unwrap();
let res: u32 = lua.eval_from(script).unwrap();

pub fn exec_from(&self, code: impl Read) -> Result<(), LuaError>

Executes some Lua code on the context.

This does the same thing as the exec method, but the code to execute is loaded from an object that implements Read.

Use this method when you potentially have a large amount of code (for example if you read the code from a file) in order to avoid having to put everything in memory first before passing it to the Lua interpreter.

Example

use std::fs::File;
use tlua::Lua;

let mut lua = Lua::new();
let script = File::open("script.lua").unwrap();
lua.exec_from(script).unwrap();

pub fn get<'lua, V, I>(&'lua self, index: I) -> Option<V>

where I: Borrow<str>, V: LuaRead<PushGuard<&'lua Self>>,

Reads the value of a global variable.

Returns None if the variable doesn’t exist or has the wrong type.

The type must implement the LuaRead trait. See the documentation at the crate root for more information.

Example

use tlua::Lua;
let lua = Lua::new();
lua.exec("a = 5").unwrap();
let a: i32 = lua.get("a").unwrap();
assert_eq!(a, 5);

pub fn into_get<V, I>(self, index: I) -> Result<V, PushGuard<Self>>

where I: Borrow<str>, V: LuaRead<PushGuard<Self>>,

Reads the value of a global, capturing the context by value.

pub fn set<'lua, I, V>(&'lua self, index: I, value: V)

where I: Borrow<str>, V: PushOneInto<&'lua Self>, <V as PushInto<&'lua Self>>::Err: Into<Void>,

Modifies the value of a global variable.

If you want to write an array, you are encouraged to use the empty_array method instead.

The type must implement the PushOne trait. See the documentation at the crate root for more information.

Example

use tlua::Lua;
let lua = Lua::new();

lua.set("a", 12);
let six: i32 = lua.eval("return a / 2;").unwrap();
assert_eq!(six, 6);

pub fn checked_set<'lua, I, V>( &'lua self, index: I, value: V ) -> Result<(), <V as PushInto<&'lua Self>>::Err>

where I: Borrow<str>, V: PushOneInto<&'lua Self>,

Modifies the value of a global variable.

pub fn empty_array<I>(&self, index: I) -> LuaTable<PushGuard<&Self>>

where I: Borrow<str>,

Sets the value of a global variable to an empty array, then loads it.

This is the function you should use if you want to set the value of a global variable to an array. After calling it, you will obtain a LuaTable object which you can then fill with the elements of the array.

Example

use tlua::Lua;
let lua = Lua::new();
lua.openlibs();     // Necessary for `ipairs`.

{
    let mut array = lua.empty_array("my_values");
    array.set(1, 10);       // Don't forget that Lua arrays are indexed from 1.
    array.set(2, 15);
    array.set(3, 20);
}

let sum: i32 = lua.eval(r#"
    local sum = 0
    for i, val in ipairs(my_values) do
        sum = sum + val
    end
    return sum
"#).unwrap();

assert_eq!(sum, 45);

pub fn globals_table(&self) -> LuaTable<PushGuard<&Self>>

Loads the array containing the global variables.

In lua, the global variables accessible from the lua code are all part of a table which you can load here.

Examples

The function can be used to write global variables, just like set.

use tlua::Lua;
let lua = Lua::new();
lua.globals_table().set("a", 5);
assert_eq!(lua.get::<i32, _>("a"), Some(5));

A more useful feature for this function is that it allows you to set the metatable of the global variables. See TODO for more info.

use tlua::Lua;
use tlua::AnyLuaValue;

let lua = Lua::new();
{
    let metatable = lua.globals_table().get_or_create_metatable();
    metatable.set("__index", tlua::function2(|_: AnyLuaValue, var: String| -> AnyLuaValue {
        println!("The user tried to access the variable {:?}", var);
        AnyLuaValue::LuaNumber(48.0)
    }));
}

let b: i32 = lua.eval("return b * 2;").unwrap();
// -> The user tried to access the variable "b"

assert_eq!(b, 96);

Trait Implementations

impl<D> AsLua for Lua<D>

where D: OnDrop,

fn as_lua(&self) -> *mut lua_State

fn try_push<T>( self, v: T ) -> Result<PushGuard<Self>, (<T as PushInto<Self>>::Err, Self)>

where Self: Sized, T: PushInto<Self>,

Try to push v onto the lua stack.

fn push<T>(self, v: T) -> PushGuard<Self>

where Self: Sized, T: PushInto<Self>, <T as PushInto<Self>>::Err: Into<Void>,

Push v onto the lua stack.

fn try_push_one<T>( self, v: T ) -> Result<PushGuard<Self>, (<T as PushInto<Self>>::Err, Self)>

where Self: Sized, T: PushOneInto<Self>,

Try to push v onto the lua stack.

fn push_one<T>(self, v: T) -> PushGuard<Self>

where Self: Sized, T: PushOneInto<Self>, <T as PushInto<Self>>::Err: Into<Void>,

Push v onto the lua stack.

fn push_iter<I>(self, iterator: I) -> Result<PushGuard<Self>, Self>

where Self: Sized, I: Iterator, <I as Iterator>::Item: PushInto<LuaState>, <<I as Iterator>::Item as PushInto<LuaState>>::Err: Into<Void>,

Push iterator onto the lua stack as a lua table.

fn try_push_iter<I>( self, iterator: I ) -> Result<PushGuard<Self>, (PushIterErrorOf<I>, Self)>

where Self: Sized, I: Iterator, <I as Iterator>::Item: PushInto<LuaState>,

Push iterator onto the lua stack as a lua table.

fn read<T>(self) -> ReadResult<T, Self>

where Self: Sized, T: LuaRead<Self>,

fn read_at<T>(self, index: i32) -> ReadResult<T, Self>

where Self: Sized, T: LuaRead<Self>,

fn read_at_nz<T>(self, index: NonZeroI32) -> ReadResult<T, Self>

where Self: Sized, T: LuaRead<Self>,

fn pcall<F, R>(&self, f: F) -> Result<R, LuaError>

where F: FnOnce(StaticLua) -> R,

Call a rust function in protected mode. If a lua error is thrown during execution of f the function will return a LuaError.

impl<OnDrop> Debug for Lua<OnDrop>

where OnDrop: OnDrop + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Drop for Lua<T>

where T: OnDrop,

fn drop(&mut self)

Executes the destructor for this type.