feat(docs): add Module Pathfinder example for the `pathf` feature

7 files changed, 191 insertions, 0 deletions

diff --git a/examples/example-pathfinder/Cargo.lock b/examples/example-pathfinder/Cargo.lock
new file mode 100644
index 0000000..92af163
--- /dev/null
+++ b/examples/example-pathfinder/Cargo.lock
@@ -0,0 +1,85 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "example-pathfinder"
+version = "0.1.0"
+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.2.0"
+dependencies = [
+ "mingling_core",
+ "mingling_macros",
+]
+
+[[package]]
+name = "mingling_core"
+version = "0.2.0"
+dependencies = [
+ "just_fmt",
+ "mingling_pathf",
+]
+
+[[package]]
+name = "mingling_macros"
+version = "0.2.0"
+dependencies = [
+ "just_fmt",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "mingling_pathf"
+version = "0.2.0"
+dependencies = [
+ "proc-macro2",
+ "syn",
+]
+
+[[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 = "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 = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
diff --git a/examples/example-pathfinder/Cargo.toml b/examples/example-pathfinder/Cargo.toml
new file mode 100644
index 0000000..bd362f2
--- /dev/null
+++ b/examples/example-pathfinder/Cargo.toml
@@ -0,0 +1,25 @@
+[package]
+name = "example-pathfinder"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies.mingling]
+path = "../../mingling"
+
+features = [
+    # Enable `pathf` features
+    "pathf",
+]
+
+[build-dependencies.mingling]
+path = "../../mingling"
+
+features = [
+    # Enable `pathf` features
+    "pathf",
+
+    # Enable the `builds` feature for build-time support
+    "builds",
+]
+
+[workspace]
diff --git a/examples/example-pathfinder/build.rs b/examples/example-pathfinder/build.rs
new file mode 100644
index 0000000..1dcc2fc
--- /dev/null
+++ b/examples/example-pathfinder/build.rs
@@ -0,0 +1,10 @@
+use mingling::builds::analyze_and_build_type_mapping;
+
+fn main() {
+    // --------- IMPORTANT ---------
+    // Use this method in build.rs,
+    //   to analyze the project structure at build time,
+    //   and automatically introduce members from other modules into gen_program!()
+    analyze_and_build_type_mapping().unwrap();
+    // --------- IMPORTANT ---------
+}
diff --git a/examples/example-pathfinder/page.toml b/examples/example-pathfinder/page.toml
new file mode 100644
index 0000000..54f4118
--- /dev/null
+++ b/examples/example-pathfinder/page.toml
@@ -0,0 +1,10 @@
+[example]
+id = "example-pathfinder"
+name = "Module Pathfinder"
+icon = "🧭"
+category = "advanced"
+desc = """
+Demonstrates the `pathf` feature, which automatically resolves type module paths at build time. Types can be defined in submodules without explicit `use` in the main module.
+"""
+tags = ["pathf", "build.rs", "architecture"]
+files = [ "Cargo.toml", "build.rs", "src/main.rs", "src/sub/mod.rs"]
diff --git a/examples/example-pathfinder/src/main.rs b/examples/example-pathfinder/src/main.rs
new file mode 100644
index 0000000..0f93a8d
--- /dev/null
+++ b/examples/example-pathfinder/src/main.rs
@@ -0,0 +1,30 @@
+//! Example: Module Pathfinder (pathf)
+//!
+//! > This example demonstrates how to use the `pathf` feature to define types
+//! > in submodules without needing explicit `use` in the main module.
+//! > All type paths are resolved automatically at build time.
+//!
+//! Run:
+//! ```bash
+//! cargo run --manifest-path examples/example-pathfinder/Cargo.toml --quiet -- greet
+//! cargo run --manifest-path examples/example-pathfinder/Cargo.toml --quiet -- greet Alice
+//! ```
+//!
+//! Output:
+//! ```plaintext
+//! Hello, World!
+//! Hello, Alice!
+//! ```
+
+mod sub;
+
+use mingling::macros::gen_program;
+use crate::sub::CMDGreet;
+
+fn main() {
+    let mut program = ThisProgram::new();
+    program.with_dispatcher(CMDGreet);
+    program.exec_and_exit();
+}
+
+gen_program!();
diff --git a/examples/example-pathfinder/src/sub/mod.rs b/examples/example-pathfinder/src/sub/mod.rs
new file mode 100644
index 0000000..ef10a75
--- /dev/null
+++ b/examples/example-pathfinder/src/sub/mod.rs
@@ -0,0 +1,21 @@
+use mingling::prelude::*;
+use crate::Next;
+
+dispatcher!("greet", CMDGreet => EntryGreet);
+pack!(ResultName = String);
+
+#[chain]
+pub fn handle_greet(args: EntryGreet) -> Next {
+    let name: ResultName = args
+        .inner
+        .first()
+        .cloned()
+        .unwrap_or_else(|| "World".to_string())
+        .into();
+    name
+}
+
+#[renderer]
+pub fn render_name(name: ResultName) {
+    r_println!("Hello, {}!", *name);
+}
diff --git a/examples/test-examples.toml b/examples/test-examples.toml
index b4cbb6d..e1a23c2 100644
--- a/examples/test-examples.toml
+++ b/examples/test-examples.toml
@@ -257,3 +257,13 @@ expect.result = '{"name":"error_not_dir_structural","info":"Cargo.toml"}'
 command = "find-structural examples --json"
 expect.exit-code = 0
 expect.result = '{"inner":"examples"}'
+
+[[test.example-pathfinder]]
+command = "greet"
+expect.exit-code = 0
+expect.result = "Hello, World!"
+
+[[test.example-pathfinder]]
+command = "greet Alice"
+expect.exit-code = 0
+expect.result = "Hello, Alice!"