4 stable releases
1.2.0 | Nov 25, 2023 |
---|---|
1.1.0 | Nov 19, 2023 |
1.0.1 | Jul 9, 2023 |
1.0.0 | Jul 8, 2023 |
#206 in Configuration
715 downloads per month
Used in 5 crates
(4 directly)
59KB
1K
SLoC
static-toml
Effortlessly embed TOML files into your Rust code as static data with custom data structures.
About
Embed TOML files into your Rust binaries via a procedural macro. This library enables the inclusion of TOML files at compile-time and generates static data structures that can be directly accessed by your Rust code without the need for runtime parsing.
Key Features
- π Embed TOML configuration files effortlessly.
- π¨ Generate reliable Rust data structures to represent your TOML contents.
- π§ Customize your generated types with prefixes and suffixes for flexibility.
- π¦ Enjoy clear and concise compile-time error messages for easier debugging.
Usage
First, make sure to add static-toml
to your Cargo.toml
dependencies:
Either by command line:
cargo add static-toml
Or by adding it to your Cargo.toml
directly:
[dependencies]
static-toml = "1"
Then, make use of the static_toml!
macro to include your TOML file:
# message.toml
[info]
welcome = "Welcome to our application!"
update = "Your data has been updated successfully."
[errors]
file_not_found = "The requested file could not be found."
permission_denied = "You do not have permission to perform this action."
static_toml::static_toml! {
static MESSAGES = include_toml!("messages.toml");
}
const WELCOME_MESSAGE: &str = MESSAGES.info.welcome;
This will read your TOML file and generate Rust data structures accordingly. Now you can access the values from the TOML file with ease.
In addition to using static
, the static_toml!
macro also allows the use of
const
for embedding TOML data.
This can be particularly useful in scenarios where a constant value is required,
such as within const functions or for const generics.
To use this feature, simply replace static
with const
in the macro call when
necessary.
Customization Options
You can configure how the macro should generate data types:
static_toml! {
#[static_toml(
prefix = Prefix,
suffix = Suffix,
root_mod = cfg,
values_ident = items,
prefer_slices = false
)]
static CONFIG = include_toml!("config.toml");
}
-
prefix
: Adds a prefix to the generated data types. It's recommended to usePascalCase
for the prefix. -
suffix
: Similar to prefix, but itβs a suffix. -
root_mod
: Sets the identifier for the root module that will contain the data types for the TOML file. -
values_ident
: When generating data types for arrays, this specifies a different name for the modules and data types (default isvalues
). -
prefer_slices
: Determines whether the macro should generate fixed-size slices for arrays. If set tofalse
, tuples will be generated (default istrue
).
Enhancing Your Types
You can use doc comments, derive attributes, and other attributes. Additionally, you can set visibility. Your code can be clean and descriptive.
static_toml! {
/// The configuration.
#[derive(Debug)]
#[allow(missing_docs)]
pub static CONFIG = include_toml!("config.toml");
}
Error Handling
Encounter compile errors?
No worries.
static-toml
provides informative error messages, whether it's TOML parsing or
file access issues.
Example
Suppose you have a simple TOML file like this:
# config.toml
[database]
url = "localhost"
port = 5432
Use the static_toml!
macro:
static_toml! {
static CONFIG = include_toml!("config.toml");
}
And just like that, you have Rust data structures ready to use.
assert_eq!(CONFIG.database.url, "localhost");
assert_eq!(CONFIG.database.port, 5432);
Dependencies
~1β1.6MB
~31K SLoC