diff options
| author | 魏曹先生 <1992414357@qq.com> | 2026-07-17 03:08:44 +0800 |
|---|---|---|
| committer | 魏曹先生 <1992414357@qq.com> | 2026-07-17 03:08:44 +0800 |
| commit | 25c603a41685230aa7ab095310273c77e75c4ca3 (patch) | |
| tree | 2e0f00651b0cff09a2f6bafd6ce35046532ffa81 /docs | |
| parent | b29c702af03fee9fe724108696f92e5b602e0d7a (diff) | |
docs(dev): update progress status in add-picker2.md
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/dev/pages/issues/add-picker2.md | 203 |
1 files changed, 11 insertions, 192 deletions
diff --git a/docs/dev/pages/issues/add-picker2.md b/docs/dev/pages/issues/add-picker2.md index 2bb79d1..f5c3ca7 100644 --- a/docs/dev/pages/issues/add-picker2.md +++ b/docs/dev/pages/issues/add-picker2.md @@ -87,195 +87,14 @@ pub struct PickerResult<Tuple> { --- -## Current Progress (2026-07-14) - -Picker2 has been significantly implemented. Here is the current status: - -### Completed - -#### Core Type System - -- **`PickerArgs`** — Three-tier ownership enum for CLI arguments: - - `Slice(&'a [&'a str])` — zero-copy borrow from `std::env::args()` - - `Vec(Vec<&'a str>)` — owned container, borrowed elements - - `Owned(Vec<String>)` — fully owned (constructed / manipulated args) - -- **`PickerResult`** — Four-state parse result: - - `Unparsed` — not yet parsed (default) - - `Parsed(Type)` — successfully parsed - - `NotFound` — requested value not found - - `FormatError` — input could not be parsed - -- **`PickerFlag`** — Const-compatible parameter constraint definition: - ```rust - pub struct PickerFlag<'a, Type: Pickable> { - pub full: &'a [&'a str], // flag names & aliases - pub short: Option<char>, // short name, e.g. 'n' - pub positional: bool, // positional or named - pub internal_type: PhantomData<Type>, - } - ``` - All fields are `pub`, enabling direct struct literal construction. - -#### `internal_repeat!` Template Engine - -A custom proc-macro template engine that generates repetitive code without nightly features or external dependencies. - -**Syntax:** - -```rust -internal_repeat!(1..=32 => { - // $ — current counter (1, 2, ..., 32) - // $+ — current + 1 - // $- — current - 1 - // $^ — loop minimum - // ^$ — loop maximum - // ident$ → ident{current} - // ident$+ → ident{current+1} - // ident$- → ident{current-1} - // ident$^ → ident{min} - // (group,+) — repeat * times (current), `,` separator - // (group,+)+ — repeat *+1 times (current + 1) - // (group,+)- — repeat *-1 times (current - 1) -}); -``` - -Generates `PickerPattern1` through `PickerPattern32` structs, each with `N` typed flag/result fields: - -```rust -pub struct PickerPattern3<'a, T1, T2, T3> { - pub args: PickerArgs<'a>, - pub flag_1: &'a PickerFlag<'a, T1>, - pub result_1: PickerResult<T1>, - pub flag_2: &'a PickerFlag<'a, T2>, - pub result_2: PickerResult<T2>, - pub flag_3: &'a PickerFlag<'a, T3>, - pub result_3: PickerResult<T3>, -} -``` - -#### `flag!` Macro - -Declarative parameter definition macro. Expands to a const-compatible struct literal: - -```rust -// Syntax variants: -flag![name: String] // named, no short -flag![name: String, 'n'] // named, with short -flag![name: String, 'n', "alias"] // named, with short & alias -flag![String] // positional, no name -flag![String, 'F'] // positional, with short -flag![String, 'o', "output"] // positional, with short & alias - -// Expansion (all const-compatible): -::mingling::picker::PickerFlag::<String> { - full: &["name"], - short: ::std::option::Option::Some('n'), - positional: false, - internal_type: ::std::marker::PhantomData, -} -``` - -The type part preserves original token spans for IDE support (Rust Analyzer). - -#### `Pickable` Trait - -Implemented for all numeric types, `String`, `PathBuf`, `Option<T>`. - -```rust -pub trait Pickable { - fn pick(raw_str: &str) -> PickerResult<Self>; -} -``` - -#### Type-Safe Chaining - -```rust -let p4: PickerPattern4<String, i32, String, String> = args - .pick(&flag![name: String]) - .pick(&flag![age: i32]) - .pick(&flag![food: String, 'F']) - .pick(&flag![kind: String]); -``` - -Each `.pick()` call adds one type parameter to the pattern. Parameter count is compile-time enforced — writing 3 `.pick()` calls produces `PickerPattern3`, and trying to assign to `PickerPattern4` fails to compile. - -### ❌ Pending - -#### `.parse()` — Runtime Parsing Engine - -Not yet implemented. The proposed parsing flow: - -```rust -let result: (String, i32) = args - .pick(&flag![name: String]) - .pick(&flag![age: i32]) - .parse(); -``` - -Procedural steps: - -1. Allocate a `Vec<Box<dyn Any>>` indexed by type position -2. Sort all flags: named flags first, positional flags after -3. Each `PickerFlag`'s `Pickable` scans the argument list and marks its tokens -4. Each `Pickable::pick()` resolves its value into the `Vec` -5. Downcast each `Box<dyn Any>` to the concrete type -6. Convert via `Into<(...)>` into the final tuple - -Planned companion code generation via `internal_repeat!`: - -```rust -internal_repeat!(1..=32 => { - impl<'a, (T$,)+> PickerPattern$<'a, (T$,)+> { - pub fn parse(self) -> ((T$,)+) { - // ... - } - } -}); -``` - -#### `.pick_route()` — Error Routing - -Post-processing with route-on-error: - -```rust -let parsed = args - .pick_route::<String, _>(flag![path: PathBuf], ErrorNotFound) - .parse(); -``` - -#### `MultiFlag` — Combined Flags - -```rust -#[derive(MultiFlag)] -pub struct Toggles { - pub install: bool, // -i - #[flag('U')] - pub uninstall: bool, // -U - #[flag('X')] - pub execute: bool, // -X -} -// Supports: `-iUX` -``` - -#### `PickerConfig` — Arg Format Configuration - -Support for `--key=value`, `/Key=Value`, etc. - -### Summary - -| Component | Status | -| ---------------------------------- | ------ | -| `PickerArgs` (3-tier ownership) | ✅ | -| `PickerResult` (4-state) | ✅ | -| `PickerFlag` (const-compatible) | ✅ | -| `Pickable` trait + impls | ✅ | -| `internal_repeat!` template engine | ✅ | -| `flag!` macro | ✅ | -| `PickerPattern1..32` structs | ✅ | -| Chainable `.pick()` (2→31) | ✅ | -| **`.parse()` runtime** | ❌ | -| `.pick_route()` error routing | ❌ | -| `MultiFlag` derive | ❌ | -| `PickerConfig` | ❌ | -| Integration with `#[chain]` | ❌ | +## 🕘 Progress + +- [x] In Progress + - [x] Added `Picker` struct and related call chain + - [x] Added `parselib` providing parsing logic + - [x] Added `Pickable` for extensibility + - [ ] Comprehensive testing! + - [ ] Improve documentation + - [ ] Add examples + - [ ] Update README +- [ ] Complete |
