Crate toml

A serde-compatible TOML-parsing library

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

[package]
name = "toml"
version = "0.4.2"
authors = ["Alex Crichton <alex@alexcrichton.com>"]

[dependencies]
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 TOML document is represented with the Table type which maps String to the Value enum:

pub enum Value {
    String(String),
    Integer(i64),
    Float(f64),
    Boolean(bool),
    Datetime(Datetime),
    Array(Array),
    Table(Table),
}

Parsing TOML

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

use toml::Table;

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

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

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

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 Table
• Serialize for Table
• Deserialize for Value
• Serialize for Value
• Deserialize for Datetime
• Serialize for Datetime
• Deserializer for de::Deserializer
• Serializer for ser::Serializer
• Deserializer for Table
• Deserializer for Value

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

An example of deserializing with TOML is:

use serde::Deserialize;

#[derive(Deserialize)]
struct Config {
   ip: String,
   port: Option<u16>,
   keys: Keys,
}

#[derive(Deserialize)]
struct Keys {
   github: String,
   travis: Option<String>,
}

let config: Config = toml::from_str(r#"
   ip = '127.0.0.1'

   [keys]
   github = 'xxxxxxxxxxxxxxxxx'
   travis = 'yyyyyyyyyyyyyyyyy'
"#).unwrap();

assert_eq!(config.ip, "127.0.0.1");
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::Serialize;

#[derive(Serialize)]
struct Config {
   ip: String,
   port: Option<u16>,
   keys: Keys,
}

#[derive(Serialize)]
struct Keys {
   github: String,
   travis: Option<String>,
}

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

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

Modules

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

Macros

• toml
  Construct a Table from TOML syntax.

Structs

• Deserializer
  Deserialization TOML document
• Serializer
  Serialization for TOML documents.
• Spanned
  A spanned value, indicating the range at which it is defined in the source.

Enums

• Value
  Representation of a TOML value.

Functions

• from_str
  Deserializes a string into a type.
• to_string
  Serialize the given data structure as a String of TOML.
• to_string_pretty
  Serialize the given data structure as a “pretty” String of TOML.

Type Aliases

• Table
  Type representing a TOML table, payload of the Value::Table variant. By default it is backed by a BTreeMap, enable the preserve_order feature to use a LinkedHashMap instead.