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
51//! `Send` requirement to Rust functions and [`UserData`] types.
52//!
53//! In this case [`Lua`] object and their types can be send or used from other threads. Internally
54//! access to Lua VM is synchronized using a reentrant mutex that can be locked many times within
55//! the same thread.
56//!
57//! [Lua programming language]: https://www.lua.org/
58//! [executing]: crate::Chunk::exec
59//! [evaluating]: crate::Chunk::eval
60//! [globals]: crate::Lua::globals
61//! [`Future`]: std::future::Future
62//! [`serde::Serialize`]: https://docs.serde.rs/serde/ser/trait.Serialize.html
63//! [`serde::Deserialize`]: https://docs.serde.rs/serde/de/trait.Deserialize.html
64//! [`AsyncThread`]: crate::thread::AsyncThread
65
66// Deny warnings inside doc tests / examples. When this isn't present, rustdoc doesn't show *any*
67// warnings at all.
68#![cfg_attr(docsrs, feature(doc_cfg))]
69#![cfg_attr(not(send), allow(clippy::arc_with_non_send_sync))]
70#![allow(unsafe_op_in_unsafe_fn)]
71
72#[macro_use]
73mod macros;
74
75mod buffer;
76mod conversion;
77mod memory;
78mod multi;
79mod scope;
80mod stdlib;
81mod traits;
82mod types;
83mod util;
84mod value;
85mod vector;
86
87pub mod chunk;
88pub mod debug;
89pub mod error;
90pub mod function;
91#[cfg(any(feature = "luau", doc))]
92#[cfg_attr(docsrs, doc(cfg(feature = "luau")))]
93pub mod luau;
94pub mod prelude;
95pub mod state;
96pub mod string;
97pub mod table;
98pub mod thread;
99pub mod userdata;
100
101pub use bstr::BString;
102pub use ffi::{self, lua_CFunction, lua_State};
103#[cfg(feature = "macros")]
104#[doc(hidden)]
105pub use inventory as __inventory;
106
107#[doc(inline)]
108pub use crate::error::{Error, Result};
109#[doc(inline)]
110pub use crate::function::Function;
111pub use crate::multi::{MultiValue, Variadic};
112pub use crate::scope::Scope;
113#[doc(inline)]
114pub use crate::state::{Lua, LuaOptions, WeakLua};
115pub use crate::stdlib::StdLib;
116#[doc(inline)]
117pub use crate::string::{BorrowedBytes, BorrowedStr, LuaString};
118#[doc(inline)]
119pub use crate::table::Table;
120#[doc(inline)]
121pub use crate::thread::Thread;
122#[doc(inline)]
123pub use crate::traits::{FromLua, FromLuaMulti, IntoLua, IntoLuaMulti, ObjectLike};
124pub use crate::types::{
125    AppDataRef, AppDataRefMut, Either, Integer, LightUserData, MaybeSend, MaybeSync, Number, RegistryKey,
126    VmState,
127};
128#[doc(inline)]
129pub use crate::userdata::AnyUserData;
130pub use crate::value::{Nil, Value};
131
132// Re-export some types to keep backward compatibility and avoid breaking changes in the public API.
133#[doc(hidden)]
134pub use crate::chunk::{AsChunk, Chunk, ChunkMode};
135#[cfg(feature = "luau")]
136#[doc(hidden)]
137pub use crate::chunk::{CompileConstant, Compiler};
138#[doc(hidden)]
139pub use crate::error::{ErrorContext, ExternalError, ExternalResult};
140#[doc(hidden)]
141pub use crate::string::LuaString as String;
142#[doc(hidden)]
143pub use crate::table::{TablePairs, TableSequence};
144#[doc(hidden)]
145pub use crate::thread::{ThreadEvent, ThreadStatus, ThreadTriggers};
146#[doc(hidden)]
147pub use crate::userdata::{
148    MetaMethod, UserData, UserDataFields, UserDataMetatable, UserDataMethods, UserDataOwned, UserDataRef,
149    UserDataRefMut, UserDataRegistry,
150};
151
152#[cfg(not(feature = "luau"))]
153#[doc(inline)]
154pub use crate::debug::HookTriggers;
155
156#[cfg(any(feature = "luau", doc))]
157#[cfg_attr(docsrs, doc(cfg(feature = "luau")))]
158pub use crate::{buffer::Buffer, vector::Vector};
159
160#[cfg(feature = "serde")]
161#[doc(hidden)]
162pub use crate::serde::{DeserializeOptions, SerializeOptions};
163#[cfg(feature = "serde")]
164#[doc(inline)]
165pub use crate::{serde::LuaSerdeExt, value::SerializableValue};
166
167#[cfg(feature = "serde")]
168#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
169pub mod serde;
170
171#[cfg(feature = "mlua_derive")]
172#[allow(unused_imports)]
173#[macro_use]
174extern crate mlua_derive;
175
176#[doc = include_str!("../docs/chunk.md")]
177#[cfg(feature = "macros")]
178#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
179pub use mlua_derive::chunk;
180
181/// Derive [`FromLua`] for a Rust type.
182///
183/// Current implementation generate code that takes [`UserData`] value, borrow it (of the Rust type)
184/// and clone.
185#[cfg(feature = "macros")]
186#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
187pub use mlua_derive::FromLua;
188
189#[doc = include_str!("../docs/UserData.md")]
190#[cfg(feature = "macros")]
191#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
192pub use mlua_derive::UserData;
193
194#[doc(hidden)]
195#[cfg(feature = "macros")]
196#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
197pub use mlua_derive::userdata_impl;
198
199#[doc = include_str!("../docs/lua_module.md")]
200#[cfg(all(feature = "mlua_derive", any(feature = "module", doc)))]
201#[cfg_attr(docsrs, doc(cfg(feature = "module")))]
202pub use mlua_derive::lua_module;
203
204#[cfg(all(feature = "module", feature = "send"))]
205compile_error!("`send` feature is not supported in module mode");
206
207pub(crate) mod private {
208    use super::*;
209
210    pub trait Sealed {}
211
212    impl Sealed for Error {}
213    impl<T> Sealed for std::result::Result<T, Error> {}
214    impl Sealed for Lua {}
215    impl Sealed for Table {}
216    impl Sealed for AnyUserData {}
217}
mlua/lib.rs

mlua/
lib.rs
