Struct hlua::Lua

pub struct Lua<'lua> { /* fields omitted */ }

Main object of the library.

The lifetime parameter corresponds to the lifetime of the content of the Lua context.

About panic safety

This type isn't panic safe. This means that if a panic happens while you were using the Lua, then it will probably stay in a corrupt state. Trying to use the Lua again will most likely result in another panic but shouldn't result in unsafety.

Methods

impl<'lua> Lua<'lua>

fn new() -> Lua<'lua>

Builds a new empty Lua context.

There are no global variables and the registry is totally empty. Even the functions from the standard library can't be used.

If you want to use the Lua standard library in the scripts of this context, see the openlibs method

Example

use hlua::Lua;
let mut lua = Lua::new();

Panic

The function panics if the underlying call to lua_newstate fails (which indicates lack of memory).

unsafe fn from_existing_state<T>(
    lua: *mut T,
    close_at_the_end: bool
) -> Lua<'lua>

Takes an existing lua_State and build a Lua object from it.

If close_at_the_end is true, lua_close will be called on the lua_State in the destructor.

fn openlibs(&mut self)

Opens all standard Lua libraries.

See the reference for the standard library here: https://www.lua.org/manual/5.2/manual.html#6

This is done by calling luaL_openlibs.

Example

use hlua::Lua;
let mut lua = Lua::new();
lua.openlibs();

fn execute<'a, T>(&'a mut self, code: &str) -> Result<T, LuaError> where
    T: for<'g> LuaRead<PushGuard<&'g mut PushGuard<&'a mut Lua<'lua>>>>, 

Executes some Lua code in the context.

The code will have access to all the global variables you set with methods such as set. Every time you execute some code in the context, the code can modify these global variables.

The template parameter of this function is the return type of the expression that is being evaluated. In order to avoid compilation error, you should call this function either by doing lua.execute::<T>(...) or let result: T = lua.execute(...); where T is the type of the expression. The function will return an error if the actual return type of the expression doesn't match the template parameter.

See the get method for more information about the possible return types.

Examples

Without a return value:

use hlua::Lua;
let mut lua = Lua::new();
lua.execute::<()>("function multiply_by_two(a) return a * 2 end").unwrap();
lua.execute::<()>("twelve = multiply_by_two(6)").unwrap();

With a return value:

use hlua::Lua;
let mut lua = Lua::new();

let twelve: i32 = lua.execute("return 3 * 4;").unwrap();
let sixty = lua.execute::<i32>("return 6 * 10;").unwrap();

fn execute_from_reader<'a, T, R>(&'a mut self, code: R) -> Result<T, LuaError> where
    T: for<'g> LuaRead<PushGuard<&'g mut PushGuard<&'a mut Lua<'lua>>>>,
    R: Read, 

Executes some Lua code on the context.

This does the same thing as the execute method, but the code to execute is loaded from an object that implements Read.

Use this method when you potentially have a large amount of code (for example if you read the code from a file) in order to avoid having to put everything in memory first before passing it to the Lua interpreter.

Example

use std::fs::File;
use hlua::Lua;

let mut lua = Lua::new();
let script = File::open("script.lua").unwrap();
lua.execute_from_reader::<(), _>(script).unwrap();

fn get<'l, V, I>(&'l mut self, index: I) -> Option<V> where
    I: Borrow<str>,
    V: LuaRead<PushGuard<&'l mut Lua<'lua>>>, 

Reads the value of a global variable.

Returns None if the variable doesn't exist or is nil.

TODO: document the return types

Example

use hlua::Lua;
let mut lua = Lua::new();
lua.execute::<()>("a = 5").unwrap();
let a: i32 = lua.get("a").unwrap();
assert_eq!(a, 5);

fn into_get<V, I>(self, index: I) -> Result<V, PushGuard<Self>> where
    I: Borrow<str>,
    V: LuaRead<PushGuard<Lua<'lua>>>, 

Reads the value of a global, capturing the context by value.

fn set<I, V>(&mut self, index: I, value: V) where
    I: Borrow<str>,
    V: PushOne<&'a mut Lua<'lua>, Err = Void>, 

Modifies the value of a global variable.

If you want to write an array, you are encouraged to use the empty_array method instead.

Example

use hlua::Lua;
let mut lua = Lua::new();

lua.set("a", 12);
let six: i32 = lua.execute("return a / 2;").unwrap();
assert_eq!(six, 6);

fn checked_set<I, V, E>(&mut self, index: I, value: V) -> Result<(), E> where
    I: Borrow<str>,
    V: PushOne<&'a mut Lua<'lua>, Err = E>, 

Modifies the value of a global variable.

fn empty_array<'a, I>(
    &'a mut self,
    index: I
) -> LuaTable<PushGuard<&'a mut Lua<'lua>>> where
    I: Borrow<str>, 

Sets the value of a global variable to an empty array, then loads it.

This is the function you should use if you want to set the value of a global variable to an array. After calling it, you will obtain a LuaTable object which you can then fill with the elements of the array.

Example

use hlua::Lua;
let mut lua = Lua::new();
lua.openlibs();     // Necessary for `ipairs`.

{
    let mut array = lua.empty_array("my_values");
    array.set(1, 10);       // Don't forget that Lua arrays are indexed from 1.
    array.set(2, 15);
    array.set(3, 20);
}

let sum: i32 = lua.execute(r#"
    local sum = 0
    for i, val in ipairs(my_values) do
        sum = sum + val
    end
    return sum
"#).unwrap();

assert_eq!(sum, 45);

fn globals_table<'a>(&'a mut self) -> LuaTable<PushGuard<&'a mut Lua<'lua>>>

Loads the array containing the global variables.

In lua, the global variables accessible from the lua code are all part of a table which you can load here.

Examples

The function can be used to write global variables, just like set.

use hlua::Lua;
let mut lua = Lua::new();
lua.globals_table().set("a", 5);
assert_eq!(lua.get::<i32, _>("a"), Some(5));

A more useful feature for this function is that it allows you to set the metatable of the global variables. See TODO for more info.

use hlua::Lua;
use hlua::AnyLuaValue;

let mut lua = Lua::new();
{
    let mut metatable = lua.globals_table().get_or_create_metatable();
    metatable.set("__index", hlua::function2(|_: AnyLuaValue, var: String| -> AnyLuaValue {
        println!("The user tried to access the variable {:?}", var);
        AnyLuaValue::LuaNumber(48.0)
    }));
}

let b: i32 = lua.execute("return b * 2;").unwrap();
// -> The user tried to access the variable "b"

assert_eq!(b, 96);

Trait Implementations

impl<'a, 'lua> AsLua<'lua> for Lua<'lua>

fn as_lua(&self) -> LuaContext

impl<'lua> AsMutLua<'lua> for Lua<'lua>

fn as_mut_lua(&mut self) -> LuaContext

Returns the raw Lua context.

impl<'lua> Drop for Lua<'lua>

fn drop(&mut self)

A method called when the value goes out of scope.