diff options
Diffstat (limited to 'mingling_core/src/program')
| -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 |
3 files changed, 56 insertions, 2 deletions
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> |