From b388be3cf31c4689e3aaf9b4966e5e03953c8c77 Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Sat, 11 Jul 2026 02:26:26 +0800
Subject: Update add-picker2.md

---
 docs/dev/pages/issues/add-picker2.md | 76 ++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

(limited to 'docs/dev/pages/issues')

diff --git a/docs/dev/pages/issues/add-picker2.md b/docs/dev/pages/issues/add-picker2.md
index 6b2df27..4ee671f 100644
--- a/docs/dev/pages/issues/add-picker2.md
+++ b/docs/dev/pages/issues/add-picker2.md
@@ -8,3 +8,79 @@
 Mingling's `parser` feature is a temporary argument parsing solution created in the early stages of the project. While it can handle basic argument parsing tasks, its functionality is incomplete and has many limitations.
 
 This article aims to propose the design and development plan for the new Picker2 (feature name: `picker`).
+
+### Picker2 Expected Syntax
+
+1. **Pos args & flag args no longer depend on parsing order:** In `parser`, all flag args must be parsed before pos args. Picker2 removes this restriction.
+2. **Declare flags with declarative macros:** Use `positional!()`, `flag![-X, --x]` etc. to declare flags — cleaner and more concise.
+3. **One-shot `parse()` replaces step-by-step `unpack()`:** Defers the entire parsing flow to the final step, leaving more room for compile-time optimization.
+
+```rust
+#[chain]
+fn handle_hello(args: EntryHello) {
+    let parsed = args
+        .pick::<String>(positional!())
+        .pick::<String>(flag![--help, -h])
+        .parse();
+}
+```
+
+4. **Post-processing & routing control:** Use `after`, `after_route` to control post-processing logic. The route type is explicitly specified by the first `route` method.
+
+```rust
+#[chain]
+fn handle_hello(args: EntryHello) {
+    let parsed = args
+        .pick::<String>(positional!())
+        .after(|v| format!("\"{}\"", v)) // post-processing
+        .parse();
+}
+```
+
+```rust
+#[chain]
+fn handle_hello(args: EntryHello) -> Next {
+    //                                         requires impl Groupped<_>
+    //                                         |
+    let parsed = args //                       vvvvvvvvvvvvvvvvvvv
+        .pick_route::<String, _>(positional!(), ErrorNoNameProvided)
+        .after_route(|v| Ok(format!("\"{}\"", v))) // post-process & route
+        .parse();
+    let routed_parsed = route!(parsed);
+    empty_result!()
+}
+```
+
+5. **Keep the `Pickable` Trait**
+6. **Keep `PickableEnum` & provide a derive macro**
+7. **Use `pick_optional`, `pick_vec` instead of implementing trait separately for `Option<T>`, `Vec<T>`**
+8. **Use `pick_flag` instead of `pick::<bool>`**
+9. **Provide `YesOrNo`, `TrueOrFalse` etc. that implement the `BoolFlag` trait for explicit bool extraction**
+10. **Provide a `MultiFlag` derive macro, supporting arg modes like `pacman`**
+
+```rust
+#[derive(MultiFlag)]
+pub struct SomeToggles {
+    // default [-i]
+    pub install: bool,
+
+    #[flag('U')]
+    pub uninstall: bool,
+
+    #[flag('X')]
+    pub execute: bool,
+}
+
+// Auto-implements Pickable, supports parsing args like `-iUX`
+```
+
+11. **Support multiple arg formats:** e.g. `--key=value`, `/Key=Value`, controlled by global config `PickerConfig` (or: `Picker::from_with_cfg(prev.inner, PickerConfig::default())`)
+
+12. `.parse()` no longer returns a bare tuple, but instead returns:
+
+```rust
+pub struct PickerResult<Tuple> {
+    pub result: Tuple,
+    pub remains_argument: Arguments,
+}
+```
-- 
cgit