Creating flexible, complex, and reusable structures in Rust with macros
Luis Soares, M.Sc.
Lead Software Engineer | Blockchain & ZK Protocol Engineer | 🦀 Rust | C++ | Web3 | Solidity | Golang | Cryptography | Author
Macros in Rust are a convenient and powerful way to write code that writes other code, enabling you to create highly reusable and flexible components. One of the advanced uses of macros is to define complex configuration structures, which we will explore in this article.
Let’s dive right in! 🦀
Understanding macro_rules!
The macro_rules! macro system in Rust allows you to define patterns and specify how they should be expanded into Rust code. This is particularly useful for boilerplate code, ensuring consistency and reducing the chance of errors. Macros can take parameters, match specific patterns, and generate code based on these patterns.
Simplified Example: Defining Configuration Structures
Let’s start with a simplified example to demonstrate how macro_rules! can be used to define configuration structures. Our goal is to create a macro that generates a struct with default values, a module containing functions to return these defaults, and an implementation of the Default trait.
Step-by-Step Implementation
First, we define the macro, specifying the pattern it should match. Each configuration field will have a name, type, and default value.
macro_rules! define_config {
($(
$(#[doc = $doc:literal])?
($name:ident: $ty:ty = $default:expr),
)*) => {
// Struct definition
pub struct Config {
$(
$(#[doc = $doc])?
pub $name: $ty,
)*
}
// Default values module
mod defaults {
use super::*;
$(
pub fn $name() -> $ty { $default }
)*
}
// Implement Default trait
impl Default for Config {
fn default() -> Self {
Self {
$(
$name: defaults::$name(),
)*
}
}
}
};
}
2. Using the Macro
We use the macro to define a Config struct with several fields.
define_config! {
/// The number of threads to use.
(num_threads: usize = 4),
/// The timeout duration in seconds.
(timeout_seconds: u64 = 30),
/// The path to the configuration file.
(config_path: String = String::from("/etc/app/config.toml")),
}
3. Generated Code
The macro invocation will expand to:
pub struct Config {
pub num_threads: usize,
pub timeout_seconds: u64,
pub config_path: String,
}
mod defaults {
use super::*;
pub fn num_threads() -> usize { 4 }
pub fn timeout_seconds() -> u64 { 30 }
pub fn config_path() -> String { String::from("/etc/app/config.toml") }
}
impl Default for Config {
fn default() -> Self {
Self {
num_threads: defaults::num_threads(),
timeout_seconds: defaults::timeout_seconds(),
config_path: defaults::config_path(),
}
}
}
Key Elements
The struct Config is defined with public fields. Each field can have an optional documentation comment, which is included using $(#[doc = $doc])?.
2. Default Values Module
A module named defaults is generated. This module contains functions that return the default values for each field. These functions are used in the Default implementation.
3. Default Trait Implementation
The Default trait is implemented for the Config struct. This implementation uses the functions from the defaults module to initialize each field with its default value.
Benefits of Using Macros for Configuration Structures
Extending the Example
To further illustrate the power and flexibility of macros in Rust, let’s extend our example to include more advanced features such as deprecated fields and custom validation logic.
Recommended by LinkedIn
Adding Deprecation and Validation
We will enhance our macro to support deprecated fields and custom validation functions. This will allow users to define fields that should be validated according to specific rules and emit warnings if deprecated fields are used.
Enhanced Macro Definition:
macro_rules! define_config {
($(
$(#[doc = $doc:literal])?
$(#[deprecated($dep:literal, $new_field:ident)])?
$(#[validate = $validate:expr])?
($name:ident: $ty:ty = $default:expr),
)*) => {
// Struct definition
pub struct Config {
$(
$(#[doc = $doc])?
pub $name: $ty,
)*
}
// Default values module
mod defaults {
use super::*;
$(
pub fn $name() -> $ty { $default }
)*
}
// Implement Default trait
impl Default for Config {
fn default() -> Self {
Self {
$(
$name: defaults::$name(),
)*
}
}
}
// Validation implementation
impl Config {
pub fn validate(&self) -> Result<(), String> {
let mut errors = vec![];
$(
if let Some(validation_fn) = $validate {
if let Err(e) = validation_fn(&self.$name) {
errors.push(format!("Field `{}`: {}", stringify!($name), e));
}
}
)*
if errors.is_empty() {
Ok(())
} else {
Err(errors.join("\n"))
}
}
pub fn check_deprecated(&self) {
$(
if let Some(deprecated_msg) = $dep {
println!("Warning: Field `{}` is deprecated. {}", stringify!($name), deprecated_msg);
println!("Use `{}` instead.", stringify!($new_field));
}
)*
}
}
};
}
Using the Enhanced Macro:
define_config! {
/// The number of threads to use.
(num_threads: usize = 4),
/// The timeout duration in seconds.
(timeout_seconds: u64 = 30),
/// The path to the configuration file.
(config_path: String = String::from("/etc/app/config.toml")),
/// A deprecated configuration field.
#[deprecated("Use `new_field` instead", new_field)]
(old_field: String = String::from("deprecated")),
/// A new configuration field.
(new_field: String = String::from("new value")),
/// A field with custom validation.
#[validate = |value: &usize| if *value > 100 { Err("must be 100 or less") } else { Ok(()) }]
(max_connections: usize = 50),
}
Generated Code:
fn main() {
let config = Config::default();
// Check for deprecated fields
config.check_deprecated();
// Validate configuration
match config.validate() {
Ok(_) => println!("Configuration is valid."),
Err(e) => println!("Configuration errors:\n{}", e),
}
}
Key Elements Explained
The macro supports a deprecated attribute, which takes a message and a new field name. When check_deprecated is called, it prints warnings for deprecated fields and suggests the new field to use.
2. Custom Validation:
Each field can have a custom validation function specified using the validate attribute. The validate method on the Config struct runs all validation functions and collects errors.
3. User-Friendly Methods:
The generated struct includes methods for checking deprecated fields and validating the configuration, making it easy for users to ensure their configuration is correct and up-to-date.
Benefits of the Enhanced Macro
Final Thoughts
Experimenting with macros can open up new possibilities in your Rust projects. Start with simple macros, understand their pattern matching and expansion, and gradually build more complex and functional macros.
🚀 Explore More by Luis Soares
📚 Learning Hub: Expand your knowledge in various tech domains, including Rust, Software Development, Cloud Computing, Cyber Security, Blockchain, and Linux, through my extensive resource collection:
🔗 Connect with Me:
Wanna talk? Leave a comment or drop me a message!
All the best,
Luis Soares luis.soares@linux.com
Lead Software Engineer | Blockchain & ZKP Protocol Engineer | 🦀 Rust | Web3 | Solidity | Golang | Cryptography | Author