diff options
Diffstat (limited to 'mingling/src')
| -rw-r--r-- | mingling/src/example_docs.rs | 2 | ||||
| -rw-r--r-- | mingling/src/setups/exit_code.rs | 62 |
2 files changed, 40 insertions, 24 deletions
diff --git a/mingling/src/example_docs.rs b/mingling/src/example_docs.rs index c9955b5..055615d 100644 --- a/mingling/src/example_docs.rs +++ b/mingling/src/example_docs.rs @@ -1318,7 +1318,7 @@ pub mod example_error_handling {} /// /// // --------- IMPORTANT --------- /// // Register `ExitCodeSetup` for the program to enable exit codes -/// program.with_setup(ExitCodeSetup::default()); +/// program.with_setup(ExitCodeSetup); /// // --------- IMPORTANT --------- /// /// program.exec_and_exit(); diff --git a/mingling/src/setups/exit_code.rs b/mingling/src/setups/exit_code.rs index e31e511..0558892 100644 --- a/mingling/src/setups/exit_code.rs +++ b/mingling/src/setups/exit_code.rs @@ -1,8 +1,5 @@ -// Doc Not Optimize -use std::marker::PhantomData; - use mingling_core::{ - ProgramCollect, + Program, ProgramCollect, hook::{ProgramControlUnit, ProgramControls, ProgramHook}, setup::ProgramSetup, this, @@ -10,30 +7,49 @@ use mingling_core::{ use crate::res::ResExitCode; -/// Provides the ability to control the program's exit code, which is returned when the program ends. +/// `ExitCodeSetup` — Setup for controlling the program's exit code /// -/// - Use `mingling::update_exit_code` to update the exit code. -/// - Use `mingling::current_exit_code` to query the current exit code. -pub struct ExitCodeSetup<C> { - _collect: PhantomData<C>, -} - -impl<C> Default for ExitCodeSetup<C> -where - C: ProgramCollect<Enum = C> + 'static, -{ - fn default() -> Self { - Self { - _collect: PhantomData, - } - } -} +/// This Setup registers an [`ResExitCode`] resource that tracks the desired exit +/// code for the program. When the program finishes, a hook reads this resource +/// and overrides the program's exit code if it has been modified from its +/// default value of `0`. +/// +/// # Usage +/// +/// This Setup can be registered using the +/// [`Program`](https://docs.rs/mingling/latest/mingling/struct.Program.html) +/// `with_setup` method, for example: +/// +/// ```rust +/// # use mingling::MockProgramCollect as ThisProgram; +/// use mingling::Program; +/// use mingling::setup::ExitCodeSetup; +/// +/// let mut program = Program::<ThisProgram>::new(); +/// program.with_setup(ExitCodeSetup); +/// ``` +/// +/// # Behavior +/// +/// - Registers an [`ResExitCode`] resource initialised to `0`. +/// - Installs a program-finish hook that: +/// - Reads the current [`ResExitCode`] value. +/// - Overrides the program's exit code with that value if it is non-zero. +/// - Leaves the exit code untouched if the resource still holds its default +/// value of `0`. +/// +/// # Notes +/// +/// - Use [`update_exit_code`](crate::update_exit_code) to set a custom exit code +/// during program execution. +/// - Use [`current_exit_code`](crate::current_exit_code) to query the current value. +pub struct ExitCodeSetup; -impl<C> ProgramSetup<C> for ExitCodeSetup<C> +impl<C> ProgramSetup<C> for ExitCodeSetup where C: ProgramCollect<Enum = C> + 'static, { - fn setup(self, program: &mut crate::Program<C>) { + fn setup(self, program: &mut Program<C>) { // Insert resource program.with_resource(ResExitCode { exit_code: 0 }); |
