diff options
60 files changed, 640 insertions, 283 deletions
diff --git a/.run/src/bin/cov-test.rs b/.run/src/bin/cov-test.rs index ff2c3fc..f62ff01 100644 --- a/.run/src/bin/cov-test.rs +++ b/.run/src/bin/cov-test.rs @@ -9,8 +9,12 @@ //! //! - `--object <PATH>`: include arbitrary binaries in the report //! (upstream issue taiki-e/cargo-llvm-cov#367) -//! - `--include-tests-examples-benches`: stop filtering those source dirs -//! (upstream issue taiki-e/cargo-llvm-cov#503) +//! - `--include-examples`: stop filtering source files under the +//! `examples` directory (upstream issue taiki-e/cargo-llvm-cov#503) +//! +//! The script itself does not use `--include-examples`; it passes +//! `--no-default-ignore-filename-regex` and supplies its own filter so that +//! `tests`/`benches` directories stay in the report too. //! //! Install it with: //! @@ -270,7 +270,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "arg-picker", "mingling", @@ -283,11 +283,11 @@ dependencies = [ [[package]] name = "mingling-workspace" -version = "0.4.0" +version = "0.5.0" [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "env_logger", "just_fmt 0.2.0", @@ -305,7 +305,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "proc-macro2", @@ -315,7 +315,7 @@ dependencies = [ [[package]] name = "mingling_pathf" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "proc-macro2", @@ -61,7 +61,7 @@ log = "0.4.33" env_logger = "0.11.11" [workspace.package] -version = "0.4.0" +version = "0.5.0" edition = "2024" license = "MIT OR Apache-2.0" repository = "https://github.com/mingling-rs/mingling" @@ -99,7 +99,7 @@ Add Mingling to your `Cargo.toml`: ```toml [dependencies.mingling] -version = "0.4.0" +version = "0.5.0" features = [] ``` diff --git a/dist/index.html b/dist/index.html index 8e7c542..905e90a 100644 --- a/dist/index.html +++ b/dist/index.html @@ -844,7 +844,7 @@ d="M97.905 67.885c.174 18.8 16.494 25.057 16.674 25.137-.138.44-2.607 8.916-8.597 17.669-5.178 7.568-10.553 15.108-19.018 15.266-8.318.152-10.993-4.934-20.504-4.934-9.508 0-12.479 4.776-20.354 5.086-8.172.31-14.395-8.185-19.616-15.724C15.822 94.961 7.669 66.8 18.616 47.791c5.438-9.44 15.158-15.417 25.707-15.571 8.024-.153 15.598 5.398 20.503 5.398 4.902 0 14.106-6.676 23.782-5.696 4.051.169 15.421 1.636 22.722 12.324-.587.365-13.566 7.921-13.425 23.639M82.272 21.719c4.338-5.251 7.258-12.563 6.462-19.836-6.254.251-13.816 4.167-18.301 9.416-4.02 4.647-7.54 12.087-6.591 19.216 6.971.54 14.091-3.542 18.43-8.796" /> </svg> - <span class="os-name">macOS</span> + <span class="os-name">Mac OS</span> <a class="file-name" href="./mling-mac.tar.gz" >DOWNLOAD<span class="btn-arrow">↓</span></a > @@ -990,7 +990,7 @@ mling update</code></pre> "mling metadata", "mling lint", "mling ra-lint", - "mling proj-init 0.4.0@basic", + "mling proj-init 0.5.0@basic", "mling class-add subcommand calc", "mling install", "mling pkg-enable your-cli@0.1.0", diff --git a/docs/_zh_CN/pages/1-getting-started.md b/docs/_zh_CN/pages/1-getting-started.md index 6aa6229..47fdda8 100644 --- a/docs/_zh_CN/pages/1-getting-started.md +++ b/docs/_zh_CN/pages/1-getting-started.md @@ -13,7 +13,7 @@ cd my-cli ```toml [dependencies.mingling] -version = "0.4.0" +version = "0.5.0" features = [] ``` @@ -25,7 +25,7 @@ features = [] ```toml [dependencies.mingling] -version = "0.4.0" +version = "0.5.0" features = [ "parser", "comp", diff --git a/docs/dev/_sidebar.md b/docs/dev/_sidebar.md index 03a0edf..cfb482a 100644 --- a/docs/dev/_sidebar.md +++ b/docs/dev/_sidebar.md @@ -1,10 +1,18 @@ - [Welcome!](README) * ❓ Issues - * [The Mingling 0.5.0 Roadmap](pages/issues/0.5.0-roadmap) * [[Solved] The Picker2 Arguments Parser](pages/issues/_add-picker2) * [[Solved] Remove r_print! and r_println! Macros](pages/issues/_remove-r-print-macro) * [[Solved] The Command Macro](pages/issues/_the-command-macro) * [[Solved] The Mod Pathfinder](pages/issues/_the-mod-pathfinder) + * [[T0] Generalize the REPL System](pages/issues/t0_generalize-repl-system) + * [[T0] Remove the pack! Family of Macros](pages/issues/t0_remove-pack-macros) + * [[T0] Remove the parser Feature](pages/issues/t0_remove-parser-feature) + * [[T0] Remove with_dispatcher and with_dispatchers](pages/issues/t0_remove-with-dispatcher) + * [[T1] Higher-Level Abstractions for the Completion System](pages/issues/t1_completion-higher-level-abstractions) + * [[T1] Modify the dispatcher! Syntax](pages/issues/t1_modify-dispatcher-syntax) + * [[T1] Move structural_renderer from mingling_core to mingling](pages/issues/t1_move-structural-renderer) + * [[T1] The pathf_export Attribute Macro](pages/issues/t1_pathf-export-macro) + * [[T2] Automated dispatcher_tree Optimization Decisions](pages/issues/t2_automated-dispatch-tree-optimization) * [The Next-Gen Mingling Pipeline](pages/issues/the-next-pipeline) * [Some Situations Where You'd Be Like "Shit!"](pages/issues/the-shit-time) * 💡 Abouts diff --git a/docs/dev/pages/issues/0.5.0-roadmap.md b/docs/dev/pages/issues/0.5.0-roadmap.md deleted file mode 100644 index 83d872f..0000000 --- a/docs/dev/pages/issues/0.5.0-roadmap.md +++ /dev/null @@ -1,142 +0,0 @@ -<h1 align="center">The Mingling 0.5.0 Roadmap</h1> - -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. - -So I plan to introduce a Breaking Change in 0.5.0: remove the entire `pack!` family of macros. - -All future type creation will be done as follows: - -```rust -// Before -pack!(ResultNames = Vec<String>); - -// After -#[derive(Grouped)] -pub struct ResultNames { - names: Vec<String> -} -``` - -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. - -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. - -4. **Breaking:** Remove `with_dispatcher` and `with_dispatchers` - -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? - -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. - -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 -``` - -8. **Feature:** A new macro designed for `pathf`: `#[pathf_export(type::TypePath)]` - -`pathf` has been around since 0.2.0 and has worked well for a long time, with many edge cases resolved. However, it still lacks an escape hatch — "when certain indirect expansions cannot be recognized by `pathf`, how can we assist its inference?" - -I plan to introduce a new attribute macro to supplement `pathf`'s path inference. - -```rust -#[macro_export] -macro_rules! repack { - ($name:ident) => { - // Ignored! This section cannot be parsed by pathf. - #[mingling::macros::pathf_ignore] - #[derive(mingling::Grouped)] - pub struct $name; - }; -} - -// The expansion contains macros that need to be parsed by pathf -#[pathf_export(MyType)] // Explicitly specified to assist pathf's inference -repack!(MyType); -``` - -9. **Breaking:** Move `structural_renderer` from `mingling_core` to `mingling` - -Mingling's Hook system is now complete, so there's no longer a need to hardcode `StructuralRenderer` into the core loop. The plan is to remove it from `exec.rs` and instead inject the Hook implementation via `StructuralRendererSetup`. - -> [!Note] -> Haha, hopefully we'll never have to use it. - -<p align="center" style="font-size: 0.85em; color: gray;"> - Written by @Weicao-CatilGrass -</p> diff --git a/docs/dev/pages/issues/t0_generalize-repl-system.md b/docs/dev/pages/issues/t0_generalize-repl-system.md new file mode 100644 index 0000000..73c9541 --- /dev/null +++ b/docs/dev/pages/issues/t0_generalize-repl-system.md @@ -0,0 +1,36 @@ +<h1 align="center">[T0] Generalize the REPL System</h1> +<p align="center"> + Breaking: remove the <code>repl</code> feature and expose execution interfaces on the Program +</p> + +> [!NOTE] +> +> This is a **Breaking Change** planned for Mingling 0.5.0. + +## Background + +The current REPL is merely _usable_, but far from _user-friendly_. The `repl` feature locks a specific interactive front-end into the framework, while the underlying execution model is what actually provides value. + +## Plan + +- Remove the `repl` feature in 0.5.0. +- 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 goal is to separate the execution model from any particular interactive front-end, letting users build their own REPL (or other execution drivers) on top of Mingling's public interfaces. + +## Tasks + +- [ ] Audit the current `repl` implementation and identify which behaviors belong to the execution model vs. the interactive front-end +- [ ] Design and expose the execution-related interfaces on `Program` (e.g. per-input execution, result handling, exit semantics) +- [ ] Remove the `repl` feature from `mingling`, `mingling_core`, and `mingling_macros` +- [ ] Remove or migrate the built-in REPL front-end +- [ ] Update examples and docs that enable `repl` + +## 🕘 Progress + +- [ ] In Progress +- [ ] Complete + +<p align="center" style="font-size: 0.85em; color: gray;"> + Written by @Weicao-CatilGrass +</p> diff --git a/docs/dev/pages/issues/t0_remove-pack-macros.md b/docs/dev/pages/issues/t0_remove-pack-macros.md new file mode 100644 index 0000000..517646a --- /dev/null +++ b/docs/dev/pages/issues/t0_remove-pack-macros.md @@ -0,0 +1,49 @@ +`<h1 align="center">[T0] Remove the pack! Family of Macros</h1> +<p align="center"> + Breaking: retire the entire <code>pack!</code> family in favor of the <code>Grouped</code> derive +</p> + +> [!NOTE] +> +> This is a **Breaking Change** planned for Mingling 0.5.0. + +## Background + +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. + +## Plan + +Remove the entire `pack!` family of macros (`pack!`, `pack_structural!`, `pack_err_structural!`) as a Breaking Change in 0.5.0. + +All future type creation will be done as follows: + +```rust +// Before +pack!(ResultNames = Vec<String>); + +// After +#[derive(Grouped)] +pub struct ResultNames { + names: Vec<String> +} +``` + +## Tasks + +- [ ] Identify all usages of `pack!` / `pack_structural!` / `pack_err_structural!` across the codebase, examples, and docs +- [ ] Migrate internal usages to `#[derive(Grouped)]` +- [ ] Remove the macro definitions and their re-exports +- [ ] Update the docs / helpdoc examples that reference `pack!` +- [ ] Update downstream feature docs (`structural_renderer` etc.) where `pack_structural!` was involved +- [ ] Verify all tests pass + +## 🕘 Progress + +- [ ] In Progress +- [ ] Complete + +<p align="center" style="font-size: 0.85em; color: gray;"> + Written by @Weicao-CatilGrass +</p> diff --git a/docs/dev/pages/issues/t0_remove-parser-feature.md b/docs/dev/pages/issues/t0_remove-parser-feature.md new file mode 100644 index 0000000..5c1cffd --- /dev/null +++ b/docs/dev/pages/issues/t0_remove-parser-feature.md @@ -0,0 +1,36 @@ +<h1 align="center">[T0] Remove the parser Feature</h1> +<p align="center"> + Breaking: retire the legacy argument parsing in favor of <code>picker</code> +</p> + +> [!NOTE] +> +> This is a **Breaking Change** planned for Mingling 0.5.0. + +## Background + +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. + +The `parser` feature was 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 (see the [Picker2 issue](_add-picker2) for the full list). + +## Plan + +Completely remove the `parser` feature in 0.5.0. This will directly affect downstream users of the `parser` feature — they must migrate to `picker` (or handle parsing manually). + +## Tasks + +- [ ] Identify all usages of the `parser` feature across the codebase, examples, and docs +- [ ] Migrate internal usages (tests, examples, dev-dependencies) to `picker` +- [ ] Remove the `parser` feature from `mingling` and its dependency (`size`) +- [ ] Remove parser-related modules and public API +- [ ] Update docs and helpdoc examples +- [ ] Note the downstream migration path in the changelog + +## 🕘 Progress + +- [ ] In Progress +- [ ] Complete + +<p align="center" style="font-size: 0.85em; color: gray;"> + Written by @Weicao-CatilGrass +</p> diff --git a/docs/dev/pages/issues/t0_remove-with-dispatcher.md b/docs/dev/pages/issues/t0_remove-with-dispatcher.md new file mode 100644 index 0000000..8779d74 --- /dev/null +++ b/docs/dev/pages/issues/t0_remove-with-dispatcher.md @@ -0,0 +1,35 @@ +<h1 align="center">[T0] Remove with_dispatcher and with_dispatchers</h1> +<p align="center"> + Breaking: make <code>Dispatcher</code> registration compile-time collected in all modes +</p> + +> [!NOTE] +> +> This is a **Breaking Change** planned for Mingling 0.5.0. + +## Background + +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? + +In fact, during usage of `dispatcher` from 0.1.0 to 0.4.0, no scenario has ever been encountered where **dynamic registration** was necessary. It is considered unnecessary. + +## Plan + +Make `Dispatcher` registration also compile-time collected in non-`dispatcher_tree` states starting from 0.5.0, and remove `with_dispatcher` / `with_dispatchers` (and the related `#[program_setup]` registration path if it becomes obsolete). + +## Tasks + +- [ ] Design how dispatchers are collected at compile time when `dispatcher_tree` is disabled (consistent with how `chain` / `renderer` / `completion` / `metadata` are collected) +- [ ] Remove `with_dispatcher` and `with_dispatchers` from the `Program` API +- [ ] Update `gen_program!` and the macros so registration happens automatically +- [ ] Migrate examples, tests, and docs that call `with_dispatcher` / `with_dispatchers` +- [ ] Verify both `dispatcher_tree`-enabled and disabled modes behave identically + +## 🕘 Progress + +- [ ] In Progress +- [ ] Complete + +<p align="center" style="font-size: 0.85em; color: gray;"> + Written by @Weicao-CatilGrass +</p> diff --git a/docs/dev/pages/issues/t1_completion-higher-level-abstractions.md b/docs/dev/pages/issues/t1_completion-higher-level-abstractions.md new file mode 100644 index 0000000..69adba0 --- /dev/null +++ b/docs/dev/pages/issues/t1_completion-higher-level-abstractions.md @@ -0,0 +1,38 @@ +<h1 align="center">[T1] Higher-Level Abstractions for the Completion System</h1> +<p align="center"> + Feature: smarter state descriptions in <code>ShellContext</code> and a <code>picker_comp</code> module +</p> + +## Background + +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. + +Currently, completion logic relies on manually identifying user behavior through fields like `previous_word`, which is fragile and requires every completion function to re-derive the user's intent. + +## Plan + +### 1. Utility functions on `ShellContext` + +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`. + +### 2. `picker_comp` module + +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 — e.g. completing picker-style flags (`--key=value`, multi-flag forms, etc.) using knowledge of the picker parsing model. + +## Tasks + +- [ ] Design the `ShellContext` utility API (state descriptions / high-level queries over the current input state) +- [ ] Implement the utility functions and add tests +- [ ] Implement the `picker_comp` module, gated on `picker` + `comp` +- [ ] Add completion behaviors specific to picker argument formats +- [ ] Update docs and examples +- [ ] Verify existing 0.4 completion edge-case fixes are preserved + +## 🕘 Progress + +- [ ] In Progress +- [ ] Complete + +<p align="center" style="font-size: 0.85em; color: gray;"> + Written by @Weicao-CatilGrass +</p> diff --git a/docs/dev/pages/issues/t1_modify-dispatcher-syntax.md b/docs/dev/pages/issues/t1_modify-dispatcher-syntax.md new file mode 100644 index 0000000..f1a9346 --- /dev/null +++ b/docs/dev/pages/issues/t1_modify-dispatcher-syntax.md @@ -0,0 +1,44 @@ +<h1 align="center">[T1] Modify the dispatcher! Syntax</h1> +<p align="center"> + Breaking: drop the <code>CMD*</code> struct from the explicit form of <code>dispatcher!</code> +</p> + +> [!NOTE] +> +> This is a **Breaking Change** planned for Mingling 0.5.0, and it depends on [Remove with_dispatcher and with_dispatchers](t0_remove-with-dispatcher). + +## Background + +Once `Dispatcher` registration is compile-time collected (see [Remove with_dispatcher and with_dispatchers](t0_remove-with-dispatcher)), the `CMD*` struct becomes unnecessary — it only existed to give `with_dispatcher` something to register. + +## Plan + +Simplify the `dispatcher!` syntax: the explicit form no longer creates a `CMD*` struct, so only the entry type needs to be given. + +```rust +// Before +dispatcher!("command", CMDCommand => EntryCommand); + +// After +dispatcher!("command", EntryCommand); + +// NOTE: The implicit mode is not affected +``` + +## Tasks + +- [ ] Update `dispatcher!` to accept the simplified explicit form (`"name", EntryType`) +- [ ] Decide whether the old `CMDType => EntryType` form should error with a helpful message or be removed outright +- [ ] Remove the generated `CMD*` struct machinery +- [ ] Update `#[command]` macro internals that depend on `CMD*` +- [ ] Migrate examples, tests, and docs +- [ ] Keep the implicit mode (`dispatcher!("name")`) working unchanged + +## 🕘 Progress + +- [ ] In Progress +- [ ] Complete + +<p align="center" style="font-size: 0.85em; color: gray;"> + Written by @Weicao-CatilGrass +</p> diff --git a/docs/dev/pages/issues/t1_move-structural-renderer.md b/docs/dev/pages/issues/t1_move-structural-renderer.md new file mode 100644 index 0000000..66da5c8 --- /dev/null +++ b/docs/dev/pages/issues/t1_move-structural-renderer.md @@ -0,0 +1,38 @@ +<h1 align="center">[T1] Move structural_renderer from mingling_core to mingling</h1> +<p align="center"> + Breaking: inject <code>StructuralRenderer</code> via Hook instead of hardcoding it into the core loop +</p> + +> [!NOTE] +> +> This is a **Breaking Change** planned for Mingling 0.5.0. + +## Background + +Mingling's Hook system is now complete, so there's no longer a need to hardcode `StructuralRenderer` into the core loop. + +The plan is to remove it from `exec.rs` and instead inject the Hook implementation via `StructuralRendererSetup`. + +## Plan + +- Remove the hardcoded `StructuralRenderer` from the core execution loop (`exec.rs`). +- Implement the renderer as a Hook and inject it via `StructuralRendererSetup`. +- `mingling_core` no longer depends on the structural renderer; the wiring moves up to the `mingling` crate level. + +## Tasks + +- [ ] Audit where `StructuralRenderer` is hardcoded in `mingling_core` (`exec.rs` and related) +- [ ] Design `StructuralRendererSetup` as a Hook implementation +- [ ] Move / re-implement the renderer wiring in `mingling` +- [ ] Clean up `mingling_core`'s `structural_renderer` feature and its serde deps (if no longer needed there) +- [ ] Migrate examples and tests +- [ ] Verify structural renderer output is unchanged + +## 🕘 Progress + +- [ ] In Progress +- [ ] Complete + +<p align="center" style="font-size: 0.85em; color: gray;"> + Written by @Weicao-CatilGrass +</p> diff --git a/docs/dev/pages/issues/t1_pathf-export-macro.md b/docs/dev/pages/issues/t1_pathf-export-macro.md new file mode 100644 index 0000000..0a98485 --- /dev/null +++ b/docs/dev/pages/issues/t1_pathf-export-macro.md @@ -0,0 +1,53 @@ +<h1 align="center">[T1] The pathf_export Attribute Macro</h1> +<p align="center"> + Feature: an escape hatch for <code>pathf</code>'s path inference +</p> + +## Background + +`pathf` has been around since 0.2.0 and has worked well for a long time, with many edge cases resolved. However, it still lacks an escape hatch — "when certain indirect expansions cannot be recognized by `pathf`, how can we assist its inference?" + +For example, when a Mingling type is created through a user-defined `macro_rules!` wrapper, `pathf` cannot see through the indirect expansion: + +```rust +#[macro_export] +macro_rules! repack { + ($name:ident) => { + // Ignored! This section cannot be parsed by pathf. + #[mingling::macros::pathf_ignore] + #[derive(mingling::Grouped)] + pub struct $name; + }; +} + +// The expansion contains macros that need to be parsed by pathf +#[pathf_export(MyType)] // Explicitly specified to assist pathf's inference +repack!(MyType); +``` + +> [!Note] +> Haha, hopefully we'll never have to use it. + +## Plan + +Introduce a new attribute macro, `#[pathf_export(type::TypePath)]`, to supplement `pathf`'s path inference. When applied to an item whose expansion contains Mingling types that `pathf` cannot recognize, it explicitly records the resulting type paths so the build-time analyzer can pick them up. + +The example above also shows `#[mingling::macros::pathf_ignore]`, which marks an item to be skipped by `pathf` (used inside macro bodies that `pathf` otherwise cannot parse). + +## Tasks + +- [ ] Design the `pathf_export` syntax and semantics (attribute position, multiple type paths, interplay with `pathf_ignore`) +- [ ] Implement `pathf_export` in `mingling_macros` +- [ ] Implement `pathf_ignore` support in `mingling_macros` +- [ ] Teach `mingling-pathf` to consume the exported mappings +- [ ] Add tests covering indirect macro expansions +- [ ] Update docs and examples + +## 🕘 Progress + +- [ ] In Progress +- [ ] Complete + +<p align="center" style="font-size: 0.85em; color: gray;"> + Written by @Weicao-CatilGrass +</p> diff --git a/docs/dev/pages/issues/t2_automated-dispatch-tree-optimization.md b/docs/dev/pages/issues/t2_automated-dispatch-tree-optimization.md new file mode 100644 index 0000000..691fd1a --- /dev/null +++ b/docs/dev/pages/issues/t2_automated-dispatch-tree-optimization.md @@ -0,0 +1,57 @@ +<h1 align="center">[T2] Automated dispatcher_tree Optimization Decisions</h1> +<p align="center"> + Feature: let Mingling decide when <code>dispatch_tree</code> pays off (under consideration) +</p> + +> [!NOTE] +> +> This item is **under consideration**. It depends on [Remove with_dispatcher and with_dispatchers](t0_remove-with-dispatcher). + +## Background + +`dispatch_tree` provides a faster dispatch path, but it is not always a win. Currently users must manually enable the `dispatch_tree` feature and make the trade-off themselves. + +After dispatcher registration becomes compile-time collected (see [Remove with_dispatcher and with_dispatchers](t0_remove-with-dispatcher)), Mingling can know the full set and depth of registered commands at compile time — making automated decisions implementable. + +## Plan + +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. + +### Resolve the `pathf` + `dispatch_tree` build-dependency issue + +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 +``` + +## Tasks + +- [ ] Collect statistics about registered commands (count, depth) at compile time +- [ ] Benchmark / tune the threshold between linear lookup and `dispatch_tree` +- [ ] Implement the automatic decision and wire it into dispatch code generation +- [ ] Remove the manual `dispatch_tree` feature toggle (or keep it as an override?) +- [ ] Refactor `pathf` so it no longer branches on `dispatch_tree` +- [ ] Update examples, tests, and docs + +## 🕘 Progress + +- [ ] Under Consideration +- [ ] In Progress +- [ ] Complete + +<p align="center" style="font-size: 0.85em; color: gray;"> + Written by @Weicao-CatilGrass +</p> diff --git a/docs/pages/1-getting-started.md b/docs/pages/1-getting-started.md index 443ed74..0131ec1 100644 --- a/docs/pages/1-getting-started.md +++ b/docs/pages/1-getting-started.md @@ -13,7 +13,7 @@ Add the following to `Cargo.toml`: ```toml [dependencies.mingling] -version = "0.4.0" +version = "0.5.0" features = [] ``` @@ -25,7 +25,7 @@ Some features **directly affect the entire lifecycle behavior**, so you need to ```toml [dependencies.mingling] -version = "0.4.0" +version = "0.5.0" features = [ "parser", "comp", diff --git a/docs/res/guide.txt b/docs/res/guide.txt index 74f9c69..e84f893 100644 --- a/docs/res/guide.txt +++ b/docs/res/guide.txt @@ -5,5 +5,5 @@ │ > cargo add mingling │ │ │ │ Or add this to your Cargo.toml │ - │ > mingling = "0.4.0" │ + │ > mingling = "0.5.0" │ └────────────────────────────────────┘ diff --git a/examples/example-argument-parse/Cargo.lock b/examples/example-argument-parse/Cargo.lock index 8debd86..146e227 100644 --- a/examples/example-argument-parse/Cargo.lock +++ b/examples/example-argument-parse/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -66,7 +66,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -74,7 +74,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-argument-picker/Cargo.lock b/examples/example-argument-picker/Cargo.lock index 9977771..f7969b6 100644 --- a/examples/example-argument-picker/Cargo.lock +++ b/examples/example-argument-picker/Cargo.lock @@ -74,7 +74,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "arg-picker", "mingling_core", @@ -83,7 +83,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -91,7 +91,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-async-support/Cargo.lock b/examples/example-async-support/Cargo.lock index 67cd6b6..a2751be 100644 --- a/examples/example-async-support/Cargo.lock +++ b/examples/example-async-support/Cargo.lock @@ -58,7 +58,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -67,7 +67,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -75,7 +75,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-basic/Cargo.lock b/examples/example-basic/Cargo.lock index 6be449c..e38b91d 100644 --- a/examples/example-basic/Cargo.lock +++ b/examples/example-basic/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -73,7 +73,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-clap-binding/Cargo.lock b/examples/example-clap-binding/Cargo.lock index 46d334e..1eb895f 100644 --- a/examples/example-clap-binding/Cargo.lock +++ b/examples/example-clap-binding/Cargo.lock @@ -166,7 +166,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -174,7 +174,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -182,7 +182,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-combine-pathf-dispatch-tree/Cargo.lock b/examples/example-combine-pathf-dispatch-tree/Cargo.lock index 8560b73..9fdbf4f 100644 --- a/examples/example-combine-pathf-dispatch-tree/Cargo.lock +++ b/examples/example-combine-pathf-dispatch-tree/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -74,7 +74,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", @@ -84,7 +84,7 @@ dependencies = [ [[package]] name = "mingling_pathf" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-combine-pathf-metadata/Cargo.lock b/examples/example-combine-pathf-metadata/Cargo.lock index 745167a..0e1782e 100644 --- a/examples/example-combine-pathf-metadata/Cargo.lock +++ b/examples/example-combine-pathf-metadata/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -74,7 +74,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", @@ -84,7 +84,7 @@ dependencies = [ [[package]] name = "mingling_pathf" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-command-macro/Cargo.lock b/examples/example-command-macro/Cargo.lock index cd1babf..53d6f18 100644 --- a/examples/example-command-macro/Cargo.lock +++ b/examples/example-command-macro/Cargo.lock @@ -74,7 +74,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "arg-picker", "mingling_core", @@ -83,7 +83,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -91,7 +91,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-completion/Cargo.lock b/examples/example-completion/Cargo.lock index dab3f37..97401e7 100644 --- a/examples/example-completion/Cargo.lock +++ b/examples/example-completion/Cargo.lock @@ -84,7 +84,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -93,7 +93,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "just_template", @@ -102,7 +102,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "proc-macro2", diff --git a/examples/example-custom-pickable/Cargo.lock b/examples/example-custom-pickable/Cargo.lock index 11f417a..3aa6236 100644 --- a/examples/example-custom-pickable/Cargo.lock +++ b/examples/example-custom-pickable/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -66,7 +66,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -74,7 +74,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-dispatch-tree/Cargo.lock b/examples/example-dispatch-tree/Cargo.lock index 015d536..b80a18e 100644 --- a/examples/example-dispatch-tree/Cargo.lock +++ b/examples/example-dispatch-tree/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -73,7 +73,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-enum-tag/Cargo.lock b/examples/example-enum-tag/Cargo.lock index b9de59b..868af79 100644 --- a/examples/example-enum-tag/Cargo.lock +++ b/examples/example-enum-tag/Cargo.lock @@ -84,7 +84,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -93,7 +93,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "just_template", @@ -102,7 +102,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "proc-macro2", diff --git a/examples/example-error-handling/Cargo.lock b/examples/example-error-handling/Cargo.lock index f03ca4d..3110ae9 100644 --- a/examples/example-error-handling/Cargo.lock +++ b/examples/example-error-handling/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -73,7 +73,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-exitcode/Cargo.lock b/examples/example-exitcode/Cargo.lock index 2924262..37170f2 100644 --- a/examples/example-exitcode/Cargo.lock +++ b/examples/example-exitcode/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -73,7 +73,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-help/Cargo.lock b/examples/example-help/Cargo.lock index 5a482a5..9c39a41 100644 --- a/examples/example-help/Cargo.lock +++ b/examples/example-help/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -73,7 +73,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-hook/Cargo.lock b/examples/example-hook/Cargo.lock index 588e6ef..e4d68ce 100644 --- a/examples/example-hook/Cargo.lock +++ b/examples/example-hook/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -73,7 +73,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-implicit-dispatcher/Cargo.lock b/examples/example-implicit-dispatcher/Cargo.lock index f9f8838..9ca0f10 100644 --- a/examples/example-implicit-dispatcher/Cargo.lock +++ b/examples/example-implicit-dispatcher/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -73,7 +73,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-lazy-resources/Cargo.lock b/examples/example-lazy-resources/Cargo.lock index 0786373..21cb251 100644 --- a/examples/example-lazy-resources/Cargo.lock +++ b/examples/example-lazy-resources/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -73,7 +73,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-metadata/Cargo.lock b/examples/example-metadata/Cargo.lock index 8517b6a..bfa1d01 100644 --- a/examples/example-metadata/Cargo.lock +++ b/examples/example-metadata/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -73,7 +73,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-outside-type/Cargo.lock b/examples/example-outside-type/Cargo.lock index a12fc80..49c8c6f 100644 --- a/examples/example-outside-type/Cargo.lock +++ b/examples/example-outside-type/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -73,7 +73,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-pack-err/Cargo.lock b/examples/example-pack-err/Cargo.lock index 1bc9022..bcfbb41 100644 --- a/examples/example-pack-err/Cargo.lock +++ b/examples/example-pack-err/Cargo.lock @@ -64,7 +64,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -73,7 +73,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -83,7 +83,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-panic-unwind/Cargo.lock b/examples/example-panic-unwind/Cargo.lock index 6481eb4..ec5492d 100644 --- a/examples/example-panic-unwind/Cargo.lock +++ b/examples/example-panic-unwind/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -66,7 +66,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -74,7 +74,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-pathfinder/Cargo.lock b/examples/example-pathfinder/Cargo.lock index e00aa91..b93e443 100644 --- a/examples/example-pathfinder/Cargo.lock +++ b/examples/example-pathfinder/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -74,7 +74,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", @@ -84,7 +84,7 @@ dependencies = [ [[package]] name = "mingling_pathf" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-repl-basic/Cargo.lock b/examples/example-repl-basic/Cargo.lock index d4d5bd9..e85083d 100644 --- a/examples/example-repl-basic/Cargo.lock +++ b/examples/example-repl-basic/Cargo.lock @@ -64,7 +64,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -73,7 +73,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "might_be_async", @@ -81,7 +81,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "proc-macro2", diff --git a/examples/example-resources/Cargo.lock b/examples/example-resources/Cargo.lock index a559bdb..9623e25 100644 --- a/examples/example-resources/Cargo.lock +++ b/examples/example-resources/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -66,7 +66,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -74,7 +74,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-setup/Cargo.lock b/examples/example-setup/Cargo.lock index 47d36e5..c8e0e34 100644 --- a/examples/example-setup/Cargo.lock +++ b/examples/example-setup/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -73,7 +73,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-structural-renderer/Cargo.lock b/examples/example-structural-renderer/Cargo.lock index c3f24c7..ac4cbba 100644 --- a/examples/example-structural-renderer/Cargo.lock +++ b/examples/example-structural-renderer/Cargo.lock @@ -64,7 +64,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -74,7 +74,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -85,7 +85,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/example-unit-test/Cargo.lock b/examples/example-unit-test/Cargo.lock index a1b4e59..455fa9d 100644 --- a/examples/example-unit-test/Cargo.lock +++ b/examples/example-unit-test/Cargo.lock @@ -57,7 +57,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -73,7 +73,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/examples/full-todolist/Cargo.lock b/examples/full-todolist/Cargo.lock index 28d551b..4fc964d 100644 --- a/examples/full-todolist/Cargo.lock +++ b/examples/full-todolist/Cargo.lock @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -75,7 +75,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -85,7 +85,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", @@ -1346,12 +1346,12 @@ pub fn complete_hello(ctx: &ShellContext) -> Suggest { cargo init # Add Mingling -cargo add mingling@0.4.0</code></pre> +cargo add mingling@0.5.0</code></pre> <pre class="carousel-code" ><code class="language-toml"># Add the Mingling dependency [dependencies.mingling] -version = "0.4.0" +version = "0.5.0" features = [ "extras", # extra macro support "picker", # argument picker @@ -1361,7 +1361,7 @@ features = [ ><code class="language-bash"># Download and install mingling-cli # https://mingling-rs.github.io/mingling/dist/ -mling proj-init 0.4.0@basic +mling proj-init 0.5.0@basic nano checklist.toml # Edit # Run `proj-init` again to deploy diff --git a/mingling_cli/Cargo.lock b/mingling_cli/Cargo.lock index fd3fb1d..c738a0e 100644 --- a/mingling_cli/Cargo.lock +++ b/mingling_cli/Cargo.lock @@ -812,7 +812,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "arg-picker", "mingling_core", @@ -821,7 +821,7 @@ dependencies = [ [[package]] name = "mingling-cli" -version = "0.4.0" +version = "0.5.0" dependencies = [ "annotate-snippets", "cargo_metadata", @@ -846,7 +846,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "just_template", @@ -856,7 +856,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "proc-macro2", @@ -866,7 +866,7 @@ dependencies = [ [[package]] name = "mingling_pathf" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "proc-macro2", diff --git a/mingling_cli/Cargo.toml b/mingling_cli/Cargo.toml index 009b334..dfc686d 100644 --- a/mingling_cli/Cargo.toml +++ b/mingling_cli/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "mingling-cli" -version = "0.4.0" +version = "0.5.0" edition = "2024" license = "MIT OR Apache-2.0" repository = "https://github.com/mingling-rs/mingling/tree/main/mingling_cli" diff --git a/mingling_cli/src/lib.rs b/mingling_cli/src/lib.rs index ae3b0e0..902ab32 100644 --- a/mingling_cli/src/lib.rs +++ b/mingling_cli/src/lib.rs @@ -1,7 +1,7 @@ use mingling::{ - ShellContext, Suggest, + RenderResult, ShellContext, Suggest, consts::HELP_FLAG, - macros::{completion, gen_program, help, suggest}, + macros::{completion, gen_program, help, renderer, suggest}, }; use crate::{ @@ -26,7 +26,7 @@ pub mod utils; #[help] pub fn help_global(_: EntryFallback) -> String { - include_str!("../help/help.txt").parse_color_code() + format!("{}\n", include_str!("../help/help.txt").parse_color_code()) } #[completion(EntryFallback)] @@ -42,4 +42,25 @@ pub fn complete_global(_ctx: &ShellContext) -> Suggest { } } +#[renderer] +pub fn handle_fallback(args: EntryFallback) -> RenderResult { + let mut r = RenderResult::new(); + let args = args.inner; + if !args.is_empty() { + eprintln_cargo!( + r, + "{}", + format!("Unknown command `{}`", args.join(" ")).parse_color_code() + ) + } else { + hprintln_cargo!( + r, + "{}", + "Welcome to MinglingCLI, please use `mling -h` to see available commands" + .parse_color_code(), + ); + } + r +} + gen_program!(); diff --git a/mingling_cli/src/pkg_mgr/cmd_install.rs b/mingling_cli/src/pkg_mgr/cmd_install.rs index ddcef7d..731ba98 100644 --- a/mingling_cli/src/pkg_mgr/cmd_install.rs +++ b/mingling_cli/src/pkg_mgr/cmd_install.rs @@ -2,9 +2,10 @@ use std::{env, fs, io, path::PathBuf, process::Command}; use cargo_metadata::TargetKind; use mingling::{ - Grouped, LazyRes, RenderResult, Routable, - macros::{chain, command, metadata, pack_err, renderer, routeify}, + Grouped, LazyRes, RenderResult, Routable, ShellContext, Suggest, + macros::{arg, chain, command, completion, metadata, pack_err, renderer, routeify, suggest}, metadata::Description, + picker::{EntryPicker, PickerArg, value::Flag}, }; use crate::{ @@ -16,6 +17,11 @@ use crate::{ pack_err!(ErrorBuildFailed = String); pack_err!(ErrorBinaryNotFound = String); +pack_err!(ErrorPkgEnableFailed = String); + +/// Flag: `--enable` — run `mling pkg-enable` after a successful install +/// to enable the package being installed. +pub static ARG_ENABLE: PickerArg<Flag> = arg![enable: Flag]; /// Resolved install paths, used by the build step. #[derive(Debug, Default, Grouped)] @@ -24,6 +30,7 @@ pub struct StateInstallBuild { pub install_dir: PathBuf, pub release_dir: PathBuf, pub exe_suffix: &'static str, + pub enable: bool, } /// State after `cargo build --release`, used by the copy step. @@ -33,6 +40,16 @@ pub struct StateInstallCopy { pub release_dir: PathBuf, pub exe_suffix: &'static str, pub installed: Vec<PathBuf>, + pub enable: bool, +} + +/// State after the copy step when `--enable` was given: run `mling pkg-enable`. +#[derive(Debug, Default, Grouped)] +pub struct StateInstallEnable { + pub install_dir: PathBuf, + pub installed: Vec<PathBuf>, + pub name: String, + pub version: String, } #[derive(Debug, Default, Grouped)] @@ -49,7 +66,12 @@ pub fn desc_install() -> Description { } #[command(routeify)] -pub fn install(packages_dir: &ResPackagesDir, metadata: &mut LazyRes<ResMetadata>) -> Next { +pub fn install( + args: EntryInstall, + packages_dir: &ResPackagesDir, + metadata: &mut LazyRes<ResMetadata>, +) -> Next { + let enable = args.pick(&ARG_ENABLE).to_result()?; let metadata = metadata.get_ref().data(); let packages_dir = &packages_dir.path; if packages_dir.as_os_str().is_empty() { @@ -69,6 +91,7 @@ pub fn install(packages_dir: &ResPackagesDir, metadata: &mut LazyRes<ResMetadata .join("release") .into_std_path_buf(), exe_suffix: env::consts::EXE_SUFFIX, + enable: enable.bool(), } .to_chain() } @@ -93,6 +116,7 @@ pub fn handle_state_install_build(state: StateInstallBuild) -> Next { release_dir: state.release_dir, exe_suffix: state.exe_suffix, installed: vec![], + enable: state.enable, } .to_chain() } @@ -153,6 +177,45 @@ pub fn handle_state_install_copy( } } + if state.enable { + let root_package = metadata + .root_package() + .or_else(|| metadata.workspace_packages().first().copied()) + .ok_or(ErrorRootPackageNotFound::default())?; + return StateInstallEnable { + install_dir: state.install_dir, + installed: state.installed, + name: root_package.name.to_string(), + version: root_package.version.to_string(), + } + .to_chain(); + } + + ResultInstall { + install_dir: state.install_dir, + installed: state.installed, + } + .to_chain() +} + +/// Step 3 (optional): enable the installed package via `mling pkg-enable` +/// when `--enable` was given. +#[chain(routeify)] +pub fn handle_state_install_enable(state: StateInstallEnable) -> Next { + let spec = format!("{}@{}", state.name, state.version); + let status = Command::new("mling") + .args(["pkg-enable", &spec]) + .status() + .map_err(|e| { + ErrorPkgEnableFailed::new(format!("failed to run `mling pkg-enable {spec}`: {e}")) + })?; + if !status.success() { + return ErrorPkgEnableFailed::new(format!( + "`mling pkg-enable {spec}` failed with {status}" + )) + .to_chain(); + } + ResultInstall { install_dir: state.install_dir, installed: state.installed, @@ -183,3 +246,20 @@ pub fn render_error_binary_not_found(err: ErrorBinaryNotFound) -> RenderResult { eprintln_cargo!(r, "binary not found: {}", err.info); r } + +#[renderer] +pub fn render_error_pkg_enable_failed(err: ErrorPkgEnableFailed) -> RenderResult { + let mut r = RenderResult::new(); + eprintln_cargo!(r, "{}", err.info); + r +} + +#[completion(EntryInstall)] +pub fn complete_install(ctx: &ShellContext) -> Suggest { + if ctx.previous_word != "install" { + return Suggest::FileCompletion; + } + suggest! { + ARG_ENABLE: "Enable the package after installing (runs `mling pkg-enable`)" + } +} diff --git a/mingling_core/tests/test-all/Cargo.lock b/mingling_core/tests/test-all/Cargo.lock index b57638b..07bc08e 100644 --- a/mingling_core/tests/test-all/Cargo.lock +++ b/mingling_core/tests/test-all/Cargo.lock @@ -129,7 +129,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -139,7 +139,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "just_template", @@ -153,7 +153,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "proc-macro2", diff --git a/mingling_core/tests/test-basic/Cargo.lock b/mingling_core/tests/test-basic/Cargo.lock index a8f189f..d425069 100644 --- a/mingling_core/tests/test-basic/Cargo.lock +++ b/mingling_core/tests/test-basic/Cargo.lock @@ -50,7 +50,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -58,7 +58,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -66,7 +66,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/mingling_core/tests/test-comp/Cargo.lock b/mingling_core/tests/test-comp/Cargo.lock index 5f4eeb3..1a37590 100644 --- a/mingling_core/tests/test-comp/Cargo.lock +++ b/mingling_core/tests/test-comp/Cargo.lock @@ -77,7 +77,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -85,7 +85,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "just_template", @@ -94,7 +94,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "proc-macro2", diff --git a/mingling_core/tests/test-dispatch-tree/Cargo.lock b/mingling_core/tests/test-dispatch-tree/Cargo.lock index c6d33ae..245893d 100644 --- a/mingling_core/tests/test-dispatch-tree/Cargo.lock +++ b/mingling_core/tests/test-dispatch-tree/Cargo.lock @@ -50,7 +50,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -58,7 +58,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -66,7 +66,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/mingling_core/tests/test-repl/Cargo.lock b/mingling_core/tests/test-repl/Cargo.lock index e359032..b55f5ba 100644 --- a/mingling_core/tests/test-repl/Cargo.lock +++ b/mingling_core/tests/test-repl/Cargo.lock @@ -50,7 +50,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -58,7 +58,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -66,7 +66,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/mingling_core/tests/test-structural-renderer/Cargo.lock b/mingling_core/tests/test-structural-renderer/Cargo.lock index d54d299..fcf244d 100644 --- a/mingling_core/tests/test-structural-renderer/Cargo.lock +++ b/mingling_core/tests/test-structural-renderer/Cargo.lock @@ -65,7 +65,7 @@ dependencies = [ [[package]] name = "mingling" -version = "0.4.0" +version = "0.5.0" dependencies = [ "mingling_core", "mingling_macros", @@ -75,7 +75,7 @@ dependencies = [ [[package]] name = "mingling_core" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "might_be_async", @@ -88,7 +88,7 @@ dependencies = [ [[package]] name = "mingling_macros" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt", "proc-macro2", diff --git a/mingling_pathf/test/Cargo.lock b/mingling_pathf/test/Cargo.lock index e7de689..58c7c9a 100644 --- a/mingling_pathf/test/Cargo.lock +++ b/mingling_pathf/test/Cargo.lock @@ -16,7 +16,7 @@ checksum = "6170dccbc3ea15dfb7f2da964097f814aba1dd8f746d4ffc56f33245c38e6d96" [[package]] name = "mingling_pathf" -version = "0.4.0" +version = "0.5.0" dependencies = [ "just_fmt 0.2.0", "proc-macro2", |