Skip to main content

Crate tsuki

Crate tsuki 

Source
Expand description

Lua 5.4 ported to Rust.

§Quickstart

use tsuki::builtin::{BaseLib, CoroLib, MathLib, StrLib, TableLib, Utf8Lib};
use tsuki::context::{Args, Context, Ret};
use tsuki::{Lua, Value, fp};

fn main() {
    // Set up.
    let lua = Lua::new(());

    lua.use_module(None, true, BaseLib).unwrap();
    lua.use_module(None, true, CoroLib).unwrap();
    lua.use_module(None, true, MathLib).unwrap();
    lua.use_module(None, true, StrLib).unwrap();
    lua.use_module(None, true, TableLib).unwrap();
    lua.use_module(None, true, Utf8Lib).unwrap();

    lua.global().set_str_key("myfunc", fp!(myfunc));

    // Create Lua thread to run Lua code.
    let chunk = lua.load("abc.lua", "return myfunc()").unwrap();
    let td = lua.create_thread();
    let result = td.call(chunk, ()).unwrap();

    match result {
        Value::Str(v) => assert_eq!(v.as_utf8(), Some("Hello world!")),
        _ => todo!(),
    }
}

fn myfunc(cx: Context<(), Args>) -> Result<Context<(), Ret>, Box<dyn core::error::Error>> {
    cx.push_str("Hello world!")?;

    Ok(cx.into())
}

§Types that can be converted to UnsafeValue

You can pass the value of the following types for impl Into<UnsafeValue>:

The value will be converted to corresponding Lua value. Tsuki does not expose [UnsafeValue] by design so you cannot construct its value. Tsuki also never handout the value of [UnsafeValue].

§Get function argument

Use Context::arg() to get an argument passed to Rust function:

fn myfunc(cx: Context<(), Args>) -> Result<Context<(), Ret>, Box<dyn core::error::Error>> {
    let arg = cx.arg(1); // One-based the same as Lua so this is first argument.
    let val = arg.to_int()?;

    if val < 0 {
        return Err(arg.error("expect positive integer"));
    }

    // This will return nil since to any values pushed to cx.
    Ok(cx.into())
}

§Parsing Lua option

Tsuki provides a derive macro FromStr to handle this.

§Store value in registry

You need to create a type per key in registry:

use tsuki::{RegKey, Table};

struct MyKey;

impl<A> RegKey<A> for MyKey {
    type Value<'a>
        = Table<A>
    where
        A: 'a;
}

Type itself is a key, not its value. Then you can use Lua::set_registry() or Context::set_registry() to set the value and Lua::registry() or Context::registry() to retrieve the value.

§Store value in Rust collection

Tsuki also provides Rust collection that can store Lua values. The following code demonstrate a registry value of BTreeMap to map Rust String to any Lua value:

use tsuki::collections::BTreeMap;
use tsuki::context::{Args, Context, Ret};
use tsuki::{Dynamic, RegKey};

fn myfunc(cx: Context<(), Args>) -> Result<Context<(), Ret>, Box<dyn core::error::Error>> {
    let v = cx.arg(1);
    let r = cx.registry::<MyKey>().unwrap();

    r.insert(String::from("abc"), v);

    Ok(cx.into())
}

struct MyKey;

impl<A> RegKey<A> for MyKey {
    type Value<'a>
        = BTreeMap<A, String, Dynamic>
    where
        A: 'a;
}

See collections module for available collections.

Modules§

builtin
Implementation of Lua standard libraries.
collections
Provides Rust collection types to store Lua values.
context
Provides Context to interact with Lua VM from Fp and AsyncFp.

Macros§

fp
Helper macro to construct Fp or AsyncFp.

Structs§

AsyncFp
Asynchronous Rust function.
CallError
Contains information how Fp, AsyncFp or YieldFp fails.
Dynamic
Unit struct to store any value in registry or collection.
DynamicInputs
Implementation of [Inputs] which size does not known at compile time.
Float
Lua floating-point number.
Fp
Non-Yieldable Rust function.
KeyMissing
Error when attempt to enumerating a table with a key that was removed.
Lua
Global states shared with all Lua threads.
LuaFn
Lua function.
ModuleExists
Represents an error when Lua::use_module() fails due to the module already exists.
Nil
Unit struct to create nil value.
RecursiveCall
Represents an error when a function that cannot be recursive call itself either directly or indirectly.
Ref
Strong reference to Lua object.
StackOverflow
Represents an error when Lua stack is overflow.
Str
Lua string.
Table
Lua table.
Thread
Lua thread.
ThreadBusy
Represents an error when attempt to use a thread that has active call.
UserData
Lua full userdata.
YieldFp
Rust function to yield Lua values.

Enums§

ArithError
Represents an error when arithmetic operation fails.
Coroutine
Result of Thread::resume() or Thread::async_resume().
MetatableError
Error when attempt to set an invalid metatable.
Number
Helper enum to encapsulates either integer or float.
ParseError
Represents an error when failed to parse Lua source.
TableError
Represents an error when the operation on a table fails.
Type
Type of Lua value.
Value
Encapsulates a Lua value.

Traits§

Class
Provides a function to create a metatable for a userdata.
Module
Provides interface for Rust to create a Lua module.
RegKey
Key to store value on Lua registry.

Attribute Macros§

class
Generate Class implementation from impl block.

Derive Macros§

FromStr
Generate core::str::FromStr implementation for enum to parse Lua option.