aboutsummaryrefslogtreecommitdiff
path: root/mingling/src
diff options
context:
space:
mode:
Diffstat (limited to 'mingling/src')
-rw-r--r--mingling/src/constants.rs3
-rw-r--r--mingling/src/constants/picker.rs16
-rw-r--r--mingling/src/example_docs.rs281
-rw-r--r--mingling/src/lib.rs20
-rw-r--r--mingling/src/picker/entry_picker.rs8
-rw-r--r--mingling/src/setups/picker/basic.rs15
6 files changed, 298 insertions, 45 deletions
diff --git a/mingling/src/constants.rs b/mingling/src/constants.rs
index 65d02e8..75f1c73 100644
--- a/mingling/src/constants.rs
+++ b/mingling/src/constants.rs
@@ -4,5 +4,8 @@ mod picker;
#[cfg(feature = "picker")]
pub use picker::*;
+#[cfg(feature = "picker")]
+pub use arg_picker::consts::*;
+
mod exit_codes;
pub use exit_codes::*;
diff --git a/mingling/src/constants/picker.rs b/mingling/src/constants/picker.rs
index f2a448b..d98dcab 100644
--- a/mingling/src/constants/picker.rs
+++ b/mingling/src/constants/picker.rs
@@ -1,20 +1,6 @@
+use arg_picker::{PickerArg, value::Flag};
use std::marker::PhantomData;
-use arg_picker::{PickerArg, PickerArgs, value::Flag};
-
-/// Remaining positional arguments (anything not consumed as an option).
-/// - `full`: `[]` (empty — not triggered by any `--` prefix).
-/// - `short`: (none)
-/// - `positional`: `false` (this is a meta‑argument that collects everything left).
-/// This constant is used internally to access any leftover arguments after
-/// all defined flags/options have been processed.
-pub const REMAINS: PickerArg<PickerArgs> = PickerArg::<PickerArgs> {
- full: &[],
- short: None,
- positional: false,
- internal_type: PhantomData,
-};
-
/// Help flag: display usage information.
/// - `full`: `["help"]`
/// - `short`: `'h'`
diff --git a/mingling/src/example_docs.rs b/mingling/src/example_docs.rs
index c4f59c9..bdefb5a 100644
--- a/mingling/src/example_docs.rs
+++ b/mingling/src/example_docs.rs
@@ -124,6 +124,251 @@
/// }
/// ```
pub mod example_argument_parse {}
+/// Example Argument Picker
+///
+/// > Demonstrates how to use Mingling's `picker` feature and `Picker` to extract typed arguments from the command line.
+///
+/// Run:
+/// ```bash
+/// cargo run --manifest-path examples/example-argument-picker/Cargo.toml --quiet -- calc 1 + 1
+/// cargo run --manifest-path examples/example-argument-picker/Cargo.toml --quiet -- calc 7 * 7
+/// cargo run --manifest-path examples/example-argument-picker/Cargo.toml --quiet -- calc
+/// cargo run --manifest-path examples/example-argument-picker/Cargo.toml --quiet -- calc 1
+/// cargo run --manifest-path examples/example-argument-picker/Cargo.toml --quiet -- calc 1 +
+/// cargo run --manifest-path examples/example-argument-picker/Cargo.toml --quiet -- calc 4 / 3
+/// cargo run --manifest-path examples/example-argument-picker/Cargo.toml --quiet -- calc 4 / 3 --round
+/// ```
+///
+/// Output:
+/// ```plaintext
+/// Result: 2
+/// Result: 49
+/// Error: First number (number_a) was not provided.
+/// Error: Operator was not provided.
+/// Error: Second number (number_b) was not provided.
+/// Result: 1.3333334
+/// Result: 1
+/// ```
+///
+/// Source code (./Cargo.toml)
+/// ```toml
+/// [package]
+/// name = "example-argument-picker"
+/// version = "0.1.0"
+/// edition = "2024"
+///
+/// [dependencies.mingling]
+/// path = "../../mingling"
+///
+/// # Enable `picker` features
+/// features = ["picker", "extra_macros"]
+///
+/// [workspace]
+/// ```
+///
+/// Source code (./src/main.rs)
+/// ```ignore
+/// use mingling::{
+/// consts::REMAINS,
+/// macros::route,
+/// picker::{
+/// IntoPicker, PickerArgResult, SinglePickable,
+/// parselib::{ParserStyle, UNIX_STYLE},
+/// value::Flag,
+/// },
+/// prelude::*,
+/// };
+///
+/// // --------- IMPORTANT ---------
+/// // Use picker::BasicProgramSetup instead of the original BasicProgramSetup
+/// // It uses arg-picker to rewrite the logic of the original BasicProgramSetup
+/// use mingling::setup::picker::BasicProgramSetup;
+///
+/// // --------- IMPORTANT ---------
+///
+/// dispatcher!("calc", CMDCalculate => EntryCalculate);
+///
+/// pack_err!(ErrorNumberANotProvided);
+/// pack_err!(ErrorNumberBNotProvided);
+/// pack_err!(ErrorNumberOperatorNotProvided);
+/// pack_err!(ErrorDivisionByZero);
+///
+/// pack!(StateAdd = (f32, f32));
+/// pack!(StateSubtract = (f32, f32));
+/// pack!(StateMultiply = (f32, f32));
+/// pack!(StateDivide = (f32, f32));
+///
+/// pack!(ResultNumber = f32);
+///
+/// #[derive(Grouped)]
+/// struct StateCalculate {
+/// number_a: f32,
+/// operator: Operator,
+/// number_b: f32,
+/// }
+///
+/// #[derive(Debug, PartialEq, Eq)]
+/// enum Operator {
+/// Plus,
+/// Dash,
+/// Slash,
+/// Star,
+/// }
+///
+/// // --------- IMPORTANT ---------
+/// // Define SinglePickable for type Operator
+/// // This allows the type to be picked as an argument
+/// impl SinglePickable for Operator {
+/// fn pick_single(str: Option<&str>) -> PickerArgResult<Self> {
+/// let Some(str) = str else {
+/// return PickerArgResult::NotFound;
+/// };
+/// let op = match str.chars().next() {
+/// Some('+') => Operator::Plus,
+/// Some('-') => Operator::Dash,
+/// Some('*') => Operator::Star,
+/// Some('/') => Operator::Slash,
+/// _ => return PickerArgResult::NotFound,
+/// };
+/// PickerArgResult::Parsed(op)
+/// }
+/// }
+/// // --------- IMPORTANT ---------
+///
+/// #[derive(Default, Clone)]
+/// struct ResNumberDisplaySetting {
+/// round: bool,
+/// }
+///
+/// fn main() {
+/// let mut program = ThisProgram::new();
+///
+/// // Use ParserStyle to manage the arg-picker theme
+/// ParserStyle::set_global_style(&UNIX_STYLE);
+///
+/// // Enable picker::BasicProgramSetup
+/// program.with_setup(BasicProgramSetup);
+///
+/// // --------- IMPORTANT ---------
+/// // Pre-process global arguments before executing commands
+/// let (round, args) = program
+/// .take_args()
+/// // Use arg![round: Flag] to indicate the `--round` | `-R` flag
+/// // |
+/// // vvvvvvvvvvvvvvvv
+/// .pick(&arg![round: Flag, 'R'])
+/// // Use REMAINS to extract remaining arguments
+/// // |
+/// // vvvvvvvv
+/// .pick(&REMAINS)
+/// // Since Flag and REMAINS will not fail to parse,
+/// // we can safely unwrap here
+/// .unwrap();
+/// program.replace_args(args.into());
+///
+/// program.with_resource(ResNumberDisplaySetting { round: *round });
+/// // --------- IMPORTANT ---------
+///
+/// program.with_dispatcher(CMDCalculate);
+/// program.exec_and_exit();
+/// }
+///
+/// #[chain]
+/// fn handle_calc(args: EntryCalculate) -> Next {
+/// // --------- IMPORTANT ---------
+/// let (number_a, operator, number_b) = route!(
+/// // Use the arg! macro to define a positional argument of type f32
+/// // |
+/// // vvvvvvvvvv
+/// args.pick_or_route(&arg![f32], || ErrorNumberANotProvided::default().to_chain())
+/// .pick_or_route(&arg![Operator], || {
+/// ErrorNumberOperatorNotProvided::default().to_chain()
+/// }) // Returns a routable type when not found or fails to parse
+/// // |
+/// // vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
+/// .pick_or_route(&arg![f32], || ErrorNumberBNotProvided::default().to_chain())
+/// // Use `to_result` to parse arguments
+/// // and convert to Result<(Tuple, ...), Route> type
+/// .to_result()
+/// );
+/// // --------- IMPORTANT ---------
+///
+/// if operator == Operator::Slash && number_b == 0. {
+/// return ErrorDivisionByZero::default().to_chain();
+/// }
+///
+/// StateCalculate {
+/// number_a,
+/// operator,
+/// number_b,
+/// }
+/// .to_chain()
+/// }
+///
+/// #[chain]
+/// fn handle_state_calculate(state: StateCalculate) -> Next {
+/// match (state.operator, state.number_a, state.number_b) {
+/// (Operator::Plus, a, b) => StateAdd::new((a, b)).to_chain(),
+/// (Operator::Dash, a, b) => StateSubtract::new((a, b)).to_chain(),
+/// (Operator::Slash, a, b) => StateDivide::new((a, b)).to_chain(),
+/// (Operator::Star, a, b) => StateMultiply::new((a, b)).to_chain(),
+/// }
+/// }
+///
+/// #[chain]
+/// fn handle_state_add(state_add: StateAdd) -> ResultNumber {
+/// let (a, b) = state_add.inner;
+/// ResultNumber::new(a + b)
+/// }
+///
+/// #[chain]
+/// fn handle_state_subtract(state_subtract: StateSubtract) -> ResultNumber {
+/// let (a, b) = state_subtract.inner;
+/// ResultNumber::new(a - b)
+/// }
+///
+/// #[chain]
+/// fn handle_state_multiply(state_multiply: StateMultiply) -> ResultNumber {
+/// let (a, b) = state_multiply.inner;
+/// ResultNumber::new(a * b)
+/// }
+///
+/// #[chain]
+/// fn handle_state_divide(state_divide: StateDivide) -> ResultNumber {
+/// let (a, b) = state_divide.inner;
+/// ResultNumber::new(a / b)
+/// }
+///
+/// #[renderer]
+/// fn render_result_number(result: ResultNumber, setting: &ResNumberDisplaySetting) -> String {
+/// let round = setting.round;
+/// let result = if round { result.round() } else { result.inner };
+/// format!("Result: {}", result)
+/// }
+///
+/// #[renderer]
+/// fn render_error_division_by_zero(_: ErrorDivisionByZero) -> String {
+/// "Error: Division by zero is not allowed!".to_string()
+/// }
+///
+/// #[renderer]
+/// fn render_error_number_a_not_provided(_: ErrorNumberANotProvided) -> String {
+/// "Error: First number (number_a) was not provided.".to_string()
+/// }
+///
+/// #[renderer]
+/// fn render_error_number_b_not_provided(_: ErrorNumberBNotProvided) -> String {
+/// "Error: Second number (number_b) was not provided.".to_string()
+/// }
+///
+/// #[renderer]
+/// fn render_error_number_operator_not_provided(_: ErrorNumberOperatorNotProvided) -> String {
+/// "Error: Operator was not provided.".to_string()
+/// }
+///
+/// gen_program!();
+/// ```
+pub mod example_argument_picker {}
/// Example Async Runtime Support
///
/// > This example shows how to drive an async runtime using the `async` feature
@@ -378,7 +623,7 @@ pub mod example_basic {}
///
/// Source code (./src/main.rs)
/// ```ignore
-/// use mingling::{Groupped, macros::dispatcher_clap, prelude::*, setup::BasicProgramSetup};
+/// use mingling::{Grouped, macros::dispatcher_clap, prelude::*, setup::BasicProgramSetup};
/// use std::io::Write;
///
/// fn main() {
@@ -407,10 +652,10 @@ pub mod example_basic {}
/// // Implement Clap Parser, and bind to Dispatcher
/// // _______________________________ Default trait, provides fallback on parse failure
/// // / ______________________ clap::Parser, parsing logic implemented by Clap
-/// // | / ________ Implement mingling::Groupped
+/// // | / ________ Implement mingling::Grouped
/// // | | / to ensure Mingling can recognize the type
-/// // vvvvvvv vvvvvvvvvvvv vvvvvvvv
-/// #[derive(Default, clap::Parser, Groupped)]
+/// // vvvvvvv vvvvvvvvvvvv vvvvvvv
+/// #[derive(Default, clap::Parser, Grouped)]
/// #[dispatcher_clap(
/// "greet", CMDGreet, // Bind EntryGreet to "greet" command
/// help = true, // Generate clap help for EntryGreet
@@ -724,15 +969,15 @@ pub mod example_completion {}
///
/// Source code (./src/main.rs)
/// ```ignore
-/// use mingling::{macros::route, parser::Pickable, prelude::*, Groupped};
+/// use mingling::{macros::route, parser::Pickable, prelude::*, Grouped};
/// use std::io::Write;
///
/// // Define types that can be recognized by Mingling
/// // ________________________ `Pickable` trait needs to implement Default
-/// // / ________ The Groupped derive macro registers an ID for this type
+/// // / ________ The Grouped derive macro registers an ID for this type
/// // | / Mingling uses this ID to identify the type
-/// // vvvvvvv vvvvvvvv
-/// #[derive(Debug, Default, Clone, Groupped)]
+/// // vvvvvvv vvvvvvv
+/// #[derive(Debug, Default, Clone, Grouped)]
/// pub struct Address {
/// pub ip: [u8; 4],
/// pub port: u16,
@@ -963,7 +1208,7 @@ pub mod example_dispatch_tree {}
/// Source code (./src/main.rs)
/// ```ignore
/// use mingling::{
-/// macros::suggest_enum, parser::PickableEnum, prelude::*, EnumTag, Groupped, ShellContext,
+/// macros::suggest_enum, parser::PickableEnum, prelude::*, EnumTag, Grouped, ShellContext,
/// Suggest,
/// };
/// use std::io::Write;
@@ -972,7 +1217,7 @@ pub mod example_dispatch_tree {}
/// // ________ adds metadata to the enum, enabling it to:
/// // / 1. Be used by the `suggest_enum!(Enum)` macro under the `comp` feature for autocompletion
/// // vvvvvvv 2. Implement the `PickableEnum` trait
-/// #[derive(Debug, Default, EnumTag, Groupped)]
+/// #[derive(Debug, Default, EnumTag, Grouped)]
/// pub enum ProgrammingLanguages {
/// #[enum_desc("An efficient and flexible compiled language widely used for system programming")]
/// C,
@@ -1691,7 +1936,7 @@ pub mod example_lazy_resources {}
/// /// Renderer for parse errors — using the outside `ParseIntError` type.
/// ///
/// /// The `ParseIntError` type is registered via `group!` above, so it implements
-/// /// `Groupped<ThisProgram>` and can be used directly in a `#[renderer]` function.
+/// /// `Grouped<ThisProgram>` and can be used directly in a `#[renderer]` function.
/// #[renderer]
/// fn render_parse_error(err: ParseIntError) -> RenderResult {
/// let mut render_result = RenderResult::new();
@@ -2436,7 +2681,7 @@ pub mod example_setup {}
/// Source code (./src/main.rs)
/// ```ignore
/// use mingling::prelude::*;
-/// use mingling::{Groupped, StructuralData, parser::Picker, setup::StructuralRendererSetup};
+/// use mingling::{parser::Picker, setup::StructuralRendererSetup, Grouped, StructuralData};
/// use serde::Serialize;
/// use std::io::Write;
///
@@ -2453,12 +2698,12 @@ pub mod example_setup {}
/// // --------- IMPORTANT ---------
/// // For beautiful output structure, do not use `pack!` to wrap the types that need to be output.
/// // Instead, manually implement
-/// // __________________________________ Mark as structured data so it can be rendered
-/// // / ____________________ Implement serde::Serialize
-/// // | / _________ Implement mingling::Groupped
-/// // | | / to ensure Mingling can recognize the type
-/// // vvvvvvvvvvvv vvvvvvvvv vvvvvvvv
-/// #[derive(StructuralData, Serialize, Groupped)]
+/// // ____________________________________ Mark as structured data so it can be rendered
+/// // / ____________________ Implement serde::Serialize
+/// // | / _________ Implement mingling::Grouped
+/// // | | / to ensure Mingling can recognize the type
+/// // vvvvvvvvvvvv vvvvvvvvv vvvvvvv
+/// #[derive(StructuralData, Serialize, Grouped)]
/// struct Info {
/// #[serde(rename = "member_name")]
/// name: String,
diff --git a/mingling/src/lib.rs b/mingling/src/lib.rs
index 499390d..a34452d 100644
--- a/mingling/src/lib.rs
+++ b/mingling/src/lib.rs
@@ -106,6 +106,10 @@ pub mod macros {
/// `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;
+ /// `#[routeify]` - An extension attribute macro that transforms `expr?` into `route!(expr)`.
+ /// Can be used standalone or as a chain/renderer extension: `#[chain(routeify, ...)]`.
+ #[cfg(feature = "extra_macros")]
+ pub use mingling_macros::routeify;
/// `suggest! { "hello", "bye" }` - Used to generate suggestions
#[cfg(feature = "comp")]
pub use mingling_macros::suggest;
@@ -118,9 +122,9 @@ pub mod macros {
#[cfg(feature = "macros")]
pub use mingling_macros::EnumTag;
-/// derive macro Groupped
+/// derive macro Grouped
#[cfg(feature = "macros")]
-pub use mingling_macros::Groupped;
+pub use mingling_macros::Grouped;
/// derive macro `StructuralData` — marks a type as supporting structured output
#[cfg(feature = "structural_renderer")]
@@ -171,12 +175,15 @@ pub mod res;
/// use mingling::prelude::*;
/// ```
pub mod prelude {
- /// Re-export of the `Groupped` derive macro for grouping types.
+ /// Re-export of the `Grouped` trait
#[cfg(feature = "core")]
- pub use crate::Groupped;
+ pub use crate::Grouped;
/// Re-export of the `RenderResult` struct for outputting rendering result
#[cfg(feature = "core")]
pub use crate::RenderResult;
+ /// Re-export of the `Routable` trait
+ #[cfg(feature = "core")]
+ pub use crate::Routable;
/// Re-export of the `chain` macro for defining a chain of commands.
#[cfg(feature = "macros")]
pub use crate::macros::chain;
@@ -218,7 +225,10 @@ pub mod prelude {
pub use crate::parser::AsPicker;
#[cfg(feature = "picker")]
- pub use arg_picker::prelude::*;
+ pub use arg_picker::prelude::arg;
+
+ #[cfg(feature = "picker")]
+ pub use crate::picker::EntryPicker;
/// Used to enable the `writeln!` macro for `RenderResult`
#[cfg(feature = "core")]
diff --git a/mingling/src/picker/entry_picker.rs b/mingling/src/picker/entry_picker.rs
index 7a980c6..7364c50 100644
--- a/mingling/src/picker/entry_picker.rs
+++ b/mingling/src/picker/entry_picker.rs
@@ -1,8 +1,8 @@
-use mingling_core::{ChainProcess, Groupped, ProgramCollect};
+use mingling_core::{ChainProcess, Grouped, ProgramCollect};
use crate::{picker::Pickable, picker::Picker, picker::PickerArg, picker::PickerPattern1};
-/// Trait for converting Mingling entry types (types that implement `Groupped<R>` and `Into<Vec<String>>`)
+/// Trait for converting Mingling entry types (types that implement `Grouped<R>` and `Into<Vec<String>>`)
/// into [`Picker`] instances for a given route type `R`.
///
/// This trait provides a bridge between entry definitions created with the `mingling` framework
@@ -12,7 +12,7 @@ use crate::{picker::Pickable, picker::Picker, picker::PickerArg, picker::PickerP
///
/// * `'a` — The lifetime of the picker and its references to argument definitions.
/// * `This` — The program type used for dispatching runtime routes; must implement [`ProgramCollect`].
-/// * `Route` — The route type used for dispatching; must implement [`Groupped<This>`].
+/// * `Route` — The route type used for dispatching; must implement [`Grouped<This>`].
pub trait EntryPicker<'a, This> {
/// Converts `self` into a [`Picker`] for the given route type `Route`.
fn to_picker(self) -> Picker<'a, ChainProcess<This>>;
@@ -117,7 +117,7 @@ pub trait EntryPicker<'a, This> {
impl<'a, This, Bind> EntryPicker<'a, This> for Bind
where
This: ProgramCollect<Enum = This>,
- Bind: Groupped<This> + Into<Vec<String>>,
+ Bind: Grouped<This> + Into<Vec<String>>,
{
fn to_picker(self) -> Picker<'a, ChainProcess<This>> {
let args = self.into();
diff --git a/mingling/src/setups/picker/basic.rs b/mingling/src/setups/picker/basic.rs
index b8cc237..c9f82b3 100644
--- a/mingling/src/setups/picker/basic.rs
+++ b/mingling/src/setups/picker/basic.rs
@@ -43,7 +43,10 @@ where
C: ProgramCollect<Enum = C>,
{
fn setup(self, program: &mut Program<C>) {
- pick_global_flag(program, self.flag);
+ let help = pick_global_flag(program, self.flag);
+ if help {
+ program.user_context.help = true;
+ }
}
}
@@ -72,7 +75,10 @@ where
C: ProgramCollect<Enum = C>,
{
fn setup(self, program: &mut Program<C>) {
- pick_global_flag(program, self.flag);
+ let help = pick_global_flag(program, self.flag);
+ if help {
+ program.stdout_setting.quiet = true;
+ }
}
}
@@ -101,7 +107,10 @@ where
C: ProgramCollect<Enum = C>,
{
fn setup(self, program: &mut Program<C>) {
- pick_global_flag(program, self.flag);
+ let help = pick_global_flag(program, self.flag);
+ if help {
+ program.user_context.confirm = true;
+ }
}
}
generated by cgit (git 2.34.1) at 2026-07-19 21:56:22 +0000