Crate hlua

source ·
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 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§

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§

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