Crate tlua

Help

Expand description

High-level zero-cost bindings for Lua (fork of hlua)

Lua is an interpreted programming language. This crate allows you to execute Lua code.

§General usage

In order to execute Lua code you first need a Lua context, which is represented in this library with the Lua struct. You can then call the the eval or exec method on this object.

For example:

use tlua::Lua;

let mut lua = Lua::new();
lua.exec("a = 12 * 5").unwrap();
let a: u32 = lua.eval("return a + 1").unwrap();

This example puts the value 60 in the global variable a. The values of all global variables are stored within the Lua struct. If you execute multiple Lua scripts on the same context, each script will have access to the same global variables that were modified by the previous scripts.

In order to do something actually useful with Lua, we will need to make Lua and Rust communicate with each other. This can be done in four ways:

You can use methods on the Lua struct to read or write the values of global variables with the get and set methods. For example you can write to a global variable with a Lua script then read it from Rust, or you can write to a global variable from Rust then read it from a Lua script.
The Lua script that you evaluate with the eval method can return a value.
You can set the value of a global variable to a Rust functions or closures, which can then be invoked with a Lua script. See the Function struct for more information. For example if you set the value of the global variable foo to a Rust function, you can then call it from Lua with foo().
Similarly you can set the value of a global variable to a Lua function, then call it from Rust. The function call can return a value.

Which method(s) you use depends on which API you wish to expose to your Lua scripts.

§Pushing and loading values

The interface between Rust and Lua involves two things:

Sending values from Rust to Lua, which is known as pushing the value.
Sending values from Lua to Rust, which is known as loading the value.

Pushing (ie. sending from Rust to Lua) can be done with the set method:

let lua = tlua::Lua::new();
lua.set("a", 50);

You can push values that implement the Push trait or the PushOne trait depending on the situation:

Integers, floating point numbers and booleans.
String and &str.
Any Rust function or closure whose parameters and loadable and whose return type is pushable. See the documentation of the Function struct for more information.
The AnyLuaValue struct. This enumeration represents any possible value in Lua.
The LuaCode and LuaCodeFromReader structs. Since pushing these structs can result in an error, you need to use checked_set instead of set.
Vecs and HashMaps whose content is pushable.
As a special case, Result can be pushed only as the return type of a Rust function or closure. If they contain an error, the Rust function call is considered to have failed.
As a special case, tuples can be pushed when they are the return type of a Rust function or closure. They implement Push but not PushOne.
TODO: userdata

Loading (ie. sending from Lua to Rust) can be done with the get method:

let a: i32 = lua.get("a").unwrap();

You can load values that implement the LuaRead trait:

Integers, floating point numbers and booleans.
String and StringInLua (ie. the equivalent of &str). Loading the latter has no cost while loading a String performs an allocation.
Any function (Lua or Rust), with the LuaFunction struct. This can then be used to execute the function.
The AnyLuaValue struct. This enumeration represents any possible value in Lua.
The LuaTable struct. This struct represents a table in Lua, where keys and values can be of different types. The table can then be iterated and individual elements can be loaded or modified.
As a special case, tuples can be loaded when they are the return type of a Lua function or as the return type of eval.
TODO: userdata

Modules§

debug
ffi: Module provides FFI bindings for the following constants, types and functions, realted to Lua C API:
util

Macros§

as_table: A helper macro for creating AsTable wrappers. Use this to pass ad-hoc lua tables into lua.
c_ptr
c_str
error: Throws the lua error with the given message. The first argument is the lua context in which the error should be thrown. When throwing an error from a rust callback use the lua state which was passed to the callback.
function
impl_object
implement_lua_push
implement_lua_read
nzi32
unwrap_ok_or
unwrap_or

Structs§

