diff options
| -rw-r--r-- | docs/dev/pages/issues/0.5.0-roadmap.md | 85 |
1 files changed, 78 insertions, 7 deletions
diff --git a/docs/dev/pages/issues/0.5.0-roadmap.md b/docs/dev/pages/issues/0.5.0-roadmap.md index 7f19774..0312193 100644 --- a/docs/dev/pages/issues/0.5.0-roadmap.md +++ b/docs/dev/pages/issues/0.5.0-roadmap.md @@ -4,7 +4,13 @@ Mingling 0.5.0 is going to be a significant release, planned as follows: 1. **Breaking:** Remove the `pack!` macro: -Since the very first version of Mingling, the `pack!` macro has been around. Its purpose has gradually narrowed from "creating a type and registering it to Mingling" to "creating a newtype that derives Grouped". In other words, the functionality of `pack!` is gradually being replaced by the `Grouped derive`. Furthermore, in 0.2.0, in order to accommodate `StructuralData derive`, Mingling introduced `pack_structural!` and `pack_err_structural!` variants all at once, which greatly increases the maintenance cost of the project. +Since the very first version of Mingling, the `pack!` macro has been around. +Its purpose has gradually narrowed from "creating a type and registering it +to Mingling" to "creating a newtype that derives Grouped". In other words, +the functionality of `pack!` is gradually being replaced by the `Grouped derive`. +Furthermore, in 0.2.0, in order to accommodate `StructuralData derive`, Mingling +introduced `pack_structural!` and `pack_err_structural!` variants all at once, +which greatly increases the maintenance cost of the project. So I plan to introduce a Breaking Change in 0.5.0: remove the entire `pack!` family of macros. @@ -23,20 +29,85 @@ pub struct ResultNames { 2. **Breaking:** Generalize the REPL system -The current REPL is merely _usable_, but far from _user-friendly_. Mingling plans to remove the `repl` feature in 0.5 and by default expose more execution-related interfaces for the Program, so that users can extend functionality beyond the REPL by leveraging Mingling's execution model. +The current REPL is merely _usable_, but far from _user-friendly_. Mingling plans +to remove the `repl` feature in 0.5 and by default expose more execution-related +interfaces for the Program, so that users can extend functionality beyond the REPL +by leveraging Mingling's execution model. 3. **Breaking:** Remove the `parser` feature -In 0.3.0, Mingling introduced the `picker` feature, which provides more powerful parameter parsing capabilities. At that point, the original `parser` feature became inadequate. Mingling plans to completely remove it, which will directly affect downstream users of the `parser` feature. +In 0.3.0, Mingling introduced the `picker` feature, which provides more powerful +parameter parsing capabilities. At that point, the original `parser` feature became +inadequate. Mingling plans to completely remove it, which will directly affect +downstream users of the `parser` feature. -4. **Feature:** Higher-level abstractions for the completion system +4. **Breaking:** Remove `with_dispatcher` and `with_dispatchers` -Mingling's completion system filled a number of behavioral gaps in 0.4 and fixed many edge cases. It's now time to introduce more powerful higher-level abstractions. +Mingling's commands must be registered through `with_dispatcher` in order to be usable +when `dispatcher_tree` is disabled. This has always been a strange semantic: `chain`, +`renderer`, `help`, `completion`, and `metadata` are all collected at compile time, +so why is `Dispatcher` the exception? -First, this feature will add a set of utility functions to `ShellContext`, enabling a smarter description of user state, rather than simply relying on manually identifying user behavior through fields like `previous_word`. +In fact, during my usage of `dispatcher` from 0.1.0 to 0.4.0, I have never encountered +a scenario where **dynamic registration** was necessary. I consider it unnecessary. -Additionally, when the `picker` feature introduced in 0.3.0 is enabled together with the `comp` feature, a module named `picker_comp` will be activated to enable more completion behaviors. +Therefore, I plan to make `Dispatcher` registration also compile-time collected in +non-`dispatcher_tree` states starting from 0.5.0. +5. **Breaking:** Modify the `dispatcher!` syntax + +After completing item #4, `dispatcher!` will be simplified, because the `CMD*` struct will no longer need to be created + +```rust +// Before +dispatcher!("command", CMDCommand => EntryCommand); + +// After +dispatcher!("command", EntryCommand); + +// NOTE: The implicit mode is not affected +``` + +6. **Feature:** Higher-level abstractions for the completion system + +Mingling's completion system filled a number of behavioral gaps in 0.4 and fixed many +edge cases. It's now time to introduce more powerful higher-level abstractions. + +First, this feature will add a set of utility functions to `ShellContext`, enabling a +smarter description of user state, rather than simply relying on manually identifying +user behavior through fields like `previous_word`. + +Additionally, when the `picker` feature introduced in 0.3.0 is enabled together with +the `comp` feature, a module named `picker_comp` will be activated to enable more +completion behaviors. + +7. **Feature:** Automated `dispatcher_tree` optimization decisions (under consideration) + +After completing item #4, this Feature becomes implementable: Mingling can automatically +decide whether to use `dispatcher_tree` to optimize dispatch efficiency based on the current +number and depth of registered commands, so users no longer need to manually enable the +`dispatch_tree` feature. + +Conditions: `dispatch_tree` has an advantage in cases where command depth is too high and +the number of commands is too large. However, if the number of commands is too small, the +increased CPU prediction failure rate will inevitably make it less efficient than linear +lookup; specifics need to be tuned during implementation. + +Additionally, the issue where `pathf` + `dispatch_tree` must be explicitly specified in +`[build-dependencies]` will be resolved: + +```toml +# Before +[build-dependencies.mingling] +version = "0.4.0" +features = [ "build", "pathf", "dispatch_tree" ] # `dispatch_tree` must be explicitly specified for `pathf` to recognize it + +# After +[build-dependencies.mingling] +version = "0.4.0" +features = [ "build", "pathf" ] # No `dispatch_tree` feature; `pathf` no longer needs to consider its branches +``` + <p align="center" style="font-size: 0.85em; color: gray;"> Written by @Weicao-CatilGrass </p> |