1 unstable release
Uses old Rust 2015
0.4.2 | Mar 28, 2018 |
---|
#2359 in Rust patterns
338 downloads per month
Used in 5 crates
155KB
3K
SLoC
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
Dependencies
~470–700KB
~18K SLoC