mlua/
lib.rs

1//! # High-level bindings to Lua
2//!
3//! The `mlua` crate provides safe high-level bindings to the [Lua programming language].
4//!
5//! # The `Lua` object
6//!
7//! The main type exported by this library is the [`Lua`] struct. In addition to methods for
8//! [executing] Lua chunks or [evaluating] Lua expressions, it provides methods for creating Lua
9//! values and accessing the table of [globals].
10//!
11//! # Converting data
12//!
13//! The [`IntoLua`] and [`FromLua`] traits allow conversion from Rust types to Lua values and vice
14//! versa. They are implemented for many data structures found in Rust's standard library.
15//!
16//! For more general conversions, the [`IntoLuaMulti`] and [`FromLuaMulti`] traits allow converting
17//! between Rust types and *any number* of Lua values.
18//!
19//! Most code in `mlua` is generic over implementors of those traits, so in most places the normal
20//! Rust data structures are accepted without having to write any boilerplate.
21//!
22//! # Custom Userdata
23//!
24//! The [`UserData`] trait can be implemented by user-defined types to make them available to Lua.
25//! Methods and operators to be used from Lua can be added using the [`UserDataMethods`] API.
26//! Fields are supported using the [`UserDataFields`] API.
27//!
28//! # Serde support
29//!
30//! The [`LuaSerdeExt`] trait implemented for [`Lua`] allows conversion from Rust types to Lua
31//! values and vice versa using serde. Any user defined data type that implements
32//! [`serde::Serialize`] or [`serde::Deserialize`] can be converted.
33//! For convenience, additional functionality to handle `NULL` values and arrays is provided.
34//!
35//! The [`Value`] enum and other types implement [`serde::Serialize`] trait to support serializing
36//! Lua values into Rust values.
37//!
38//! Requires `feature = "serde"`.
39//!
40//! # Async/await support
41//!
42//! The [`Lua::create_async_function`] allows creating non-blocking functions that returns
43//! [`Future`]. Lua code with async capabilities can be executed by [`Function::call_async`] family
44//! of functions or polling [`AsyncThread`] using any runtime (eg. Tokio).
45//!
46//! Requires `feature = "async"`.
47//!
48//! # `Send` and `Sync` support
49//!
50//! By default `mlua` is `!Send`. This can be changed by enabling `feature = "send"` that adds a
51//! `Send` requirement to Rust functions and a `Send + Sync` requirement to [`UserData`] types.
52//! A `Send`-only userdata types must therefore be wrapped (e.g. in a `Mutex`) or created through a
53//! [`Scope`] to be used with the `send` feature.
54//!
55//! In this case [`Lua`] object and their types can be send or used from other threads. Internally
56//! access to Lua VM is synchronized using a reentrant mutex that can be locked many times within
57//! the same thread.
58//!
59//! [Lua programming language]: https://www.lua.org/
60//! [executing]: crate::chunk::Chunk::exec
61//! [evaluating]: crate::chunk::Chunk::eval
62//! [globals]: crate::Lua::globals
63//! [`Future`]: std::future::Future
64//! [`serde::Serialize`]: https://docs.serde.rs/serde/ser/trait.Serialize.html
65//! [`serde::Deserialize`]: https://docs.serde.rs/serde/de/trait.Deserialize.html
66//! [`AsyncThread`]: crate::thread::AsyncThread
67
68// Deny warnings inside doc tests / examples. When this isn't present, rustdoc doesn't show *any*
69// warnings at all.
70#![cfg_attr(docsrs, feature(doc_cfg))]
71#![cfg_attr(not(feature = "send"), allow(clippy::arc_with_non_send_sync))]
72#![allow(unsafe_op_in_unsafe_fn)]
73
74#[macro_use]
75mod macros;
76
77mod buffer;
78mod conversion;
79mod memory;
80mod multi;
81mod scope;
82mod stdlib;
83mod traits;
84mod types;
85mod util;
86mod value;
87mod vector;
88
89pub mod chunk;
90pub mod debug;
91pub mod error;
92pub mod function;
93#[cfg(any(feature = "luau", doc))]
94#[cfg_attr(docsrs, doc(cfg(feature = "luau")))]
95pub mod luau;
96pub mod prelude;
97pub mod state;
98pub mod string;
99pub mod table;
100pub mod thread;
101pub mod userdata;
102
103pub use bstr::BString;
104pub use ffi::{self, lua_CFunction, lua_State};
105#[cfg(feature = "macros")]
106#[doc(hidden)]
107pub use inventory as __inventory;
108
109#[doc(inline)]
110pub use crate::error::{Error, Result};
111pub use crate::error::{ErrorContext, ExternalError, ExternalResult};
112#[doc(inline)]
113pub use crate::function::Function;
114pub use crate::multi::{MultiValue, Variadic};
115pub use crate::scope::Scope;
116#[doc(inline)]
117pub use crate::state::{Lua, LuaOptions, WeakLua};
118pub use crate::stdlib::StdLib;
119#[doc(inline)]
120pub use crate::string::LuaString;
121pub use crate::string::{BorrowedBytes, BorrowedStr};
122#[doc(inline)]
123pub use crate::table::Table;
124#[doc(inline)]
125pub use crate::thread::Thread;
126#[doc(inline)]
127pub use crate::traits::{FromLua, FromLuaMulti, IntoLua, IntoLuaMulti, ObjectLike};
128pub use crate::types::{
129    AppDataRef, AppDataRefMut, Either, Integer, LightUserData, MaybeSend, MaybeSync, Number, RegistryKey,
130    VmState,
131};
132#[doc(inline)]
133pub use crate::userdata::{AnyUserData, UserData};
134pub use crate::userdata::{
135    MetaMethod, UserDataFields, UserDataMethods, UserDataOwned, UserDataRef, UserDataRefMut, UserDataRegistry,
136};
137pub use crate::value::{Nil, Value};
138
139/// Deprecated alias to [`LuaString`].
140#[deprecated(since = "0.12.0", note = "use `mlua::LuaString` instead")]
141#[doc(hidden)]
142pub type String = crate::string::LuaString;
143
144#[cfg(not(feature = "luau"))]
145pub use crate::debug::HookTriggers;
146
147#[cfg(any(feature = "luau", doc))]
148#[cfg_attr(docsrs, doc(cfg(feature = "luau")))]
149pub use crate::{buffer::Buffer, vector::Vector};
150
151#[cfg(feature = "serde")]
152#[doc(inline)]
153pub use crate::{serde::LuaSerdeExt, value::SerializableValue};
154
155#[cfg(feature = "serde")]
156#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
157pub mod serde;
158
159#[cfg(feature = "mlua_derive")]
160#[allow(unused_imports)]
161#[macro_use]
162extern crate mlua_derive;
163
164#[doc = include_str!("../docs/chunk.md")]
165#[cfg(feature = "macros")]
166#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
167pub use mlua_derive::chunk;
168
169/// Derive [`FromLua`] for a Rust type.
170///
171/// Current implementation generate code that takes [`UserData`] value, borrow it (of the Rust type)
172/// and clone.
173#[cfg(feature = "macros")]
174#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
175pub use mlua_derive::FromLua;
176
177#[doc = include_str!("../docs/UserData.md")]
178#[cfg(feature = "macros")]
179#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
180pub use mlua_derive::UserData;
181
182/// Registers items in an `impl` block as methods/fields of a [`UserData`](trait@UserData) type.
183///
184/// See the [`UserData`](derive@UserData) derive macro documentation for usage details.
185#[cfg(feature = "macros")]
186#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
187pub use mlua_derive::userdata_impl;
188
189#[doc = include_str!("../docs/lua_module.md")]
190#[cfg(all(feature = "mlua_derive", any(feature = "module", doc)))]
191#[cfg_attr(docsrs, doc(cfg(feature = "module")))]
192pub use mlua_derive::lua_module;
193
194#[cfg(all(feature = "module", feature = "send"))]
195compile_error!("`send` feature is not supported in module mode");
196
197pub(crate) mod private {
198    use super::*;
199
200    pub trait Sealed {}
201
202    impl Sealed for Error {}
203    impl<T> Sealed for std::result::Result<T, Error> {}
204    impl Sealed for Lua {}
205    impl Sealed for Table {}
206    impl Sealed for AnyUserData {}
207}
mlua/lib.rs

mlua/
lib.rs
