refactor: rename `PickerResult` to `PickerArgResult` and add new

`PickerResult` struct

2 files changed, 79 insertions, 4 deletions

diff --git a/mingling_picker/src/picker/patterns.rs b/mingling_picker/src/picker/patterns.rs
index 4f54f9d..b828849 100644
--- a/mingling_picker/src/picker/patterns.rs
+++ b/mingling_picker/src/picker/patterns.rs
@@ -1,6 +1,6 @@
 use mingling_picker_macros::internal_repeat;
 
-use crate::{Pickable, Picker, PickerArgs, PickerFlag, PickerResult};
+use crate::{Pickable, Picker, PickerArgResult, PickerArgs, PickerFlag};
 
 internal_repeat!(1..=32 => {
     #[doc(hidden)]
@@ -10,7 +10,7 @@ internal_repeat!(1..=32 => {
         pub args: PickerArgs<'a>,
         (
             pub flag_$: &'a PickerFlag<'a, T$>,
-            pub result_$: PickerResult<T$>,
+            pub result_$: PickerArgResult<T$>,
             pub default_$: Option<Box<dyn FnOnce() -> T$>>,
             pub post_$: Option<Box<dyn FnOnce(T$) -> T$>>,
         +)
@@ -43,6 +43,27 @@ internal_repeat!(1..=32 => {
             self
         }
 
+        /// Uses the default value for this flag's type if the flag is not provided.
+        ///
+        /// If the flag is not provided by the user at runtime, the default value for `T$`
+        /// (as defined by the `Default` trait) will be used.
+        ///
+        /// # Example
+        ///
+        /// ```ignore
+        /// let pattern = picker
+        ///     .pick(&my_flag)
+        ///     .or_default();
+        /// ```
+        #[allow(clippy::type_complexity)]
+        pub fn or_default(mut self) -> Self
+        where
+            T$: Default,
+        {
+            self.default_$ = Some(Box::new(|| T$::default()));
+            self
+        }
+
         /// Attaches a post-processing function to this flag.
         ///
         /// After the flag's value is parsed (or defaulted), the given closure will be
@@ -88,7 +109,7 @@ internal_repeat!(1..32 => {
 
                // Current
                flag_$+: flag,
-               result_$+: PickerResult::Unparsed,
+               result_$+: PickerArgResult::Unparsed,
                default_$+: None,
                post_$+: None,
 
@@ -116,7 +137,7 @@ impl<'a> Picker<'a> {
         PickerPattern1 {
             args: self.args,
             flag_1: flag,
-            result_1: PickerResult::Unparsed,
+            result_1: PickerArgResult::Unparsed,
             default_1: None,
             post_1: None,
         }
diff --git a/mingling_picker/src/picker/result.rs b/mingling_picker/src/picker/result.rs
new file mode 100644
index 0000000..bd283cf
--- /dev/null
+++ b/mingling_picker/src/picker/result.rs
@@ -0,0 +1,54 @@
+use mingling_picker_macros::internal_repeat;
+
+internal_repeat!(1..=32 => {
+    #[doc(hidden)]
+    pub struct PickerResult$<(T$,+), Route> {
+        /// The route selected by the picker, if any.
+        /// If this is `Some`, the picker chose to follow a route instead of selecting values,
+        /// and all value fields (`v1`, `v2`, ...) will be `None`.
+        ///
+        /// Note: "route" here refers to an alternative path/choice, not a network route.
+        pub route: Option<Route>,
+
+        (
+            #[doc = concat!("The optional value for the ", $, "th type parameter.")]
+            pub v$: Option<T$>,
+        +)
+    }
+});
+
+internal_repeat!(1..=32 => {
+    impl<(T$,+), Route> PickerResult$<(T$,+), Route> {
+        /// Unwraps the result, panicking if a route was selected.
+        ///
+        /// # Panics
+        ///
+        /// Panics if `self.route` is `Some(...)`.
+        pub fn unwrap(self) -> ((T$,+)) {
+            ((self.v$.unwrap(),+))
+        }
+
+        /// Returns the individual option values without checking the route.
+        pub fn unpack(self) -> ((Option<T$>,+)) {
+            ((self.v$,+))
+        }
+
+        /// Converts to a `Result`, returning `Err(route)` if a route was selected,
+        /// or `Ok(values)` otherwise.
+        pub fn to_result(self) -> Result<((T$,+)), Route> {
+            if let Some(r) = self.route {
+                return Err(r);
+            }
+            Ok(self.unwrap())
+        }
+
+        /// Converts to an `Option`, returning `None` if a route was selected,
+        /// or `Some(values)` otherwise.
+        pub fn to_option(self) -> Option<((T$,+))> {
+            if let Some(_) = self.route {
+                return None;
+            }
+            Some(self.unwrap())
+        }
+    }
+});