Yet another format-preserving TOML parser

7 releases

0.2.0 Jun 18, 2020
0.1.5 Aug 4, 2019
0.1.4 Jul 6, 2019
0.1.3 Jun 30, 2018
0.1.1 Dec 17, 2017

#27 in Parser implementations

Download history 3108/week @ 2020-12-25 4398/week @ 2021-01-01 5471/week @ 2021-01-08 4595/week @ 2021-01-15 4964/week @ 2021-01-22 5290/week @ 2021-01-29 5567/week @ 2021-02-05 7301/week @ 2021-02-12 7787/week @ 2021-02-19 7161/week @ 2021-02-26 6584/week @ 2021-03-05 6052/week @ 2021-03-12 6013/week @ 2021-03-19 5883/week @ 2021-03-26 5720/week @ 2021-04-02 4705/week @ 2021-04-09

22,401 downloads per month
Used in 90 crates (70 directly)




Build Status codecov crates.io docs Join the chat at https://gitter.im/toml_edit/Lobby

This crate allows you to parse and modify toml documents, while preserving comments, spaces* and relative order* or items.

toml_edit is primarily tailored for cargo-edit needs.


extern crate toml_edit;

use toml_edit::{Document, value};

fn main() {
    let toml = r#"
"hello" = 'toml!' # comment
    let mut doc = toml.parse::<Document>().expect("invalid doc");
    assert_eq!(doc.to_string(), toml);
    // let's add a new key/value pair inside a.b: c = {d = "hello"}
    doc["a"]["b"]["c"]["d"] = value("hello");
    // autoformat inline table a.b.c: { d = "hello" }
    doc["a"]["b"]["c"].as_inline_table_mut().map(|t| t.fmt());
    let expected = r#"
"hello" = 'toml!' # comment
c = { d = "hello" }
    assert_eq!(doc.to_string(), expected);


Things it does not preserve:

  • Different quotes and spaces around the same table key, e.g.
[ 'a'. b]
[ "a"  .c]

will be represented as (spaces are removed, the first encountered quote type is used)

  • Children tables before parent table (tables are reordered by default, see test).
  • Scattered array of tables (tables are reordered by default, see test).

The reason behind the first limitation is that Table does not store its header, allowing us to safely swap two tables (we store a mapping in each table: child key -> child table).

This last two limitations allow us to represent a toml document as a tree-like data structure, which enables easier implementation of editing operations and an easy to use and type-safe API. If you care about the above two cases, you can use Document::to_string_in_original_order() to reconstruct tables in their original order.


Licensed under either of


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


~32K SLoC