diff options
Diffstat (limited to 'mingling_core/src/any.rs')
| -rw-r--r-- | mingling_core/src/any.rs | 31 |
1 files changed, 31 insertions, 0 deletions
diff --git a/mingling_core/src/any.rs b/mingling_core/src/any.rs index dac0d44..d550ec7 100644 --- a/mingling_core/src/any.rs +++ b/mingling_core/src/any.rs @@ -6,8 +6,18 @@ use serde::Serialize; use crate::Groupped; use crate::error::ChainProcessError; +#[doc(hidden)] pub mod group; +/// Any type output +/// +/// Accepts any type that implements `Send + Groupped<G>` +/// After being passed into AnyOutput, it will be converted to `Box<dyn Any + Send + 'static>` +/// +/// Note: +/// - If an enum value that does not belong to this type is incorrectly specified, it will be **unsafely** unwrapped by the scheduler +/// - Under the `general_renderer` feature, the passed value must ensure it implements `serde::Serialize` +/// - It is recommended to use the `pack!` macro from [mingling_macros](https://crates.io/crates/mingling_macros) to create types that can be converted to `AnyOutput`, which guarantees runtime safety #[derive(Debug)] pub struct AnyOutput<G> where @@ -22,6 +32,7 @@ impl<G> AnyOutput<G> where G: Display, { + /// Create an AnyOutput from a `Send + Groupped<G> + Serialize` type #[cfg(feature = "general_renderer")] pub fn new<T>(value: T) -> Self where @@ -34,6 +45,7 @@ where } } + /// Create an AnyOutput from a `Send + Groupped<G>` type #[cfg(not(feature = "general_renderer"))] pub fn new<T>(value: T) -> Self where @@ -46,6 +58,7 @@ where } } + /// Downcast the AnyOutput to a concrete type T pub fn downcast<T: 'static>(self) -> Result<T, Self> { if self.type_id == std::any::TypeId::of::<T>() { Ok(*self.inner.downcast::<T>().unwrap()) @@ -54,6 +67,7 @@ where } } + /// Check if the inner value is of type T pub fn is<T: 'static>(&self) -> bool { self.type_id == std::any::TypeId::of::<T>() } @@ -89,6 +103,12 @@ where } } +/// Chain exec result type +/// +/// Stores `Ok` and `Err` types of execution results, used to notify the scheduler what to execute next +/// - Returns `Ok((`[`AnyOutput`](./struct.AnyOutput.html)`, `[`Next::Chain`](./enum.Next.html)`))` to continue execution with this type next +/// - Returns `Ok((`[`AnyOutput`](./struct.AnyOutput.html)`, `[`Next::Renderer`](./enum.Next.html)`))` to render this type next and output to the terminal +/// - Returns `Err(`[`ChainProcessError`](./error/enum.ChainProcessError.html)`]` to terminate the program directly pub enum ChainProcess<G> where G: Display, @@ -97,6 +117,10 @@ where Err(ChainProcessError), } +/// Indicates the next step after processing +/// +/// - `Chain`: Continue execution to the next chain +/// - `Renderer`: Send output to renderer and end execution pub enum Next { Chain, Renderer, @@ -106,14 +130,17 @@ impl<G> ChainProcess<G> where G: Display, { + /// Returns true if the result is Ok (has a next step) pub fn is_next(&self) -> bool { matches!(self, Self::Ok(_)) } + /// Returns true if the result is an error pub fn is_err(&self) -> bool { matches!(self, Self::Err(_)) } + /// Returns the next step if the result is Ok pub fn next(&self) -> Option<&Next> { match self { Self::Ok((_, next)) => Some(next), @@ -121,6 +148,7 @@ where } } + /// Returns the error if the result is Err pub fn err(&self) -> Option<&ChainProcessError> { match self { Self::Ok(_) => None, @@ -128,6 +156,7 @@ where } } + /// Unwraps the result, panics if it's an error pub fn unwrap(self) -> (AnyOutput<G>, Next) { match self { Self::Ok(tuple) => tuple, @@ -135,6 +164,7 @@ where } } + /// Returns the Ok value or a provided default pub fn unwrap_or(self, default: (AnyOutput<G>, Next)) -> (AnyOutput<G>, Next) { match self { Self::Ok(tuple) => tuple, @@ -142,6 +172,7 @@ where } } + /// Returns the Ok value or computes it from the error pub fn unwrap_or_else<F>(self, f: F) -> (AnyOutput<G>, Next) where F: FnOnce(ChainProcessError) -> (AnyOutput<G>, Next), |