tomldir

tomldir is a small, opinionated Rust crate for loading TOML configuration files into map-based data structures, optimized for runtime access, flattening, and configuration composition.

Usage

Add to Cargo.toml:

[dependencies]
tomldir = "0.1"
# Optional: for order-preserving keys
indexmap = "2.0"

Basic Usage

use tomldir::Config;

fn main() -> tomldir::Result<()> {
    let toml_data = r#"
        [database]
        host = "localhost"
        port = 5432
    "#;

    // Load into default HashMap
    let cfg = Config::from_toml(toml_data)?;
    
    // Thread-safe access (explicit cheap clone)
    let cfg = cfg.shared(); 

    assert_eq!(cfg.get_string("database.host"), Some("localhost"));
    Ok(())
}

Advanced: Preserving Order with IndexMap

If you need to iterate over keys in the order they were defined (e.g., for help text generation or consistent output), use IndexMap.

use tomldir::{Config, Value};
use indexmap::IndexMap;

fn main() -> tomldir::Result<()> {
    let toml_data = r#"
        first = 1
        second = 2
    "#;

    // Specify storage type explicitly
    let cfg = Config::<IndexMap<String, Value>>::from_toml_with(toml_data)?;

    let keys: Vec<_> = cfg.flatten_into::<Vec<(String, String)>>()
        .into_iter()
        .map(|(k, _)| k)
        .collect();
    assert_eq!(keys, vec!["first", "second"]);
    
    Ok(())
}

You can get an iterator over all flattened key-value pairs as strings:

for (key, value) in cfg.flatten() {
    println!("{key} = {value}");
}

Or collect them into a specific map (like HashMap<String, String>) using flatten_into():

let flat: HashMap<String, String> = cfg.flatten_into();

Or flatten into any custom type using flatten_into():

use std::collections::BTreeMap;

// Flatten to BTreeMap (sorted keys)
let flat_sorted: BTreeMap<String, String> = cfg.flatten_into();

// Flatten to Vec
let flat_vec: Vec<(String, String)> = cfg.flatten_into();

Features

• TOML-only: Built directly on toml::Value.
• Map-first: Stores data as HashMap by default, but swapable for IndexMap or BTreeMap.
• Thread-safe: Designed for Arc usage and concurrency.
• Deterministic Flattening: Nested tables become dot-separated keys.

License

MIT