From a5647e89bc5110a07c8f3c695c3c9582aa31d354 Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Sat, 16 May 2026 16:24:55 +0800
Subject: Simplify example imports to use prelude and add resources example

Add a new example demonstrating global resource injection in chain
functions,
and update all existing examples to import from `mingling::prelude`
instead
of individual macro paths. Also add `example-resources` to the workspace
exclude list.
---
 Cargo.toml                                    |  1 +
 examples/example-async/src/main.rs            |  2 +-
 examples/example-basic/src/main.rs            |  2 +-
 examples/example-completion/src/main.rs       |  5 +-
 examples/example-dispatch-tree/src/main.rs    |  2 +-
 examples/example-exit-code/src/main.rs        |  2 +-
 examples/example-general-renderer/src/main.rs |  8 +--
 examples/example-picker/src/main.rs           |  9 +--
 examples/example-resources/Cargo.lock         | 91 +++++++++++++++++++++++++++
 examples/example-resources/Cargo.toml         |  7 +++
 examples/example-resources/src/main.rs        | 57 +++++++++++++++++
 mingling_macros/src/chain.rs                  | 20 ++++--
 12 files changed, 182 insertions(+), 24 deletions(-)
 create mode 100644 examples/example-resources/Cargo.lock
 create mode 100644 examples/example-resources/Cargo.toml
 create mode 100644 examples/example-resources/src/main.rs

diff --git a/Cargo.toml b/Cargo.toml
index 8037fd6..de023e2 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -9,6 +9,7 @@ exclude = [
     "examples/example-exit-code",
     "examples/example-general-renderer",
     "examples/example-picker",
+    "examples/example-resources",
     "dev_tools",
 ]
 
diff --git a/examples/example-async/src/main.rs b/examples/example-async/src/main.rs
index 15aba7d..889895c 100644
--- a/examples/example-async/src/main.rs
+++ b/examples/example-async/src/main.rs
@@ -16,7 +16,7 @@
 //! cargo run --manifest-path ./examples/example-async/Cargo.toml -- hello World
 //! ```
 
-use mingling::macros::{chain, dispatcher, gen_program, pack, r_println, renderer};
+use mingling::prelude::*;
 
 dispatcher!("hello", HelloCommand => HelloEntry);
 
diff --git a/examples/example-basic/src/main.rs b/examples/example-basic/src/main.rs
index 79853ad..660cd68 100644
--- a/examples/example-basic/src/main.rs
+++ b/examples/example-basic/src/main.rs
@@ -5,7 +5,7 @@
 //! cargo run --manifest-path ./examples/example-basic/Cargo.toml -- hello World
 //! ```
 
-use mingling::macros::{chain, dispatcher, gen_program, pack, r_println, renderer};
+use mingling::prelude::*;
 
 // Define dispatcher `HelloCommand`, directing subcommand "hello" to `HelloEntry`
 dispatcher!("hello", HelloCommand => HelloEntry);
diff --git a/examples/example-completion/src/main.rs b/examples/example-completion/src/main.rs
index 3f1a377..8f1714c 100644
--- a/examples/example-completion/src/main.rs
+++ b/examples/example-completion/src/main.rs
@@ -34,11 +34,10 @@
 //! 4. Write `main.rs`, adding completion logic for your command entry point
 //! 5. Execute `cargo install --path ./`, then run the corresponding completion script in your shell
 
+use mingling::prelude::*;
 use mingling::{
     EnumTag, Groupped, ShellContext, Suggest,
-    macros::{
-        chain, completion, dispatcher, gen_program, r_println, renderer, suggest, suggest_enum,
-    },
+    macros::{suggest, suggest_enum},
     parser::{PickableEnum, Picker},
 };
 
diff --git a/examples/example-dispatch-tree/src/main.rs b/examples/example-dispatch-tree/src/main.rs
index 104f002..90879e5 100644
--- a/examples/example-dispatch-tree/src/main.rs
+++ b/examples/example-dispatch-tree/src/main.rs
@@ -18,7 +18,7 @@
 
 #![allow(unused_mut)]
 
