asset_derive/lib.rs
1//! <div align="center">
2//!
3//! # asset-derive
4//!
5//! <a href="https://docs.rs/asset-derive/latest/asset_derive/"> </a>
6//! <a href="https://crates.io/crates/asset-derive"> </a>
7//! <a href="/LICENSE"> </a>
8//! <a href="#todos">  </a>
9//!
10//! [Summary](#summary)
11//! •
12//! [Todos](#todos)
13//! •
14//! [Docs](https://docs.rs/asset-derive/latest/asset_derive/)
15//!
16//! </div>
17//!
18//! <div align="center">
19//!
20//! <br>
21//!
22//! # Summary
23//!
24//! </div>
25//!
26//! > Simple Rust asset loading derive macro for Enums, and a resource for learning
27//! proc-macros!
28//!
29//! Please feel free to offer any advice or create a pull request.
30//!
31//!
32//! The original intent of this library was for compile time loading assets
33//! into a binary. This will eventually allow for run-time loading as well,
34//! but as for now that will be a future expansion.
35//!
36//! ## TODOs
37//!
38//! > List of ideas I have at the moment for this project's expansion.
39//! > Please create an issue for a new item to add to this list, using
40//! > `todo` label.
41//!
42//! - [ ] Filename prefix
43//! - [ ] Run-time Loading
44//! - [ ] Static (Once on init)
45//! - [ ] Dynamic (Fluid loading)
46//! - [X] ~~Compile-time Loading~~
47//!
48//! ## Structure
49//!
50//! Since `asset-derive` is meant to be a procedural macro crate, while also housing
51//! a trait implementation as well (to be derived), there is a somewhat complex
52//! project structue. This is because of the current annoyance of proc-macro crates
53//! having to be defined completely separate to normal crates.
54//!
55//! The external API shall stay the same fortunately, `asset-derive` will now be stuck
56//! as the trait implementation crate which depends on `asset-derive-macro` which
57//! houses the actual macro implementation. This is unavoidable for the time being, but
58//! I did the best I could to not have the external API change and make it as simple as
59//! can be.
60//!
61//! ### Code Tree
62//!
63//! ```ignore
64//! asset-derive/ <-- Crate to use (trait implementation)
65//! src/
66//! examples/ <-- Houses examples using the trait and macro itself.
67//! asset-derive-macro/ <-- Actual internal derive macro crate. Will be pulled in by main crate.
68//! src/
69//! ```
70//!
71//! ## Example
72//!
73//! ```no_run
74//! use asset_derive::Asset;
75//!
76//! #[derive(Asset)]
77//! #[asset(basepath = "../examples/assets/", ext = "svg")]
78//! enum Icon {
79//! #[asset(ext = "png")]
80//! Select,
81//! Folder,
82//! #[asset(filename = "folder-dim")]
83//! FolderDim,
84//! }
85//!
86//! Icon::Select.fetch();
87//! Icon::FolderDim.fetch_static();
88//! ```
89pub use asset_derive_macro::Asset;
90
91/// Trait to be derived by `asset-derive` macro.
92pub trait Asset {
93 /// Method responsible for fetching requested resource.
94 ///
95 /// ## Example
96 ///
97 /// ```ignore
98 /// let data = Icon::Select.fetch();
99 /// ```
100 fn fetch(&self) -> Vec<u8>;
101
102 /// Method responsible for fetching requested static resource.
103 ///
104 /// NOTE: this returns an `Option<&'static [u8]>` because it will
105 /// only be useable for compile-time loaded resources. Dynamic
106 /// will return `None`.
107 ///
108 /// ## Example
109 ///
110 /// ```ignore
111 /// let static_data = Icon::Select.fetch_static().unwrap();
112 /// ```
113 fn fetch_static(&self) -> &'static [u8];
114}