Adding `envman` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add envman

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

envman = "2.1.0"

The envman library will be automatically available globally. Read the envman library documentation.

Back to the crate overview.

Readme

EnvMan: Environments (variables) Manager

EnvMan is a Rust crate that provides a procedural macro to simplify the management of environment variables. It allows you to automatically load and parse environment variables into your Rust structs, with support for default values, custom parsers, and more.

Features

Automatic Environment Variable Loading: Automatically load environment variables into struct fields.
Array/Vec Support: Parse comma-separated or custom-delimited values into vectors using the separator attribute.
Validation: Custom validation functions to ensure values meet your requirements.
Enhanced Error Messages: Detailed error messages showing the key name, actual value, and expected type for easier debugging.
Secret Masking: Protect sensitive data in debug output with the EnvManDebug derive macro and secret attribute.
Customizable Field Attributes: Use attributes to customize field names, parsers, default values, and nested structures efficiently.
Support for Nested Structs: Easily manage nested configurations with support for nested structs.
Flexible Naming Conventions: Use rename_all, prefix, and suffix to control environment variable naming.

Usage

Here's a basic example demonstrating how to use EnvMan to manage environment variables:

use envman::EnvMan;
use std::net::IpAddr;

#[derive(EnvMan)]
struct Config {
    #[envman(rename = "APP_PORT", test = 8080)]
    port: u16,
    #[envman(nest)]
    database: DatabaseConfig,
}

#[derive(EnvMan)]
#[envman(prefix = "DB_",)]
struct DatabaseConfig {
    #[envman(default = "127.0.0.1")]
    host: IpAddr,
    #[envman(default = 5432)]
    port: u16,
}

// NOTE: This is for demonstration purposes only in README.
// In real applications, set environment variables through your system or .env files.
#[allow(unused_unsafe)]
unsafe {
    std::env::set_var("APP_PORT", "5000");
    std::env::set_var("DB_HOST", "192.168.1.1");
    std::env::set_var("DB_PORT", "5432");
}

// Load the configuration from environment variables
let config = Config::load_from_env().expect("Failed to load configuration");

// Assertions to verify the configuration
assert_eq!(config.port, 5000);
assert_eq!(config.database.host.to_string(), "192.168.1.1");
assert_eq!(config.database.port, 5432);

Attributes

Struct Attributes

rename_all: Apply a naming convention to all fields (default: SCREAMING_SNAKE_CASE).
prefix: Add a prefix to all field names.
suffix: Add a suffix to all field names.

Field Attributes

rename: Specify a custom environment variable name for a field.
default: Provide a default value if the environment variable is not set.
parser: Use a custom parser function to parse the environment variable. (default: FromStr::from_str)
nest: Indicate that the field is a nested struct implementing EnvMan.
separator: For Vec<T> fields, specify the delimiter to split the string (e.g., separator = "," for comma-separated values).
validate: Specify a custom validation function that returns Result<(), E> where E: Display. The error message will be included in the validation failure.
secret: Mark a field as secret to mask its value in debug output (requires EnvManDebug derive).

Advanced Examples

Array/Vec Support

Parse comma-separated or custom-delimited values into vectors:

use envman::EnvMan;

#[derive(EnvMan)]
struct Config {
    // Comma-separated tags: "rust,cargo,testing"
    #[envman(separator = ",")]
    tags: Vec<String>,
    
    // Colon-separated ports: "8080:9090:3000"
    #[envman(separator = ":")]
    ports: Vec<u16>,
    
    // Optional array
    #[envman(separator = ",")]
    categories: Option<Vec<String>>,
}

Validation

Ensure values meet your requirements with custom validation:

use envman::EnvMan;

fn validate_port(port: &u16) -> Result<(), String> {
    if *port < 1024 {
        Err(format!("Port {} is reserved (must be >= 1024)", port))
    } else if *port > 65535 {
        Err(format!("Port {} is invalid (must be <= 65535)", port))
    } else {
        Ok(())
    }
}

#[derive(EnvMan)]
struct Config {
    #[envman(validate = validate_port)]
    port: u16,
}

Secret Masking

Protect sensitive data in debug output:

use envman::{EnvMan, EnvManDebug};

#[derive(EnvMan, EnvManDebug)]
struct Config {
    username: String,
    
    #[envman(secret)]
    password: String,
    
    #[envman(secret)]
    api_key: String,
}

let config = Config::load_from_env().unwrap();
// Debug output will show: Config { username: "admin", password: "***", api_key: "***" }
println!("{:?}", config);

Adding envman library as a dependency

Adding `envman` library as a dependency