devela/code/util/
include.rs

Help
1// devela::code::util::include
2//
3//! include code macros
4//
5
6/// Includes a Rust source file relative to the project's directory.
7///
8/// The contents of the specified file are inserted into the current file
9/// at the location of the macro invocation. This allows you to reuse code
10/// from other files without creating separate modules.
11///
12/// # Usage
13///
14/// - To include a file relative to the project's directory:
15/// ```ignore
16/// include_from!("src/helper.rs");
17/// ```
18///
19/// - To include a file using its module name (relative to the project's directory):
20/// ```ignore
21/// include_from!(helper); // Resolves to "helper.rs" in the project's root.
22/// ```
23///
24/// - When using [`cargo-script`], the path is relative to the script's directory:
25/// ```ignore
26/// #!/usr/bin/env -S cargo +nightly -Zscript
27/// include_from!(utils);
28/// ```
29/// [`cargo-script`]: https://github.com/rust-lang/cargo/issues/12207
30///
31/// See also [`mod_from!`].
32#[doc(hidden)]
33#[macro_export]
34macro_rules! _include_from {
35    ($module_name:ident) => {
36        include!(concat!(std::env!("CARGO_MANIFEST_DIR"), "/", stringify!($module_name), ".rs"));
37    };
38    ($module_path_str:literal) => {
39        include!(concat!(std::env!("CARGO_MANIFEST_DIR"), "/", $module_path_str));
40    };
41}
42#[doc(inline)]
43pub use _include_from as include_from;
44
45/// Declares a module by including a Rust source file relative to the project's directory.
46///
47/// The macro generates a `mod` declaration and inserts the contents of the specified file
48/// into the module. This is a more ergonomic alternative to manually wrapping `include!`
49/// within a module declaration.
50///
51/// # Usage
52///
53/// - To declare a module using its name:
54/// ```ignore
55/// // Declares `pub(super) mod helper` with contents from "helper.rs":
56/// mod_from!(pub(super) helper);
57/// ```
58///
59/// - To declare a module with a specific path:
60/// ```ignore
61/// // Declares `mod helper` with contents from "src/helper.rs":
62/// mod_from!(helper, "src/helper.rs");
63/// ```
64///
65/// See also [`include_from!`].
66#[doc(hidden)]
67#[macro_export]
68macro_rules! _mod_from {
69    ($vis:vis $module_name:ident) => {
70        $vis mod $module_name { $crate::include_from!($module_name); }
71    };
72    ($vis:vis $module_name:ident, $module_path_str:literal) => {
73        $vis mod $module_name { $crate::include_from!($module_path_str); }
74    };
75}
76#[doc(inline)]
77pub use _mod_from as mod_from;
devela/code/util/include.rs

devela/code/util/
include.rs
