feat(arg_picker): add preprocessing and postprocessing priority levels

Add `Begin`, `Preprocess`, `Final`, and `Postprocess` variants to
`PickerArgAttr` enum, and implement `Pickable` for `PickerArgs` as a
built-in picker that consumes all remaining unclaimed arguments at
lowest priority. Expose `is_masked` and `build_masked_args` as public
functions for use by custom pickers.

1 files changed, 25 insertions, 1 deletions

diff --git a/arg_picker/src/arg.rs b/arg_picker/src/arg.rs
index 78ad539..a352418 100644
--- a/arg_picker/src/arg.rs
+++ b/arg_picker/src/arg.rs
@@ -138,9 +138,27 @@ where
 /// Describes the attribute (behavior) of a command-line parameter.
 ///
 /// The ordering reflects parse priority (higher = parsed first):
-/// `PositionalMulti < Positional < Flag < Single < Multi`
+/// `Postprocess < Final < PositionalMulti < Positional < Flag < Single < Multi < Begin < Preprocess`
+///
+/// # Variants
+///
+/// - `Postprocess` — Reserved lowest priority, used only in special cases.
+/// - `Final` — Reserved post-processing priority, used only in special cases.
+/// - `PositionalMulti` — Positional argument that accepts multiple values (e.g., multiple input files).
+/// - `Positional` — Positional argument matched by its position (e.g., an input file).
+/// - `Flag` — Boolean flag with no associated value (e.g., `--verbose`).
+/// - `Single` — Accepts a single value (e.g., `--name Alice`).
+/// - `Multi` — Accepts multiple values (e.g., `--file a.txt --file b.txt`).
+/// - `Begin` — Reserved pre-processing priority, used only in special cases.
+/// - `Preprocess` — Reserved highest priority, used only in special cases.
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub enum PickerArgAttr {
+    /// Reserved lowest priority, used only in special cases.
+    Postprocess,
+
+    /// Reserved post-processing priority, used only in special cases.
+    Final,
+
     /// Positional argument that accepts multiple values (e.g., multiple input files).
     PositionalMulti,
 
@@ -156,6 +174,12 @@ pub enum PickerArgAttr {
 
     /// Accepts multiple values (e.g., `--file a.txt --file b.txt`).
     Multi,
+
+    /// Reserved pre-processing priority, used only in special cases.
+    Begin,
+
+    /// Reserved highest priority, used only in special cases.
+    Preprocess,
 }
 
 impl PickerArgAttr {