A crate to enhance the APIs provided by the rlua and mlua crates
It aims to do this by improving the following:
- Allow the api to have easily accessible documentation embedded into it
- Allow the documentation to be built to web pages (using tealrdocgen )
- To go along with the documentation, tealr also allow you to be more precise in the types your api works with. Think generic methods and typed lambdas. No more Lua::Value
- Allow for the generation of .d.tl files. They allow the API to be used in teal, exposing type errors at compile time.
It does this by adding new traits and replacing/extending the existing ones from rlua and mlua. As a result, the api that tealr exposes is as similar as the api from those 2 crates as possible.
It also contains some macro's to easily generate new types to better express the API type wise and also some macro's to make it easier to embed teal.
instance.help()The library shown is https://github.com/lenscas/tealsql
Rendered html is also available at https://lenscas.github.io/tealsql/
Both rlua and mlua are behind the feature flags rlua and mlua.
It also reexports these crates and allows you to set flags through it (the forwarded flags are the same with either the prefix rlua_ or mlua_. For example if you want to enable mlua/async then you need to enable tealr/mlua_async)
Exposing types to lua as userdata is almost the same using tealr as it is using rlua and mlua
```rust ignore use tealr::TypeName;
struct ExampleRlua {}
//now, implement rlu::TealData. //This tells rlua what methods are available and tealr what the types are impl tealr::rlu::TealData for ExampleRlua { //implement your methods/functions fn addmethods<'lua, T: tealr::rlu::TealDataMethods<'lua, Self>>(methods: &mut T) { methods.documenttype("This is documentation added to the type itself.");
methods.document("This documentation gets added to the exposed function bellow.");
methods.add_method("example_method", |_, _, x: i8| Ok(x));
methods.add_method_mut("example_method_mut", |_, _, x: (i8, String)| Ok(x.1));
methods.add_function("example_function", |_, x: Vec<String>| Ok((x, 8)));
methods.document("***You*** can also embed markdown to the documentation, which gets picked up by [tealr_doc_gen](https://github.com/lenscas/type_generator)`");
methods.document("It is also possible to use this function multiple times. These are added as paragraphs.");
methods.add_function_mut("example_function_mut", |_, x: (bool, Option<ExampleRlua>)| {
Ok(x)
});
///This creates the instance.help() function, which returns the documentation as a string.
methods.generate_help();
}
}
Mlua:
rust ignore
use tealr::TypeName;
struct ExampleMlua {}
impl tealr::mlu::TealData for ExampleMlua {
//implement your methods/functions
fn addmethods<'lua, T: tealr::mlu::TealDataMethods<'lua, Self>>(methods: &mut T) {
methods.documenttype("This is documentation added to the type itself.");
methods.document("This documentation gets added to the exposed function bellow.");
methods.addmethod("examplemethod", |, _, x: i8| Ok(x));
methods.addmethodmut("examplemethodmut", |, , x: (i8, String)| Ok(x.1));
methods.addfunction("examplefunction", |, x: Vec
Though it is perfectly possible to use the lua::Value from rlua and mlua, tealr does offer some alternatives to better document your code.
These allow you to easily create a type that is only one of the types you give.
rust ignore
use tealr::{
create_union_mlua,
mlu::{mlua::{FromLua,Lua,ToLua}, TealData, TealDataMethods, TypedFunction},
MluaUserData, TypeName, TypeWalker,
};
create_union_mlua!(enum YourTypeName = i32 | String);
```rust ignore use mlua::ToLua; use tealr::{ creategenericmlua, mlu::{mlua::FromLua, TealData, TealDataMethods, TypedFunction}, MluaUserData, TypeName, TypeWalker, };
creategenericmlua!(X);
struct Example {}
impl TealData for Example {
fn addmethods<'lua, T: TealDataMethods<'lua, Self>>(methods: &mut T) {
methods.addmethod(
"genericfunctioncallback",
|lua, , fun: TypedFunction
In this example, the generated signature ofgenericfunctioncallbackwill befunction. Without generics and usinglua::Valueinstead, the generated signature would have instead becomefunction(function(string):any):any` which is a lot less descriptive.
For rlua, all you have to do is replace mlua for rlua
The teal language is basically just a statically typed variant of lua and can even be made to run in the lua vm without compiling to lua first.
As a result of this and tealr's focus on enabling a richer typed api causes the 2 projects to work well together. However, to further help bind the 2 projects, tealr contains some extra helpers for those that want to use teal.
.d.tl files are type definition files used by the teal compiler so it knows what types a library has that isn't written in teal. Similar to how .d.ts files allow typescript to work with libraries written in JS
tealr allows you to easily create these .d.tl files based on your types.
```rust
//set your type up with either rlua or mlua
use tealr::{TypeName};
use tealr::{MluaUserData,mlu::TealData};
use tealr::{RluaUserData,rlu::TealData};
struct Example {} impl TealData for Example {};
//time to create the type definitions
let filecontents = tealr::TypeWalker::new()
.processtype::
//write the output to a file println!("{}",file_contents) ```
Both rlua and mlua allow you to run lua code embedded in your application.
Similarly, tealr allows you to compile embedded teal code to lua while compiling your application. This can then be executed by rlua and mlua.
This means that you can make use of teal's static type system even for small scripts inside your rust codebase.
rust
use tealr::compile_inline_teal;
let code = compile_inline_teal!("local x : number = 5 return x");
Teal makes it possible for the lua vm to load teal files as if they are normal lua files.
Tealr makes doing this from withing rust a bit easier, by exposing a macro that can embed the teal compiler in your application and create a function that creates the needed lua code to set the VM up. This function takes a string, which is the file that needs to get required.
```rust norun use tealr::embedcompiler; let compiler = embed_compiler!("v0.13.1");
{ let res : u8 = tealr::rlu::rlua::Lua::new().context(|ctx| { let code = compiler("example/basictealfile"); ctx.load(&code).setname("embeddedcompiler")?.eval() })?; };
{
let code = compiler("example/basictealfile");
let lua = tealr::mlu::mlua::Lua::new();
let res: u8 = lua.load(&code).setname("embeddedcompiler")?.eval()?;
};
Ok::<(), Box
There are a few sources tealr can use to get the compiler. If no source is specified it defaults to github releases.
Other sources can be specified as follows:
rust ignore
//get the teal compiler using the given path
embedcompiler!(Local(path = "some/path/to/tl.tl"));
//this uses luarocks to try and discover the location of the compiler
embedcompiler!(Local());
//download the compiler at compile time from github (default)
embedcompiler!(GitHub(version = "v0.13.1"));
//download the compiler at compile time from luarocks
embedcompiler!(Luarocks(version = "v0.13.1"));
```
You can find longer ones with comments on what each call does here