diff --git a/crates/rune-modules/src/http.rs b/crates/rune-modules/src/http.rs index 7195d46d1..082b45c66 100644 --- a/crates/rune-modules/src/http.rs +++ b/crates/rune-modules/src/http.rs @@ -52,9 +52,18 @@ use rune::{Any, Module, Value, ContextError}; use rune::runtime::{Bytes, Ref, Formatter, VmResult}; use rune::alloc::fmt::TryWrite; -/// Construct the `http` module. +/// A simple HTTP module for Rune. +/// +/// # Examples +/// +/// ```rune,no_run +/// let res = http::get("https://httpstat.us/200?sleep=100").await; +/// +/// dbg!(res.text().await?); +/// ``` +#[rune::module(::http)] pub fn module(_stdio: bool) -> Result { - let mut module = Module::with_crate("http")?; + let mut module = Module::from_meta(self::module_meta)?; module.ty::()?; module.ty::()?; @@ -81,6 +90,7 @@ pub fn module(_stdio: bool) -> Result { Ok(module) } +/// An error returned by methods in the `http` module. #[derive(Debug, Any)] #[rune(item = ::http)] pub struct Error { @@ -138,6 +148,7 @@ impl Response { } } +/// An HTTP status code. #[derive(Debug, Any)] #[rune(item = ::http)] pub struct StatusCode { diff --git a/crates/rune/src/compile/context.rs b/crates/rune/src/compile/context.rs index 226d8c3f0..6effa0157 100644 --- a/crates/rune/src/compile/context.rs +++ b/crates/rune/src/compile/context.rs @@ -156,6 +156,7 @@ impl Context { this.install(crate::modules::io::module(stdio)?)?; this.install(crate::modules::iter::module()?)?; this.install(crate::modules::macros::module()?)?; + this.install(crate::modules::macros::builtin::module()?)?; this.install(crate::modules::mem::module()?)?; this.install(crate::modules::object::module()?)?; this.install(crate::modules::ops::module()?)?; diff --git a/crates/rune/src/module/module.rs b/crates/rune/src/module/module.rs index d38b5f21e..cce03f4b7 100644 --- a/crates/rune/src/module/module.rs +++ b/crates/rune/src/module/module.rs @@ -422,6 +422,8 @@ impl Module { } /// Modify the current module to utilise a special identifier. + /// + /// TODO: Deprecate after next major release. #[doc(hidden)] pub fn with_unique(self, id: &'static str) -> Self { Self { diff --git a/crates/rune/src/modules/any.rs b/crates/rune/src/modules/any.rs index f913624a8..975277487 100644 --- a/crates/rune/src/modules/any.rs +++ b/crates/rune/src/modules/any.rs @@ -1,4 +1,4 @@ -//! The `std::any` rune module. +//! Dynamic typing and type reflection. use crate as rune; use crate::alloc::fmt::TryWrite; @@ -6,7 +6,7 @@ use crate::alloc::String; use crate::runtime::{Formatter, Type, Value, VmResult}; use crate::{ContextError, Module}; -/// Utilities for dynamic typing or type reflection. +/// Dynamic typing and type reflection. /// /// # `Type` /// diff --git a/crates/rune/src/modules/bytes.rs b/crates/rune/src/modules/bytes.rs index b608b1fbc..8489c41b0 100644 --- a/crates/rune/src/modules/bytes.rs +++ b/crates/rune/src/modules/bytes.rs @@ -1,4 +1,4 @@ -//! The `std::bytes` module. +//! The bytes module. use crate as rune; use crate::alloc::prelude::*; @@ -6,9 +6,10 @@ use crate::alloc::Vec; use crate::runtime::{Bytes, VmResult}; use crate::{ContextError, Module}; -/// Construct the `std::bytes` module. +/// The bytes module. +#[rune::module(::std::bytes)] pub fn module() -> Result { - let mut module = Module::with_crate_item("std", ["bytes"])?; + let mut module = Module::from_meta(self::module_meta)?; module.ty::()?; module.function_meta(new)?; diff --git a/crates/rune/src/modules/capture_io.rs b/crates/rune/src/modules/capture_io.rs index 82128d93a..473265d9a 100644 --- a/crates/rune/src/modules/capture_io.rs +++ b/crates/rune/src/modules/capture_io.rs @@ -1,5 +1,7 @@ //! I/O module capable of capturing what's been written to a buffer. //! +//! # Examples +//! //! ``` //! use rune::{Context, ContextError}; //! use rune::modules::capture_io::{self, CaptureIo}; @@ -17,15 +19,17 @@ use ::rust_alloc::sync::Arc; use parking_lot::Mutex; +use crate as rune; use crate::alloc::fmt::TryWrite; use crate::alloc::string::FromUtf8Error; use crate::alloc::{String, Vec}; use crate::runtime::{Stack, VmError, VmResult}; use crate::{ContextError, Module, Value}; -/// Provide a bunch of `std` functions that can be used during tests to capture output. +/// I/O module capable of capturing what's been written to a buffer. +#[rune::module(::std::io)] pub fn module(io: &CaptureIo) -> Result { - let mut module = Module::with_crate_item("std", ["io"])?; + let mut module = Module::from_meta(self::module_meta)?; let o = io.clone(); diff --git a/crates/rune/src/modules/char.rs b/crates/rune/src/modules/char.rs index e7a56e624..02b685d77 100644 --- a/crates/rune/src/modules/char.rs +++ b/crates/rune/src/modules/char.rs @@ -1,4 +1,4 @@ -//! The `std::char` module. +//! The character module for Rune. use core::char::ParseCharError; @@ -7,11 +7,12 @@ use crate::{ContextError, Module}; use crate as rune; -/// Construct the `std::char` module. +/// The character module for Rune. +#[rune::module(::std::char)] pub fn module() -> Result { - let mut module = Module::with_crate_item("std", ["char"])?; - module.ty::()?; + let mut module = Module::from_meta(self::module_meta)?; + module.ty::()?; module.function_meta(from_i64)?; module.function_meta(to_i64)?; module.function_meta(is_alphabetic)?; diff --git a/crates/rune/src/modules/clone.rs b/crates/rune/src/modules/clone.rs index b9cbd3730..3b4ebb499 100644 --- a/crates/rune/src/modules/clone.rs +++ b/crates/rune/src/modules/clone.rs @@ -1,16 +1,16 @@ -//! The `std::clone` module. +//! The cloning trait for Rune. use crate as rune; use crate::runtime::{Value, VmResult}; use crate::{ContextError, Module}; -#[rune::module(::std::clone)] -/// The `std::clone` module. +/// The cloning trait for Rune. /// /// This module defines methods and types used when cloning values. /// /// By default all values in rune are structurally shared, so in order to get a /// unique instance of it you must call [`clone`] over it. +#[rune::module(::std::clone)] pub fn module() -> Result { let mut module = Module::from_meta(self::module_meta)?; module.function_meta(clone)?; diff --git a/crates/rune/src/modules/cmp.rs b/crates/rune/src/modules/cmp.rs index 781c694b2..971eba75c 100644 --- a/crates/rune/src/modules/cmp.rs +++ b/crates/rune/src/modules/cmp.rs @@ -1,4 +1,4 @@ -//! The `std::cmp` module. +//! Comparison and ordering. use core::cmp::Ordering; @@ -7,9 +7,10 @@ use crate::alloc::fmt::TryWrite; use crate::runtime::{Formatter, Value, VmResult}; use crate::{ContextError, Module}; -/// Construct the `std::cmp` module. +/// Comparison and ordering. +#[rune::module(::std::cmp)] pub fn module() -> Result { - let mut m = Module::with_crate_item("std", ["cmp"])?; + let mut m = Module::from_meta(self::module_meta)?; { let ty = m.ty::()?.docs([ diff --git a/crates/rune/src/modules/collections.rs b/crates/rune/src/modules/collections.rs index d69b2a76d..5695a59a8 100644 --- a/crates/rune/src/modules/collections.rs +++ b/crates/rune/src/modules/collections.rs @@ -1,4 +1,4 @@ -//! `std::collections` module. +//! Dynamic collections. #[cfg(feature = "alloc")] mod hash_map; @@ -15,8 +15,8 @@ pub(crate) use self::hash_set::HashSet; pub(crate) use self::vec_deque::VecDeque; use crate as rune; +/// Dynamic collections. #[rune::module(::std::collections)] -/// The `std::collections` module. pub fn module() -> Result { let mut module = Module::from_meta(self::module_meta)?; #[cfg(feature = "alloc")] diff --git a/crates/rune/src/modules/core.rs b/crates/rune/src/modules/core.rs index cf8dad06b..f61449007 100644 --- a/crates/rune/src/modules/core.rs +++ b/crates/rune/src/modules/core.rs @@ -1,4 +1,4 @@ -//! The core `std` module. +//! Core types and methods in Rune. use crate as rune; use crate::alloc::prelude::*; @@ -9,7 +9,9 @@ use crate::runtime::{Panic, Value, VmResult}; use crate::{ContextError, Module}; #[rune::module(::std)] -/// The Rune standard library. +/// Core types and methods in Rune. +/// +/// These are types and methods for which Rune as a language would not work without. pub fn module() -> Result { let mut module = Module::from_meta(self::module_meta)?.with_unique("std"); diff --git a/crates/rune/src/modules/disable_io.rs b/crates/rune/src/modules/disable_io.rs index 289d13de4..e492bcea5 100644 --- a/crates/rune/src/modules/disable_io.rs +++ b/crates/rune/src/modules/disable_io.rs @@ -1,4 +1,6 @@ -//! I/O module ignoring everything written to output. +//! I/O methods which will cause any output to be ignored. +//! +//! # Examples //! //! ``` //! use rune::{Context, ContextError}; @@ -9,15 +11,16 @@ //! # Ok::<_, ContextError>(()) //! ``` +use crate as rune; use crate::runtime::{Stack, VmResult}; use crate::{ContextError, Module}; -/// Provide a bunch of `std::io` functions which will cause any output to be ignored. +/// I/O methods which will cause any output to be ignored. +#[rune::module(::std::io)] pub fn module() -> Result { - let mut module = Module::with_crate_item("std", ["io"])?; + let mut module = Module::from_meta(self::module_meta)?; module.function("print", move |_: &str| {}).build()?; - module.function("println", move |_: &str| {}).build()?; module diff --git a/crates/rune/src/modules/f64.rs b/crates/rune/src/modules/f64.rs index d83ee699e..5ec6c8125 100644 --- a/crates/rune/src/modules/f64.rs +++ b/crates/rune/src/modules/f64.rs @@ -1,4 +1,4 @@ -//! The `std::f64` module. +//! Floating point numbers. use core::cmp::Ordering; use core::num::ParseFloatError; @@ -7,9 +7,13 @@ use crate as rune; use crate::runtime::{VmErrorKind, VmResult}; use crate::{ContextError, Module}; -/// Install the core package into the given functions namespace. +/// Floating point numbers. +/// +/// This provides methods for computing over and parsing 64-bit floating pointer +/// numbers. +#[rune::module(::std::f64)] pub fn module() -> Result { - let mut m = Module::with_crate_item("std", ["f64"])?; + let mut m = Module::from_meta(self::module_meta)?; m.function_meta(parse)? .deprecated("Use std::string::parse:: instead")?; diff --git a/crates/rune/src/modules/fmt.rs b/crates/rune/src/modules/fmt.rs index 9c31d1a02..9623774c9 100644 --- a/crates/rune/src/modules/fmt.rs +++ b/crates/rune/src/modules/fmt.rs @@ -1,4 +1,4 @@ -//! The `std::fmt` module. +//! Formatting text. use core::fmt; @@ -10,9 +10,21 @@ use crate::parse::Parser; use crate::runtime::{Format, Formatter, VmResult}; use crate::{ContextError, Module}; -/// Construct the `std::fmt` module. +/// Formatting text. +/// +/// This includes types, macros, and functions used to format text. +/// +/// # Examples +/// +/// ```rune +/// let who = "World"; +/// let string = format!("Hello {}", who); +/// assert_eq!(string, "Hello World"); +/// ``` +#[rune::module(::std::fmt)] pub fn module() -> Result { - let mut module = Module::with_crate_item("std", ["fmt"])?.with_unique("std::fmt"); + let mut module = Module::from_meta(self::module_meta)?.with_unique("std::fmt"); + module.ty::()?; module.ty::()?; module.ty::()?; diff --git a/crates/rune/src/modules/future.rs b/crates/rune/src/modules/future.rs index 019d3145e..870ba97c5 100644 --- a/crates/rune/src/modules/future.rs +++ b/crates/rune/src/modules/future.rs @@ -1,51 +1,16 @@ -//! The `std::future` module. +//! Asynchronous computations. +use crate as rune; use crate::alloc::Vec; -use crate::runtime::{Future, Mut, SelectFuture, Stack, Value, ValueKind, VmErrorKind, VmResult}; +use crate::runtime::{Future, Mut, SelectFuture, Value, ValueKind, VmErrorKind, VmResult}; use crate::{ContextError, Module}; -/// Construct the `std::future` module. +/// Asynchronous computations. +#[rune::module(::std::future)] pub fn module() -> Result { - let mut module = Module::with_crate_item("std", ["future"])?; + let mut module = Module::from_meta(self::module_meta)?; module.ty::()?; - - module - .raw_function("join", raw_join) - .build()? - .is_async(true) - .args(1) - .argument_types([None])? - .docs([ - "Waits for a collection of futures to complete and joins their result.", - "", - "# Examples", - "", - "```rune", - "let a = async { 1 };", - "let b = async { 2 };", - "let (a, b) = std::future::join((a, b)).await;", - "assert_eq!(1, a);", - "assert_eq!(2, b);", - "```", - "", - "Using a vector:", - "", - "```rune", - "let a = async { 1 };", - "let b = async { 2 };", - "let [a, b] = std::future::join([a, b]).await;", - "assert_eq!(1, a);", - "assert_eq!(2, b);", - "```", - "", - "Joining an empty collection:", - "", - "```rune", - "let () = std::future::join(()).await;", - "let [] = std::future::join([]).await;", - "```", - ])?; - + module.function_meta(join)?; Ok(module) } @@ -89,6 +54,35 @@ where factory(results) } +/// Waits for a collection of futures to complete and joins their result. +/// +/// # Examples +/// +/// ```rune +/// let a = async { 1 }; +/// let b = async { 2 }; +/// let (a, b) = std::future::join((a, b)).await; +/// assert_eq!(1, a); +/// assert_eq!(2, b); +/// ``` +/// +/// Using a vector: +/// +/// ```rune +/// let a = async { 1 }; +/// let b = async { 2 }; +/// let [a, b] = std::future::join([a, b]).await; +/// assert_eq!(1, a); +/// assert_eq!(2, b); +/// ``` +/// +/// Joining an empty collection: +/// +/// ```rune +/// let () = std::future::join(()).await; +/// let [] = std::future::join([]).await; +/// ``` +#[rune::function] async fn join(value: Value) -> VmResult { match &*vm_try!(value.borrow_kind_ref()) { ValueKind::EmptyTuple => VmResult::Ok(vm_try!(Value::empty())), @@ -107,18 +101,3 @@ async fn join(value: Value) -> VmResult { ]), } } - -/// The join implementation. -fn raw_join(stack: &mut Stack, args: usize) -> VmResult<()> { - if args != 1 { - return VmResult::err(VmErrorKind::BadArgumentCount { - actual: args, - expected: 1, - }); - } - - let value = vm_try!(stack.pop()); - let future = vm_try!(Future::new(join(value))); - vm_try!(stack.push(future)); - VmResult::Ok(()) -} diff --git a/crates/rune/src/modules/generator.rs b/crates/rune/src/modules/generator.rs index 950acfe90..6436a5cec 100644 --- a/crates/rune/src/modules/generator.rs +++ b/crates/rune/src/modules/generator.rs @@ -1,9 +1,13 @@ -//! The `std::generator` module. +//! Generators. +use crate as rune; use crate::{ContextError, Module}; -/// Construct the `std::generator` module. +/// Generators. +/// +/// Generator functionality has been moved into [::std::ops]. #[deprecated = "Generators have been moved into std::ops"] +#[rune::module(::std::generator)] pub fn module() -> Result { - Module::with_crate_item("std", ["generator"]) + Module::from_meta(self::module_meta) } diff --git a/crates/rune/src/modules/hash.rs b/crates/rune/src/modules/hash.rs index 5e5428a57..f5153c0c9 100644 --- a/crates/rune/src/modules/hash.rs +++ b/crates/rune/src/modules/hash.rs @@ -1,11 +1,11 @@ -//! The `std::hash` module. +//! Hashing types. use crate as rune; use crate::runtime::Hasher; use crate::{ContextError, Module}; +/// Hashing types. #[rune::module(::std::hash)] -/// Types for dealing with hashing in Rune. pub fn module() -> Result { #[allow(unused_mut)] let mut module = Module::from_meta(self::module_meta)?; diff --git a/crates/rune/src/modules/i64.rs b/crates/rune/src/modules/i64.rs index e7dd604aa..5c4fb7e74 100644 --- a/crates/rune/src/modules/i64.rs +++ b/crates/rune/src/modules/i64.rs @@ -1,4 +1,4 @@ -//! The `std::i64` module. +//! Integers. use core::cmp::Ordering; use core::num::ParseIntError; @@ -9,9 +9,12 @@ use crate::alloc::string::TryToString; use crate::runtime::{VmErrorKind, VmResult}; use crate::{ContextError, Module}; -/// Construct the `std::i64` module. +/// Integers. +/// +/// This provides methods for computing over and parsing 64-bit integers. +#[rune::module(::std::i64)] pub fn module() -> Result { - let mut module = Module::with_crate_item("std", ["i64"])?; + let mut module = Module::from_meta(self::module_meta)?; module.function("parse", parse).build()?; module.function_meta(to_float)?; diff --git a/crates/rune/src/modules/io.rs b/crates/rune/src/modules/io.rs index ecb7942a4..280a80494 100644 --- a/crates/rune/src/modules/io.rs +++ b/crates/rune/src/modules/io.rs @@ -1,4 +1,4 @@ -//! The `std::io` module. +//! I/O functions. use std::io::{self, Write as _}; @@ -10,9 +10,10 @@ use crate::parse::Parser; use crate::runtime::{Formatter, Panic, Stack, Value, VmResult}; use crate::{ContextError, Module}; -/// Construct the `std::io` module. +/// I/O functions. +#[rune::module(::std::io)] pub fn module(stdio: bool) -> Result { - let mut module = Module::with_crate_item("std", ["io"])?.with_unique("std::io"); + let mut module = Module::from_meta(self::module_meta)?.with_unique("std::io"); module.item_mut().docs([ "The std::io module contains a number of common things", diff --git a/crates/rune/src/modules/iter.rs b/crates/rune/src/modules/iter.rs index 50de9cc9a..be038aa68 100644 --- a/crates/rune/src/modules/iter.rs +++ b/crates/rune/src/modules/iter.rs @@ -1,4 +1,4 @@ -//! The `std::iter` module. +//! Iterators. use core::convert::identity; @@ -14,9 +14,13 @@ use crate::runtime::{ }; use crate::{ContextError, Module}; -/// Construct the `std::iter` module. +/// Iterators. +/// +/// This module contains types and methods for working with iterators in Rune. +#[rune::module(::std::iter)] pub fn module() -> Result { - let mut module = Module::with_crate_item("std", ["iter"])?; + let mut module = Module::from_meta(self::module_meta)?; + module.ty::()?; module.function_meta(next)?; diff --git a/crates/rune/src/modules/macros.rs b/crates/rune/src/modules/macros.rs index b86c9c514..606a42fa3 100644 --- a/crates/rune/src/modules/macros.rs +++ b/crates/rune/src/modules/macros.rs @@ -1,68 +1,12 @@ -//! `std::macros` module for the [Rune Language]. -//! -//! [Rune Language]: https://rune-rs.github.io +//! Macro support. + +pub mod builtin; use crate as rune; -use crate::compile; -use crate::macros::{quote, MacroContext, TokenStream}; -use crate::parse::Parser; use crate::{ContextError, Module}; -/// Construct the `std::macros` module. +/// Macro support. +#[rune::module(::std::macros)] pub fn module() -> Result { - let mut builtins = - Module::with_crate_item("std", ["macros", "builtin"])?.with_unique("std::macros::builtin"); - builtins.macro_meta(file)?; - builtins.macro_meta(line)?; - Ok(builtins) -} - -/// Return the line in the current file. -/// -/// # Examples -/// -/// ```rune -/// println!("{}:{}: Something happened", file!(), line!()); -/// ``` -#[rune::macro_] -pub(crate) fn line( - cx: &mut MacroContext<'_, '_, '_>, - stream: &TokenStream, -) -> compile::Result { - use crate as rune; - - let mut parser = Parser::from_token_stream(stream, cx.input_span()); - parser.eof()?; - - let stream = quote!( - #[builtin] - line!() - ); - - Ok(stream.into_token_stream(cx)?) -} - -/// Return the name of the current file. -/// -/// # Examples -/// -/// ```rune -/// println!("{}:{}: Something happened", file!(), line!()); -/// ``` -#[rune::macro_] -pub(crate) fn file( - cx: &mut MacroContext<'_, '_, '_>, - stream: &TokenStream, -) -> compile::Result { - use crate as rune; - - let mut parser = Parser::from_token_stream(stream, cx.input_span()); - parser.eof()?; - - let stream = quote!( - #[builtin] - file!() - ); - - Ok(stream.into_token_stream(cx)?) + Module::from_meta(self::module_meta) } diff --git a/crates/rune/src/modules/macros/builtin.rs b/crates/rune/src/modules/macros/builtin.rs new file mode 100644 index 000000000..8368eccc2 --- /dev/null +++ b/crates/rune/src/modules/macros/builtin.rs @@ -0,0 +1,66 @@ +//! Built-in macros. + +use crate as rune; +use crate::compile; +use crate::macros::{quote, MacroContext, TokenStream}; +use crate::parse::Parser; +use crate::{ContextError, Module}; + +/// Built-in macros. +#[rune::module(::std::macros::builtin)] +pub fn module() -> Result { + let mut builtins = Module::from_meta(self::module_meta)?.with_unique("std::macros::builtin"); + builtins.macro_meta(file)?; + builtins.macro_meta(line)?; + Ok(builtins) +} + +/// Return the line in the current file. +/// +/// # Examples +/// +/// ```rune +/// println!("{}:{}: Something happened", file!(), line!()); +/// ``` +#[rune::macro_] +pub(crate) fn line( + cx: &mut MacroContext<'_, '_, '_>, + stream: &TokenStream, +) -> compile::Result { + use crate as rune; + + let mut parser = Parser::from_token_stream(stream, cx.input_span()); + parser.eof()?; + + let stream = quote!( + #[builtin] + line!() + ); + + Ok(stream.into_token_stream(cx)?) +} + +/// Return the name of the current file. +/// +/// # Examples +/// +/// ```rune +/// println!("{}:{}: Something happened", file!(), line!()); +/// ``` +#[rune::macro_] +pub(crate) fn file( + cx: &mut MacroContext<'_, '_, '_>, + stream: &TokenStream, +) -> compile::Result { + use crate as rune; + + let mut parser = Parser::from_token_stream(stream, cx.input_span()); + parser.eof()?; + + let stream = quote!( + #[builtin] + file!() + ); + + Ok(stream.into_token_stream(cx)?) +} diff --git a/crates/rune/src/modules/mem.rs b/crates/rune/src/modules/mem.rs index b10ff62d7..99dc314a6 100644 --- a/crates/rune/src/modules/mem.rs +++ b/crates/rune/src/modules/mem.rs @@ -1,12 +1,13 @@ -//! The `std::mem` module. +//! Working with memory. use crate as rune; use crate::runtime::{Value, VmResult}; use crate::{ContextError, Module}; -/// Construct the `std` module. +/// Working with memory. +#[rune::module(::std::mem)] pub fn module() -> Result { - let mut module = Module::with_crate_item("std", ["mem"])?; + let mut module = Module::from_meta(self::module_meta)?; module.function_meta(drop)?; Ok(module) } diff --git a/crates/rune/src/modules/num.rs b/crates/rune/src/modules/num.rs index 3eb4b73c3..fd6070869 100644 --- a/crates/rune/src/modules/num.rs +++ b/crates/rune/src/modules/num.rs @@ -1,12 +1,17 @@ -//! The `std::num` module. +//! Working with numbers. use core::num::{ParseFloatError, ParseIntError}; +use crate as rune; use crate::{ContextError, Module}; -/// Install the core package into the given functions namespace. +/// Working with numbers. +/// +/// This module provides types generic for working over numbers, such as errors +/// when a number cannot be parsed. +#[rune::module(::std::num)] pub fn module() -> Result { - let mut module = Module::with_crate_item("std", ["num"])?; + let mut module = Module::from_meta(self::module_meta)?; module.ty::()?; module.ty::()?; Ok(module) diff --git a/crates/rune/src/modules/object.rs b/crates/rune/src/modules/object.rs index 267e7cc4c..c69c21a78 100644 --- a/crates/rune/src/modules/object.rs +++ b/crates/rune/src/modules/object.rs @@ -1,4 +1,4 @@ -//! The `std::object` module. +//! The dynamic [`Object`] container. use core::cmp::Ordering; @@ -8,9 +8,35 @@ use crate::alloc::Vec; use crate::runtime::{EnvProtocolCaller, Iterator, Object, Protocol, Value, VmResult}; use crate::{ContextError, Module}; -/// Construct the `std::object` module. +/// The dynamic [`Object`] container. +/// +/// This modules contains the [`Object`] type, which is a dynamic type erased +/// container. +/// +/// Objects in Rune are declared using the special `#{}` syntax, but can also be +/// interacted with through the fundamental [`Object`] type. +/// +/// Fields can be added to objects "on the fly", simply by assigning to them: +/// +/// ``` +/// let object = #{}; +/// object.hello = "World"; +/// assert_eq!(object.hello, "World"); +/// ``` +/// +/// # Examples +/// +/// ```rune +/// let object1 = #{hello: "World"}; +/// +/// let object2 = Object::new(); +/// object2.insert("Hello", "World"); +/// +/// assert_eq!(object1, object2); +/// ``` +#[rune::module(::std::object)] pub fn module() -> Result { - let mut m = Module::with_crate_item("std", ["object"])?; + let mut m = Module::from_meta(self::module_meta)?; m.ty::()?; diff --git a/crates/rune/src/modules/ops.rs b/crates/rune/src/modules/ops.rs index 48ade2b9b..817f243d4 100644 --- a/crates/rune/src/modules/ops.rs +++ b/crates/rune/src/modules/ops.rs @@ -1,4 +1,4 @@ -//! The `std::ops` module. +//! Overloadable operators and associated types. use core::cmp::Ordering; @@ -14,8 +14,8 @@ use crate::{ContextError, Module}; static STATE: OnceCell = OnceCell::new(); +/// Overloadable operators and associated types. #[rune::module(::std::ops)] -/// Overloadable operators. pub fn module() -> Result { let mut m = Module::from_meta(self::module_meta)?; diff --git a/crates/rune/src/modules/option.rs b/crates/rune/src/modules/option.rs index bde8aa696..1e6d9e086 100644 --- a/crates/rune/src/modules/option.rs +++ b/crates/rune/src/modules/option.rs @@ -1,13 +1,17 @@ -//! The `std::option` module. +//! The [`Option`] type. use crate as rune; use crate::runtime::{ControlFlow, Formatter, Function, Iterator, Panic, Value, VmResult}; use crate::{ContextError, Module}; -/// Construct the `std::option` module. +/// The [`Option`] type. +/// +/// This module deals with the fundamental [`Option`] type in rune. +#[rune::module(::std::option)] pub fn module() -> Result { - let mut module = Module::with_crate_item("std", ["option"])?; + let mut module = Module::from_meta(self::module_meta)?; module.option(["Option"])?; + // Sorted for ease of finding module.function_meta(expect)?; module.function_meta(unwrap)?; diff --git a/crates/rune/src/modules/result.rs b/crates/rune/src/modules/result.rs index 642778069..c27acaa40 100644 --- a/crates/rune/src/modules/result.rs +++ b/crates/rune/src/modules/result.rs @@ -1,4 +1,4 @@ -//! The `std::result` module. +//! The [`Result`] type. use crate as rune; use crate::alloc::fmt::TryWrite; @@ -6,9 +6,13 @@ use crate::alloc::prelude::*; use crate::runtime::{ControlFlow, Formatter, Function, Panic, Value, VmResult}; use crate::{ContextError, Module}; -/// Construct the `std::result` module. +/// The [`Result`] type. +/// +/// This module deals with the fundamental [`Result`] type in Rune. +#[rune::module(::std::result)] pub fn module() -> Result { - let mut module = Module::with_crate_item("std", ["result"])?; + let mut module = Module::from_meta(self::module_meta)?; + // Sorted for ease of finding let mut result = module .result("Result")? diff --git a/crates/rune/src/modules/stream.rs b/crates/rune/src/modules/stream.rs index d9fd8ee30..3b4ba6ad4 100644 --- a/crates/rune/src/modules/stream.rs +++ b/crates/rune/src/modules/stream.rs @@ -1,11 +1,13 @@ -//! The `std::stream` module. +//! Asynchronous streams. +use crate as rune; use crate::runtime::{Stream, Vm}; use crate::{ContextError, Module}; -/// Construct the `std::stream` module. +/// Asynchronous streams. +#[rune::module(::std::stream)] pub fn module() -> Result { - let mut module = Module::with_crate_item("std", ["stream"])?; + let mut module = Module::from_meta(self::module_meta)?; module.ty::>()?; module.associated_function("next", Stream::::next_shared)?; module.associated_function("resume", Stream::::resume_shared)?; diff --git a/crates/rune/src/modules/string.rs b/crates/rune/src/modules/string.rs index 3403a8e82..418e9bd17 100644 --- a/crates/rune/src/modules/string.rs +++ b/crates/rune/src/modules/string.rs @@ -1,4 +1,4 @@ -//! The `std::string` module. +//! Strings. use core::char; use core::cmp::Ordering; @@ -13,9 +13,10 @@ use crate::alloc::{String, Vec}; use crate::runtime::{Bytes, Formatter, Iterator, Panic, Value, ValueKind, VmErrorKind, VmResult}; use crate::{Any, ContextError, Module}; -/// Construct the `std::string` module. +/// Strings. +#[rune::module(::std::string)] pub fn module() -> Result { - let mut module = Module::with_crate_item("std", ["string"])?; + let mut module = Module::from_meta(self::module_meta)?; module.ty::()?; diff --git a/crates/rune/src/modules/test.rs b/crates/rune/src/modules/test.rs index 3c367d6e1..1de31bc0d 100644 --- a/crates/rune/src/modules/test.rs +++ b/crates/rune/src/modules/test.rs @@ -1,6 +1,4 @@ -//! `std::test` module for the [Rune Language]. -//! -//! [Rune Language]: https://rune-rs.github.io +//! Testing and benchmarking. use crate as rune; use crate::alloc::{try_format, Vec}; @@ -11,6 +9,24 @@ use crate::parse::Parser; use crate::runtime::Function; use crate::{Any, ContextError, Module, T}; +/// Testing and benchmarking. +#[rune::module(::std::test)] +pub fn module() -> Result { + let mut module = Module::from_meta(self::module_meta)?.with_unique("std::test"); + + module.macro_meta(assert)?; + module.macro_meta(assert_eq)?; + module.macro_meta(assert_ne)?; + + module.ty::()?.docs([ + "A type to perform benchmarks.", + "", + "This is the type of the argument to any function which is annotated with `#[bench]`", + ])?; + module.function_meta(Bencher::iter)?; + Ok(module) +} + /// A helper type to capture benchmarks. #[derive(Default, Any)] #[rune(module = crate, item = ::std::test)] @@ -31,21 +47,6 @@ impl Bencher { } } -/// Construct the `std::test` module. -pub fn module() -> Result { - let mut module = Module::with_crate_item("std", ["test"])?.with_unique("std::test"); - module.macro_meta(assert)?; - module.macro_meta(assert_eq)?; - module.macro_meta(assert_ne)?; - module.ty::()?.docs([ - "A type to perform benchmarks.", - "", - "This is the type of the argument to any function which is annotated with `#[bench]`", - ])?; - module.function_meta(Bencher::iter)?; - Ok(module) -} - /// Assert that the expression provided as an argument is true, or cause a vm /// panic. /// diff --git a/crates/rune/src/modules/tuple.rs b/crates/rune/src/modules/tuple.rs index edef85766..4af4b8d3c 100644 --- a/crates/rune/src/modules/tuple.rs +++ b/crates/rune/src/modules/tuple.rs @@ -1,4 +1,4 @@ -//! The `std::tuple` module. +//! The [`Tuple`] fixed collection. use core::cmp::Ordering; @@ -6,7 +6,38 @@ use crate as rune; use crate::runtime::{EnvProtocolCaller, Hasher, Iterator, Ref, Tuple, Value, Vec, VmResult}; use crate::{ContextError, Module}; -/// Dynamic tuples. +/// The [`Tuple`] fixed collection. +/// +/// Tuples are anonymous types that can hold a fixed number of elements. +/// +/// Tuples in Rune are declared with the special `(a)` syntax, but can also be +/// interacted with through the fundamental [`Tuple`] type. +/// +/// Once a tuple has been declared, its size cannot change. +/// +/// The tuple type has support for native pattern matching: +/// +/// ``` +/// let value = (1, 2); +/// +/// if let (a, b) = value { +/// assert_eq!(a, 1); +/// assert_eq!(a, 2); +/// } +/// ``` +/// +/// # Examples +/// +/// ``` +/// let empty = (,); +/// let one = (10,); +/// let two = (10, 20); +/// +/// assert!(empty.is_empty()); +/// assert_eq!(one.0, 10); +/// assert_eq!(two.0, 10); +/// assert_eq!(two.1, 20); +/// ``` #[rune::module(::std::tuple)] pub fn module() -> Result { let mut m = Module::from_meta(self::module_meta)?; diff --git a/crates/rune/src/modules/vec.rs b/crates/rune/src/modules/vec.rs index db0aa8413..9bb09b286 100644 --- a/crates/rune/src/modules/vec.rs +++ b/crates/rune/src/modules/vec.rs @@ -1,4 +1,4 @@ -//! The `std::vec` module. +//! The [`Vec`] dynamic vector. use core::cmp::Ordering; @@ -10,9 +10,40 @@ use crate::runtime::{ }; use crate::{ContextError, Module}; -/// Construct the `std::vec` module. +/// The [`Vec`] dynamic vector. +/// +/// The vector type is a growable dynamic array that can hold an ordered +/// collection of values. +/// +/// Tuples in Rune are declared with the special `[a]` syntax, but can also be +/// interacted with through the fundamental [`Vec`] type. +/// +/// The vector type has support for native pattern matching: +/// +/// ``` +/// let value = [1, 2]; +/// +/// if let [a, b] = value { +/// assert_eq!(a, 1); +/// assert_eq!(a, 2); +/// } +/// ``` +/// +/// # Examples +/// +/// ``` +/// let empty = []; +/// let one = [10]; +/// let two = [10, 20]; +/// +/// assert!(empty.is_empty()); +/// assert_eq!(one.0, 10); +/// assert_eq!(two.0, 10); +/// assert_eq!(two.1, 20); +/// ``` +#[rune::module(::std::vec)] pub fn module() -> Result { - let mut m = Module::with_crate_item("std", ["vec"])?; + let mut m = Module::from_meta(self::module_meta)?; m.ty::()?.docs([ "A dynamic vector.",