Crate toml

source ·
Expand description

A TOML-parsing library

This library implements a TOML v0.5.0 compatible parser, primarily supporting the serde library for encoding/decoding various types in Rust.

TOML itself is a simple, ergonomic, and readable configuration format:

name = "toml"
version = "0.4.2"
authors = ["Alex Crichton <>"]

serde = "1.0"

The TOML format tends to be relatively common throughout the Rust community for configuration, notably being used by Cargo, Rust’s package manager.

§TOML values

A value in TOML is represented with the Value enum in this crate:

pub enum Value {

TOML is similar to JSON with the notable addition of a Datetime type. In general, TOML and JSON are interchangeable in terms of formats.

§Parsing TOML

The easiest way to parse a TOML document is via the Value type:

use toml::Value;

let value = "foo = 'bar'".parse::<Value>().unwrap();

assert_eq!(value["foo"].as_str(), Some("bar"));

The Value type implements a number of convenience methods and traits; the example above uses FromStr to parse a str into a Value.

§Deserialization and Serialization

This crate supports serde 1.0 with a number of implementations of the Deserialize, Serialize, Deserializer, and Serializer traits. Namely, you’ll find:

  • Deserialize for Value
  • Serialize for Value
  • Deserialize for Datetime
  • Serialize for Datetime
  • Deserializer for de::Deserializer
  • Serializer for ser::Serializer
  • Deserializer for Value

This means that you can use Serde to deserialize/serialize the Value type as well as the Datetime type in this crate. You can also use the Deserializer, Serializer, or Value type itself to act as a deserializer/serializer for arbitrary types.

An example of deserializing with TOML is:

use serde_derive::Deserialize;

struct Config {
    ip: String,
    port: Option<u16>,
    keys: Keys,

struct Keys {
    github: String,
    travis: Option<String>,

fn main() {
    let config: Config = toml::from_str(r#"
        ip = ''

        github = 'xxxxxxxxxxxxxxxxx'
        travis = 'yyyyyyyyyyyyyyyyy'

    assert_eq!(config.ip, "");
    assert_eq!(config.port, None);
    assert_eq!(config.keys.github, "xxxxxxxxxxxxxxxxx");
    assert_eq!(config.keys.travis.as_ref().unwrap(), "yyyyyyyyyyyyyyyyy");

You can serialize types in a similar fashion:

use serde_derive::Serialize;

struct Config {
    ip: String,
    port: Option<u16>,
    keys: Keys,

struct Keys {
    github: String,
    travis: Option<String>,

fn main() {
    let config = Config {
        ip: "".to_string(),
        port: None,
        keys: Keys {
            github: "xxxxxxxxxxxxxxxxx".to_string(),
            travis: Some("yyyyyyyyyyyyyyyyy".to_string()),

    let toml = toml::to_string(&config).unwrap();



  • Deserializing TOML into Rust structures.
  • A map of String to toml::Value.
  • Serializing Rust structures into TOML.
  • Definition of a TOML value



  • A spanned value, indicating the range at which it is defined in the source.