AbsoluteIndex
AnyLuaString
AsTable: A wrapper type for pushing and reading rust tuples as lua tables.
CData: CData A wrapper type for reading/writing rust values as luajit cdata.
CDataOnStack: A cdata value stored on lua stack. Can be used to check type of cdata, access the raw bytes of the data, downcast it to a rust type or passed as an argument into a lua function.
CFunction: A wrapper around ffi::lua_CFunction to push C functions into lua as values.
Callable: An opaque value on lua stack that can be called. Can represent a lua function, a lua table with a __call metamethod or other callable lua value.
False
Function: Opaque type containing a Rust function or closure.
Indexable: An opaque value on lua stack that can be indexed. Can represent a lua table, a lua table with a __index metamethod or other indexable lua value.
IndexableRW: An opaque value on lua stack that can be indexed immutably as well as mutably. Can represent a lua table, a lua table with a __index and __newindex metamethods or other indexable lua value.
InsideCallback: Opaque type that represents the Lua context when inside a callback.
Lua: Main object of the library.
LuaCode: Wrapper around a &str. When pushed, the content will be parsed as Lua code and turned into a function.
LuaCodeFromReader: Wrapper around a Read object. When pushed, the content will be parsed as Lua code and turned into a function.
LuaFunction: Handle to a function in the Lua context.
LuaTable: Represents a table stored in the Lua context.
LuaTableIterator: Iterator that enumerates the content of a Lua table.
Nil
Null
Object: A single value stored on the lua stack. Type parameter L represents a value guarding the state of the lua stack (see PushGuard).
PushGuard: RAII guard for a value pushed on the stack.
Strict: A wrapper type for reading lua numbers of concrete precisions without implicit coercions.
StringInLua: String on the Lua stack.
TableFromIter: A wrapper struct for converting arbitrary iterators into lua tables. Use this instead of converting the iterator into a Vec to avoid unnecessary allocations
Throw: A wrapper type for throwing lua errors from a rust callback’s result.
ToString: String wrapper struct that can be used to read a lua value by converting it to string possibly using __tostring metamethod.
True
Typename
UserdataOnStack: Represents a user data located inside the Lua context.
WrongType

Enums§

AnyHashableLuaValue: Represents any value that can be stored by Lua
AnyLuaValue: Represents any value that can be stored by Lua
CallError: Error that can happen when calling a type implementing Call.
LuaError: Error that can happen when executing Lua code.
MethodCallError
PushIterError
TuplePushError: Error that can happen when pushing multiple values at once.
Void: Type that cannot be instantiated.

Constants§

NEGATIVE_ONE
NEGATIVE_TWO

Traits§

AsCData: AsCData Types implementing this trait can be represented as luajit’s cdata.
AsLua: Trait for objects that have access to a Lua context.
Call
Index: Types implementing this trait represent a single lua value that can be indexed, i.e. a regular lua table or other value implementing __index metamethod.
LuaRead: Types that can be obtained from a Lua context.
NewIndex: Types implementing this trait represent a single lua value that can be changed by indexed, i.e. a regular lua table or other value implementing __newindex metamethod.
Push: Types implementing this trait can be pushed onto the Lua stack by reference.
PushInto: Types implementing this trait can be pushed onto the Lua stack by value.
PushOne: Extension trait for Push. Guarantees that only one element will be pushed.
PushOneInto: Extension trait for PushInto. Guarantees that only one element will be pushed.

Functions§

function0: Wraps a type that implements FnMut so that it can be used by tlua.
function1: Wraps a type that implements FnMut so that it can be used by tlua.
function2: Wraps a type that implements FnMut so that it can be used by tlua.
function3: Wraps a type that implements FnMut so that it can be used by tlua.
function4: Wraps a type that implements FnMut so that it can be used by tlua.
function5: Wraps a type that implements FnMut so that it can be used by tlua.
function6: Wraps a type that implements FnMut so that it can be used by tlua.
function7: Wraps a type that implements FnMut so that it can be used by tlua.
function8: Wraps a type that implements FnMut so that it can be used by tlua.
function9: Wraps a type that implements FnMut so that it can be used by tlua.
function10: Wraps a type that implements FnMut so that it can be used by tlua.
protected_call: See AsLua::pcall.
push_some_userdata^⚠: Pushes value of type T onto the stack as a userdata. The value is put inside a Option so that it can be safely moved out of there. Useful for example when passing FnOnce as a c closure, because it must be dropped after the call. [0, +1, -]
push_userdata: Pushes an object as a user data.
read_userdata
typename
typenames

Type Aliases§

LuaFunctionCallErrorDeprecated
LuaSequence
LuaState
LuaTableMap
LuaThread: A lua context corresponding to a lua thread (see ffi::lua_newthread) stored in the global REGISTRY and will be removed from there when dropped.
PushIntoResult: Type returned from PushInto::push_into_lua function.
PushIterErrorOf
PushResult: Type returned from Push::push_to_lua function.
ReadResult
StaticLua: A static lua context that must be created from an existing lua state pointer and that will not be closed when dropped.
TempLua: A temporary lua context that will be closed when dropped.

Attribute Macros§

test: The recommended way to describe tests in tlua crate

Derive Macros§

LuaRead
Push
PushInto

Crate tluaCopy item path