Crate hlua

High-level zero-cost bindings for Lua

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 execute method on this object.

For example:

use hlua::Lua;

let mut lua = Lua::new();
lua.execute::<()>("a = 12 * 5").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 execute with the execute 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:

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 execute.
• TODO: userdata

Macros

implement_lua_push
implement_lua_read

Structs

AnyLuaString
Function	Opaque type containing a Rust function or closure.
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.
LuaContext	Opaque type that contains the raw Lua context.
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.
PushGuard	RAII guard for a value pushed on the stack.
StringInLua	String on the Lua stack.
UserdataOnStack	Represents a user data located inside the Lua context.

Enums

AnyHashableLuaValue	Represents any value that can be stored by Lua
AnyLuaValue	Represents any value that can be stored by Lua
LuaError	Error that can happen when executing Lua code.
LuaFunctionCallError	Error that can happen when calling a LuaFunction.
TuplePushError	Error that can happen when pushing multiple values at once.
Void	Type that cannot be instantiated.

Traits

AsLua	Trait for objects that have access to a Lua context. When using a context returned by a AsLua, you are not allowed to modify the stack.
AsMutLua	Trait for objects that have access to a Lua context. You are allowed to modify the stack, but it must be in the same state as it was when you started.
LuaRead	Types that can be obtained from a Lua context.
Push	Types that can be given to a Lua context, for example with lua.set() or as a return value of a function.
PushOne	Extension trait for Push. Guarantees that only one element will be pushed.

Functions

function0	Wraps a type that implements FnMut so that it can be used by hlua.
function1	Wraps a type that implements FnMut so that it can be used by hlua.
function2	Wraps a type that implements FnMut so that it can be used by hlua.
function3	Wraps a type that implements FnMut so that it can be used by hlua.
function4	Wraps a type that implements FnMut so that it can be used by hlua.
function5	Wraps a type that implements FnMut so that it can be used by hlua.
function6	Wraps a type that implements FnMut so that it can be used by hlua.
function7	Wraps a type that implements FnMut so that it can be used by hlua.
function8	Wraps a type that implements FnMut so that it can be used by hlua.
function9	Wraps a type that implements FnMut so that it can be used by hlua.
function10	Wraps a type that implements FnMut so that it can be used by hlua.
push_userdata	Pushes an object as a user data.
read_userdata