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

use toml_edit::{Document, value};

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:

• Different quotes and spaces around the same table key, e.g.

[ 'a'. b]
[ "a"  .c]
[a.d]

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

['a'.b]
['a'.c]
['a'.d]

• 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.

Structs

Array	Type representing a TOML array, payload of the Value::Array variant's value
ArrayOfTables	Type representing a TOML array of tables
Decor	A prefix and suffix, including comments, whitespaces and newlines.
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.
decorated	Sets the prefix and the suffix for value.
table	Returns an empty table.
value	Returns a formatted value.

Type Definitions

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