Merge pull request #43 from jonas-schievink/dire-dire-docs
More documentation work
This commit is contained in:
commit
121bac8394
|
@ -1,3 +1,5 @@
|
|||
//! Bindings to the Lua 5.3 C API.
|
||||
|
||||
#![allow(non_camel_case_types)]
|
||||
#![allow(non_snake_case)]
|
||||
|
||||
|
|
41
src/lib.rs
41
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;
|
||||
|
|
12
src/lua.rs
12
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.
|
||||
|
|
37
src/multi.rs
37
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())
|
||||
}
|
||||
|
|
|
@ -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,
|
||||
|
|
Loading…
Reference in New Issue