trillium_include_dir/
lib.rs

1//! An extension to the `include_str!()` and `include_bytes!()` macro for embedding an entire
2//! directory tree into your binary.
3//!
4//! # Examples
5//!
6//! The `include_dir!()` macro will include a directory **relative to the
7//! project root** (using the `CARGO_MANIFEST_DIR` variable), in this example
8//! the source code for the `include_dir` crate has been included inside itself.
9//!
10//! ```rust
11//! use trillium_include_dir::{include_dir, Dir};
12//! use std::path::Path;
13//!
14//! const PROJECT_DIR: Dir = include_dir!(".");
15//!
16//! // of course, you can retrieve a file by its full path
17//! let lib_rs = PROJECT_DIR.get_file("src/lib.rs").unwrap();
18//!
19//! // you can also inspect the file's contents
20//! let body = lib_rs.contents_utf8().unwrap();
21//! assert!(body.contains("SOME_INTERESTING_STRING"));
22//!
23//! // if you enable the `search` feature, you can for files (and directories) using glob patterns
24//! #[cfg(feature = "search")]
25//! {
26//!     let glob = "**/*.rs";
27//!     for entry in PROJECT_DIR.find(glob).unwrap() {
28//!         println!("Found {}", entry.path().display());
29//!     }
30//! }
31//! ```
32//!
33//! # Features
34//!
35//! This library exposes a couple feature flags for enabling and disabling extra
36//! functionality. These are:
37//!
38//! - **example:** compile in an example of the embedded directory tree
39
40#![deny(
41    elided_lifetimes_in_paths,
42    future_incompatible,
43    missing_copy_implementations,
44    missing_debug_implementations,
45    missing_docs,
46    rust_2018_idioms
47)]
48
49#[allow(unused_imports)]
50#[macro_use]
51pub extern crate trillium_include_dir_impl;
52
53mod dir;
54mod file;
55
56#[cfg(feature = "search")]
57mod globs;
58
59pub use crate::dir::Dir;
60pub use crate::file::File;
61#[cfg(feature = "search")]
62pub use crate::globs::DirEntry;
63
64/// include a directory relative to the current crate root. this will
65/// panic if the directory cannot be found or accessed.
66#[macro_export]
67macro_rules! include_dir {
68    ($dir:literal) => {{
69        use $crate::{Dir, File};
70        $crate::trillium_include_dir_impl::include_dir!($dir)
71    }};
72}
73
74/// macro to attempt to include a directory relative to the current
75/// crate root. if it cannot find the directory, it will return a
76/// static Err result with a &'static str. this will never panic.
77#[macro_export]
78macro_rules! try_include_dir {
79    ($dir:literal) => {{
80        use $crate::{Dir, File};
81        $crate::trillium_include_dir_impl::try_include_dir!($dir)
82    }};
83}
84
85/// Example the output generated when running `include_dir!()` on itself.
86#[cfg(feature = "example-output")]
87pub static GENERATED_EXAMPLE: Dir<'_> = include_dir!(".");
trillium_include_dir/lib.rs

trillium_include_dir/
lib.rs
