Crate tlua

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

• 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