From bb662e5a124d4e052b4ea6533a214501117941ef Mon Sep 17 00:00:00 2001 From: Jonas Schievink Date: Wed, 26 Jul 2017 01:53:39 +0200 Subject: [PATCH 1/3] Document the UserData trait --- src/lua.rs | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/src/lua.rs b/src/lua.rs index a7beb0d..e4e296f 100644 --- a/src/lua.rs +++ b/src/lua.rs @@ -1081,6 +1081,82 @@ 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. +/// +/// # Examples +/// +/// ``` +/// # extern crate rlua; +/// # use rlua::{Lua, UserData, Result}; +/// # fn try_main() -> Result<()> { +/// struct MyUserData(i32); +/// +/// impl UserData for MyUserData {} +/// +/// let lua = Lua::new(); +/// +/// // `MyUserData` now implements `ToLua`: +/// lua.globals().set("myobject", MyUserData(123))?; +/// +/// lua.exec::<()>("assert(type(myobject) == 'userdata')", None)?; +/// # Ok(()) +/// # } +/// # fn main() { +/// # try_main().unwrap(); +/// # } +/// ``` +/// +/// Custom methods and operators can be provided by implementing `add_methods` (refer to +/// [`UserDataMethods`] for more information): +/// +/// ``` +/// # #[macro_use] extern crate hlist_macro; +/// # extern crate rlua; +/// # use rlua::{Lua, MetaMethod, UserData, UserDataMethods, Integer, Result}; +/// # fn try_main() -> Result<()> { +/// struct MyUserData(i32); +/// +/// impl UserData for MyUserData { +/// fn add_methods(methods: &mut UserDataMethods) { +/// methods.add_method("get", |lua, this, args| { +/// # let _ = (lua, args); // used +/// lua.pack(this.0) +/// }); +/// +/// methods.add_method_mut("add", |lua, this, args| { +/// let hlist_pat![value]: HList![Integer] = lua.unpack(args)?; +/// +/// this.0 += value as i32; +/// lua.pack(()) +/// }); +/// +/// methods.add_meta_method(MetaMethod::Add, |lua, this, args| { +/// let hlist_pat![value]: HList![Integer] = lua.unpack(args)?; +/// lua.pack(this.0 + value as i32) +/// }); +/// } +/// } +/// +/// let lua = Lua::new(); +/// +/// lua.globals().set("myobject", MyUserData(123))?; +/// +/// lua.exec::<()>(r#" +/// assert(myobject:get() == 123) +/// myobject:add(7) +/// assert(myobject:get() == 130) +/// assert(myobject + 10 == 140) +/// "#, None)?; +/// # Ok(()) +/// # } +/// # fn main() { +/// # try_main().unwrap(); +/// # } +/// ``` +/// +/// [`UserDataMethods`]: struct.UserDataMethods.html pub trait UserData: 'static + Sized { /// Adds custom methods and operators specific to this userdata. fn add_methods(_methods: &mut UserDataMethods) {} From f657d301daa29fd24ef102d8616d23328d44e160 Mon Sep 17 00:00:00 2001 From: Jonas Schievink Date: Wed, 26 Jul 2017 01:54:40 +0200 Subject: [PATCH 2/3] Document Lua::create_function --- src/lua.rs | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/src/lua.rs b/src/lua.rs index e4e296f..f6380d2 100644 --- a/src/lua.rs +++ b/src/lua.rs @@ -1457,6 +1457,51 @@ impl Lua { } /// Wraps a Rust function or closure, creating a callable Lua function handle to it. + /// + /// # Examples + /// + /// Create a function which prints its argument: + /// + /// ``` + /// # extern crate rlua; + /// # use rlua::{Lua, Result}; + /// # fn try_main() -> Result<()> { + /// let lua = Lua::new(); + /// + /// let greet = lua.create_function(|lua, args| { + /// let name: String = lua.unpack(args)?; + /// println!("Hello, {}!", name); + /// lua.pack(()) + /// }); + /// # let _ = greet; // used + /// # Ok(()) + /// # } + /// # fn main() { + /// # try_main().unwrap(); + /// # } + /// ``` + /// + /// Use the `hlist_macro` crate to use multiple arguments: + /// + /// ``` + /// #[macro_use] extern crate hlist_macro; + /// # extern crate rlua; + /// # use rlua::{Lua, Result}; + /// # fn try_main() -> Result<()> { + /// let lua = Lua::new(); + /// + /// let print_person = lua.create_function(|lua, args| { + /// let hlist_pat![name, age]: HList![String, u8] = lua.unpack(args)?; + /// println!("{} is {} years old!", name, age); + /// lua.pack(()) + /// }); + /// # let _ = print_person; // used + /// # Ok(()) + /// # } + /// # fn main() { + /// # try_main().unwrap(); + /// # } + /// ``` pub fn create_function<'lua, F>(&'lua self, func: F) -> Function<'lua> where F: 'lua + for<'a> FnMut(&'a Lua, MultiValue<'a>) -> Result>, From 2b182860f7d91e55a10f4f0327eeb972e322d060 Mon Sep 17 00:00:00 2001 From: Jonas Schievink Date: Wed, 26 Jul 2017 17:28:47 +0200 Subject: [PATCH 3/3] Don't use hlist macros in userdata example --- src/lua.rs | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/src/lua.rs b/src/lua.rs index f6380d2..1231ac4 100644 --- a/src/lua.rs +++ b/src/lua.rs @@ -1112,9 +1112,8 @@ impl<'lua, T: UserData> UserDataMethods<'lua, T> { /// [`UserDataMethods`] for more information): /// /// ``` -/// # #[macro_use] extern crate hlist_macro; /// # extern crate rlua; -/// # use rlua::{Lua, MetaMethod, UserData, UserDataMethods, Integer, Result}; +/// # use rlua::{Lua, MetaMethod, UserData, UserDataMethods, Result}; /// # fn try_main() -> Result<()> { /// struct MyUserData(i32); /// @@ -1126,15 +1125,15 @@ impl<'lua, T: UserData> UserDataMethods<'lua, T> { /// }); /// /// methods.add_method_mut("add", |lua, this, args| { -/// let hlist_pat![value]: HList![Integer] = lua.unpack(args)?; +/// let value: i32 = lua.unpack(args)?; /// -/// this.0 += value as i32; +/// this.0 += value; /// lua.pack(()) /// }); /// /// methods.add_meta_method(MetaMethod::Add, |lua, this, args| { -/// let hlist_pat![value]: HList![Integer] = lua.unpack(args)?; -/// lua.pack(this.0 + value as i32) +/// let value: i32 = lua.unpack(args)?; +/// lua.pack(this.0 + value) /// }); /// } /// }