Skip to content

Commit 969aa4a

Browse files
AlphaModderAlphaModder
committed
Expose the lua searcher as an advanced feature of the public API.
1 parent 3885500 commit 969aa4a

File tree

4 files changed

+23
-10
lines changed

4 files changed

+23
-10
lines changed

‎README.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,19 @@
11
# include-lua #
22
include-lua is a crate that allows the embedding of a lua source tree into a Rust application binary. This tree can then be loaded into an [`rlua`](https://github.com/kyren/rlua) context, and code imported from it via `require`.
33

4-
## Usage ##
4+
## Basic Usage ##
55
First, create an instance of the `LuaModules` struct via the macro `include_lua!`. This macro takes a string literal parameter specifying a directory, relative to your crate's `src` folder. All `.lua` files in this directory and its subdirectories will be included as loadable modules.
66

7-
It is possible to specify a name to use for the `LuaModules` struct, though at the moment this will only appear in lua stacktraces. Simply invoke the macro like `include_lua!("name": "path")`, instead of just `include_lua!("path")`.
8-
97
Once you've created a `LuaModules` struct, you can import it into an `rlua::Context` by calling `ctx.add_modules(modules)`. This is an extension method provided by a trait, so make sure you have a `use include_lua::*;` statement in your code. Once it has been called, any calls to `require` executed in that context will be able to load modules from the embedded source tree.
108

11-
If you would like to load the modules in a custom environment for some reason, call `ctx.add_modules_with_env(modules, env)`, where `env` is a table that will be used as the `_ENV` value of all modules within the source tree.
9+
## Advanced Usage ##
10+
It is possible to specify a name to use for the `LuaModules` struct, which will appear in stacktraces from any code within it. Simply invoke the `include_lua` macro like `include_lua!("name": "path")`, instead of just `include_lua!("path")`.
11+
12+
If you would like to load modules in a custom environment for some reason, instead of `ctx.add_modules`, you can call `ctx.add_modules_with_env(modules, env)`, where `env` is a table that will be used as the `_ENV` value of all modules within the source tree.
13+
14+
The methods `ctx.make_searcher(modules)` and `ctx.make_searcher_with_env(modules, env)` are also available. They produce a piece of userdata that in Lua code, acts like a function to load a module from the source tree by name.
15+
16+
As they are lower-level methods, values returned by `make_searcher` or `make_searcher_with_env` do not cache modules like `require`. This means that if you want to avoid multiple calls with the same name loading multiple copies of the same module you will have to implement a wrapper in your lua code.
1217

1318
## Example ##
1419
See [example/main.rs](https://github.com/AlphaModder/include-lua/blob/master/example/src/main.rs) for a working example of the macro's use.

‎example/Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,5 @@ edition = "2018"
66
publish = false
77

88
[dependencies]
9-
include-lua = "0.1.2"
9+
include-lua = "0.1.3"
1010
rlua = "0.16.2"

‎include-lua/Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ name = "include-lua"
33
description = "A crate that allows the embedding of a lua source tree into a Rust application binary."
44
repository = "https://github.com/AlphaModder/include-lua"
55
readme = "../README.md"
6-
version = "0.1.2"
6+
version = "0.1.3"
77
license = "MIT"
88
authors = ["AlphaModder"]
99
edition = "2018"

‎include-lua/src/lib.rs‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ impl LuaModules {
1818
}
1919
}
2020

21-
struct Searcher(LuaModules, RegistryKey);
21+
pub struct Searcher(LuaModules, RegistryKey);
2222

2323
impl UserData for Searcher {
2424
fn add_methods<'lua, M: UserDataMethods<'lua, Self>>(methods: &mut M) {
@@ -40,6 +40,8 @@ impl UserData for Searcher {
4040
pub trait ContextExt<'a> {
4141
fn add_modules(&self, modules: LuaModules) -> Result<()>;
4242
fn add_modules_with_env(&self, modules: LuaModules, environment: Table<'a>) -> Result<()>;
43+
fn make_searcher(&self, modules: LuaModules) -> Result<Searcher>;
44+
fn make_searcher_with_env(&self, modules: LuaModules, environment: Table<'a>) -> Result<Searcher>;
4345
}
4446

4547
impl<'a> ContextExt<'a> for Context<'a> {
@@ -48,9 +50,15 @@ impl<'a> ContextExt<'a> for Context<'a> {
4850
}
4951

5052
fn add_modules_with_env(&self, modules: LuaModules, environment: Table<'a>) -> Result<()> {
51-
let key = self.create_registry_value(environment)?;
5253
let searchers: Table = self.globals().get::<_, Table>("package")?.get("searchers")?;
53-
searchers.set(searchers.len()? + 1, Searcher(modules, key))?;
54-
Ok(())
54+
searchers.set(searchers.len()? + 1, self.make_searcher_with_env(modules, environment)?)
55+
}
56+
57+
fn make_searcher(&self, modules: LuaModules) -> Result<Searcher> {
58+
self.make_searcher_with_env(modules, self.globals())
59+
}
60+
61+
fn make_searcher_with_env(&self, modules: LuaModules, environment: Table<'a>) -> Result<Searcher> {
62+
Ok(Searcher(modules, self.create_registry_value(environment)?))
5563
}
5664
}

0 commit comments

Comments
 (0)