Trail Config

Simple Rust library to help with reading (and formatting) values from config files. Supports YAML format (uses serde_yaml_bw library).

Features

📖 Simple path-based config value access
🔧 Customizable path separators (/, ::, etc.)
🌍 Environment-specific config files
📝 String formatting and interpolation
✅ Comprehensive error handling with custom ConfigError type
📋 Type conversion for strings, numbers, booleans, and sequences
🔐 Escape sequence support for keys containing separators
🔄 Hot reload support for detecting configuration changes at runtime

Quick Start

use trail_config::Config;

// Load config.yaml file
let config = Config::default();

// Get values with lenient API (returns empty/None on missing)
let port = config.str("app/port");          // -> "8080"
let timeout = config.get_int("app/timeout"); // -> Some(30)

// Or use strict API for explicit error handling
match config.str_strict("database/host") {
    Ok(host) => println!("Connecting to {}", host),
    Err(e) => eprintln!("Config error: {}", e),
}

Loading Configuration

Trail Config provides different loading strategies for different use cases:

Production Code (Strict)

Use Config::load_required() when the configuration file must exist:

use trail_config::Config;

let config = Config::load_required("config.yaml", "/", None)?;
// Will error if file is missing, invalid YAML, or permission denied

Testing/Optional Configs (Lenient)

Use Config::default() when missing config is acceptable:

let config = Config::default(); // Never panics, gracefully handles missing config.yaml

Custom Loading

// With custom separator
let config = Config::new("config.yaml", "::", None)?;

// With environment substitution
let config = Config::new("config.{env}.yaml", "/", Some("dev"))?; // Loads config.dev.yaml

// From YAML string
let config = Config::load_yaml("app:\n  port: 8080", "/")?;

API Overview

Trail Config organizes methods into two API styles:

Goal	Method Style	Returns
Lenient access (handles missing gracefully)	`get()`, `str()`, `list()`, etc.	`Option<T>` or empty defaults
Strict access (explicit error handling)	`get_strict()`, `str_strict()`, etc.	`Result<T, ConfigError>`

Both styles share the same path syntax and navigate nested YAML using separators (default: /).

Main Methods (Lenient API)

Lenient methods return None or empty values for missing paths or type mismatches.

Reading Values

get(path) → Option<Value> - Get raw serde_yaml::Value
str(path) → String - Get string representation (empty if missing)
list(path) → Vec<String> - Get sequence as vector (empty if missing)
contains(path) → bool - Check if path exists

Type Conversion

get_int(path) → Option<i64> - Get integer value
get_float(path) → Option<f64> - Get floating-point value
get_bool(path) → Option<bool> - Get boolean value

Formatting

fmt(format, path) → String - Format multiple values (empty on any error)

Configuration Metadata

get_filename() → &str - Get loaded config filename
environment() → Option<&str> - Get environment name (if used)

Hot Reload

reload() → Result<(), ConfigError> - Reload from current file
reload_from(filename) → Result<(), ConfigError> - Load from different file

Strict Methods (Error Handling API)

Strict methods return Result<T, ConfigError> for explicit error handling.

get_strict(path) - Get value, fails with PathNotFound if missing
str_strict(path) - Get string, fails with PathNotFound if missing
list_strict(path) - Get sequence, fails with PathNotFound if missing
fmt_strict(format, path) - Format values, fails with PathNotFound or FormatError
get_int_strict(path) - Get integer, fails with PathNotFound or FormatError on type mismatch
get_float_strict(path) - Get float, fails with PathNotFound or FormatError on type mismatch
get_bool_strict(path) - Get boolean, fails with PathNotFound or FormatError on type mismatch

Type Conversion

Convert config values to typed Rust values safely:

let config = Config::default();

// Lenient - returns None on missing or type mismatch
let port = config.get_int("app/port");
let timeout = config.get_float("app/timeout");
let debug = config.get_bool("app/debug");

if let Some(port) = port {
    println!("Listening on port {}", port);
}

// Strict - returns error details
match config.get_int_strict("app/port") {
    Ok(port) => println!("Port: {}", port),
    Err(e) => eprintln!("Failed to read port: {}", e),
}

Example config (YAML):

app:
  port: 8080
  timeout: 30.5
  debug: true

Error Handling

Trail Config uses a custom ConfigError enum for precise error handling:

Error Types

use trail_config::ConfigError;

// Four error variants:
// - IoError(io::Error)       - File I/O errors (missing file, permission denied, etc.)
// - YamlError(String)        - YAML parsing errors
// - PathNotFound(String)     - Configuration path not found in document
// - FormatError(String)      - String formatting or configuration errors

Basic Error Handling

use trail_config::{Config, ConfigError};

match Config::load_required("config.yaml", "/", None) {
    Ok(config) => {
        let host = config.str("database/host");
        println!("Connecting to {}", host);
    }
    Err(ConfigError::IoError(e)) => {
        eprintln!("Config file error: {}", e);
    }
    Err(ConfigError::YamlError(msg)) => {
        eprintln!("Invalid YAML: {}", msg);
    }
    Err(e) => eprintln!("Config error: {}", e),
}

Strict Method Error Handling

use trail_config::{Config, ConfigError};

let config = Config::default();

match config.str_strict("database/host") {
    Ok(host) => println!("Connecting to {}", host),
    Err(ConfigError::PathNotFound(path)) => {
        eprintln!("Missing required config: {}", path);
    }
    Err(e) => eprintln!("Config error: {}", e),
}

// Type conversion with error details
match config.get_int_strict("app/port") {
    Ok(port) => println!("Port: {}", port),
    Err(ConfigError::FormatError(msg)) => {
        eprintln!("Port value has wrong type: {}", msg);
    }
    Err(ConfigError::PathNotFound(path)) => {
        eprintln!("Port config not found: {}", path);
    }
    Err(e) => eprintln!("Unexpected error: {}", e),
}

