Update docs
This commit is contained in:
parent
9f073ad879
commit
2fee3e7891
|
@ -17,7 +17,7 @@ with async/await features and support of writing native Lua modules in Rust.
|
|||
"""
|
||||
|
||||
[package.metadata.docs.rs]
|
||||
features = ["lua53", "async", "send", "serialize", "macros"]
|
||||
features = ["lua54", "vendored", "async", "send", "serialize", "macros"]
|
||||
rustdoc-args = ["--cfg", "docsrs"]
|
||||
|
||||
[workspace]
|
||||
|
|
|
@ -127,7 +127,7 @@ fn main() -> LuaResult<()> {
|
|||
```
|
||||
|
||||
### Module mode
|
||||
In a module mode `mlua` allows to create a compiled Lua module that can be loaded from Lua code using [`require`](https://www.lua.org/manual/5.3/manual.html#pdf-require). In this case `mlua` uses an external Lua runtime which could lead to potential unsafety due to unpredictability of the Lua environment and usage of libraries such as [`debug`](https://www.lua.org/manual/5.3/manual.html#6.10).
|
||||
In a module mode `mlua` allows to create a compiled Lua module that can be loaded from Lua code using [`require`](https://www.lua.org/manual/5.4/manual.html#pdf-require). In this case `mlua` uses an external Lua runtime which could lead to potential unsafety due to unpredictability of the Lua environment and usage of libraries such as [`debug`](https://www.lua.org/manual/5.4/manual.html#6.10).
|
||||
|
||||
[Example](examples/module)
|
||||
|
||||
|
@ -164,7 +164,7 @@ And then (**macOS** example):
|
|||
``` sh
|
||||
$ cargo rustc -- -C link-arg=-undefined -C link-arg=dynamic_lookup
|
||||
$ ln -s ./target/debug/libmy_module.dylib ./my_module.so
|
||||
$ lua5.3 -e 'require("my_module").hello("world")'
|
||||
$ lua5.4 -e 'require("my_module").hello("world")'
|
||||
hello, world!
|
||||
```
|
||||
|
||||
|
|
|
@ -11,9 +11,9 @@ use crate::lua::Lua;
|
|||
/// The `Debug` structure is provided as a parameter to the hook function set with
|
||||
/// [`Lua::set_hook`]. You may call the methods on this structure to retrieve information about the
|
||||
/// Lua code executing at the time that the hook function was called. Further information can be
|
||||
/// found in the [Lua 5.3 documentation][lua_doc].
|
||||
/// found in the Lua [documentation][lua_doc].
|
||||
///
|
||||
/// [lua_doc]: https://www.lua.org/manual/5.3/manual.html#lua_Debug
|
||||
/// [lua_doc]: https://www.lua.org/manual/5.4/manual.html#lua_Debug
|
||||
/// [`Lua::set_hook`]: crate::Lua::set_hook
|
||||
pub struct Debug<'lua> {
|
||||
lua: &'lua Lua,
|
||||
|
@ -171,10 +171,10 @@ pub struct DebugSource<'a> {
|
|||
pub struct DebugStack {
|
||||
pub num_ups: i32,
|
||||
/// Requires `feature = "lua54/lua53/lua52"`
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52", doc))]
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52"))]
|
||||
pub num_params: i32,
|
||||
/// Requires `feature = "lua54/lua53/lua52"`
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52", doc))]
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52"))]
|
||||
pub is_vararg: bool,
|
||||
}
|
||||
|
||||
|
|
19
src/lib.rs
19
src/lib.rs
|
@ -192,6 +192,23 @@ extern crate mlua_derive;
|
|||
#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
|
||||
pub use mlua_derive::chunk;
|
||||
|
||||
#[cfg(any(feature = "module"))]
|
||||
/// Registers Lua module entrypoint.
|
||||
///
|
||||
/// You can register multiple entrypoints as required.
|
||||
///
|
||||
/// ```
|
||||
/// use mlua::{Lua, Result, Table};
|
||||
///
|
||||
/// #[mlua::lua_module]
|
||||
/// fn my_module(lua: &Lua) -> Result<Table> {
|
||||
/// let exports = lua.create_table()?;
|
||||
/// exports.set("hello", "world")?;
|
||||
/// Ok(exports)
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// Internally in the code above the compiler defines C function `luaopen_my_module`.
|
||||
///
|
||||
#[cfg(any(feature = "module", docsrs))]
|
||||
#[cfg_attr(docsrs, doc(cfg(feature = "module")))]
|
||||
pub use mlua_derive::lua_module;
|
||||
|
|
34
src/lua.rs
34
src/lua.rs
|
@ -119,14 +119,14 @@ struct MemoryInfo {
|
|||
/// In Lua 5.4 GC can work in two modes: incremental and generational.
|
||||
/// Previous Lua versions support only incremental GC.
|
||||
///
|
||||
/// More information can be found in the Lua 5.x [documentation].
|
||||
/// More information can be found in the Lua [documentation].
|
||||
///
|
||||
/// [documentation]: https://www.lua.org/manual/5.4/manual.html#2.5
|
||||
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
|
||||
pub enum GCMode {
|
||||
Incremental,
|
||||
/// Requires `feature = "lua54"`
|
||||
#[cfg(any(feature = "lua54", doc))]
|
||||
#[cfg(any(feature = "lua54"))]
|
||||
Generational,
|
||||
}
|
||||
|
||||
|
@ -144,8 +144,8 @@ pub struct LuaOptions {
|
|||
///
|
||||
/// Default: **true**
|
||||
///
|
||||
/// [`pcall`]: https://www.lua.org/manual/5.3/manual.html#pdf-pcall
|
||||
/// [`xpcall`]: https://www.lua.org/manual/5.3/manual.html#pdf-xpcall
|
||||
/// [`pcall`]: https://www.lua.org/manual/5.4/manual.html#pdf-pcall
|
||||
/// [`xpcall`]: https://www.lua.org/manual/5.4/manual.html#pdf-xpcall
|
||||
pub catch_rust_panics: bool,
|
||||
|
||||
/// Max size of thread (coroutine) object cache used to execute asynchronous functions.
|
||||
|
@ -157,6 +157,7 @@ pub struct LuaOptions {
|
|||
///
|
||||
/// [`lua_resetthread`]: https://www.lua.org/manual/5.4/manual.html#lua_resetthread
|
||||
#[cfg(feature = "async")]
|
||||
#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
|
||||
pub thread_cache_size: usize,
|
||||
}
|
||||
|
||||
|
@ -188,6 +189,7 @@ impl LuaOptions {
|
|||
///
|
||||
/// [`thread_cache_size`]: #structfield.thread_cache_size
|
||||
#[cfg(feature = "async")]
|
||||
#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
|
||||
pub const fn thread_cache_size(mut self, size: usize) -> Self {
|
||||
self.thread_cache_size = size;
|
||||
self
|
||||
|
@ -616,7 +618,7 @@ impl Lua {
|
|||
///
|
||||
/// Behavior is similar to Lua's [`require`] function.
|
||||
///
|
||||
/// [`require`]: https://www.lua.org/manual/5.3/manual.html#pdf-require
|
||||
/// [`require`]: https://www.lua.org/manual/5.4/manual.html#pdf-require
|
||||
pub fn load_from_function<'lua, S, T>(
|
||||
&'lua self,
|
||||
modname: &S,
|
||||
|
@ -935,7 +937,7 @@ impl Lua {
|
|||
/// Does not work on module mode where Lua state is managed externally.
|
||||
///
|
||||
/// Requires `feature = "lua54/lua53/lua52"`
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52", doc))]
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52"))]
|
||||
pub fn set_memory_limit(&self, memory_limit: usize) -> Result<usize> {
|
||||
unsafe {
|
||||
match &mut (*self.extra.get()).mem_info {
|
||||
|
@ -952,7 +954,7 @@ impl Lua {
|
|||
/// Returns true if the garbage collector is currently running automatically.
|
||||
///
|
||||
/// Requires `feature = "lua54/lua53/lua52"`
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52", doc))]
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52"))]
|
||||
pub fn gc_is_running(&self) -> bool {
|
||||
let state = self.main_state.unwrap_or(self.state);
|
||||
unsafe { ffi::lua_gc(state, ffi::LUA_GCISRUNNING, 0) != 0 }
|
||||
|
@ -1005,10 +1007,10 @@ impl Lua {
|
|||
|
||||
/// Sets the 'pause' value of the collector.
|
||||
///
|
||||
/// Returns the previous value of 'pause'. More information can be found in the [Lua 5.3
|
||||
/// documentation][lua_doc].
|
||||
/// Returns the previous value of 'pause'. More information can be found in the Lua
|
||||
/// [documentation][lua_doc].
|
||||
///
|
||||
/// [lua_doc]: https://www.lua.org/manual/5.3/manual.html#2.5
|
||||
/// [lua_doc]: https://www.lua.org/manual/5.4/manual.html#2.5
|
||||
pub fn gc_set_pause(&self, pause: c_int) -> c_int {
|
||||
let state = self.main_state.unwrap_or(self.state);
|
||||
unsafe { ffi::lua_gc(state, ffi::LUA_GCSETPAUSE, pause) }
|
||||
|
@ -1017,9 +1019,9 @@ impl Lua {
|
|||
/// Sets the 'step multiplier' value of the collector.
|
||||
///
|
||||
/// Returns the previous value of the 'step multiplier'. More information can be found in the
|
||||
/// Lua 5.x [documentation][lua_doc].
|
||||
/// Lua [documentation][lua_doc].
|
||||
///
|
||||
/// [lua_doc]: https://www.lua.org/manual/5.3/manual.html#2.5
|
||||
/// [lua_doc]: https://www.lua.org/manual/5.4/manual.html#2.5
|
||||
pub fn gc_set_step_multiplier(&self, step_multiplier: c_int) -> c_int {
|
||||
let state = self.main_state.unwrap_or(self.state);
|
||||
unsafe { ffi::lua_gc(state, ffi::LUA_GCSETSTEPMUL, step_multiplier) }
|
||||
|
@ -1028,7 +1030,7 @@ impl Lua {
|
|||
/// Changes the collector to incremental mode with the given parameters.
|
||||
///
|
||||
/// Returns the previous mode (always `GCMode::Incremental` in Lua < 5.4).
|
||||
/// More information can be found in the Lua 5.x [documentation][lua_doc].
|
||||
/// More information can be found in the Lua [documentation][lua_doc].
|
||||
///
|
||||
/// [lua_doc]: https://www.lua.org/manual/5.4/manual.html#2.5.1
|
||||
pub fn gc_inc(&self, pause: c_int, step_multiplier: c_int, step_size: c_int) -> GCMode {
|
||||
|
@ -1070,7 +1072,7 @@ impl Lua {
|
|||
/// Requires `feature = "lua54"`
|
||||
///
|
||||
/// [lua_doc]: https://www.lua.org/manual/5.4/manual.html#2.5.2
|
||||
#[cfg(any(feature = "lua54", doc))]
|
||||
#[cfg(any(feature = "lua54"))]
|
||||
pub fn gc_gen(&self, minor_multiplier: c_int, major_multiplier: c_int) -> GCMode {
|
||||
let state = self.main_state.unwrap_or(self.state);
|
||||
let prev_mode =
|
||||
|
@ -2558,7 +2560,7 @@ pub enum ChunkMode {
|
|||
|
||||
/// Trait for types [loadable by Lua] and convertible to a [`Chunk`]
|
||||
///
|
||||
/// [loadable by Lua]: https://www.lua.org/manual/5.3/manual.html#3.3.2
|
||||
/// [loadable by Lua]: https://www.lua.org/manual/5.4/manual.html#3.3.2
|
||||
/// [`Chunk`]: crate::Chunk
|
||||
pub trait AsChunk<'lua> {
|
||||
/// Returns chunk data (can be text or binary)
|
||||
|
@ -2571,7 +2573,7 @@ pub trait AsChunk<'lua> {
|
|||
|
||||
/// Returns optional chunk [environment]
|
||||
///
|
||||
/// [environment]: https://www.lua.org/manual/5.3/manual.html#2.2
|
||||
/// [environment]: https://www.lua.org/manual/5.4/manual.html#2.2
|
||||
fn env(&self, _lua: &'lua Lua) -> Result<Option<Value<'lua>>> {
|
||||
Ok(None)
|
||||
}
|
||||
|
|
|
@ -6,32 +6,32 @@ use std::u32;
|
|||
pub struct StdLib(u32);
|
||||
|
||||
impl StdLib {
|
||||
/// [`coroutine`](https://www.lua.org/manual/5.3/manual.html#6.2) library
|
||||
/// [`coroutine`](https://www.lua.org/manual/5.4/manual.html#6.2) library
|
||||
///
|
||||
/// Requires `feature = "lua54/lua53/lua52"`
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52", doc))]
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52"))]
|
||||
pub const COROUTINE: StdLib = StdLib(1);
|
||||
/// [`table`](https://www.lua.org/manual/5.3/manual.html#6.6) library
|
||||
/// [`table`](https://www.lua.org/manual/5.4/manual.html#6.6) library
|
||||
pub const TABLE: StdLib = StdLib(1 << 1);
|
||||
/// [`io`](https://www.lua.org/manual/5.3/manual.html#6.8) library
|
||||
/// [`io`](https://www.lua.org/manual/5.4/manual.html#6.8) library
|
||||
pub const IO: StdLib = StdLib(1 << 2);
|
||||
/// [`os`](https://www.lua.org/manual/5.3/manual.html#6.9) library
|
||||
/// [`os`](https://www.lua.org/manual/5.4/manual.html#6.9) library
|
||||
pub const OS: StdLib = StdLib(1 << 3);
|
||||
/// [`string`](https://www.lua.org/manual/5.3/manual.html#6.4) library
|
||||
/// [`string`](https://www.lua.org/manual/5.4/manual.html#6.4) library
|
||||
pub const STRING: StdLib = StdLib(1 << 4);
|
||||
/// [`utf8`](https://www.lua.org/manual/5.3/manual.html#6.5) library
|
||||
/// [`utf8`](https://www.lua.org/manual/5.4/manual.html#6.5) library
|
||||
///
|
||||
/// Requires `feature = "lua54/lua53"`
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
|
||||
#[cfg(any(feature = "lua54", feature = "lua53"))]
|
||||
pub const UTF8: StdLib = StdLib(1 << 5);
|
||||
/// [`bit`](https://www.lua.org/manual/5.2/manual.html#6.7) library
|
||||
///
|
||||
/// Requires `feature = "lua52/luajit"`
|
||||
#[cfg(any(feature = "lua52", feature = "luajit", doc))]
|
||||
pub const BIT: StdLib = StdLib(1 << 6);
|
||||
/// [`math`](https://www.lua.org/manual/5.3/manual.html#6.7) library
|
||||
/// [`math`](https://www.lua.org/manual/5.4/manual.html#6.7) library
|
||||
pub const MATH: StdLib = StdLib(1 << 7);
|
||||
/// [`package`](https://www.lua.org/manual/5.3/manual.html#6.3) library
|
||||
/// [`package`](https://www.lua.org/manual/5.4/manual.html#6.3) library
|
||||
pub const PACKAGE: StdLib = StdLib(1 << 8);
|
||||
/// [`jit`](http://luajit.org/ext_jit.html) library
|
||||
///
|
||||
|
@ -44,7 +44,7 @@ impl StdLib {
|
|||
/// Requires `feature = "luajit"`
|
||||
#[cfg(any(feature = "luajit", doc))]
|
||||
pub const FFI: StdLib = StdLib(1 << 30);
|
||||
/// (**unsafe**) [`debug`](https://www.lua.org/manual/5.3/manual.html#6.10) library
|
||||
/// (**unsafe**) [`debug`](https://www.lua.org/manual/5.4/manual.html#6.10) library
|
||||
pub const DEBUG: StdLib = StdLib(1 << 31);
|
||||
|
||||
/// No libraries
|
||||
|
|
|
@ -380,7 +380,7 @@ impl<'lua> Table<'lua> {
|
|||
/// ```
|
||||
///
|
||||
/// [`Result`]: crate::Result
|
||||
/// [Lua manual]: http://www.lua.org/manual/5.3/manual.html#pdf-next
|
||||
/// [Lua manual]: http://www.lua.org/manual/5.4/manual.html#pdf-next
|
||||
pub fn pairs<K: FromLua<'lua>, V: FromLua<'lua>>(self) -> TablePairs<'lua, K, V> {
|
||||
TablePairs {
|
||||
table: self.0,
|
||||
|
@ -429,7 +429,7 @@ impl<'lua> Table<'lua> {
|
|||
///
|
||||
/// [`pairs`]: #method.pairs
|
||||
/// [`Result`]: crate::Result
|
||||
/// [Lua manual]: http://www.lua.org/manual/5.3/manual.html#pdf-next
|
||||
/// [Lua manual]: http://www.lua.org/manual/5.4/manual.html#pdf-next
|
||||
pub fn sequence_values<V: FromLua<'lua>>(self) -> TableSequence<'lua, V> {
|
||||
TableSequence {
|
||||
table: self.0,
|
||||
|
@ -514,6 +514,7 @@ pub trait TableExt<'lua> {
|
|||
///
|
||||
/// The metamethod is called with the table as its first argument, followed by the passed arguments.
|
||||
#[cfg(feature = "async")]
|
||||
#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
|
||||
fn call_async<'fut, A, R>(&self, args: A) -> LocalBoxFuture<'fut, Result<R>>
|
||||
where
|
||||
'lua: 'fut,
|
||||
|
|
|
@ -7,7 +7,7 @@ use crate::types::LuaRef;
|
|||
use crate::util::{check_stack, error_traceback, pop_error, StackGuard};
|
||||
use crate::value::{FromLuaMulti, ToLuaMulti};
|
||||
|
||||
#[cfg(any(feature = "lua54", all(feature = "luajit", feature = "vendored"), doc))]
|
||||
#[cfg(any(feature = "lua54", all(feature = "luajit", feature = "vendored")))]
|
||||
use crate::function::Function;
|
||||
|
||||
#[cfg(feature = "async")]
|
||||
|
@ -182,7 +182,7 @@ impl<'lua> Thread<'lua> {
|
|||
///
|
||||
/// [Lua 5.4]: https://www.lua.org/manual/5.4/manual.html#lua_resetthread
|
||||
/// [LuaJIT]: https://github.com/openresty/luajit2#lua_resetthread
|
||||
#[cfg(any(feature = "lua54", all(feature = "luajit", feature = "vendored"), doc))]
|
||||
#[cfg(any(feature = "lua54", all(feature = "luajit", feature = "vendored")))]
|
||||
pub fn reset(&self, func: Function<'lua>) -> Result<()> {
|
||||
let lua = self.0.lua;
|
||||
unsafe {
|
||||
|
|
|
@ -54,29 +54,29 @@ pub enum MetaMethod {
|
|||
Unm,
|
||||
/// The floor division (//) operator.
|
||||
/// Requires `feature = "lua54/lua53"`
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
|
||||
#[cfg(any(feature = "lua54", feature = "lua53"))]
|
||||
IDiv,
|
||||
/// The bitwise AND (&) operator.
|
||||
/// Requires `feature = "lua54/lua53"`
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
|
||||
#[cfg(any(feature = "lua54", feature = "lua53"))]
|
||||
BAnd,
|
||||
/// The bitwise OR (|) operator.
|
||||
/// Requires `feature = "lua54/lua53"`
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
|
||||
#[cfg(any(feature = "lua54", feature = "lua53"))]
|
||||
BOr,
|
||||
/// The bitwise XOR (binary ~) operator.
|
||||
/// Requires `feature = "lua54/lua53"`
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
|
||||
#[cfg(any(feature = "lua54", feature = "lua53"))]
|
||||
BXor,
|
||||
/// The bitwise NOT (unary ~) operator.
|
||||
/// Requires `feature = "lua54/lua53"`
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
|
||||
#[cfg(any(feature = "lua54", feature = "lua53"))]
|
||||
BNot,
|
||||
/// The bitwise left shift (<<) operator.
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
|
||||
#[cfg(any(feature = "lua54", feature = "lua53"))]
|
||||
Shl,
|
||||
/// The bitwise right shift (>>) operator.
|
||||
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
|
||||
#[cfg(any(feature = "lua54", feature = "lua53"))]
|
||||
Shr,
|
||||
/// The string concatenation operator `..`.
|
||||
Concat,
|
||||
|
@ -108,7 +108,6 @@ pub enum MetaMethod {
|
|||
feature = "lua53",
|
||||
feature = "lua52",
|
||||
feature = "luajit52",
|
||||
doc
|
||||
))]
|
||||
Pairs,
|
||||
/// The `__ipairs` metamethod.
|
||||
|
@ -130,7 +129,7 @@ pub enum MetaMethod {
|
|||
/// Requires `feature = "lua54"`
|
||||
///
|
||||
/// [lua_doc]: https://www.lua.org/manual/5.4/manual.html#3.3.8
|
||||
#[cfg(any(feature = "lua54", doc))]
|
||||
#[cfg(any(feature = "lua54"))]
|
||||
Close,
|
||||
/// A custom metamethod.
|
||||
///
|
||||
|
|
Loading…
Reference in New Issue