Features

Mingling's complete feature list

# 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:** Enables serde formatting support for all serialization formats (JSON, RON, TOML, YAML) in `structural_renderer`. Enabling this feature will automatically enable the four sub-features: `json_serde_fmt`, `ron_serde_fmt`, `toml_serde_fmt`, `yaml_serde_fmt`. ## Feature `async` **Description:** Enables async runtime support, allowing `#[chain]` to bind `async` functions, e.g.: ```rust // Features: ["async"] pack!(StateFoo = ()); #[chain] async fn handle_state_foo(foo: StateFoo) -> Next { StateFoo::new(()).into() } ``` See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-async-support) ## Feature `builds` **Description:** Enables scripts needed for use in `build.rs`, currently including: 1. Completion script generation under the `comp` feature: ```rust // BUILD TIME // Features: ["builds", "comp"] use mingling::build::build_comp_scripts; // Generate completion scripts for `myprogram` build_comp_scripts("myprogram").unwrap(); ``` ## Feature `clap` **Description:** Enables integration with the [clap](https://crates.io/crates/clap) command-line argument parsing library, making it easy to build CLI apps. With this feature enabled, you can use the `#[dispatcher_clap]` attribute macro to generate a dispatcher from a `clap::Parser` struct. See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-clap-binding) ## Feature `comp` **Description:** Enables code completion functionality, providing auto-completion support for interactive environments. When enabled, you can use the `#[completion]` attribute macro to define dynamic completion logic, and generate completion scripts for shells such as bash, zsh, fish, and pwsh. See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-completion) ## Feature `debug` **Description:** Enables debugging-related features, providing more detailed error info and diagnostic output. ## Feature `dispatch_tree` **Description:** Enables the dispatch tree mechanism, supporting conditional dispatch and routing. When enabled, Mingling **at compile time** hard-codes the subcommand structure as a prefix tree (Trie), achieving extremely fast subcommand lookup. Lookup complexity is **O(n)**, where _n_ is the input length, not the number of commands. See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-dispatch-tree) ## Feature `extras` **Description:** Enables an additional set of macros, providing more convenient syntactic sugar and metaprogramming capabilities. For example, allows the shorthand form `dispatcher!("greet")`, which auto-generates `CMDGreet` / `EntryGreet`. | Macro | Description | | ------------------------------------------------------- | --------------------------------------------------------------- | | `empty_result!()` | Shorthand for returning an empty result early in a chain | | `entry!(Type, ["a", "b"])` | Construct test data for an entry type | | `group!(Type)` | Register external types as group members without modifying them | | `pack_err!(ErrorType)` / `pack_err!(ErrorType = Inner)` | Create error types with an automatic `name` field | | `#[program_setup]` | Declare a program initialization function | | `dispatcher!("cmd.path")` **shorthand** | Omit `CMDStruct => EntryStruct`, names are auto-derived |
Details ### `empty_result!()` ```rust // Features: ["extras"] pack!(StatePrev1 = ()); pack!(StatePrev2 = ()); pack!(StateNext = ()); #[chain] fn handle_state_prev2(_p: StatePrev2) { // A #[chain] with no return type can simply omit the return value } #[chain] fn handle_state_prev1(_p: StatePrev1) -> Next { let foo = 1; let bar = 2; if foo != bar { // When Next is needed but no return value is required, use this empty_result!() } else { StateNext::new(()).into() } } ``` ### `#[program_setup]` ```rust // Features: ["extras"] use mingling::{macros::program_setup, Program}; fn main() { let mut program = ThisProgram::new(); program.with_setup(NoErrorSetup); program.exec_and_exit(); } #[program_setup] fn no_error_setup(program: &mut Program) { program.global_flag(["--no-error"], |program| { program.stdout_setting.error_output = false; }); } ``` ### `entry!` ```rust // Features: ["extras"] use mingling::macros::entry; pack!(EntryHello = Vec); fn main() { let result: Next = handle_hello(entry!("--name", "Bob")).into(); // ... assertion logic here } #[chain] fn handle_hello(args: EntryHello) {} ``` ### `group!` Registers an external type as a member of the program group without modifying its definition. The type's simple name is used as the enum variant, just like `pack!` or `#[derive(Grouped)]`. ```rust // Features: ["extras"] use mingling::macros::group; use std::num::ParseIntError; // Register std::num::ParseIntError as a group member. // After this, ParseIntError can be used in #[chain] and #[renderer] functions. group!(std::num::ParseIntError); ``` ### `pack_err!` Creates an error struct with an automatic `name: String` field set to the snake_case of the struct name. Optionally wraps an inner type for additional context. ```rust // Features: ["extras"] use std::path::PathBuf; // Simple form — only a name field: pack_err!(ErrorNotFound); // Generates: // struct ErrorNotFound { pub name: String } // impl Default for ErrorNotFound { ... } // Typed form — with additional info field: pack_err!(ErrorNotDir = PathBuf); // Generates: // struct ErrorNotDir { pub name: String, pub info: PathBuf } // impl ErrorNotDir { pub fn new(info: PathBuf) -> Self { ... } } ```
## Feature `structural_renderer` **Description:** Enables the structural renderer, providing basic content rendering capabilities. Enabling this feature will automatically enable `json_serde_fmt`. When enabled, users can get structured output via flags like `--json` or `--yaml`. See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-structural-renderer) ## Feature `structural_renderer_empty` **Description:** Enables an empty implementation of the structural renderer, suitable for scenarios where no actual rendering is needed. This feature does not enable any serde formatting backend. ## Feature `structural_renderer_full` **Description:** Enables the full implementation of the structural renderer, including all rendering capabilities and serialization format support. Enabling this feature will automatically enable `all_serde_fmt`. ## Feature `json_serde_fmt` **Description:** Enables JSON serde serialization/deserialization formatting support. ## Feature `nightly` **Description:** Enables experimental features only available in the Nightly Rust compiler. ## Feature `pathf` > [!IMPORTANT] > > This feature is **EXPERIMENTAL**, its API may change in future versions. **Description:** Enables the Module Pathfinder, which at build time automatically resolves the full module paths of all Mingling types and generates a `use` statement mapping file for `gen_program!()` to consume. When enabled, types can be defined in any submodule, and `gen_program!()` can automatically identify them and generate the correct full-path references without requiring manual `use` imports. ```toml # Cargo.toml [dependencies.mingling] features = ["pathf"] [build-dependencies.mingling] features = ["builds", "pathf"] ``` ```rust // BUILD TIME // Features: ["pathf"] analyze_and_build_type_mapping().unwrap(); ``` See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-pathfinder) ## Feature `parser` **Description:** Enables the argument parser module, providing argument parsing functionality. When enabled, you can use `Picker` for simple argument extraction, supporting methods like `pick()` and `pick_or()`. See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-argument-parse) ## Feature `picker` **Description:** Introduces the `arg-picker` dependency, providing more advanced argument parsing capabilities for Mingling. It can coexist with the `parser` and `clap` features, but it is recommended not to enable it alongside the `parser` feature, as their APIs are very similar. `picker` is an argument parser independent of Mingling and does not rely on the built-in argument extraction API of `mingling_core`. See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-argument-picker) ## Feature `repl` **Description:** Enables interactive REPL (Read-Eval-Print Loop) environment support. When enabled, you can turn your CLI into an interactive shell via `program.exec_repl()`. See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-repl-basic) ## Feature `ron_serde_fmt` **Description:** Enables RON (Rusty Object Notation) serde serialization/deserialization formatting support. ## Feature `toml_serde_fmt` **Description:** Enables TOML serde serialization/deserialization formatting support. ## Feature `yaml_serde_fmt` **Description:** Enables YAML serde serialization/deserialization formatting support.

Written by @Weicao-CatilGrass