Refactor crate-root re-exports and drop hidden backward-compat aliases

khvzak · khvzak · commit cddbcc5e7ba7 · 2026-07-05T18:36:19.000+01:00
diff --git a/examples/async_http_server.rs b/examples/async_http_server.rs
@@ -11,7 +11,7 @@ use hyper::{Request, Response};
 use hyper_util::rt::TokioIo;
 use tokio::net::TcpListener;
 
-use mlua::{Error as LuaError, Function, Lua, String as LuaString, Table, UserData, UserDataMethods, chunk};
+use mlua::{Error as LuaError, Function, Lua, LuaString, Table, UserData, UserDataMethods, chunk};
 
 /// Wrapper around incoming request that implements UserData
 struct LuaRequest(SocketAddr, Request<Incoming>);
diff --git a/mlua_derive/src/chunk/mod.rs b/mlua_derive/src/chunk/mod.rs
@@ -109,7 +109,8 @@ impl Chunk {
         });
 
         quote! {{
-            use mlua::{AsChunk, ChunkMode, Lua, Result, Table};
+            use mlua::chunk::{AsChunk, ChunkMode};
+            use mlua::{Lua, Result, Table};
             use ::std::borrow::Cow;
             use ::std::cell::Cell;
             use ::std::io::Result as IoResult;
diff --git a/src/lib.rs b/src/lib.rs
@@ -57,8 +57,8 @@
 //! the same thread.
 //!
 //! [Lua programming language]: https://www.lua.org/
-//! [executing]: crate::Chunk::exec
-//! [evaluating]: crate::Chunk::eval
+//! [executing]: crate::chunk::Chunk::exec
+//! [evaluating]: crate::chunk::Chunk::eval
 //! [globals]: crate::Lua::globals
 //! [`Future`]: std::future::Future
 //! [`serde::Serialize`]: https://docs.serde.rs/serde/ser/trait.Serialize.html
@@ -108,6 +108,7 @@ pub use inventory as __inventory;
 
 #[doc(inline)]
 pub use crate::error::{Error, Result};
+pub use crate::error::{ErrorContext, ExternalError, ExternalResult};
 #[doc(inline)]
 pub use crate::function::Function;
 pub use crate::multi::{MultiValue, Variadic};
@@ -116,7 +117,8 @@ pub use crate::scope::Scope;
 pub use crate::state::{Lua, LuaOptions, WeakLua};
 pub use crate::stdlib::StdLib;
 #[doc(inline)]
-pub use crate::string::{BorrowedBytes, BorrowedStr, LuaString};
+pub use crate::string::LuaString;
+pub use crate::string::{BorrowedBytes, BorrowedStr};
 #[doc(inline)]
 pub use crate::table::Table;
 #[doc(inline)]
@@ -128,43 +130,24 @@ pub use crate::types::{
     VmState,
 };
 #[doc(inline)]
-pub use crate::userdata::AnyUserData;
+pub use crate::userdata::{AnyUserData, UserData};
+pub use crate::userdata::{
+    MetaMethod, UserDataFields, UserDataMethods, UserDataOwned, UserDataRef, UserDataRefMut, UserDataRegistry,
+};
 pub use crate::value::{Nil, Value};
 
-// Re-export some types to keep backward compatibility and avoid breaking changes in the public API.
-#[doc(hidden)]
-pub use crate::chunk::{AsChunk, Chunk, ChunkMode};
-#[cfg(feature = "luau")]
-#[doc(hidden)]
-pub use crate::chunk::{CompileConstant, Compiler};
-#[doc(hidden)]
-pub use crate::error::{ErrorContext, ExternalError, ExternalResult};
-#[doc(hidden)]
-pub use crate::string::LuaString as String;
-#[doc(hidden)]
-pub use crate::table::{TablePairs, TableSequence};
+/// Deprecated alias to [`LuaString`].
+#[deprecated(since = "0.12.0", note = "use `mlua::LuaString` instead")]
 #[doc(hidden)]
-pub use crate::thread::{ThreadEvent, ThreadStatus, ThreadTriggers};
-#[doc(hidden)]
-pub use crate::userdata::{
-    MetaMethod, UserData, UserDataFields, UserDataMetatable, UserDataMethods, UserDataOwned, UserDataRef,
-    UserDataRefMut, UserDataRegistry,
-};
+pub type String = crate::string::LuaString;
 
 #[cfg(not(feature = "luau"))]
-#[doc(inline)]
 pub use crate::debug::HookTriggers;
 
-#[cfg(any(feature = "luau-jit", doc))]
-#[doc(inline)]
-pub use crate::state::JitOptions;
 #[cfg(any(feature = "luau", doc))]
 #[cfg_attr(docsrs, doc(cfg(feature = "luau")))]
 pub use crate::{buffer::Buffer, vector::Vector};
 
-#[cfg(feature = "serde")]
-#[doc(hidden)]
-pub use crate::serde::{DeserializeOptions, SerializeOptions};
 #[cfg(feature = "serde")]
 #[doc(inline)]
 pub use crate::{serde::LuaSerdeExt, value::SerializableValue};
@@ -196,7 +179,9 @@ pub use mlua_derive::FromLua;
 #[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
 pub use mlua_derive::UserData;
 
-#[doc(hidden)]
+/// Registers items in an `impl` block as methods/fields of a [`UserData`](trait@UserData) type.
+///
+/// See the [`UserData`](derive@UserData) derive macro documentation for usage details.
 #[cfg(feature = "macros")]
 #[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
 pub use mlua_derive::userdata_impl;
diff --git a/src/prelude.rs b/src/prelude.rs
@@ -3,25 +3,26 @@
 #[doc(no_inline)]
 pub use crate::{
     AnyUserData as LuaAnyUserData, BorrowedBytes as LuaBorrowedBytes, BorrowedStr as LuaBorrowedStr,
-    Either as LuaEither, Error as LuaError, FromLua, FromLuaMulti, Function as LuaFunction,
-    Integer as LuaInteger, IntoLua, IntoLuaMulti, LightUserData as LuaLightUserData, Lua, LuaOptions,
-    LuaString, MetaMethod as LuaMetaMethod, MultiValue as LuaMultiValue, Nil as LuaNil, Number as LuaNumber,
-    ObjectLike as LuaObjectLike, RegistryKey as LuaRegistryKey, Result as LuaResult, StdLib as LuaStdLib,
-    Table as LuaTable, Thread as LuaThread, UserData as LuaUserData, UserDataFields as LuaUserDataFields,
-    UserDataMetatable as LuaUserDataMetatable, UserDataMethods as LuaUserDataMethods,
+    Either as LuaEither, Error as LuaError, ErrorContext as LuaErrorContext,
+    ExternalError as LuaExternalError, ExternalResult as LuaExternalResult, FromLua, FromLuaMulti,
+    Function as LuaFunction, Integer as LuaInteger, IntoLua, IntoLuaMulti, LightUserData as LuaLightUserData,
+    Lua, LuaOptions, LuaString, MetaMethod as LuaMetaMethod, MultiValue as LuaMultiValue, Nil as LuaNil,
+    Number as LuaNumber, ObjectLike as LuaObjectLike, RegistryKey as LuaRegistryKey, Result as LuaResult,
+    StdLib as LuaStdLib, Table as LuaTable, Thread as LuaThread, UserData as LuaUserData,
+    UserDataFields as LuaUserDataFields, UserDataMethods as LuaUserDataMethods,
     UserDataOwned as LuaUserDataOwned, UserDataRef as LuaUserDataRef, UserDataRefMut as LuaUserDataRefMut,
     UserDataRegistry as LuaUserDataRegistry, Value as LuaValue, Variadic as LuaVariadic,
     VmState as LuaVmState, WeakLua, chunk::AsChunk as AsLuaChunk, chunk::Chunk as LuaChunk,
-    chunk::ChunkMode as LuaChunkMode, error::ErrorContext as LuaErrorContext,
-    error::ExternalError as LuaExternalError, error::ExternalResult as LuaExternalResult,
-    function::FunctionInfo as LuaFunctionInfo, function::LuaNativeFn, function::LuaNativeFnMut,
-    state::GcIncParams as LuaGcIncParams, state::GcMode as LuaGcMode, table::TablePairs as LuaTablePairs,
-    table::TableSequence as LuaTableSequence, thread::ThreadStatus as LuaThreadStatus,
+    chunk::ChunkMode as LuaChunkMode, function::FunctionInfo as LuaFunctionInfo, function::LuaNativeFn,
+    function::LuaNativeFnMut, state::GcIncParams as LuaGcIncParams, state::GcMode as LuaGcMode,
+    table::TablePairs as LuaTablePairs, table::TableSequence as LuaTableSequence,
+    thread::ThreadEvent as LuaThreadEvent, thread::ThreadStatus as LuaThreadStatus,
+    thread::ThreadTriggers as LuaThreadTriggers, userdata::UserDataMetatable as LuaUserDataMetatable,
 };
 
 #[cfg(not(feature = "luau"))]
 #[doc(no_inline)]
-pub use crate::HookTriggers as LuaHookTriggers;
+pub use crate::debug::HookTriggers as LuaHookTriggers;
 
 #[cfg(any(feature = "lua54", feature = "lua55"))]
 #[doc(no_inline)]
@@ -50,6 +51,6 @@ pub use crate::{function::LuaNativeAsyncFn, thread::AsyncThread as LuaAsyncThrea
 #[cfg(feature = "serde")]
 #[doc(no_inline)]
 pub use crate::{
-    DeserializeOptions as LuaDeserializeOptions, LuaSerdeExt, SerializableValue as LuaSerializableValue,
-    SerializeOptions as LuaSerializeOptions,
+    LuaSerdeExt, SerializableValue as LuaSerializableValue,
+    serde::DeserializeOptions as LuaDeserializeOptions, serde::SerializeOptions as LuaSerializeOptions,
 };
diff --git a/src/serde/mod.rs b/src/serde/mod.rs
@@ -101,7 +101,8 @@ pub trait LuaSerdeExt: Sealed {
     /// # Example
     ///
     /// ```
-    /// use mlua::{Lua, Result, LuaSerdeExt, SerializeOptions};
+    /// use mlua::serde::SerializeOptions;
+    /// use mlua::{Lua, Result, LuaSerdeExt};
     ///
     /// fn main() -> Result<()> {
     ///     let lua = Lua::new();
@@ -151,7 +152,8 @@ pub trait LuaSerdeExt: Sealed {
     /// # Example
     ///
     /// ```
-    /// use mlua::{Lua, Result, LuaSerdeExt, DeserializeOptions};
+    /// use mlua::serde::DeserializeOptions;
+    /// use mlua::{Lua, Result, LuaSerdeExt};
     /// use serde::Deserialize;
     ///
     /// #[derive(Deserialize, Debug, PartialEq)]
diff --git a/src/state.rs b/src/state.rs
@@ -804,7 +804,8 @@ impl Lua {
     ///
     /// ```
     /// # use std::sync::{Arc, atomic::{AtomicU64, Ordering}};
-    /// # use mlua::{Lua, Result, ThreadStatus, VmState};
+    /// # use mlua::thread::ThreadStatus;
+    /// # use mlua::{Lua, Result, VmState};
     /// # #[cfg(feature = "luau")]
     /// # fn main() -> Result<()> {
     /// let lua = Lua::new();
@@ -899,7 +900,8 @@ impl Lua {
     /// Subscribe only to yield events:
     ///
     /// ```
-    /// # use mlua::{Lua, Result, ThreadTriggers, ThreadEvent};
+    /// # use mlua::thread::{ThreadTriggers, ThreadEvent};
+    /// # use mlua::{Lua, Result};
     /// # fn main() -> Result<()> {
     /// let lua = Lua::new();
     /// lua.set_thread_event_callback(
@@ -1342,7 +1344,7 @@ impl Lua {
     /// similar on the returned builder. Code is not even parsed until one of these methods is
     /// called.
     ///
-    /// [`Chunk::exec`]: crate::Chunk::exec
+    /// [`Chunk::exec`]: crate::chunk::Chunk::exec
     #[track_caller]
     pub fn load<'a>(&self, chunk: impl AsChunk + 'a) -> Chunk<'a> {
         self.load_with_location(chunk, Location::caller())
diff --git a/tests/chunk.rs b/tests/chunk.rs
@@ -1,7 +1,8 @@
 #[cfg(not(target_os = "wasi"))]
 use std::{fs, io};
 
-use mlua::{Chunk, ChunkMode, Lua, Result};
+use mlua::chunk::{Chunk, ChunkMode};
+use mlua::{Lua, Result};
 
 #[test]
 fn test_chunk_methods() -> Result<()> {
@@ -131,7 +132,7 @@ fn test_chunk_macro() -> Result<()> {
 #[cfg(feature = "luau")]
 #[test]
 fn test_compiler() -> Result<()> {
-    let compiler = mlua::Compiler::new()
+    let compiler = mlua::chunk::Compiler::new()
         .set_optimization_level(2)
         .set_debug_level(2)
         .set_type_info_level(1)
@@ -158,7 +159,8 @@ fn test_compiler() -> Result<()> {
 #[cfg(feature = "luau")]
 #[test]
 fn test_compiler_library_constants() {
-    use mlua::{Compiler, Vector};
+    use mlua::Vector;
+    use mlua::chunk::Compiler;
 
     let compiler = Compiler::new()
         .set_optimization_level(2)
diff --git a/tests/function.rs b/tests/function.rs
@@ -239,7 +239,7 @@ fn test_function_dump() -> Result<()> {
 fn test_function_coverage() -> Result<()> {
     let lua = Lua::new();
 
-    lua.set_compiler(mlua::Compiler::default().set_coverage_level(1));
+    lua.set_compiler(mlua::chunk::Compiler::default().set_coverage_level(1));
 
     let f = lua
         .load(
diff --git a/tests/luau.rs b/tests/luau.rs
@@ -4,9 +4,8 @@ use std::fmt::Debug;
 use std::sync::Arc;
 use std::sync::atomic::{AtomicU64, Ordering};
 
-use mlua::{
-    Compiler, Error, Function, Lua, LuaOptions, ObjectLike, Result, StdLib, Table, Value, Vector, VmState,
-};
+use mlua::chunk::Compiler;
+use mlua::{Error, Function, Lua, LuaOptions, ObjectLike, Result, StdLib, Table, Value, Vector, VmState};
 
 #[test]
 fn test_version() -> Result<()> {
@@ -362,7 +361,7 @@ fn test_fflags() {
 #[test]
 fn test_jit_inliner() -> Result<()> {
     let lua = Lua::new();
-    lua.set_jit_options(mlua::JitOptions::new().inliner(true));
+    lua.set_jit_options(mlua::state::JitOptions::new().inliner(true));
 
     // An inlinable helper called in a hot loop.
     let sum = lua
diff --git a/tests/memory.rs b/tests/memory.rs
@@ -148,7 +148,7 @@ fn test_gc_set_mode_in_finalizer() -> Result<()> {
     })?;
     lua.globals().set("finalizer", finalizer)?;
     lua.load("setmetatable({}, { __gc = finalizer })").exec()?;
-    lua.globals().remove("finalizer")?;
+    lua.globals().raw_remove("finalizer")?;
 
     lua.gc_collect()?;
     lua.gc_collect()?;
diff --git a/tests/serde.rs b/tests/serde.rs
@@ -4,9 +4,9 @@ use std::collections::HashMap;
 use std::error::Error as StdError;
 
 use bstr::BString;
+use mlua::serde::{DeserializeOptions, SerializeOptions};
 use mlua::{
-    AnyUserData, DeserializeOptions, Error, ExternalResult, IntoLua, Lua, LuaSerdeExt, Result as LuaResult,
-    SerializeOptions, UserData, Value,
+    AnyUserData, Error, ExternalResult, IntoLua, Lua, LuaSerdeExt, Result as LuaResult, UserData, Value,
 };
 use serde::{Deserialize, Serialize};
 
diff --git a/tests/tests.rs b/tests/tests.rs
@@ -5,9 +5,10 @@ use std::panic::{AssertUnwindSafe, catch_unwind};
 use std::sync::Arc;
 use std::{error, f32, f64, fmt};
 
+use mlua::chunk::ChunkMode;
 use mlua::{
-    ChunkMode, Error, ExternalError, Function, Lua, LuaOptions, Nil, Result, StdLib, Table, UserData, Value,
-    Variadic, ffi,
+    Error, ExternalError, Function, Lua, LuaOptions, Nil, Result, StdLib, Table, UserData, Value, Variadic,
+    ffi,
 };
 
 #[test]
@@ -187,7 +188,7 @@ fn test_load_mode() -> Result<()> {
     #[cfg(not(feature = "luau"))]
     let bytecode = lua.load("return 1 + 1").into_function()?.dump(true);
     #[cfg(feature = "luau")]
-    let bytecode = mlua::Compiler::new().compile("return 1 + 1")?;
+    let bytecode = mlua::chunk::Compiler::new().compile("return 1 + 1")?;
     assert_eq!(lua.load(&bytecode).eval::<i32>()?, 2);
     assert_eq!(lua.load(&bytecode).set_mode(ChunkMode::Binary).eval::<i32>()?, 2);
     match lua.load(&bytecode).set_mode(ChunkMode::Text).exec() {
diff --git a/tests/thread.rs b/tests/thread.rs
@@ -2,7 +2,8 @@ use std::panic::catch_unwind;
 use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
 
-use mlua::{Error, Function, IntoLua, Lua, Result, Thread, ThreadEvent, ThreadStatus, ThreadTriggers, Value};
+use mlua::thread::{ThreadEvent, ThreadStatus, ThreadTriggers};
+use mlua::{Error, Function, IntoLua, Lua, Result, Thread, Value};
 
 #[test]
 fn test_thread() -> Result<()> {
