aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
author魏曹先生 <1992414357@qq.com>2026-08-03 00:27:31 +0800
committer魏曹先生 <1992414357@qq.com>2026-08-03 00:28:29 +0800
commit3668b49c0d3423f1d5d10bb6b4a0e0e7b61f2046 (patch)
treeb006a40678f68c3d9c53a9035ca251596701ecef
parenteaf1ce9fa63e364774a4685b777cacdbb4f63df6 (diff)
docs: Add preset feature groups and improve feature docs
Add convenience presets (`mini`, `advanced`, `full`, `build_advanced`, `build_full`) to `mingling/Cargo.toml` and document them in both English and Chinese feature docs. Update getting-started guides to reflect the new default `core`/`macros` features.
-rw-r--r--CHANGELOG.md12
-rw-r--r--docs/_zh_CN/pages/1-getting-started.md2
-rw-r--r--docs/_zh_CN/pages/other/features.md60
-rw-r--r--docs/pages/1-getting-started.md2
-rw-r--r--docs/pages/other/features.md61
-rw-r--r--mingling/Cargo.toml21
-rw-r--r--mingling/src/features.rs55
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"))]