#toml-config #toml-parser #codec #encoding #encoder #structures #decoder

toml

A native Rust encoder and decoder of TOML-formatted files and streams. Provides implementations of the standard Serialize/Deserialize traits for TOML data to facilitate deserializing and serializing Rust structures.

78 releases

new 0.8.12 Mar 18, 2024
0.8.10 Feb 5, 2024
0.8.8 Nov 6, 2023
0.7.6 Jul 5, 2023
0.1.3 Nov 22, 2014

#9 in Parser implementations

Download history 1618746/week @ 2023-11-28 1628710/week @ 2023-12-05 1565554/week @ 2023-12-12 1293693/week @ 2023-12-19 888317/week @ 2023-12-26 1488238/week @ 2024-01-02 1615991/week @ 2024-01-09 1783897/week @ 2024-01-16 1748231/week @ 2024-01-23 1872875/week @ 2024-01-30 1841438/week @ 2024-02-06 1772449/week @ 2024-02-13 1925877/week @ 2024-02-20 1956397/week @ 2024-02-27 1954874/week @ 2024-03-05 531661/week @ 2024-03-12

6,651,463 downloads per month
Used in 14,855 crates (4,121 directly)

MIT/Apache

260KB
6K SLoC

toml

Latest Version Documentation

A serde-compatible TOML decoder and encoder for Rust.

For format-preserving edits or finer control over output, see toml_edit

License

This project is licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in toml-rs by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.


lib.rs:

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::

().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, keys: Keys, }

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

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();


[TOML]: https://github.com/toml-lang/toml
[Cargo]: https://crates.io/
[`serde`]: https://serde.rs/
[serde]: https://serde.rs/

Dependencies

~110–630KB
~13K SLoC