diff options
| -rw-r--r-- | CHANGELOG.md | 12 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/1-getting-started.md | 2 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/other/features.md | 60 | ||||
| -rw-r--r-- | docs/pages/1-getting-started.md | 2 | ||||
| -rw-r--r-- | docs/pages/other/features.md | 61 | ||||
| -rw-r--r-- | mingling/Cargo.toml | 21 | ||||
| -rw-r--r-- | mingling/src/features.rs | 55 |
7 files changed, 205 insertions, 8 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index bcb3ec3..baa7f19 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -156,6 +156,18 @@ None 7. **[`core`]** **[`comp`]** Added `Suggest::combine(self, other: impl Into<Suggest>) -> Self` method that merges two `Suggest` values. If both are `Suggest::Suggest`, their inner `BTreeSet`s are merged (all items from `other` are added into `self`). Otherwise, the first `Suggest::Suggest` (or `FileCompletion`) is returned unchanged, and the other value is discarded. This enables ergonomic aggregation of completion suggestions from multiple sources. +**[`features`]** Added preset feature groups to `mingling/Cargo.toml`, providing convenience combinations for common use cases: + +- **`mini`** — `extras`, `picker`. Minimal mode for small CLI tools. +- **`advanced`** — `extras`, `picker`, `repl`, `comp`, `dispatch_tree`, `structural_renderer`. Full-featured mode for medium-sized applications. +- **`full`** — `extras`, `picker`, `repl`, `clap`, `comp`, `dispatch_tree`, `structural_renderer_full`, `pathf`. Complete mode for large, feature-comprehensive applications. +- **`build_advanced`** — `build`, `comp`. Build-time configuration for generating completion scripts etc. +- **`build_full`** — `build`, `comp`, `pathf`, `dispatch_tree`. Full build-time configuration including the path analyzer. + + `build_advanced` and `build_full` are intended for use in `[build-dependencies]` alongside their corresponding runtime feature groups. + + Also reorganized the `[features]` section of `mingling/Cargo.toml` into logical subsections (Presets, Core, Special features, Features, LEGACY) for improved maintainability and documentation. + #### **BREAKING CHANGES** (API CHANGES): 1. **[`macros`]** **[BREAKING]** Renamed the `extra_macros` feature to `extras`. All feature-gated macro re-exports in `mingling/src/lib.rs` (and throughout the codebase) have been updated from `#[cfg(feature = "extra_macros")]` to `#[cfg(feature = "extras")]`. diff --git a/docs/_zh_CN/pages/1-getting-started.md b/docs/_zh_CN/pages/1-getting-started.md index 84870b2..2fca931 100644 --- a/docs/_zh_CN/pages/1-getting-started.md +++ b/docs/_zh_CN/pages/1-getting-started.md @@ -19,7 +19,7 @@ features = [] ## 启用特性 -**Mingling** 默认所有特性关闭，且不提供类似 `full` 的全开特性。 +**Mingling** 默认只启用 `core` 和 `macros`，其余部分需要按需启用 因为部分特性会 **直接影响整个生命周期的行为**，需要你按需启用，例如： diff --git a/docs/_zh_CN/pages/other/features.md b/docs/_zh_CN/pages/other/features.md index 84010c4..2d65e47 100644 --- a/docs/_zh_CN/pages/other/features.md +++ b/docs/_zh_CN/pages/other/features.md @@ -3,6 +3,66 @@ <b>Mingling</b> 的所有特性一览 </p> +# 预设特性组 + +Mingling 提供了一系列**预设特性组**，方便用户按需组合启用特性。 + +## `mini` + +**启用特性：** `extras`、`picker` + +**定位：** 精简模式，适合小型 CLI 工具或需要快速起步的项目。仅包含最核心的便捷宏和参数解析能力。 + +## `advanced` + +**启用特性：** `extras`、`picker`、`repl`、`comp`、`dispatch_tree`、`structural_renderer` + +**定位：** 进阶模式，在 `mini` 的基础上加入了交互式 REPL 环境、代码补全、调度树加速以及基础的结构化输出能力，适合功能较完整的中型命令行应用。 + +## `full` + +**启用特性：** `extras`、`picker`、`repl`、`clap`、`comp`、`dispatch_tree`、`structural_renderer_full`、`pathf` + +**定位：** 完整模式，启用 Mingling 的全部核心功能。在 `advanced` 的基础上额外包含 clap 集成、完整的结构化渲染器（含所有序列化格式）以及实验性的路径分析器，适合大型、功能全面的命令行应用。 + +## `build_advanced` + +**启用特性：** `build`、`comp` + +**定位：** 构建期增强配置，用于在项目构建时生成补全脚本等构建辅助材料（`comp` 特性提供补全脚本生成能力）。 + +> [!NOTE] +> +> 此特性组为**构建依赖**专用，需配合 `advanced` 特性使用。请在 `Cargo.toml` 的 `[build-dependencies]` 中启用： + +```toml +[dependencies.mingling] +features = ["advanced"] + +[build-dependencies.mingling] +features = ["build_advanced"] +``` + +## `build_full` + +**启用特性：** `build`、`comp`、`pathf`、`dispatch_tree` + +**定位：** 完整的构建期配置，在 `build_advanced` 的基础上额外包含路径分析器（`pathf`）以自动解析类型模块路径，适合结构复杂、需要自动化构建期分析的项目。 + +> [!NOTE] +> +> 此特性组为**构建依赖**专用，需配合 `full` 特性使用。请在 `Cargo.toml` 的 `[build-dependencies]` 中启用： + +```toml +[dependencies.mingling] +features = ["full"] + +[build-dependencies.mingling] +features = ["build_full"] +``` + +# 特性详解 + ## 特性 `all_serde_fmt` **介绍:** diff --git a/docs/pages/1-getting-started.md b/docs/pages/1-getting-started.md index 2f31d69..8c81100 100644 --- a/docs/pages/1-getting-started.md +++ b/docs/pages/1-getting-started.md @@ -19,7 +19,7 @@ features = [] ## Enable Features -**Mingling** has all features disabled by default and does **not** provide an all-in-one feature like `full`. +**Mingling** by default only enables `core` and `macros`; the rest need to be enabled as needed. Some features **directly affect the entire lifecycle behavior**, so you need to enable them as needed, e.g.: diff --git a/docs/pages/other/features.md b/docs/pages/other/features.md index 465c290..55b6cc8 100644 --- a/docs/pages/other/features.md +++ b/docs/pages/other/features.md @@ -3,6 +3,67 @@ <b>Mingling</b>'s complete feature list </p> +# Preset Feature Groups + +Mingling provides a set of **preset feature groups** that make it easy to enable features in whatever combination you need. + +## `mini` + +**Enables features:** `extras`, `picker` + +**Positioning:** Minimal mode, suitable for small CLI tools or projects that need to get started quickly. Includes only the most essential convenience macros and argument parsing capabilities. + +## `advanced` + +**Enables features:** `extras`, `picker`, `repl`, `comp`, `dispatch_tree`, `structural_renderer` + +**Positioning:** Advanced mode, builds on `mini` by adding an interactive REPL environment, code completion, dispatch tree acceleration, and basic structured output capabilities. Suitable for medium-sized command-line applications with a fuller feature set. + +## `full` + +**Enables features:** `extras`, `picker`, `repl`, `clap`, `comp`, `dispatch_tree`, `structural_renderer_full`, `pathf` + +**Positioning:** Full mode, enables all of Mingling's core functionality. In addition to `advanced`, it includes clap integration, the full structural renderer (with all serialization formats), and the experimental path analyzer. Suitable for large, feature-complete command-line applications. + +## `build_advanced` + +**Enables features:** `build`, `comp` + +**Positioning:** Build-time enhanced configuration, used to generate build helpers such as completion scripts at build time (the `comp` feature provides completion script generation). + +> [!NOTE] +> +> This feature group is intended for **build dependencies** only and must be used alongside the `advanced` feature. Enable it in the `[build-dependencies]` section of `Cargo.toml`: + +```toml +[dependencies.mingling] +features = ["advanced"] + +[build-dependencies.mingling] +features = ["build_advanced"] +``` + +## `build_full` + +**Enables features:** `build`, `comp`, `pathf`, `dispatch_tree` + +**Positioning:** Full build-time configuration, extends `build_advanced` with the path analyzer (`pathf`) to automatically resolve type module paths, suitable for projects with complex structures that require automated build-time analysis. + +> [!NOTE] +> +> This feature group is intended for **build dependencies** only and must be used alongside the `full` feature. Enable it in the `[build-dependencies]` section of `Cargo.toml`: + +```toml +[dependencies.mingling] +features = ["full"] + +[build-dependencies.mingling] +features = ["build_full"] +``` + +# Feature Details + + ## Feature `all_serde_fmt` **Description:** diff --git a/mingling/Cargo.toml b/mingling/Cargo.toml index 6f1cc16..f17285f 100644 --- a/mingling/Cargo.toml +++ b/mingling/Cargo.toml @@ -37,17 +37,28 @@ features = [ ] [features] + +# Presets +mini = ["extras", "picker"] +advanced = ["extras", "picker", "repl", "comp", "dispatch_tree", "structural_renderer"] +full = ["extras", "picker", "repl", "clap", "comp", "dispatch_tree", "structural_renderer_full", "pathf"] +build_advanced = ["build", "comp"] +build_full = ["build", "comp", "pathf", "dispatch_tree"] + +# Core core = ["dep:mingling_core", "mingling_core/default"] macros = ["dep:mingling_macros", "mingling_macros/default"] +# Special features nightly = ["mingling_core/nightly", "mingling_macros/nightly"] debug = ["mingling_core/debug"] async = ["mingling_core/async", "mingling_macros/async"] - -build = ["mingling_core/build"] - default = ["core", "macros"] +build = ["mingling_core/build"] +# - Section only shown in docs.rs +docs_rs = [] +# Features clap = ["mingling_core/clap", "mingling_macros/clap"] dispatch_tree = ["mingling_core/dispatch_tree", "mingling_macros/dispatch_tree"] repl = ["mingling_core/repl", "mingling_macros/repl"] @@ -90,9 +101,7 @@ ron_serde_fmt = ["mingling_core/ron_serde_fmt"] extras = ["mingling_macros/extras"] -# Section only shown in docs.rs -docs_rs = [] - +# - LEGACY - # These are old names, will be Breaking Change in the future builds = ["mingling_core/build"] diff --git a/mingling/src/features.rs b/mingling/src/features.rs index d1fcbd2..2925f03 100644 --- a/mingling/src/features.rs +++ b/mingling/src/features.rs @@ -1,3 +1,14 @@ +/// Whether the `advanced` feature is enabled +/// Current: `disabled` +#[cfg(not(feature = "advanced"))] +#[allow(unused)] +pub const MINGLING_ADVANCED: bool = false; + +/// Whether the `advanced` feature is enabled +/// Current: `enabled` +#[cfg(feature = "advanced")] +#[allow(unused)] +pub const MINGLING_ADVANCED: bool = true; /// Whether the `all_serde_fmt` feature is enabled /// Current: `disabled` #[cfg(not(feature = "all_serde_fmt"))] @@ -31,6 +42,28 @@ pub const MINGLING_BUILD: bool = false; #[cfg(feature = "build")] #[allow(unused)] pub const MINGLING_BUILD: bool = true; +/// Whether the `build_advanced` feature is enabled +/// Current: `disabled` +#[cfg(not(feature = "build_advanced"))] +#[allow(unused)] +pub const MINGLING_BUILD_ADVANCED: bool = false; + +/// Whether the `build_advanced` feature is enabled +/// Current: `enabled` +#[cfg(feature = "build_advanced")] +#[allow(unused)] +pub const MINGLING_BUILD_ADVANCED: bool = true; +/// Whether the `build_full` feature is enabled +/// Current: `disabled` +#[cfg(not(feature = "build_full"))] +#[allow(unused)] +pub const MINGLING_BUILD_FULL: bool = false; + +/// Whether the `build_full` feature is enabled +/// Current: `enabled` +#[cfg(feature = "build_full")] +#[allow(unused)] +pub const MINGLING_BUILD_FULL: bool = true; /// Whether the `builds` feature is enabled /// Current: `disabled` #[cfg(not(feature = "builds"))] @@ -141,6 +174,17 @@ pub const MINGLING_EXTRAS: bool = false; #[cfg(feature = "extras")] #[allow(unused)] pub const MINGLING_EXTRAS: bool = true; +/// Whether the `full` feature is enabled +/// Current: `disabled` +#[cfg(not(feature = "full"))] +#[allow(unused)] +pub const MINGLING_FULL: bool = false; + +/// Whether the `full` feature is enabled +/// Current: `enabled` +#[cfg(feature = "full")] +#[allow(unused)] +pub const MINGLING_FULL: bool = true; /// Whether the `json_serde_fmt` feature is enabled /// Current: `disabled` #[cfg(not(feature = "json_serde_fmt"))] @@ -163,6 +207,17 @@ pub const MINGLING_MACROS: bool = false; #[cfg(feature = "macros")] #[allow(unused)] pub const MINGLING_MACROS: bool = true; +/// Whether the `mini` feature is enabled +/// Current: `disabled` +#[cfg(not(feature = "mini"))] +#[allow(unused)] +pub const MINGLING_MINI: bool = false; + +/// Whether the `mini` feature is enabled +/// Current: `enabled` +#[cfg(feature = "mini")] +#[allow(unused)] +pub const MINGLING_MINI: bool = true; /// Whether the `nightly` feature is enabled /// Current: `disabled` #[cfg(not(feature = "nightly"))] |