aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--docs/example-pages/examples.json16
-rw-r--r--examples/example-command-macro/Cargo.lock234
-rw-r--r--examples/example-command-macro/Cargo.toml16
-rw-r--r--examples/example-command-macro/page.toml10
-rw-r--r--examples/example-command-macro/src/main.rs66
-rw-r--r--examples/test-examples.toml15
-rw-r--r--mingling/src/example_docs.rs90
7 files changed, 447 insertions, 0 deletions
diff --git a/docs/example-pages/examples.json b/docs/example-pages/examples.json
index 2a07365..349248e 100644
--- a/docs/example-pages/examples.json
+++ b/docs/example-pages/examples.json
@@ -95,6 +95,22 @@
]
},
{
+ "id": "example-command-macro",
+ "name": "Command Macro",
+ "icon": "🚀",
+ "category": "advanced",
+ "desc": "Introduced how to use the `#[command]` macro to generate commands with minimal boilerplate\n",
+ "tags": [
+ "#[command]",
+ "dispatcher!",
+ "#[chain]"
+ ],
+ "files": [
+ "src/main.rs",
+ "Cargo.toml"
+ ]
+ },
+ {
"id": "example-completion",
"name": "Completion",
"icon": "🔄",
diff --git a/examples/example-command-macro/Cargo.lock b/examples/example-command-macro/Cargo.lock
new file mode 100644
index 0000000..025b322
--- /dev/null
+++ b/examples/example-command-macro/Cargo.lock
@@ -0,0 +1,234 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "arg-picker"
+version = "0.1.1"
+dependencies = [
+ "arg-picker-macros",
+ "just_fmt",
+]
+
+[[package]]
+name = "arg-picker-macros"
+version = "0.1.1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "example-command-macro"
+version = "0.1.0"
+dependencies = [
+ "mingling",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "indexmap"
+version = "2.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
+[[package]]
+name = "just_fmt"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6170dccbc3ea15dfb7f2da964097f814aba1dd8f746d4ffc56f33245c38e6d96"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "might_be_async"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eca871cea620b07bd2e6da0c883891a25bead698c43a9ab64b0fd663a7a78d5f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+ "toml",
+]
+
+[[package]]
+name = "mingling"
+version = "0.3.0"
+dependencies = [
+ "arg-picker",
+ "mingling_core",
+ "mingling_macros",
+]
+
+[[package]]
+name = "mingling_core"
+version = "0.3.0"
+dependencies = [
+ "just_fmt",
+ "might_be_async",
+]
+
+[[package]]
+name = "mingling_macros"
+version = "0.3.0"
+dependencies = [
+ "just_fmt",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "serde_spanned"
+version = "0.6.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.118"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "toml"
+version = "0.8.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362"
+dependencies = [
+ "serde",
+ "serde_spanned",
+ "toml_datetime",
+ "toml_edit",
+]
+
+[[package]]
+name = "toml_datetime"
+version = "0.6.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "toml_edit"
+version = "0.22.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"
+dependencies = [
+ "indexmap",
+ "serde",
+ "serde_spanned",
+ "toml_datetime",
+ "toml_write",
+ "winnow",
+]
+
+[[package]]
+name = "toml_write"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "winnow"
+version = "0.7.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
+dependencies = [
+ "memchr",
+]
diff --git a/examples/example-command-macro/Cargo.toml b/examples/example-command-macro/Cargo.toml
new file mode 100644
index 0000000..b73c2c6
--- /dev/null
+++ b/examples/example-command-macro/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "example-command-macro"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies.mingling]
+path = "../../mingling"
+features = [
+ # Use `extra_macros` to introduce the `#[command]` macro
+ "extra_macros",
+
+ # Use `picker` to parse arguments
+ "picker",
+]
+
+[workspace]
diff --git a/examples/example-command-macro/page.toml b/examples/example-command-macro/page.toml
new file mode 100644
index 0000000..fe36d7a
--- /dev/null
+++ b/examples/example-command-macro/page.toml
@@ -0,0 +1,10 @@
+[example]
+id = "example-command-macro"
+name = "Command Macro"
+icon = "🚀"
+category = "advanced"
+desc = """
+Introduced how to use the `#[command]` macro to generate commands with minimal boilerplate
+"""
+tags = ["#[command]", "dispatcher!", "#[chain]"]
+files = ["src/main.rs", "Cargo.toml"]
diff --git a/examples/example-command-macro/src/main.rs b/examples/example-command-macro/src/main.rs
new file mode 100644
index 0000000..2bf932a
--- /dev/null
+++ b/examples/example-command-macro/src/main.rs
@@ -0,0 +1,66 @@
+//! Example Command Macro
+//!
+//! > Introduced how to use the `#[command]` macro to generate commands with minimal boilerplate
+//!
+//! Run:
+//! ```base
+//! cargo run --manifest-path examples/example-command-macro/Cargo.toml --quiet -- hello world
+//! cargo run --manifest-path examples/example-command-macro/Cargo.toml --quiet -- greet-someone Alice
+//! cargo run --manifest-path examples/example-command-macro/Cargo.toml --quiet -- goodbye
+//! ```
+//!
+//! Output:
+//! ```plaintext
+//! Hello, World
+//! Hello, Alice
+//! Goodbye!
+//! ```
+
+use mingling::{macros::buffer, picker::IntoPicker, prelude::*};
+
+fn main() {
+ let mut program = ThisProgram::new();
+
+ // Import the dispatchers generated by the `#[command]` macro
+ program.with_dispatcher(CMDHelloWorld);
+ program.with_dispatcher(CMDGreetSomeone);
+ program.with_dispatcher(CMDGoodBye);
+
+ program.exec_and_exit();
+}
+
+pack!(ResultGreeting = String);
+pack!(ResultGoodbye = ());
+
+// --------- IMPORTANT ---------
+// Auto-generates dispatcher!("hello.world", CMDHelloWorld => EntryHelloWorld);
+#[command]
+fn hello_world() -> ResultGreeting {
+ ResultGreeting::new("World".to_string())
+}
+
+// Auto-generates dispatcher!("hello-world", CMDGreetSomeone => EntryGreetSomeone);
+#[command(node = "greet-someone")]
+fn greet_someone(args: Vec<String>) -> ResultGreeting {
+ let name = args.pick_or(&arg![String], || "World".to_string()).unwrap();
+ ResultGreeting::new(name)
+}
+
+// Auto-generates dispatcher!("goodbye", CMDGoodBye => EntryGoodBye);
+#[command(name = CMDGoodBye, entry = EntryGoodBye)]
+fn goodbye() -> ResultGoodbye {
+ ResultGoodbye::default()
+}
+// --------- IMPORTANT ---------
+
+#[renderer(buffer)]
+fn render_greeting(result: ResultGreeting) {
+ r_println!("Hello, {}", *result);
+}
+
+#[renderer(buffer)]
+fn render_goodbye(_: ResultGoodbye) {
+ r_println!("Goodbye!");
+}
+
+gen_program!();
diff --git a/examples/test-examples.toml b/examples/test-examples.toml
index e450919..b74c9a5 100644
--- a/examples/test-examples.toml
+++ b/examples/test-examples.toml
@@ -312,3 +312,18 @@ expect.result = "Result: 1.3333334"
command = "calc 4 / 3 --round"
expect.exit-code = 0
expect.result = "Result: 1"
+
+[[test.example-command-macro]]
+command = "hello world"
+expect.exit-code = 0
+expect.result = "Hello, World"
+
+[[test.example-command-macro]]
+command = "greet-someone Alice"
+expect.exit-code = 0
+expect.result = "Hello, Alice"
+
+[[test.example-command-macro]]
+command = "goodbye"
+expect.exit-code = 0
+expect.result = "Goodbye!"
diff --git a/mingling/src/example_docs.rs b/mingling/src/example_docs.rs
index 35cf024..3e9bd26 100644
--- a/mingling/src/example_docs.rs
+++ b/mingling/src/example_docs.rs
@@ -768,6 +768,96 @@ pub mod example_clap_binding {}
/// gen_program!();
/// ```
pub mod example_combine_pathf_dispatch_tree {}
+/// Example Command Macro
+///
+/// > Introduced how to use the `#[command]` macro to generate commands with minimal boilerplate
+///
+/// Run:
+/// ```base
+/// cargo run --manifest-path examples/example-command-macro/Cargo.toml --quiet -- hello world
+/// cargo run --manifest-path examples/example-command-macro/Cargo.toml --quiet -- greet-someone Alice
+/// cargo run --manifest-path examples/example-command-macro/Cargo.toml --quiet -- goodbye
+/// ```
+///
+/// Output:
+/// ```plaintext
+/// Hello, World
+/// Hello, Alice
+/// Goodbye!
+/// ```
+///
+/// Source code (./Cargo.toml)
+/// ```toml
+/// [package]
+/// name = "example-command-macro"
+/// version = "0.1.0"
+/// edition = "2024"
+///
+/// [dependencies.mingling]
+/// path = "../../mingling"
+/// features = [
+/// # Use `extra_macros` to introduce the `#[command]` macro
+/// "extra_macros",
+///
+/// # Use `picker` to parse arguments
+/// "picker",
+/// ]
+///
+/// [workspace]
+/// ```
+///
+/// Source code (./src/main.rs)
+/// ```ignore
+/// use mingling::{macros::buffer, picker::IntoPicker, prelude::*};
+///
+/// fn main() {
+/// let mut program = ThisProgram::new();
+///
+/// // Import the dispatchers generated by the `#[command]` macro
+/// program.with_dispatcher(CMDHelloWorld);
+/// program.with_dispatcher(CMDGreetSomeone);
+/// program.with_dispatcher(CMDGoodBye);
+///
+/// program.exec_and_exit();
+/// }
+///
+/// pack!(ResultGreeting = String);
+/// pack!(ResultGoodbye = ());
+///
+/// // --------- IMPORTANT ---------
+/// // Auto-generates dispatcher!("hello.world", CMDHelloWorld => EntryHelloWorld);
+/// #[command]
+/// fn hello_world() -> ResultGreeting {
+/// ResultGreeting::new("World".to_string())
+/// }
+///
+/// // Auto-generates dispatcher!("hello-world", CMDGreetSomeone => EntryGreetSomeone);
+/// #[command(node = "greet-someone")]
+/// fn greet_someone(args: Vec<String>) -> ResultGreeting {
+/// let name = args.pick_or(&arg![String], || "World".to_string()).unwrap();
+/// ResultGreeting::new(name)
+/// }
+///
+/// // Auto-generates dispatcher!("goodbye", CMDGoodBye => EntryGoodBye);
+/// #[command(name = CMDGoodBye, entry = EntryGoodBye)]
+/// fn goodbye() -> ResultGoodbye {
+/// ResultGoodbye::default()
+/// }
+/// // --------- IMPORTANT ---------
+///
+/// #[renderer(buffer)]
+/// fn render_greeting(result: ResultGreeting) {
+/// r_println!("Hello, {}", *result);
+/// }
+///
+/// #[renderer(buffer)]
+/// fn render_goodbye(_: ResultGoodbye) {
+/// r_println!("Goodbye!");
+/// }
+///
+/// gen_program!();
+/// ```
+pub mod example_command_macro {}
/// Example Completion
///
/// > This example demonstrates how to use **Mingling** to create fully dynamic command-line completions
generated by cgit (git 2.34.1) at 2026-07-29 03:13:57 +0000