Hot Reload

Detect and apply configuration changes at runtime without restarting:

let mut config = Config::load_required("config.yaml", "/", None)?;

// Reload from the same file
config.reload()?; // Updates content from disk

// Or switch to a different config file
config.reload_from("other_config.yaml")?;

Server Loop Example

use trail_config::Config;
use std::thread;
use std::time::Duration;

fn main() {
    let mut config = Config::load_required("config.yaml", "/", None)
        .expect("Failed to load config");
    
    loop {
        // Check for config updates every 5 seconds
        if let Ok(_) = config.reload() {
            println!("✓ Configuration reloaded");
            
            // Apply updated settings
            let timeout = config.get_int("app/timeout").unwrap_or(30);
            let debug = config.get_bool("app/debug").unwrap_or(false);
            
            println!("Timeout: {} seconds, Debug: {}", timeout, debug);
        }
        
        // Main application logic here
        thread::sleep(Duration::from_secs(5));
    }
}

Escape Sequences

Keys containing the path separator can be accessed using escape sequences.

Syntax

\/ - Include literal separator in the key
\\ - Include literal backslash in the key
Works with any separator: /, ::, ->, etc.

Example

Given this YAML with special characters in keys:

database:
  "host/port": localhost:5432      # Key contains /
  "user\name": admin\user          # Key contains \

Access using escape sequences:

let config = Config::load_yaml(yaml, "/").unwrap();

// Access key containing separator (/)
let value = config.str("database/host\\/port"); // -> "localhost:5432"

// Access key containing backslash (\)
let value = config.str("database/user\\\\name"); // -> "admin\user"

With custom separator:

let config = Config::load_yaml(yaml, "::").unwrap();

// Path: a::b\::c::d navigates to keys ["a", "b::c", "d"]
let value = config.str("a::b\\::c::d");

Input Validation

Trail Config validates inputs automatically and returns FormatError for invalid configurations:

Input	Constraint	Error
Path Separator	Cannot be empty	Returns `FormatError`
File Paths	Empty filename treated as no file	Returns `IoError`
Paths	Empty paths safely handled	Returns `None` or empty
Separators (leading/trailing)	Handled gracefully	No error
Filename Templates	Must be valid format strings	Returns `FormatError`

Examples:

// Empty separator - error
let result = Config::new("config.yaml", "", None);
assert!(result.is_err()); // FormatError

// Missing file with load_required - error
let result = Config::load_required("missing.yaml", "/", None);
assert!(result.is_err()); // IoError

// Missing file with default - ok, empty config
let config = Config::default();
assert!(config.str("any/path") == ""); // Graceful fallback

Real-World Examples

Web Server Configuration

use trail_config::Config;

let config = Config::load_required("server.yaml", "/", None)?;

let host = config.str("server/host");
let port = config.get_int_strict("server/port")?;
let ssl = config.get_bool("server/ssl").unwrap_or(false);
let workers = config.get_int("server/workers").unwrap_or(4);

println!("Starting server on {}:{} (workers: {})", host, port, workers);

Environment-Specific Configuration

use trail_config::Config;
use std::env;

let env = env::var("APP_ENV").unwrap_or_else(|_| "development".to_string());
let config = Config::load_required(
    "config.{env}.yaml",
    "/",
    Some(&env)
)?;

let db_url = config.str_strict("database/url")?;
let log_level = config.str("logging/level");

println!("Using {} environment", env);

Database Connection Pooling

use trail_config::Config;

let config = Config::default();

let db_config = DatabaseConfig {
    host: config.str("db/host"),
    port: config.get_int("db/port").unwrap_or(5432) as u16,
    username: config.str("db/username"),
    password: config.str("db/password"),
    pool_size: config.get_int("db/pool_size").unwrap_or(10) as usize,
    timeout: config.get_float("db/timeout").unwrap_or(30.0),
};

let pool = create_pool(db_config)?;

Sample YAML:

db:
  host: localhost
  port: 5432
  username: admin
  password: secret
  pool_size: 20
  timeout: 60.0

Feature Flags and Feature Detection

use trail_config::Config;

let config = Config::default();

if config.get_bool("features/analytics").unwrap_or(false) {
    init_analytics();
}

if config.get_bool("features/profiling").unwrap_or(false) {
    enable_profiling();
}

let beta_features = config.list("features/beta");
for feature in beta_features {
    println!("Beta feature enabled: {}", feature);
}

Sample Configuration File

app:
  name: MyApp
  port: 8080
  timeout: 30.5
  debug: false

database:
  host: localhost
  port: 5432
  name: myapp_db
  username: admin
  password: secret
  pool_size: 10

server:
  bind: 127.0.0.1
  workers: 4
  log_level: info

features:
  analytics: true
  profiling: false
  beta:
    - new_ui
    - advanced_search

License

This project is licensed under the MIT License - see the LICENSE file for details

trail-config 0.3.0

Trail Config

Features

Quick Start

Loading Configuration

Production Code (Strict)

Testing/Optional Configs (Lenient)

Custom Loading

API Overview

Main Methods (Lenient API)

Reading Values

Type Conversion

Formatting

Configuration Metadata

Hot Reload

Strict Methods (Error Handling API)

Type Conversion

Error Handling

Error Types

Basic Error Handling

Strict Method Error Handling

Hot Reload

Server Loop Example

Escape Sequences

Syntax

Example

Input Validation

Real-World Examples

Web Server Configuration

Environment-Specific Configuration

Database Connection Pooling

Feature Flags and Feature Detection

Sample Configuration File

License