staticfilemap 0.4.1

Procedural macro to create a static map of compressed files during compilation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

# staticfilemap


[![Crates.io](https://img.shields.io/crates/v/staticfilemap)](https://crates.io/crates/staticfilemap)
[![Docs.rs](https://docs.rs/staticfilemap/badge.svg)](https://docs.rs/staticfilemap)

Procedural macro to embed optionally compressed files during compilation.

Similar to `include_file!` or [`include_dir!`](https://crates.io/crates/include_dir), but accepts a list of files that can be specified through environment variables and supports compression with [LZ4](https://github.com/lz4/lz4) or [zstd](https://github.com/facebook/zstd).

## Usage


Derive from `StaticFileMap` to create a map.

Specify the files to be included and the names they should be accessed by with the `files` and `names` attributes.
These can either be strings containing values separated with `;`, or environment variables containing them when the `parse` attribute is set to `env`.
Relative paths are resolved relative to `CARGO_MANIFEST_DIR`. If the `names` attribute is not specified, the names are inferred from the filenames.

The compression level is controlled by the `compression` attribute. With a compression level above `0` the included files are compresed with LZ4. LZ4 accepts a compression level up to `12`.
Alternatively, zstd can be used for compression by setting the `algorithm` attribute to `zstd`. Zstd supports a compression level up to `21`.

The cargo features `lz4` and `zstd` are available to select compression support. `lz4` is enabled by default.

Files can be accessed as `&'static [u8]` slices by the `get(name)` and `get_match(name)` functions at runtime.
`get_match(name)` accepts partial names if only one name matches. `keys()` returns a list of all keys.

See the examples, [the tests](tests/tests.rs) or [the implementation](src/lib.rs) for details.

### Dependency


```toml
[dependencies]
staticfilemap = "^0.3"
```

### Examples


```rust
use staticfilemap::StaticFileMap;

#[derive(StaticFileMap)]

#[names = "a;b"]

#[files = "README.md;LICENSE"]

struct StaticMap;

fn main() {
    let content: &[u8] = StaticMap::get("b").unwrap();
    let keys: &[&str] = StaticMap::keys();
}
```

```rust
use staticfilemap::StaticFileMap;
use minilz4::Decode;
use std::io::Read;

#[derive(StaticFileMap)]

#[parse = "env"]

#[names = "FILENAMES"]

#[files = "FILEPATHS"]

#[compression = 8]

struct StaticMap;

fn main() {
    let compressed = StaticMap::get_match("diogenes")
        .expect("file matching diogenes was not included");
    let content = compressed.decode();
}
```

```rust
use staticfilemap::StaticFileMap;
use zstd::decode_all;

#[derive(StaticFileMap)]

#[parse = "env"]

#[names = "FILENAMES"]

#[files = "FILEPATHS"]

#[compression = 8]

#[algorithm = "zstd"]

struct StaticMap;

fn main() {
    let mut compressed = StaticMap::get("diogenes.txt")
        .expect("file diogenes.txt was not included");
    let content = decode_all(&mut compressed);
}
```

```rust
use staticfilemap::StaticFileMap;

#[derive(StaticFileMap)]

#[files = "README.md;LICENSE"]

struct StaticMap;

fn main() {
    for (key, data) in StaticMap::iter() {
        println!("{}: {}", key, String::from_utf8_lossy(data));
    }
}
```