diff options
| -rw-r--r-- | src/ffi.rs | 2 | ||||
| -rw-r--r-- | src/lib.rs | 41 | ||||
| -rw-r--r-- | src/lua.rs | 12 | ||||
| -rw-r--r-- | src/multi.rs | 37 | ||||
| -rw-r--r-- | src/prelude.rs | 2 |
5 files changed, 86 insertions, 8 deletions
@@ -1,3 +1,5 @@ +//! Bindings to the Lua 5.3 C API. + #![allow(non_camel_case_types)] #![allow(non_snake_case)] @@ -1,4 +1,43 @@ -// Deny warnings inside doc tests / examples +//! # High-level bindings to Lua +//! +//! The `rlua` crate provides safe high-level bindings to the [Lua programming language]. +//! +//! # The `Lua` object +//! +//! The main type exported by this library is the [`Lua`] struct. In addition to methods for +//! [executing] Lua chunks or [evaluating] Lua expressions, it provides methods for creating Lua +//! values and accessing the table of [globals]. +//! +//! # Converting data +//! +//! The [`ToLua`] and [`FromLua`] traits allow conversion from Rust types to Lua values and vice +//! versa. They are implemented for many data structures found in Rust's standard library. +//! +//! For more general conversions, the [`ToLuaMulti`] and [`FromLuaMulti`] traits allow converting +//! between Rust types and *any number* of Lua values. +//! +//! Most code in `rlua` is generic over implementors of those traits, so in most places the normal +//! Rust data structures are accepted without having to write any boilerplate. +//! +//! # Custom Userdata +//! +//! The [`UserData`] trait can be implemented by user-defined types to make them available to Lua. +//! Methods and operators to be used from Lua can be added using the [`UserDataMethods`] API. +//! +//! [Lua programming language]: https://www.lua.org/ +//! [`Lua`]: struct.Lua.html +//! [executing]: struct.Lua.html#method.exec +//! [evaluating]: struct.Lua.html#method.eval +//! [globals]: struct.Lua.html#method.globals +//! [`ToLua`]: trait.ToLua.html +//! [`FromLua`]: trait.FromLua.html +//! [`ToLuaMulti`]: trait.ToLuaMulti.html +//! [`FromLuaMulti`]: trait.FromLuaMulti.html +//! [`UserData`]: trait.UserData.html +//! [`UserDataMethods`]: struct.UserDataMethods.html + +// Deny warnings inside doc tests / examples. When this isn't present, rustdoc doesn't show *any* +// warnings at all. #![doc(test(attr(deny(warnings))))] extern crate libc; @@ -85,6 +85,7 @@ pub trait FromLua<'lua>: Sized { pub struct MultiValue<'lua>(VecDeque<Value<'lua>>); impl<'lua> MultiValue<'lua> { + /// Creates an empty `MultiValue` containing no values. pub fn new() -> MultiValue<'lua> { MultiValue(VecDeque::new()) } @@ -436,6 +437,9 @@ impl<'lua> Table<'lua> { } } + /// Returns a reference to the metatable of this table, or `None` if no metatable is set. + /// + /// Unlike the `getmetatable` Lua function, this method ignores the `__metatable` field. pub fn get_metatable(&self) -> Option<Table<'lua>> { let lua = self.0.lua; unsafe { @@ -454,6 +458,10 @@ impl<'lua> Table<'lua> { } } + /// Sets or removes the metatable of this table. + /// + /// If `metatable` is `None`, the metatable is removed (if no metatable is set, this does + /// nothing). pub fn set_metatable(&self, metatable: Option<Table<'lua>>) { let lua = self.0.lua; unsafe { @@ -1177,7 +1185,7 @@ impl<'lua, T: UserData> UserDataMethods<'lua, T> { /// Trait for custom userdata types. /// /// By implementing this trait, a struct becomes eligible for use inside Lua code. Implementations -/// of `ToLua` and `FromLua` are automatically provided. +/// of [`ToLua`] and [`FromLua`] are automatically provided. /// /// # Examples /// @@ -1245,6 +1253,8 @@ impl<'lua, T: UserData> UserDataMethods<'lua, T> { /// # } /// ``` /// +/// [`ToLua`]: trait.ToLua.html +/// [`FromLua`]: trait.FromLua.html /// [`UserDataMethods`]: struct.UserDataMethods.html pub trait UserData: 'static + Sized { /// Adds custom methods and operators specific to this userdata. diff --git a/src/multi.rs b/src/multi.rs index 636239c..17533b3 100644 --- a/src/multi.rs +++ b/src/multi.rs @@ -5,8 +5,8 @@ use std::result::Result as StdResult; use error::*; use lua::*; -/// Result is convertible to `MultiValue` following the common lua idiom of returning the result -/// on success, or in the case of an error, returning nil followed by the error +/// Result is convertible to `MultiValue` following the common Lua idiom of returning the result +/// on success, or in the case of an error, returning `nil` and an error message. impl<'lua, T: ToLua<'lua>, E: ToLua<'lua>> ToLuaMulti<'lua> for StdResult<T, E> { fn to_lua_multi(self, lua: &'lua Lua) -> Result<MultiValue<'lua>> { let mut result = MultiValue::new(); @@ -49,14 +49,39 @@ impl<'lua> FromLuaMulti<'lua> for MultiValue<'lua> { } } -/// Can be used to pass variadic values to or receive variadic values from Lua, where the type of -/// the values is all the same and the number of values is defined at runtime. This can be included -/// in a tuple when converting from a MultiValue, but it must be the final entry, and it will -/// consume the rest of the parameters given. +/// Wraps a variable number of `T`s. +/// +/// Can be used to work with variadic functions more easily. Using this type as the last argument of +/// a Rust callback will accept any number of arguments from Lua and convert them to the type `T` +/// using [`FromLua`]. `Variadic<T>` can also be returned from a callback, returning a variable +/// number of values to Lua. +/// +/// The [`MultiValue`] type is equivalent to `Variadic<Value>`. +/// +/// # Examples +/// +/// ``` +/// # extern crate rlua; +/// # use rlua::{Lua, Variadic, Result}; +/// # fn try_main() -> Result<()> { +/// let lua = Lua::new(); +/// +/// let add = lua.create_function(|_, vals: Variadic<f64>| -> Result<f64> { +/// Ok(vals.iter().sum()) +/// }); +/// lua.globals().set("add", add)?; +/// assert_eq!(lua.eval::<f64>("add(3, 2, 5)", None)?, 10.0); +/// # Ok(()) +/// # } +/// # fn main() { +/// # try_main().unwrap(); +/// # } +/// ``` #[derive(Debug, Clone)] pub struct Variadic<T>(Vec<T>); impl<T> Variadic<T> { + /// Creates an empty `Variadic` wrapper containing no values. pub fn new() -> Variadic<T> { Variadic(Vec::new()) } diff --git a/src/prelude.rs b/src/prelude.rs index 18f80a3..71517a3 100644 --- a/src/prelude.rs +++ b/src/prelude.rs @@ -1,3 +1,5 @@ +//! Re-exports most types with an extra `Lua*` prefix to prevent name clashes. + pub use {Error as LuaError, Result as LuaResult, ExternalError as LuaExternalError, ExternalResult as LuaExternalResult, Value as LuaValue, Nil as LuaNil, ToLua, FromLua, MultiValue as LuaMultiValue, ToLuaMulti, FromLuaMulti, Integer as LuaInteger, |