summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--src/ffi.rs2
-rw-r--r--src/lib.rs41
-rw-r--r--src/lua.rs12
-rw-r--r--src/multi.rs37
-rw-r--r--src/prelude.rs2
5 files changed, 86 insertions, 8 deletions
diff --git a/src/ffi.rs b/src/ffi.rs
index b155a2a..a944afe 100644
--- a/src/ffi.rs
+++ b/src/ffi.rs
@@ -1,3 +1,5 @@
+//! Bindings to the Lua 5.3 C API.
+
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
diff --git a/src/lib.rs b/src/lib.rs
index d2d7de2..1c4097e 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -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;
diff --git a/src/lua.rs b/src/lua.rs
index b0a2dda..9008b97 100644
--- a/src/lua.rs
+++ b/src/lua.rs
@@ -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,