Crate toml_edit

toml_edit

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

It is primarily tailored to the needs of cargo-edit.

Example

extern crate toml_edit;

use toml_edit::{Document, value};

fn main() {
    let toml = r#"
"hello" = 'toml!' # comment
['a'.b]
    "#;
    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
['a'.b]
c = { d = "hello" }
    "#;
    assert_eq!(doc.to_string(), expected);
}

Limitations

*Things it does not preserve: 1. Different quotes and spaces around the same table key, e.g. toml [ 'a'. b] [ "a" .c] [a.d] will be represented as (spaces are removed, the first encountered quote type is used) toml ['a'.b] ['a'.c] ['a'.d] 2. Children tables before parent table (tables are reordered, see [test]). 3. Scattered array of tables (tables are reordered, 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.

Structs

Array	Type representing a TOML array, payload of the Value::Array variant's value
ArrayOfTables	Type representing a TOML array of tables
Document	Type representing a TOML document
InlineTable	Type representing a TOML inline table, payload of the Value::InlineTable variant
Key	Key as part of a Key/Value Pair or a table header.
Table	Type representing a TOML non-inline table
TomlError	Type representing a TOML parse error

Enums

Item	Type representing either a value, a table, an array of tables, or none.
Value	Representation of a TOML Value (as part of a Key/Value Pair).

Traits

TableLike

This trait represents either a Table, or an InlineTable.

Functions

array	Returns an empty array of tables.
table	Returns an empty table.
value	Returns a formatted value.

Type Definitions

Iter	An iterator type over Table's key/value pairs.