Expand description
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 theget
andset
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 variablefoo
to a Rust function, you can then call it from Lua withfoo()
. -
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
andLuaCodeFromReader
structs. Since pushing these structs can result in an error, you need to usechecked_set
instead ofset
. Vec
s andHashMap
s 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 notPushOne
. - 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
andStringInLua
(ie. the equivalent of&str
). Loading the latter has no cost while loading aString
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§
Structs§
- Opaque type containing a Rust function or closure.
- Opaque type that represents the Lua context when inside a callback.
- Main object of the library.
- Wrapper around a
&str
. When pushed, the content will be parsed as Lua code and turned into a function. - Wrapper around a
Read
object. When pushed, the content will be parsed as Lua code and turned into a function. - Opaque type that contains the raw Lua context.
- Handle to a function in the Lua context.
- Represents a table stored in the Lua context.
- Iterator that enumerates the content of a Lua table.
- RAII guard for a value pushed on the stack.
- String on the Lua stack.
- Represents a user data located inside the Lua context.
Enums§
- Represents any value that can be stored by Lua
- Represents any value that can be stored by Lua
- Error that can happen when executing Lua code.
- Error that can happen when calling a
LuaFunction
. - Error that can happen when pushing multiple values at once.
- Type that cannot be instantiated.
Traits§
- 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. - 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.
- Types that can be obtained from a Lua context.
- Types that can be given to a Lua context, for example with
lua.set()
or as a return value of a function. - Extension trait for
Push
. Guarantees that only one element will be pushed.
Functions§
- Wraps a type that implements
FnMut
so that it can be used by hlua. - Wraps a type that implements
FnMut
so that it can be used by hlua. - Wraps a type that implements
FnMut
so that it can be used by hlua. - Wraps a type that implements
FnMut
so that it can be used by hlua. - Wraps a type that implements
FnMut
so that it can be used by hlua. - Wraps a type that implements
FnMut
so that it can be used by hlua. - Wraps a type that implements
FnMut
so that it can be used by hlua. - Wraps a type that implements
FnMut
so that it can be used by hlua. - Wraps a type that implements
FnMut
so that it can be used by hlua. - Wraps a type that implements
FnMut
so that it can be used by hlua. - Wraps a type that implements
FnMut
so that it can be used by hlua. - Pushes an object as a user data.