toml

toml is a native Rust library for reading and writing TOML, the configuration format used by Cargo and much of the Rust ecosystem. It implements the standard Serde Serialize and Deserialize traits, so you can turn a TOML document straight into strongly typed Rust structs and serialize them back out with the same derive macros you already use for JSON or YAML.

Beyond struct mapping, it exposes a dynamic Table and Value model for working with arbitrary documents, supports no_std targets, and can preserve key order when built with the appropriate feature. It sits atop a focused stack of sibling crates (toml_parser, toml_edit, toml_datetime, toml_writer) that power format-preserving editing and low-level parsing when you need them.

What You Get

• Serde-powered from_str / to_string helpers that map TOML directly to and from typed Rust structs
• A dynamic Table and Value model for reading arbitrary documents without a predefined schema
• Spec-compliant parsing validated against the official toml-test suite for both decoding and encoding
• no_std support and optional features for preserving map key order and tuning hashing
• Access to sibling crates (toml_edit, toml_parser) for format-preserving edits and low-level control

Common Use Cases

• Loading application and tool configuration files into typed settings structs
• Reading and writing Cargo-style manifest and metadata files
• Serializing Rust data structures out to human-readable TOML for storage or interchange
• Inspecting TOML documents dynamically when the schema is not known ahead of time

Under The Hood

Architecture The crate is organized as the deserialization (src/de) and serialization (src/ser) halves of a Serde codec built on a dynamic data model in src/value.rs, src/table.rs, and src/map.rs. Parsing flows through the sibling toml_parser crate, which lexes and parses spans that are then materialized into typed Rust values or a Value tree; serialization mirrors this by walking values through a document strategy in src/ser/document and emitting text via toml_writer. It lives in a Cargo workspace alongside toml_edit, toml_datetime, and serde_spanned, each owning one concern so the top-level crate stays focused on the Serde surface.

Tech Stack It is written in Rust targeting the 2024 edition with a stated MSRV of 1.85. Core dependencies are serde_core for the trait plumbing, winnow as the parser-combinator engine behind toml_parser, and toml_datetime for TOML’s datetime type; optional dependencies include indexmap (for key-order preservation) and foldhash. Feature flags gate std, serde, parse, display, and preserve_order, allowing no_std and minimal builds.

Code Quality The crate carries an extensive test tree covering decoder and encoder behavior, serde round-trips, and snapshot fixtures, and it wires in the official toml-test conformance harness through custom decoder_compliance and encoder_compliance test targets. Clippy configuration and pre-commit hooks are checked in at the workspace root, and runnable examples (decode.rs, toml2json.rs) document real usage. The result is a mature, well-covered codebase rather than a thinly tested one.

API Design The public surface is deliberately small and predictable: toml::from_str and toml::to_string cover the common typed path, while a FromStr-based Table plus the Value enum handle dynamic access, so most users get productive with a single function call. Naming follows Serde conventions developers already know, thorough rustdoc is published on docs.rs, and heavier needs are cleanly delegated to toml_edit rather than bloating this crate’s API.