diff options
| -rw-r--r-- | mingling/src/lib.rs | 63 | ||||
| -rw-r--r-- | mingling_core/src/any.rs | 2 | ||||
| -rw-r--r-- | mingling_core/src/any/group.rs | 2 | ||||
| -rw-r--r-- | mingling_core/src/debug.rs | 7 | ||||
| -rw-r--r-- | mingling_core/src/program/collection/mock.rs | 1 | ||||
| -rw-r--r-- | mingling_core/src/program/config.rs | 12 | ||||
| -rw-r--r-- | mingling_core/src/program/hook.rs | 45 |
7 files changed, 103 insertions, 29 deletions
diff --git a/mingling/src/lib.rs b/mingling/src/lib.rs index b021479..b4372dc 100644 --- a/mingling/src/lib.rs +++ b/mingling/src/lib.rs @@ -47,7 +47,7 @@ //! gen_program!(); //! ``` //! -// Output: +//! Output: //! //! ```text //! > mycmd greet @@ -60,7 +60,10 @@ //! //! # Examples //! `Mingling` provides detailed usage examples for your reference. -//! See [Examples](_mingling_examples/index.html) +//! See [Examples](_mingling_examples/index.html) or [Helpdoc](https://mingling-rs.github.io/mingling/docs/examples.html) +//! +//! # About Features +//! All features of `Mingling` are opt-in. To learn what each feature provides, see [Features](feature/index.html) or [Helpdoc](https://mingling-rs.github.io/mingling/docs/doc.html#/pages/other/features) mod example_docs; @@ -72,46 +75,56 @@ pub use mingling_core as mingling; #[cfg(feature = "parser")] pub mod parser; -/// Re-export from `mingling_macros` +/// Re-export of all macros from `mingling_macros`. +/// +/// This module re-exports all macros provided by the `mingling_macros` crate, +/// including `dispatcher!`, `chain!`, `renderer!`, `gen_program!`, `pack!`, +/// `r_print!`, `r_println!`, and many others. These macros form the core +/// building blocks of the Mingling framework. +/// +/// For detailed documentation, usage examples, and the full list of available +/// macros, please refer to the `mingling_macros` crate [documentation](https://docs.rs/mingling_macros/latest/mingling_macros/): +/// +/// <https://docs.rs/mingling_macros/latest/mingling_macros/> #[allow(unused_imports)] pub mod macros { - /// Used to generate a struct implementing the `Chain` trait via a method + /// `#[chain]` - Used to generate a struct implementing the `Chain` trait via a method pub use mingling_macros::chain; - /// Used to generate completion entry + /// `#[completion(EntryType)]` - Used to generate completion entry #[cfg(feature = "comp")] pub use mingling_macros::completion; - /// Used to create a dispatcher that routes to a `Chain` + /// `dispatcher!("greet", CMDGreet => EntryGreet)` - Used to create a dispatcher that routes to a `Chain` pub use mingling_macros::dispatcher; - /// Used to create a dispatcher with clap argument parsing + /// `#[dispatcher_clap("greet", CMDGreet)]` - Used to create a dispatcher with clap argument parsing #[cfg(feature = "clap")] pub use mingling_macros::dispatcher_clap; - /// Used to create an empty result value for early return from a chain function + /// `empty_result!()` - Used to create an empty result value for early return from a chain function #[cfg(feature = "extra_macros")] pub use mingling_macros::empty_result; - /// Creates a packed entry value from a list of string literals + /// `entry!["--greet", "Alice"]` - Creates a packed entry value from a list of string literals #[cfg(feature = "extra_macros")] pub use mingling_macros::entry; - /// Used to collect data and create a command-line context + /// `gen_program!()` - Used to collect data and create a command-line context pub use mingling_macros::gen_program; - /// Used to register an external type as a group member + /// `group!(ErrorIo = std::io::Error)` - Used to register an external type as a group member #[cfg(feature = "extra_macros")] pub use mingling_macros::group; - /// Like `group!` but also marks the type for structured output + /// `group_structural!(ErrorIo = std::io::Error)` - Like `group!` but also marks the type for structured output #[cfg(all(feature = "structural_renderer", feature = "extra_macros"))] pub use mingling_macros::group_structural; - /// Used to generate a struct implementing the `HelpRequest` trait via a method + /// `#[help]` - Used to generate a struct implementing the `HelpRequest` trait via a method pub use mingling_macros::help; - /// Used to create a `Node` struct via a literal + /// `node!("remote.rm")` - Used to create a `Node` struct via a literal pub use mingling_macros::node; - /// Used to create a wrapper type for use with `Chain` and `Renderer` + /// `pack!(StateGreet = String)` - Used to create a wrapper type for use with `Chain` and `Renderer` pub use mingling_macros::pack; - /// Like `pack!` but also marks the type for structured output + /// `pack_structural!(StateGreet = String)` - Like `pack!` but also marks the type for structured output #[cfg(feature = "structural_renderer")] pub use mingling_macros::pack_structural; - /// Used to create an error struct with automatic `name` field + /// `pack_err!(ErrorUnknown)` - Used to create an error struct with automatic `name` field #[cfg(feature = "extra_macros")] pub use mingling_macros::pack_err; - /// Like `pack_err!` but also marks the type for structured output + /// `pack_err_structural!(ErrorUnknown)` - Like `pack_err!` but also marks the type for structured output #[cfg(all(feature = "structural_renderer", feature = "extra_macros"))] pub use mingling_macros::pack_err_structural; #[cfg(feature = "comp")] @@ -121,12 +134,12 @@ pub mod macros { pub use mingling_macros::program_fallback_gen; #[doc(hidden)] pub use mingling_macros::program_final_gen; - /// Used to generate program setup + /// `#[program_setup]` - Used to generate program setup #[cfg(feature = "extra_macros")] pub use mingling_macros::program_setup; - /// Used to print content within a `Renderer` context + /// `r_print!("{someting}")` - Used to print content within a `Renderer` context pub use mingling_macros::r_print; - /// Used to print content with a newline within a `Renderer` context + /// `r_println!("{someting}")` - Used to print content with a newline within a `Renderer` context pub use mingling_macros::r_println; #[doc(hidden)] pub use mingling_macros::register_chain; @@ -138,16 +151,16 @@ pub mod macros { pub use mingling_macros::register_renderer; #[doc(hidden)] pub use mingling_macros::register_type; - /// Used to generate a struct implementing the `Renderer` trait via a method + /// `#[renderer]` - Used to generate a struct implementing the `Renderer` trait via a method pub use mingling_macros::renderer; - /// Used to generate a route that either returns a successful result or early returns an error. + /// `route! { /* ... */ }` - Used to generate a route that either returns a successful result or early returns an error. #[cfg(feature = "extra_macros")] pub use mingling_macros::route; + /// `suggest! { "hello", "bye" }` - Used to generate suggestions #[cfg(feature = "comp")] - /// Used to generate suggestions pub use mingling_macros::suggest; + /// `suggest_enum!(EnumNames)` - Used to generate enum suggestions #[cfg(feature = "comp")] - /// Used to generate enum suggestions pub use mingling_macros::suggest_enum; } diff --git a/mingling_core/src/any.rs b/mingling_core/src/any.rs index b115e28..b586f09 100644 --- a/mingling_core/src/any.rs +++ b/mingling_core/src/any.rs @@ -12,7 +12,7 @@ pub mod group; /// Note: /// - If an enum value that does not belong to this type is incorrectly specified, it will be **unsafely** unwrapped by the scheduler /// - Structured output via `--json`/`--yaml` is only available for types that implement -/// [`StructuralData`], which implies `serde::Serialize`. +/// \[`StructuralData`\], which implies `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> { diff --git a/mingling_core/src/any/group.rs b/mingling_core/src/any/group.rs index afe5e3a..cb847d9 100644 --- a/mingling_core/src/any/group.rs +++ b/mingling_core/src/any/group.rs @@ -4,7 +4,7 @@ use crate::{AnyOutput, ChainProcess}; /// /// **Note:** Unlike earlier versions, `Groupped` no longer requires `Serialize` /// even when the `structural_renderer` feature is enabled. Structured output is -/// controlled separately via the [`StructalData`] trait. +/// controlled separately via the \[`StructuralData`\] trait. pub trait Groupped<Group> where Self: Sized + 'static, diff --git a/mingling_core/src/debug.rs b/mingling_core/src/debug.rs index f92cd3d..4865016 100644 --- a/mingling_core/src/debug.rs +++ b/mingling_core/src/debug.rs @@ -1,4 +1,5 @@ #[macro_export] +#[doc(hidden)] /// A macro that only executes the given expressions when the `debug` feature is enabled. /// If the feature is not enabled, the expressions are compiled away. macro_rules! only_debug { @@ -11,6 +12,7 @@ macro_rules! only_debug { } #[macro_export] +#[doc(hidden)] /// Logs a message at the trace level, but only if the `debug` feature is enabled. /// Delegates to `log::trace!` internally. macro_rules! trace { @@ -22,6 +24,7 @@ macro_rules! trace { } #[macro_export] +#[doc(hidden)] /// Logs a message at the debug level, but only if the `debug` feature is enabled. /// Delegates to `log::debug!` internally. macro_rules! debug { @@ -33,6 +36,7 @@ macro_rules! debug { } #[macro_export] +#[doc(hidden)] /// Logs a message at the info level, but only if the `debug` feature is enabled. /// Delegates to `log::info!` internally. macro_rules! info { @@ -44,6 +48,7 @@ macro_rules! info { } #[macro_export] +#[doc(hidden)] /// Logs a message at the warn level, but only if the `debug` feature is enabled. /// Delegates to `log::warn!` internally. macro_rules! warn { @@ -55,6 +60,7 @@ macro_rules! warn { } #[macro_export] +#[doc(hidden)] /// Logs a message at the error level, but only if the `debug` feature is enabled. /// Delegates to `log::error!` internally. macro_rules! error { @@ -66,6 +72,7 @@ macro_rules! error { } #[cfg(feature = "debug")] +#[doc(hidden)] pub fn init_env_logger() { let mut log_path = std::env::current_exe() .expect("Failed to get current executable path") diff --git a/mingling_core/src/program/collection/mock.rs b/mingling_core/src/program/collection/mock.rs index b37a709..568000a 100644 --- a/mingling_core/src/program/collection/mock.rs +++ b/mingling_core/src/program/collection/mock.rs @@ -17,6 +17,7 @@ use serde::Serialize; #[cfg_attr(feature = "structural_renderer", derive(Serialize))] #[allow(unused)] +#[doc(hidden)] pub enum MockProgramCollect { Foo, Bar, diff --git a/mingling_core/src/program/config.rs b/mingling_core/src/program/config.rs index 6d54a4e..c5f91da 100644 --- a/mingling_core/src/program/config.rs +++ b/mingling_core/src/program/config.rs @@ -42,13 +42,21 @@ pub struct ProgramStdoutSetting { pub clap_help_print_behaviour: ClapHelpPrintBehaviour, } +/// Behavior when Clap Dispatcher outputs help information #[cfg(feature = "clap")] #[derive(Debug, Default, Clone)] pub enum ClapHelpPrintBehaviour { - /// Write to RenderResult + /// Write help information to `RenderResult` instead of printing to stdout directly. + /// + /// This allows the help text to be captured and processed as part of the program's + /// structured output, which is useful when integrating with external tools or + /// when the output needs to be further transformed. WriteToRenderResult, - /// Print directly + /// Print help information directly to stdout. + /// + /// This is the default behavior, which prints help text immediately to the terminal + /// without any intermediate processing or capture. #[default] PrintDirectly, } diff --git a/mingling_core/src/program/hook.rs b/mingling_core/src/program/hook.rs index cd758ca..630baae 100644 --- a/mingling_core/src/program/hook.rs +++ b/mingling_core/src/program/hook.rs @@ -1,5 +1,40 @@ #![allow(dead_code)] +//! Program lifecycle hook system. +//! +//! The hook system lets you observe and influence the program's execution +//! at well-defined lifecycle points — before dispatch, after chain processing, +//! on finish, etc. +//! +//! # Architecture +//! +//! Hooks are registered on [`ProgramHook`] via builder methods (`.on_begin()`, +//! `.on_pre_dispatch()`, `.on_finish()`, …) and attached to the program with +//! [`Program::with_hook`]. +//! +//! Each hook callback receives a structured info type (e.g. [`HookPreDispatchInfo`]) +//! and returns either `()` (no-op) or a [`ProgramControlUnit`] / [`ProgramControls`] +//! to influence the execution flow (override exit code, re-route to another +//! chain/renderer/help, etc.). +//! +//! # Hook Lifecycle Order +//! +//! ```text +//! begin +//! │ +//! ├─ pre_dispatch ← before an entry is dispatched +//! ├─ post_dispatch ← after dispatching, before chain +//! ├─ pre_chain ← before the type enters the chain pipeline +//! ├─ post_chain ← after chain processing completes +//! ├─ pre_render ← before the type enters the renderer +//! ├─ post_render ← after rendering completes +//! │ +//! finish ← before program exits +//! ``` +//! +//! When the `repl` feature is enabled, additional REPL-specific hooks are +//! available (e.g. `repl_post_readline`, `repl_on_receive_result`). + use crate::{Program, ProgramCollect}; mod hook_info; @@ -8,6 +43,16 @@ pub use hook_info::*; mod control_unit; pub use control_unit::*; +/// The program's lifecycle hook registry. +/// +/// `ProgramHook<C>` stores optional callbacks for each supported lifecycle +/// event — from program start (`begin`) through dispatch, chaining, rendering, +/// and finally program exit (`finish`). +/// +/// Hooks are constructed via the builder pattern (see methods like +/// [`on_begin`](Self::on_begin), [`on_pre_dispatch`](Self::on_pre_dispatch), +/// etc.) and attached to a [`Program`] using +/// [`Program::with_hook`]. #[derive(Default)] #[allow(clippy::type_complexity)] // Shutup! pub struct ProgramHook<C> |