diff options
Diffstat (limited to 'mingling')
| -rw-r--r-- | mingling/Cargo.toml | 12 | ||||
| -rw-r--r-- | mingling/mingling-ci.toml | 2 | ||||
| -rw-r--r-- | mingling/src/example_docs.rs | 98 | ||||
| -rw-r--r-- | mingling/src/features.rs | 55 | ||||
| -rw-r--r-- | mingling/src/lib.rs | 4 | ||||
| -rw-r--r-- | mingling/src/setups/dirs.rs | 70 | ||||
| -rw-r--r-- | mingling/src/setups/exit_code.rs | 56 |
7 files changed, 103 insertions, 194 deletions
diff --git a/mingling/Cargo.toml b/mingling/Cargo.toml index 6130b1b..7c7993b 100644 --- a/mingling/Cargo.toml +++ b/mingling/Cargo.toml @@ -25,7 +25,6 @@ features = [ "docs_rs", "core", "macros", - "builds", "structural_renderer", "repl", "comp", @@ -40,8 +39,6 @@ features = [ mini = ["extras", "picker"] advanced = ["extras", "picker", "repl", "comp", "dispatch_tree", "structural_renderer"] full = ["extras", "picker", "repl", "clap", "comp", "dispatch_tree", "structural_renderer_full", "pathf"] -build_advanced = ["build", "comp"] -build_full = ["build", "comp", "pathf", "dispatch_tree"] # Core core = ["dep:mingling_core", "mingling_core/default"] @@ -52,7 +49,6 @@ nightly = ["mingling_core/nightly", "mingling_macros/nightly"] debug = ["mingling_core/debug"] async = ["mingling_core/async", "mingling_macros/async"] default = ["core", "macros"] -build = ["mingling_core/build"] # - Section only shown in docs.rs docs_rs = [] @@ -62,7 +58,7 @@ dispatch_tree = ["mingling_macros/dispatch_tree"] repl = ["mingling_core/repl", "mingling_macros/repl"] comp = ["mingling_core/comp", "mingling_macros/comp"] picker = ["mingling_core/picker", "dep:arg-picker", "arg-picker/mingling_support"] -pathf = ["mingling_core/pathf", "mingling_macros/pathf"] +pathf = ["mingling_macros/pathf"] structural_renderer = [ "mingling_core/structural_renderer", @@ -98,12 +94,6 @@ ron_serde_fmt = ["mingling_core/ron_serde_fmt"] extras = ["mingling_macros/extras"] -# - LEGACY - -# These are old names, will be Breaking Change in the future - -builds = ["mingling_core/build"] -extra_macros = ["mingling_macros/extras"] - [dependencies] mingling_core = { workspace = true, optional = true } mingling_macros = { workspace = true, optional = true } diff --git a/mingling/mingling-ci.toml b/mingling/mingling-ci.toml new file mode 100644 index 0000000..767c133 --- /dev/null +++ b/mingling/mingling-ci.toml @@ -0,0 +1,2 @@ +[test] +command = ["cargo", "test", "-p", "mingling", "--features", "<<<features>>>"] diff --git a/mingling/src/example_docs.rs b/mingling/src/example_docs.rs index d37e762..055615d 100644 --- a/mingling/src/example_docs.rs +++ b/mingling/src/example_docs.rs @@ -595,11 +595,13 @@ pub mod example_clap_binding {} /// > Types are defined in a submodule (`sub`), and `gen_program!()` resolves /// > them automatically via pathf without explicit `use` imports. /// > -/// > **Important**: `dispatch_tree` must be enabled in BOTH `[dependencies]` -/// > AND `[build-dependencies]` so that pathf's builder can detect -/// > `__internal_dispatcher_*` types needed by the dispatch tree. +/// > **Important**: `dispatch_tree` must be enabled so that pathf's builder can +/// > detect `__internal_dispatcher_*` types needed by the dispatch tree. /// > /// > Also requires `extras` for the implicit `dispatcher!("hello")` form. +/// > +/// > With the `pathf` feature, `gen_program!()` automatically invokes +/// > `build_pathf!()` at compile time — no `build.rs` needed. /// /// Run: /// ```bash @@ -625,19 +627,6 @@ pub mod example_clap_binding {} /// "pathf", /// ] } /// -/// [build-dependencies] -/// mingling = { path = "../../mingling", features = [ -/// "builds", -/// -/// # --------- IMPORTANT --------- -/// # To use pathf under dispatch_tree -/// # **must** enable the `dispatch_tree` -/// # feature in build dependencies -/// "dispatch_tree", -/// "pathf", -/// # --------- IMPORTANT --------- -/// ] } -/// /// [workspace] /// ``` /// @@ -691,15 +680,6 @@ pub mod example_combine_pathf_dispatch_tree {} /// "pathf", /// ] /// -/// [build-dependencies.mingling] -/// path = "../../mingling" -/// features = [ -/// # Enable the `build` feature for build-time support -/// "build", -/// # `pathf` must also be enabled in build-dependencies -/// "pathf", -/// ] -/// /// [workspace] /// ``` /// @@ -811,30 +791,15 @@ pub mod example_command_macro {} /// To make your completions work, you need to generate a completion script using Mingling's tools /// /// 1. Enable features -/// You need to enable the `build` and `comp` features for `mingling` in `[build-dependencies]` -/// -/// 2. Write `build.rs` -/// Write the following in `build.rs` -/// -/// ```rust,ignore -/// fn main() { -/// build_scripts(); -/// } -/// -/// /// Generate completion scripts -/// fn build_scripts() { -/// // `env!("CARGO_PKG_NAME")` equals the crate name, which matches the binary name. -/// // If your binary name differs from the crate name, specify it explicitly. -/// mingling::build::build_comp_scripts( -/// // Your binary name: -/// env!("CARGO_PKG_NAME"), -/// ) -/// .unwrap(); -/// } -/// ``` +/// Enable the `comp` feature for `mingling` in `[dependencies]` +/// +/// 2. Generate completion scripts +/// When the `comp` feature is enabled, `gen_program!()` automatically invokes +/// `build_comp!()` at compile time, which generates the completion scripts +/// (named after `CARGO_PKG_NAME`) into `target/mingling/`. /// /// 3. Verify -/// Build your project with `cargo build --release`. The completion scripts will be generated in `target/release/` +/// Build your project with `cargo build`. The completion scripts will be generated in `target/mingling/` /// /// Execute the script or have it be automatically sourced by your Shell /// @@ -864,18 +829,6 @@ pub mod example_command_macro {} /// "picker", /// ] /// -/// [build-dependencies.mingling] -/// path = "../../mingling" -/// -/// features = [ -/// # Enable `comp` features -/// "comp", -/// -/// # If you want to build completion scripts, -/// # enable `build` features -/// "build", -/// ] -/// /// [workspace] /// ``` /// @@ -893,12 +846,12 @@ pub mod example_command_macro {} /// } /// /// // --------- IMPORTANT --------- -/// // __________________________________________ Entry point bound to completion behavior -/// // / _________________________ Shell context for obtaining user input state -/// // | / ________ Suggest, used to return completion results -/// // vvvvvvvvvv | / -/// #[completion(EntryGreet)] // vvvvvvvvvvvv vvvvvvv -/// fn complete_greet_entry(ctx: &ShellContext) -> Suggest { +/// // _________________________________________ Entry point bound to completion behavior +/// // / _________________________ Shell context for obtaining user input state +/// // | / ________ Suggest, used to return completion results +/// // vvvvvvvvvv | / +/// #[completion(EntryGreet)] // vvvvvvvvvvvv vvvvvvv +/// fn complete_greet_entry(ctx: ShellContext) -> Suggest { /// // When the previous word is `greet` (the current command being typed) /// if ctx.previous_word == "greet" { /// // Return suggestions @@ -1178,7 +1131,7 @@ pub mod example_dispatch_tree {} /// } /// /// #[completion(EntryLanguageSelection)] -/// fn complete_language_selection(_: &ShellContext) -> Suggest { +/// fn complete_language_selection(_: ShellContext) -> Suggest { /// // Use `suggest_enum!` directly to generate enum suggestions /// suggest_enum!(ProgrammingLanguages) /// } @@ -1365,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(); @@ -2104,17 +2057,6 @@ pub mod example_panic_unwind {} /// "pathf", /// ] /// -/// [build-dependencies.mingling] -/// path = "../../mingling" -/// -/// features = [ -/// # Enable `pathf` features -/// "pathf", -/// -/// # Enable the `build` feature for build-time support -/// "build", -/// ] -/// /// [workspace] /// ``` /// diff --git a/mingling/src/features.rs b/mingling/src/features.rs index 9445328..8a3ce75 100644 --- a/mingling/src/features.rs +++ b/mingling/src/features.rs @@ -31,50 +31,6 @@ pub const MINGLING_ASYNC: bool = false; #[cfg(feature = "async")] #[allow(unused)] pub const MINGLING_ASYNC: bool = true; -/// Whether the `build` feature is enabled -/// Current: `disabled` -#[cfg(not(feature = "build"))] -#[allow(unused)] -pub const MINGLING_BUILD: bool = false; - -/// Whether the `build` feature is enabled -/// Current: `enabled` -#[cfg(feature = "build")] -#[allow(unused)] -pub const MINGLING_BUILD: bool = true; -/// Whether the `build_advanced` feature is enabled -/// Current: `disabled` -#[cfg(not(feature = "build_advanced"))] -#[allow(unused)] -pub const MINGLING_BUILD_ADVANCED: bool = false; - -/// Whether the `build_advanced` feature is enabled -/// Current: `enabled` -#[cfg(feature = "build_advanced")] -#[allow(unused)] -pub const MINGLING_BUILD_ADVANCED: bool = true; -/// Whether the `build_full` feature is enabled -/// Current: `disabled` -#[cfg(not(feature = "build_full"))] -#[allow(unused)] -pub const MINGLING_BUILD_FULL: bool = false; - -/// Whether the `build_full` feature is enabled -/// Current: `enabled` -#[cfg(feature = "build_full")] -#[allow(unused)] -pub const MINGLING_BUILD_FULL: bool = true; -/// Whether the `builds` feature is enabled -/// Current: `disabled` -#[cfg(not(feature = "builds"))] -#[allow(unused)] -pub const MINGLING_BUILDS: bool = false; - -/// Whether the `builds` feature is enabled -/// Current: `enabled` -#[cfg(feature = "builds")] -#[allow(unused)] -pub const MINGLING_BUILDS: bool = true; /// Whether the `clap` feature is enabled /// Current: `disabled` #[cfg(not(feature = "clap"))] @@ -152,17 +108,6 @@ pub const MINGLING_DOCS_RS: bool = false; #[cfg(feature = "docs_rs")] #[allow(unused)] pub const MINGLING_DOCS_RS: bool = true; -/// Whether the `extra_macros` feature is enabled -/// Current: `disabled` -#[cfg(not(feature = "extra_macros"))] -#[allow(unused)] -pub const MINGLING_EXTRA_MACROS: bool = false; - -/// Whether the `extra_macros` feature is enabled -/// Current: `enabled` -#[cfg(feature = "extra_macros")] -#[allow(unused)] -pub const MINGLING_EXTRA_MACROS: bool = true; /// Whether the `extras` feature is enabled /// Current: `disabled` #[cfg(not(feature = "extras"))] diff --git a/mingling/src/lib.rs b/mingling/src/lib.rs index 55240e5..45c8ec3 100644 --- a/mingling/src/lib.rs +++ b/mingling/src/lib.rs @@ -64,6 +64,10 @@ pub mod macros { #[cfg(feature = "picker")] pub use arg_picker::macros::*; pub use mingling_macros::buffer; + #[cfg(feature = "comp")] + pub use mingling_macros::build_comp; + #[cfg(feature = "pathf")] + pub use mingling_macros::build_pathf; pub use mingling_macros::chain; #[cfg(feature = "extras")] pub use mingling_macros::command; diff --git a/mingling/src/setups/dirs.rs b/mingling/src/setups/dirs.rs index ea7f282..65196c2 100644 --- a/mingling/src/setups/dirs.rs +++ b/mingling/src/setups/dirs.rs @@ -1,37 +1,53 @@ -// Doc Not Optimize -use std::marker::PhantomData; - -use mingling_core::{ProgramCollect, setup::ProgramSetup}; +use mingling_core::{Program, ProgramCollect, setup::ProgramSetup}; use crate::res::{ResCurrentDir, ResCurrentExe, ResHomeDir, ResTempDir}; -/// Provides the ability to set up commonly used directory resources for the program. -/// -/// This setup item registers the following directory resources in the program: -/// - `ResCurrentDir`: Current working directory -/// - `ResCurrentExe`: Directory containing the executable -/// - `ResHomeDir`: User's home directory -/// - `ResTempDir`: Temporary directory -pub struct DirectoryEnvironmentSetup<C> { - _collect: PhantomData<C>, -} - -impl<C> Default for DirectoryEnvironmentSetup<C> -where - C: ProgramCollect<Enum = C> + 'static, -{ - fn default() -> Self { - Self { - _collect: PhantomData, - } - } -} +/// `Directory Environment` Setup for managing common directory resources +/// +/// This Setup registers commonly used directory resources into the program's +/// resource store. It provides the current working directory, the executable's +/// directory, the user's home directory, and the system's temporary directory, +/// so that these paths can be retrieved from the resource store without +/// recomputing them each time. +/// +/// # 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::DirectoryEnvironmentSetup; +/// +/// let mut program = Program::<ThisProgram>::new(); +/// program.with_setup(DirectoryEnvironmentSetup); +/// ``` +/// +/// # Behavior +/// +/// - Registers an [`ResCurrentDir`] resource containing the current working +/// directory. +/// - Registers an [`ResCurrentExe`] resource containing the directory of the +/// currently running executable. +/// - Registers an [`ResHomeDir`] resource containing the user's home directory. +/// - Registers an [`ResTempDir`] resource containing the system's temporary +/// directory. +/// +/// # Notes +/// +/// - All directory values are resolved at setup time and stored in the +/// resource store. +/// - These resources can be retrieved later using the program's `resource` +/// accessor with the corresponding resource type. +pub struct DirectoryEnvironmentSetup; -impl<C> ProgramSetup<C> for DirectoryEnvironmentSetup<C> +impl<C> ProgramSetup<C> for DirectoryEnvironmentSetup where C: ProgramCollect<Enum = C> + 'static, { - fn setup(self, program: &mut crate::Program<C>) { + fn setup(self, program: &mut Program<C>) { program.with_resource(ResCurrentDir::default()); program.with_resource(ResCurrentExe::default()); program.with_resource(ResHomeDir::default()); diff --git a/mingling/src/setups/exit_code.rs b/mingling/src/setups/exit_code.rs index e31e511..49d5f9f 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,43 @@ 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`. +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 }); |