diff --git a/crates/lb/src/chan.rs b/crates/lb/src/chan.rs deleted file mode 100644 index a096dd3..0000000 --- a/crates/lb/src/chan.rs +++ /dev/null @@ -1,79 +0,0 @@ -//! # Channel library -//! -//! The `lb:chan` library provides primitives for asynchronous communication between tasks via -//! message passing channels. -//! -//! ## Exports -//! -//! See [`lb_chanlib`] for items exported by this library. -use luaffi::{cdef, metatype}; - -/// Items exported by the `lb:chan` library. -/// -/// This library can be acquired by calling -/// [`require("lb:chan")`](https://www.lua.org/manual/5.1/manual.html#pdf-require). -/// -/// ```lua -/// local chan = require("lb:chan"); -/// ``` -#[cdef(module = "lb:chan")] -pub struct lb_chanlib; - -#[metatype] -impl lb_chanlib { - #[new] - extern "Lua-C" fn new() -> Self { - Self - } - - extern "Lua" fn unbounded(self) { - let (send, recv) = (__new(__ct.lb_sender), __new(__ct.lb_receiver)); - self.__unbounded(send, recv); - (send, recv) - } - - extern "Lua" fn bounded(self, cap: u32) { - assert(cap >= 0, "channel capacity must be nonnegative"); - let (send, recv) = (__new(__ct.lb_sender), __new(__ct.lb_receiver)); - self.__bounded(cap, send, recv); - (send, recv) - } - - // extern "Lua-C" fn __unbounded(&self, s: *mut lb_sender, r: *mut lb_receiver) { - // let (send, recv) = flume::unbounded(); - // unsafe { - // ptr::write(s, lb_sender { send }); - // ptr::write(r, lb_receiver { recv }); - // } - // } - - // extern "Lua-C" fn __bounded(&self, cap: usize, s: *mut lb_sender, r: *mut lb_receiver) { - // let (send, recv) = flume::bounded(cap); - // unsafe { - // ptr::write(s, lb_sender { send }); - // ptr::write(r, lb_receiver { recv }); - // } - // } -} - -// #[cdef] -// pub struct lb_sender { -// #[opaque] -// send: Sender, -// } - -// #[metatype] -// impl lb_sender { -// extern "Lua" fn send(self, value: _) { -// let key = __ref(value); -// } -// } - -// #[cdef] -// pub struct lb_receiver { -// #[opaque] -// recv: Receiver, -// } - -// #[metatype] -// impl lb_receiver {} diff --git a/crates/lb/src/fs.rs b/crates/lb/src/fs.rs index 5e6a9a4..1fc706e 100644 --- a/crates/lb/src/fs.rs +++ b/crates/lb/src/fs.rs @@ -1,4 +1,4 @@ -//! # Filesystem library +//! Filesystem library. //! //! The `lb:fs` library provides synchronous and asynchronous utilities for interacting with the //! filesystem. diff --git a/crates/lb/src/lib.rs b/crates/lb/src/lib.rs index d119491..9929521 100644 --- a/crates/lb/src/lib.rs +++ b/crates/lb/src/lib.rs @@ -1,6 +1,4 @@ -//! luby standard library -#[cfg(feature = "task")] -pub mod chan; +//! luby core libraries. #[cfg(feature = "fs")] pub mod fs; #[cfg(feature = "net")] diff --git a/crates/lb/src/net.rs b/crates/lb/src/net.rs index 606613a..3948187 100644 --- a/crates/lb/src/net.rs +++ b/crates/lb/src/net.rs @@ -1,7 +1,7 @@ -//! # Networking library +//! Network library. //! -//! The `lb:net` library provides an asynchronous network API for creating TCP or UDP servers and -//! clients. +//! The `lb:net` library provides an asynchronous network API for woring with TCP, UDP and IPC +//! sockets. //! //! ## Exports //! diff --git a/crates/lb/src/task.rs b/crates/lb/src/task.rs index 93816d6..b835e0a 100644 --- a/crates/lb/src/task.rs +++ b/crates/lb/src/task.rs @@ -1,7 +1,7 @@ -//! # Task library +//! Task library. //! -//! The `lb:task` library primitives for asynchronous communication between tasks via message -//! passing channels. +//! The `lb:task` library provides utilities for the scheduling of and communication between +//! asynchronous tasks. //! //! ## Exports //! diff --git a/crates/lb/src/time.rs b/crates/lb/src/time.rs index 4f31d58..b140fee 100644 --- a/crates/lb/src/time.rs +++ b/crates/lb/src/time.rs @@ -1,5 +1,21 @@ +//! Time library. +//! +//! The `lb:time` library provides utilities for working with the date and time and its related +//! constructs. +//! +//! ## Exports +//! +//! See [`lb_timelib`] for items exported by this library. use luaffi::{cdef, metatype}; +/// Items exported by the `lb:time` library. +/// +/// This library can be acquired by calling +/// [`require("lb:time")`](https://www.lua.org/manual/5.1/manual.html#pdf-require). +/// +/// ```lua +/// local time = require("lb:time"); +/// ``` #[cdef(module = "lb:time")] pub struct lb_timelib; @@ -10,11 +26,13 @@ impl lb_timelib { Self } + /// Returns an instant object that represents the current time at the time of calling. pub extern "Lua-C" fn instant() -> lb_instant { lb_instant::new(std::time::Instant::now()) } } +/// Represents the measurement of a monotonically nondecreasing clock. #[cdef] pub struct lb_instant(#[opaque] std::time::Instant); @@ -24,7 +42,8 @@ impl lb_instant { Self(instant) } - pub extern "Lua-C" fn elapsed(&self) -> f64 { + /// Returns the number of seconds elapsed since this instant was measured. + pub extern "Lua-C" fn elapsed_secs(&self) -> f64 { self.0.elapsed().as_secs_f64() } } diff --git a/crates/luaify/src/lib.rs b/crates/luaify/src/lib.rs index 33cb5ca..35024c5 100644 --- a/crates/luaify/src/lib.rs +++ b/crates/luaify/src/lib.rs @@ -1,6 +1,53 @@ //! # luaify //! -//! A Rust for generating Lua code from Rust syntax. +//! A macro for generating Lua code from Rust syntax. +//! +//! This macro performs a direct one-to-one translation of Rust expressions and blocks into +//! equivalent Lua code. For example, +//! +//! ```rust +//! use luaify::luaify; +//! +//! luaify!(|a, b| { +//! let c = a + b; +//! +//! fn inner_function(c: _) { +//! print(concat!("the sum of ", a, " and ", b, " is ", c)); +//! c +//! } +//! +//! inner_function(c); +//! }); +//! ``` +//! +//! will translate to the following equivalent Lua code (embedded as an [`&str`] or [`String`] in +//! Rust): +//! +//! ```lua +//! function(a, b) +//! local c = a + b +//! +//! local function inner_function(c) +//! print("the sum of " .. a .. " and " .. b .. " is " .. c) +//! return c +//! end +//! +//! inner_function(c) +//! end +//! ``` +//! +//! This macro accepts a smaller subset of all valid Rust syntax due to the difference between +//! Rust's expression-based syntax and Lua's statement-based syntax. Most Rust syntax are translated +//! to their equivalents in Lua, however the following features are not supported and will result in +//! a compile-time error: +//! +//! - static typing (typed local variables, parameters and return types in function signatures, +//! etc.) +//! - pattern matching (e.g. `match`, `if let`, `while let`) +//! - items other than statements or functions (e.g. `struct`, `enum`, `trait`, `impl`) +//! - block statements in expression position (e.g. `if`, `while`, `for`, `loop` that evaluate to a +//! value) +//! - expressions in statement position (except for function calls and assignments) use crate::{ generate::{generate, generate_chunk}, transform::{transform, transform_chunk}, @@ -13,6 +60,7 @@ mod generate; mod transform; mod utils; +/// Generates Lua code for the given expression. #[proc_macro] pub fn luaify(input: TokenStream1) -> TokenStream1 { let mut expr = parse_macro_input!(input); @@ -23,6 +71,7 @@ pub fn luaify(input: TokenStream1) -> TokenStream1 { .into() } +/// Generates Lua code for the given block. #[proc_macro] pub fn luaify_chunk(input: TokenStream1) -> TokenStream1 { let mut block = parse_macro_input!(input); diff --git a/crates/luajit-sys/lib.rs b/crates/luajit-sys/lib.rs index 516bce4..7f61de0 100644 --- a/crates/luajit-sys/lib.rs +++ b/crates/luajit-sys/lib.rs @@ -1,3 +1,18 @@ +//! Raw bindings for LuaJIT generated using [bindgen](https://docs.rs/bindgen/). +//! +//! ## Feature flags +//! +//! Features flags are used to control certain features of LuaJIT. They are not enabled by default +//! unless otherwise specified below. +//! +//! - `runtime`: links the target with `libluajit`. This should only be enabled by binary targets. +//! - `jit`: enables the JIT compiler. *This is enabled by default.* +//! - `ffi`: enables the FFI library. *This is enabled by default.* +//! - `unwind`: configures LuaJIT to use stack unwinding instead of `longjmp` for error handling. +//! **This MUST be enabled if `panic = "unwind"` is set.** +//! - `bundled-alloc`: configures LuaJIT to include its own bundled allocator. If this is not +//! enabled, LuaJIT will use the system allocator by default. +//! - `lua52`: enables Lua 5.2 compatibility mode. *This is enabled by default.* #![allow(nonstandard_style)] use std::{ffi::*, ptr}; diff --git a/crates/luajit/src/lib.rs b/crates/luajit/src/lib.rs index 6a8240c..34f8e91 100644 --- a/crates/luajit/src/lib.rs +++ b/crates/luajit/src/lib.rs @@ -1,3 +1,4 @@ +//! Safe LuaJIT bindings for Rust. #![allow(non_snake_case)] use bitflags::bitflags; use bstr::{BStr, BString, ByteSlice}; diff --git a/src/lib.rs b/src/lib.rs index 1f7486d..e9383de 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,5 +1,4 @@ -#[cfg(feature = "task")] -pub use lb::chan; +//! luby standard library. #[cfg(feature = "fs")] pub use lb::fs; #[cfg(feature = "net")] @@ -13,8 +12,6 @@ pub use lb::time; pub fn open(#[allow(unused)] rt: &mut lb::runtime::Builder) { #[cfg(feature = "task")] rt.module::(); - #[cfg(feature = "task")] - rt.module::(); #[cfg(feature = "time")] rt.module::(); #[cfg(feature = "fs")] diff --git a/tests/main.lua b/tests/main.lua index 2f3e3ed..82ae3cd 100644 --- a/tests/main.lua +++ b/tests/main.lua @@ -117,7 +117,7 @@ local function main(item) fail = fail + 1 end end - local elapsed = time:elapsed() + local elapsed = time:elapsed_secs() local code = 1 if fail == 0 then print("", style("pass", ("%s %d tests passed"):format(icon.check, pass)))