Macro flate

macro_rules! flate {
    ($(#[$meta:meta])*
        $(pub $(($($vis:tt)+))?)? static $name:ident: [u8] from $path:literal) => { ... };
    ($(#[$meta:meta])*
        $(pub $(($($vis:tt)+))?)? static $name:ident: str from $path:literal) => { ... };
}

This macro is like include_bytes! or include_str!, but compresses at compile time and lazily decompresses at runtime.

Parameters

The macro can be used like this:

flate!($meta $vis static $name: $type from $file);

• $meta is zero or more #[...] attributes that can be applied on the static parameters of lazy_static. For the actual semantics of the meta attributes, please refer to lazy_static documentation.
• $vis is a visibility modifier (e.g. pub, pub(crate)) or empty.
• $name is the name of the static variable..
• $type can be either [u8] or str. However, the actual type created would dereference into Vec<u8> and String (although they are AsRef<[u8]> and AsRef<str>) respectively.
• $file is a path relative to the current CARGO_MANIFEST_DIR. Absolute paths are not supported. Note that this is distinct from the behaviour of the builtin include_bytes!/include_str! macros — includle_bytes!/include_str! paths are relative to the current source file, while flate! paths are relative to CARGO_MANIFEST_DIR.

Returns

The macro expands to a lazy_static call, which lazily inflates the compressed bytes.

Compile errors

• If the input format is incorrect
• If the referenced file does not exist or is not readable
• If $type is str but the file is not fully valid UTF-8

Algorithm

Compression and decompression use the DEFLATE algorithm from libflate.

Examples

Below are some basic examples. For actual compiled examples, see the tests directory.

// This declares a `static VAR_NAME: impl Deref<Vec<u8>>`
flate!(static VAR_NAME: [u8] from "binary-file.dat");

// This declares a `static VAR_NAME: impl Deref<String>`
flate!(static VAR_NAME: str from "text-file.txt");

// Visibility modifiers can be added in the front
flate!(pub static VAR_NAME: str from "public-file.txt");

// Meta attributes can also be added
flate!(#[allow(unused)]
       #[doc = "Example const"]
       pub static VAR_NAME: str from "file.txt");