-use mingling::macros::{dispatcher, gen_program};
+use mingling::prelude::*;
 
 fn main() {
     let mut program = ThisProgram::new();
diff --git a/examples/example-exit-code/src/main.rs b/examples/example-exit-code/src/main.rs
index 1fe5424..def96d8 100644
--- a/examples/example-exit-code/src/main.rs
+++ b/examples/example-exit-code/src/main.rs
@@ -11,8 +11,8 @@
 //! cargo run --manifest-path ./examples/example-exit-code/Cargo.toml -- error
 //! ```
 
+use mingling::prelude::*;
 use mingling::{
-    macros::{chain, dispatcher, gen_program, pack, r_println, renderer},
     res::{exit_code, update_exit_code},
     setup::ExitCodeSetup,
 };
diff --git a/examples/example-general-renderer/src/main.rs b/examples/example-general-renderer/src/main.rs
index 23f1eab..867c43e 100644
--- a/examples/example-general-renderer/src/main.rs
+++ b/examples/example-general-renderer/src/main.rs
@@ -32,12 +32,8 @@
 //! member_age: 22
 //! ```
 
-use mingling::{
-    Groupped,
-    macros::{chain, dispatcher, gen_program, r_println, renderer},
-    parser::Picker,
-    setup::GeneralRendererSetup,
-};
+use mingling::prelude::*;
+use mingling::{Groupped, parser::Picker, setup::GeneralRendererSetup};
 use serde::Serialize;
 
 dispatcher!("render", RenderCommand => RenderCommandEntry);
diff --git a/examples/example-picker/src/main.rs b/examples/example-picker/src/main.rs
index fa895fc..e5bf403 100644
--- a/examples/example-picker/src/main.rs
+++ b/examples/example-picker/src/main.rs
@@ -17,10 +17,7 @@
 //! cargo run --manifest-path ./examples/example-picker/Cargo.toml -- pick --age 99
 //! ```
 
-use mingling::{
-    macros::{chain, dispatcher, gen_program, pack, r_println, renderer},
-    parser::Picker,
-};
+use mingling::prelude::*;
 
 dispatcher!("pick", PickCommand => PickEntry);
 
@@ -35,9 +32,7 @@ pack!(ParsedPickInput = (i32, String));
 
 #[chain]
 fn parse(prev: PickEntry) -> NextProcess {
-    // Extract arguments from `PickEntry`'s inner and create a `Picker`
-    let picker = Picker::new(prev.inner);
-    let picked = picker
+    let picked = prev
         // First extract the named argument
         .pick_or("--age", 20)
         .after(|n: i32| n.clamp(0, 100))
diff --git a/examples/example-resources/Cargo.lock b/examples/example-resources/Cargo.lock
new file mode 100644
index 0000000..78c3cac
--- /dev/null
+++ b/examples/example-resources/Cargo.lock
@@ -0,0 +1,91 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "example-resources"
+version = "0.0.1"
+dependencies = [
+ "mingling",
+]
+
+[[package]]
+name = "just_fmt"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5454cda0d57db59778608d7a47bff5b16c6705598265869fb052b657f66cf05e"
+
+[[package]]
+name = "mingling"
+version = "0.1.8"
+dependencies = [
+ "mingling_core",
+ "mingling_macros",
+ "size",
+]
+
+[[package]]
+name = "mingling_core"
+version = "0.1.8"
+dependencies = [
+ "just_fmt",
+ "once_cell",
+]
+
+[[package]]
+name = "mingling_macros"
+version = "0.1.8"
+dependencies = [
+ "just_fmt",
+ "once_cell",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[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.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "size"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b6709c7b6754dca1311b3c73e79fcce40dd414c782c66d88e8823030093b02b"
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
diff --git a/examples/example-resources/Cargo.toml b/examples/example-resources/Cargo.toml
new file mode 100644
index 0000000..ca783f3
--- /dev/null
+++ b/examples/example-resources/Cargo.toml
@@ -0,0 +1,7 @@
+[package]
+name = "example-resources"
+version = "0.0.1"
+edition = "2024"
+
+[dependencies]
+mingling = { path = "../../mingling", features = ["parser"] }
diff --git a/examples/example-resources/src/main.rs b/examples/example-resources/src/main.rs
new file mode 100644
index 0000000..63ebfe6
--- /dev/null
+++ b/examples/example-resources/src/main.rs
@@ -0,0 +1,57 @@
+//! `Mingling` Example - Global Resource Injection
+//!
+//! This example demonstrates how to use global resource injection in `#[chain]` functions.
+//! You can inject both immutable (`&T`) and mutable (`&mut T`) references to global resources.
+//!
+//! # How to Run
+//! ```bash
+//! cargo run --manifest-path ./examples/example-resources/Cargo.toml -- setup
+//! ```
+
+use mingling::prelude::*;
+use std::{env::current_dir, path::PathBuf};
+
+// Define a resource for storing global state
+#[derive(Default, Clone)]
+pub struct MyResource {
+    current_dir: PathBuf,
+}
+
+fn main() {
+    let mut program = ThisProgram::new();
+
+    // Add the resource to the program
+    program.with_resource(MyResource::default());
+
+    program.with_dispatcher(SetupCommand);
+    program.exec_and_exit();
+}
+
+dispatcher!("setup", SetupCommand => SetupEntry);
+pack!(StateRead = ());
+pack!(ResultCurrentDir = PathBuf);
+
+#[chain]
+fn setup(
+    _prev: SetupEntry,
+    resource: &mut MyResource, // Import the resource into `setup`
+) -> NextProcess {
+    // Set the global resource
+    resource.current_dir = current_dir().unwrap();
+
+    StateRead::default()
+}
+
+#[chain]
+fn read(_prev: StateRead, resource: &MyResource) -> NextProcess {
+    // Read the global resource
+    let current_dir = resource.current_dir.clone();
+    ResultCurrentDir::new(current_dir).to_render()
+}
+
+#[renderer]
+fn render_current_dir(dir: ResultCurrentDir) {
+    r_println!("Current dir: {}", dir.to_string_lossy())
+}
+
+gen_program!();
diff --git a/mingling_macros/src/chain.rs b/mingling_macros/src/chain.rs
index 496a0a4..9d3a901 100644
--- a/mingling_macros/src/chain.rs
+++ b/mingling_macros/src/chain.rs
@@ -213,6 +213,19 @@ pub fn chain_attr(attr: TokenStream, item: TokenStream) -> TokenStream {
         quote! { #group_name }
     };
 
+    // Check for async fn + &mut combination, which is not supported
+    #[cfg(feature = "async")]
+    if is_async_fn {
+        if let Some(mut_res) = resources.iter().find(|r| r.is_mut) {
+            return syn::Error::new(
+                mut_res.var_name.span(),
+                "Cannot use `&mut` resource injection in async chain function. ",
+            )
+            .to_compile_error()
+            .into();
+        }
+    }
+
     // Separate resources into immutable refs and mutable refs
     let immut_resources: Vec<_> = resources.iter().filter(|r| !r.is_mut).collect();
     let mut_resources: Vec<_> = resources.iter().filter(|r| r.is_mut).collect();
@@ -243,9 +256,9 @@ pub fn chain_attr(attr: TokenStream, item: TokenStream) -> TokenStream {
         })
         .collect();
 
-    // Build nested __modify_res_and_return_any wrappers for mutable references
-    // The innermost layer is the original function body, wrapping outward for each mutable resource.
-    // The function returns a value, so the return values need to be properly chained.
+    // Build nested __modify_res_and_return_any wrappers for mutable references.
+    // The innermost layer is the original function body, wrapping outward for each
+    // mutable resource.
     let body_stmts = &fn_body.stmts;
     let mut wrapped_body = quote! {
         #(#body_stmts)*
@@ -253,7 +266,6 @@ pub fn chain_attr(attr: TokenStream, item: TokenStream) -> TokenStream {
 
     // Wrap from inside to outside: the first mutable parameter becomes the outermost wrapper,
     // and the last mutable parameter becomes the innermost wrapper.
-    // Therefore iterate mut_resources and wrap outward.
     for res in mut_resources.iter() {
         let var_name = &res.var_name;
         let inner_type = &res.inner_type;
-- 
cgit