Rework examples and add entry macro for testing

3 files changed, 194 insertions, 0 deletions

diff --git a/examples/example-async-support/Cargo.lock b/examples/example-async-support/Cargo.lock
new file mode 100644
index 0000000..1c4d5b1
--- /dev/null
+++ b/examples/example-async-support/Cargo.lock
@@ -0,0 +1,111 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "example-async-support"
+version = "0.1.0"
+dependencies = [
+ "mingling",
+ "tokio",
+]
+
+[[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.9"
+dependencies = [
+ "mingling_core",
+ "mingling_macros",
+ "size",
+]
+
+[[package]]
+name = "mingling_core"
+version = "0.1.9"
+dependencies = [
+ "just_fmt",
+]
+
+[[package]]
+name = "mingling_macros"
+version = "0.1.9"
+dependencies = [
+ "just_fmt",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[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 = "tokio"
+version = "1.52.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
+dependencies = [
+ "pin-project-lite",
+ "tokio-macros",
+]
+
+[[package]]
+name = "tokio-macros"
+version = "2.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[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-async-support/Cargo.toml b/examples/example-async-support/Cargo.toml
new file mode 100644
index 0000000..3a66e52
--- /dev/null
+++ b/examples/example-async-support/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "example-async-support"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies.mingling]
+path = "../../mingling"
+
+# Enable `parser` features
+features = ["async", "parser"]
+
+# Import any async runtime, e.g. Tokio
+[dependencies.tokio]
+version = "1.52.3"
+features = ["macros", "rt", "rt-multi-thread", "time"]
diff --git a/examples/example-async-support/src/main.rs b/examples/example-async-support/src/main.rs
new file mode 100644
index 0000000..12b1b9c
--- /dev/null
+++ b/examples/example-async-support/src/main.rs
@@ -0,0 +1,68 @@
+//! Example Async Runtime Support
+//!
+//! > This example shows how to drive an async runtime using the `async` feature
+//!
+//! ## Note
+//!
+//! When the `async` feature is enabled, **Mingling** provides a different framework implementation,
+//! allowing you to use the `async` keyword directly within `#[chain]`.
+//!
+//! However, you will lose some capabilities:
+//!
+//! 1. `&mut` resource injection is not available in async chain functions
+//! 2. The program will not be able to use panic unwind functionality
+//!
+//! Run:
+//! ```bash
+//! cargo run --manifest-path examples/example-async-support/Cargo.toml --quiet -- download README.md
+//! ```
+//!
+//! Output:
+//! ```plaintext
+//! Download begin
+//! # (Will pause for 1 second here)
+//! "README.md" downloaded.
+//! ```
+
+use mingling::{hook::ProgramHook, prelude::*};
+
+#[tokio::main]
+async fn main() {
+    let mut program = ThisProgram::new();
+
+    program.with_dispatcher(CMDDownload);
+
+    // Add a hook to display when the download begins
+    program.with_hook(ProgramHook::empty().on_begin(|| println!("Download begin")));
+
+    // --------- IMPORTANT ---------
+    // The return values of `exec_*()` related functions have been replaced with Futures
+    program.exec_and_exit().await;
+    // --------- IMPORTANT ---------
+}
+
+dispatcher!("download", CMDDownload => EntryDownload);
+
+pack!(ResultDownloaded = String);
+
+// --------- IMPORTANT ---------
+#[chain]
+//  vvvvv_ `async` keyword can be used directly here
+pub async fn handle_download(args: EntryDownload) -> Next {
+    let file_name = args.pick(()).unpack();
+    fake_download(file_name).await
+}
+
+#[renderer]
+// But renderers cannot use the `async` keyword
+pub fn render_downloaded(result: ResultDownloaded) {
+    r_println!("\"{}\" downloaded.", *result);
+}
+// --------- IMPORTANT ---------
+
+gen_program!();
+
+async fn fake_download(file_name: String) -> ResultDownloaded {
+    tokio::time::sleep(std::time::Duration::from_secs(1)).await;
+    ResultDownloaded::new(file_name)
+}