diff --git a/crates/luajit/src/lib.rs b/crates/luajit/src/lib.rs index 4a6964c..6c8c309 100644 --- a/crates/luajit/src/lib.rs +++ b/crates/luajit/src/lib.rs @@ -19,6 +19,11 @@ use std::{ }; use thiserror::Error; +/// LuaJIT version string. +pub fn version() -> &'static str { + LUAJIT_VERSION.to_str().unwrap() +} + /// Lua error. #[derive(Debug, Error)] #[non_exhaustive] @@ -149,7 +154,7 @@ pub enum Status { /// Thread is alive (currently running or can run a function). #[default] Normal, - /// Thread terminated with an error and cannot be resumed. + /// Thread terminated with an error and can no longer be used. Dead, /// Thread suspended with `coroutine.yield(...)` and is awaiting resume. Suspended, @@ -166,7 +171,7 @@ impl Status { }) } - /// Name of this status, like `"normal"` or `"dead"`. + /// Name of this status, like `"normal"` or `"suspended"`. pub fn name(&self) -> &'static str { match self { Status::Normal => "normal", @@ -430,8 +435,7 @@ impl Drop for GlobalState { /// Lua value handle into the registry. /// -/// The value is managed by [`luaL_ref`] and [`luaL_unref`] with [`LUA_REGISTRYINDEX`] as the target -/// table. +/// Equivalent to [`luaL_ref`] and [`luaL_unref`] with [`LUA_REGISTRYINDEX`] as the target table. #[derive(Debug)] pub struct Ref { state: Rc, @@ -1306,7 +1310,12 @@ impl<'s> Slot<'s> { } } +/// Pushes a value onto a [`Stack`]. +/// +/// This trait can be implemented by any type that can be reasonably converted to an equivalent Lua +/// value. Any type implementing this trait can be passed as an argument to [`Stack::push`]. pub trait Push { + /// Pushes this value to the given stack. fn push(&self, stack: &mut Stack); } @@ -1413,8 +1422,14 @@ impl_push_str!(BString); impl_push_str!(&str); impl_push_str!(String); +/// [`Push`]es a copy of the value at an index onto a [`Stack`]. +/// +/// Equivalent to [`lua_pushvalue`]. #[derive(Debug, Default, Clone, Copy, Hash)] -pub struct Index(pub c_int); +pub struct Index( + /// Index of the value to copy. + pub c_int, +); impl Push for Index { fn push(&self, stack: &mut Stack) { @@ -1423,25 +1438,38 @@ impl Push for Index { } } +/// [`Push`]es a new table onto a [`Stack`]. +/// +/// This value can be used as an argument to [`Stack::push`] to create a new empty table onto the +/// stack. +/// +/// Equivalent to [`lua_createtable`]. #[derive(Debug, Default, Clone, Copy, Hash)] pub struct NewTable { + /// Size of the preallocated array part. pub narr: c_int, + /// Size of the preallocated hash part. pub nrec: c_int, } impl NewTable { + /// Creates a new [`NewTable`] with no preallocations defined. pub fn new() -> Self { Self::new_sized(0, 0) } + /// Creates a new [`NewTable`] with the array part set to preallocate `size`. pub fn new_array(size: c_int) -> Self { Self::new_sized(size, 0) } + /// Creates a new [`NewTable`] with the hash part set to preallocate `size`. pub fn new_record(size: c_int) -> Self { Self::new_sized(0, size) } + /// Creates a new [`NewTable`] with the array and hash parts set to preallocate `narr` and + /// `rec`. pub fn new_sized(narr: c_int, nrec: c_int) -> Self { Self { narr, nrec } } @@ -1457,6 +1485,12 @@ impl Push for NewTable { } } +/// [`Push`]es the current thread onto a [`Stack`]. +/// +/// This value can be used as an argument to [`Stack::push`] to push the current thread as a +/// `coroutine` object onto the stack. +/// +/// Equivalent to [`lua_pushthread`]. #[derive(Debug, Default, Clone, Copy, Hash)] pub struct CurrentThread; @@ -1467,7 +1501,13 @@ impl Push for CurrentThread { } } +/// Parses a value on a [`Stack`]. +/// +/// This trait can be implemented by any type that can be reasonably converted from an equivalent +/// Lua value. Any type implementing this trait can be passed as a generic argument to +/// [`Slot::parse`]. pub trait Parse<'s>: Sized { + /// Parses the value in the given slot. fn parse(slot: &Slot<'s>) -> Result; }