Make table module public

Author: khvzak

src/lib.rs

@@ -84,7 +84,6 @@ mod scope;
 mod state;
 mod stdlib;
 mod string;
-mod table;
 mod thread;
 mod traits;
 mod types;
@@ -95,6 +94,7 @@ mod vector;
 
 pub mod function;
 pub mod prelude;
+pub mod table;
 
 pub use bstr::BString;
 pub use ffi::{self, lua_CFunction, lua_State};
@@ -108,7 +108,7 @@ pub use crate::scope::Scope;
 pub use crate::state::{GCMode, Lua, LuaOptions, WeakLua};
 pub use crate::stdlib::StdLib;
 pub use crate::string::{BorrowedBytes, BorrowedStr, LuaString, LuaString as String};
-pub use crate::table::{Table, TablePairs, TableSequence};
+pub use crate::table::Table;
 pub use crate::thread::{Thread, ThreadStatus};
 pub use crate::traits::{
     FromLua, FromLuaMulti, IntoLua, IntoLuaMulti, LuaNativeFn, LuaNativeFnMut, ObjectLike,

src/prelude.rs

@@ -9,12 +9,12 @@ pub use crate::{
     LightUserData as LuaLightUserData, Lua, LuaNativeFn, LuaNativeFnMut, 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, TablePairs as LuaTablePairs, TableSequence as LuaTableSequence, Thread as LuaThread,
-    ThreadStatus as LuaThreadStatus, UserData as LuaUserData, UserDataFields as LuaUserDataFields,
-    UserDataMetatable as LuaUserDataMetatable, UserDataMethods as LuaUserDataMethods,
-    UserDataRef as LuaUserDataRef, UserDataRefMut as LuaUserDataRefMut,
-    UserDataRegistry as LuaUserDataRegistry, Value as LuaValue, Variadic as LuaVariadic,
-    VmState as LuaVmState, WeakLua, function::FunctionInfo as LuaFunctionInfo,
+    Table as LuaTable, Thread as LuaThread, ThreadStatus as LuaThreadStatus, UserData as LuaUserData,
+    UserDataFields as LuaUserDataFields, UserDataMetatable as LuaUserDataMetatable,
+    UserDataMethods as LuaUserDataMethods, UserDataRef as LuaUserDataRef,
+    UserDataRefMut as LuaUserDataRefMut, UserDataRegistry as LuaUserDataRegistry, Value as LuaValue,
+    Variadic as LuaVariadic, VmState as LuaVmState, WeakLua, function::FunctionInfo as LuaFunctionInfo,
+    table::TablePairs as LuaTablePairs, table::TableSequence as LuaTableSequence,
 };
 
 #[cfg(not(feature = "luau"))]

src/table.rs

@@ -1,3 +1,162 @@
+//! Lua table handling.
+//!
+//! Tables are Lua's primary data structure, used for arrays, dictionaries, objects, modules,
+//! and more. This module provides types for creating and manipulating Lua tables from Rust.
+//!
+//! # Main Types
+//!
+//! - [`Table`] - A handle to a Lua table.
+//! - [`TablePairs`] - An iterator over key-value pairs in a table.
+//! - [`TableSequence`] - An iterator over the array (sequence) portion of a table.
+//!
+//! # Basic Operations
+//!
+//! Tables support key-value access similar to Rust's `HashMap`:
+//!
+//! ```
+//! # use mlua::{Lua, Result};
+//! # fn main() -> Result<()> {
+//! let lua = Lua::new();
+//! let table = lua.create_table()?;
+//!
+//! // Set and get values
+//! table.set("key", "value")?;
+//! let value: String = table.get("key")?;
+//! assert_eq!(value, "value");
+//!
+//! // Keys and values can be any Lua-compatible type
+//! table.set(1, "first")?;
+//! table.set("nested", lua.create_table()?)?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! # Array Operations
+//!
+//! Tables can be used as arrays with 1-based indexing:
+//!
+//! ```
+//! # use mlua::{Lua, Result};
+//! # fn main() -> Result<()> {
+//! let lua = Lua::new();
+//! let array = lua.create_table()?;
+//!
+//! // Push values to the end (like Vec::push)
+//! array.push("first")?;
+//! array.push("second")?;
+//! array.push("third")?;
+//!
+//! // Pop from the end
+//! let last: String = array.pop()?;
+//! assert_eq!(last, "third");
+//!
+//! // Get length
+//! assert_eq!(array.raw_len(), 2);
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! # Iteration
+//!
+//! Iterate over all key-value pairs with [`Table::pairs`]:
+//!
+//! ```
+//! # use mlua::{Lua, Result, Value};
+//! # fn main() -> Result<()> {
+//! let lua = Lua::new();
+//! let table = lua.create_table()?;
+//! table.set("a", 1)?;
+//! table.set("b", 2)?;
+//!
+//! for pair in table.pairs::<String, i32>() {
+//!     let (key, value) = pair?;
+//!     println!("{key} = {value}");
+//! }
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! For array portions, use [`Table::sequence_values`]:
+//!
+//! ```
+//! # use mlua::{Lua, Result};
+//! # fn main() -> Result<()> {
+//! let lua = Lua::new();
+//! let array = lua.create_sequence_from(["a", "b", "c"])?;
+//!
+//! for value in array.sequence_values::<String>() {
+//!     println!("{}", value?);
+//! }
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! # Raw vs Normal Access
+//!
+//! Methods prefixed with `raw_` (like [`Table::raw_get`], [`Table::raw_set`]) bypass
+//! metamethods, directly accessing the table's contents. Normal methods may trigger
+//! `__index`, `__newindex`, and other metamethods:
+//!
+//! ```
+//! # use mlua::{Lua, Result};
+//! # fn main() -> Result<()> {
+//! let lua = Lua::new();
+//!
+//! // raw_set bypasses __newindex metamethod
+//! let t = lua.create_table()?;
+//! t.raw_set("key", "value")?;
+//!
+//! // raw_get bypasses __index metamethod
+//! let v: String = t.raw_get("key")?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! # Metatables
+//!
+//! Tables can have metatables that customize their behavior:
+//!
+//! ```
+//! # use mlua::{Lua, Result};
+//! # fn main() -> Result<()> {
+//! let lua = Lua::new();
+//!
+//! let table = lua.create_table()?;
+//! let metatable = lua.create_table()?;
+//!
+//! // Set a default value via __index
+//! metatable.set("__index", lua.create_function(|_, _: ()| Ok("default"))?)?;
+//! table.set_metatable(Some(metatable))?;
+//!
+//! // Accessing missing keys returns "default"
+//! let value: String = table.get("missing")?;
+//! assert_eq!(value, "default");
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! # Global Table
+//!
+//! The Lua global environment is itself a table, accessible via [`Lua::globals`]:
+//!
+//! ```
+//! # use mlua::{Lua, Result};
+//! # fn main() -> Result<()> {
+//! let lua = Lua::new();
+//! let globals = lua.globals();
+//!
+//! // Set a global variable
+//! globals.set("my_var", 42)?;
+//!
+//! // Now accessible from Lua code
+//! let result: i32 = lua.load("my_var + 8").eval()?;
+//! assert_eq!(result, 50);
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! [`Lua::globals`]: crate::Lua::globals
+
 use std::collections::HashSet;
 use std::fmt;
 use std::marker::PhantomData;