packer/
lib.rs

1//! packer is a library that helps you pack static files into binaries using macro magic. Here's
2//! how it's done:
3//!
4//! ### Step 1: Include
5//!
6//! Include the crate in your `Cargo.toml`:
7//!
8//! ```toml
9//! [dependencies]
10//! packer = "0.5"
11//! ```
12//!
13//! ### Step 2: Derive
14//!
15//! Start deriving `Packer` from your structs. You need to provide a `source` attribute to indicate
16//! the directory from which it should be pulling. Paths are relative to the crate root.
17//!
18//! ```
19//! use packer::Packer;
20//! #[derive(Packer)]
21//! #[packer(source = "tests/basic")]
22//! struct Assets;
23//! ```
24//!
25//! ### Step 3: Use it!
26//!
27//! You can now access any file using the `get` function:
28//!
29//! ```
30//! use packer::Packer;
31//! # #[derive(Packer)]
32//! # #[packer(source = "tests/basic")]
33//! # struct Assets;
34//! let data: Option<&'static [u8]> = Assets::get("kermit.jpg");
35//! ```
36//!
37//! You may also choose to list all the files that have been stored.
38//!
39//! ```
40//! use packer::Packer;
41//! # #[derive(Packer)]
42//! # #[packer(source = "tests/basic")]
43//! # struct Assets;
44//! let files /*: impl Iterator<Item = &'static str>*/ = Assets::list();
45//! // Result (with no guarantee of order):
46//! // files = ["tests/basic/first/kermit.jpg", "tests/basic/second/ignored.x", "tests/basic/second/LICENSE"]
47//! ```
48//!
49//! _(See the documentation for the Packer trait for the full listing of methods.)_
50//!
51//! When you build in dev mode, it will fetch off your filesystem as usual, but when you build with
52//! `--release`, it will pack the assets into your binary!
53//!
54//! # Ignoring Paths
55//!
56//! You can choose to ignore certain paths using the `ignore` option:
57//!
58//! ```
59//! # use std::collections::BTreeSet;
60//! # use packer::Packer;
61//! #[derive(Packer)]
62//! #[packer(source = "tests/basic/second", ignore = "*.x")]
63//! struct Assets;
64//!
65//! // using BTreeSet since there's no guarantee of order
66//! assert_eq!(Assets::list().into_iter().collect::<BTreeSet<_>>(),
67//!            vec!["tests/basic/second/LICENSE"].into_iter().collect::<BTreeSet<_>>());
68//! ```
69//!
70//! # Stripping the Prefix
71//!
72//! By default, the path will keep the prefix. For example, if your file is located at `static/index.html`
73//! relative to your project root, then the path that's in the packed version will also be `static/index.html`.
74//! If you would like it to instead be just `index.html`, configure the `prefixed` option as follows:
75//!
76//! ```
77//! # use std::collections::BTreeSet;
78//! # use packer::Packer;
79//! #[derive(Packer)]
80//! #[packer(source = "tests/basic", prefixed = false)]
81//! struct Assets;
82//! ```
83//!
84//! By default, this option is set to true.
85
86#[doc(hidden)]
87pub extern crate phf;
88
89#[doc(hidden)]
90pub use lazy_static::*;
91#[doc(hidden)]
92pub use packer_derive::*;
93
94pub trait Packer {
95    // used for iterator, will be changed when impl Trait is stable in trait methods
96    #[doc(hidden)]
97    type Item: Iterator<Item = &'static str> + Sized;
98
99    /// Lists the files stored in the `Packer`.
100    fn list() -> Self::Item;
101
102    /// Returns the contents of the file named `file_name` as a `&'static [u8]` if it exists,
103    /// `None` otherwise.
104    fn get(file_name: impl AsRef<str>) -> Option<&'static [u8]>;
105
106    /// Returns the contents of the file named `file_name` as a `&'static str` if it exists and is
107    /// valid UTF-8, `None` otherwise.
108    fn get_str(file_name: impl AsRef<str>) -> Option<&'static str>;
109}
packer/lib.rs

packer/
lib.rs
