rust_embed/
lib.rs

1#![forbid(unsafe_code)]
2#[cfg(feature = "compression")]
3#[cfg_attr(feature = "compression", doc(hidden))]
4pub use include_flate::flate;
5
6#[cfg(feature = "compression")]
7pub use include_flate;
8
9extern crate rust_embed_impl;
10pub use rust_embed_impl::*;
11
12#[cfg(feature = "compression")]
13pub use rust_embed_utils::EmbeddedCompressedFile;
14pub use rust_embed_utils::{EmbeddedFile, Metadata};
15
16#[doc(hidden)]
17pub extern crate rust_embed_utils as utils;
18
19/// A directory of binary assets.
20///
21/// The files in the specified folder will be embedded into the executable in
22/// release builds. Debug builds will read the data from the file system at
23/// runtime.
24///
25/// This trait is meant to be derived like so:
26/// ```
27/// use rust_embed::Embed;
28///
29/// #[derive(Embed)]
30/// #[folder = "examples/public/"]
31/// struct Asset;
32///
33/// fn main() {}
34/// ```
35pub trait RustEmbed {
36  /// Get file compressed
37  #[cfg(feature = "compression")]
38  fn compressed(file_path: &str) -> Option<EmbeddedCompressedFile>;
39
40  /// Get an embedded file and its metadata.
41  ///
42  /// If the feature `debug-embed` is enabled or the binary was compiled in
43  /// release mode, the file information is embedded in the binary and the file
44  /// data is returned as a `Cow::Borrowed(&'static [u8])`.
45  ///
46  /// Otherwise, the information is read from the file system on each call and
47  /// the file data is returned as a `Cow::Owned(Vec<u8>)`.
48  fn get(file_path: &str) -> Option<EmbeddedFile>;
49
50  /// Iterates over the file paths in the folder.
51  ///
52  /// If the feature `debug-embed` is enabled or the binary is compiled in
53  /// release mode, a static array containing the list of relative file paths
54  /// is used.
55  ///
56  /// Otherwise, the files are listed from the file system on each call.
57  fn iter() -> impl Iterator<Item = std::borrow::Cow<'static, str>> + 'static;
58}
59
60pub use RustEmbed as Embed;
61
62/// An iterator over filenames.
63///
64/// This enum exists for optimization purposes, to avoid boxing the iterator in
65/// some cases. Do not try and match on it, as different variants will exist
66/// depending on the compilation context.
67pub enum Filenames {
68  /// Release builds use a named iterator type, which can be stack-allocated.
69  #[cfg(any(not(debug_assertions), feature = "debug-embed"))]
70  Embedded(std::slice::Iter<'static, &'static str>),
71
72  /// The debug iterator type is currently unnameable and still needs to be
73  /// boxed.
74  #[cfg(all(debug_assertions, not(feature = "debug-embed")))]
75  Dynamic(Box<dyn Iterator<Item = std::borrow::Cow<'static, str>>>),
76}
77
78impl Iterator for Filenames {
79  type Item = std::borrow::Cow<'static, str>;
80  fn next(&mut self) -> Option<Self::Item> {
81    match self {
82      #[cfg(any(not(debug_assertions), feature = "debug-embed"))]
83      Filenames::Embedded(names) => names.next().map(|x| std::borrow::Cow::from(*x)),
84
85      #[cfg(all(debug_assertions, not(feature = "debug-embed")))]
86      Filenames::Dynamic(boxed) => boxed.next(),
87    }
88  }
89}
rust_embed/lib.rs

rust_embed/
lib.rs
