include_lines/
lib.rs

1//! include-lines
2//!
3//! Rust macros for reading in all lines from a file at compile time. This can be very useful for loading static data.
4//!
5//! # Examples
6//!
7//! For the examples, there is a file `file.txt` in the same directory as the project's Cargo.toml file:
8//!
9//! ```text
10//! these
11//! are
12//! file
13//! lines
14//! ```
15//!
16//! ## Read in a file and store it an an array of type `[&'static str]`
17//!
18//! ```ignore
19//! use include_lines::include_lines;
20//! let lines = include_lines!("file.txt");
21//! ```
22//!
23//! For the example file, this expands to:
24//!
25//! ```ignore
26//! let lines = [
27//!     "these",
28//!     "are",
29//!     "file",
30//!     "lines",
31//! ];
32//! ```
33//!
34//! ## Read in a file and store it an an array of type `[String]`
35//!
36//! ```ignore
37//! use include_lines::include_lines_s;
38//! let lines = include_lines_s!("file.txt");
39//! ```
40//!
41//! For the example file, this expands to:
42//!
43//! ```ignore
44//! let lines = [
45//!     String::from("these"),
46//!     String::from("are"),
47//!     String::from("file"),
48//!     String::from("lines"),
49//! ];
50//! ```
51//!
52//! ## Get the number of lines in a file at compile time as type `usize`
53//!
54//! ```ignore
55//! use include_lines::count_lines;
56//! let num_lines = count_lines!("file.txt");
57//! ```
58//!
59//! For the example file, this expands to:
60//!
61//! ```ignore
62//! let num_lines = 4usize;
63//! ```
64//!
65//! ## Create a static array from a file at compile time
66//!
67//! You can use the `static_include_lines!` and `static_include_lines_s!` macros to initialize static text arrays at compile time:
68//!
69//! ```ignore
70//! use include_lines::{static_include_lines};
71//! static_include_lines!(LINES, "file.txt");
72//! ```
73//!
74//! For the example file, this expands to:
75//!
76//! ```ignore
77//! static LINES: [&str; 4] = [
78//!     "these",
79//!     "are",
80//!     "file",
81//!     "lines",
82//! ];
83//! ```
84
85pub use include_lines_proc::*;
86
87/// Include lines from a file and save them to a static variable with the given name.
88/// Each line is saved as type `&str`.
89///
90/// Example:
91/// ```ignore
92/// static_include_lines!(MY_LINES, "file.txt");
93/// ```
94///
95/// Expands to:
96/// ```ignore
97/// static MY_LINES: [&str; include_lines::count_lines!("file.txt")] = include_lines::include_lines!("file.txt");
98/// ```
99#[allow(unused_macros)]
100#[macro_export]
101macro_rules! static_include_lines {
102    ($var: ident, $filename: literal) => {
103        static $var: [&str; include_lines::count_lines!($filename)] =
104            include_lines::include_lines!($filename);
105    };
106}
107
108/// This macro functions identically to [static_include_lines], but the created static variable is public.
109#[allow(unused_macros)]
110#[macro_export]
111macro_rules! pub_static_include_lines {
112    ($var: ident, $filename: literal) => {
113        pub static $var: [&str; include_lines::count_lines!($filename)] =
114            include_lines::include_lines!($filename);
115    };
116}
117
118/// This macro functions identically to [static_include_lines], but each line is returned as type `String`.
119#[allow(unused_macros)]
120#[macro_export]
121macro_rules! static_include_lines_s {
122    ($var: ident, $filename: literal) => {
123        static $var: [String; include_lines::count_lines!($filename)] =
124            include_lines::include_lines_s!($filename);
125    };
126}
127
128/// This macro functions identically to [static_include_lines_s], but the created static variable is public.
129#[allow(unused_macros)]
130#[macro_export]
131macro_rules! pub_static_include_lines_s {
132    ($var: ident, $filename: literal) => {
133        pub static $var: [String; include_lines::count_lines!($filename)] =
134            include_lines::include_lines_s!($filename);
135    };
136}
137
include_lines/lib.rs

include_lines/
lib.rs
