Crate toml_edit

toml_edit

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

If you also need the ease of a more traditional API, see the toml crate.

Example

use toml_edit::{DocumentMut, value};

let toml = r#"
"hello" = 'toml!' # comment
['a'.b]
"#;
let mut doc = toml.parse::<DocumentMut>().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);

Controlling formatting

By default, values are created with default formatting

let mut doc = toml_edit::DocumentMut::new();
doc["foo"] = toml_edit::value("bar");
let expected = r#"foo = "bar"
"#;
assert_eq!(doc.to_string(), expected);

You can choose a custom TOML representation by parsing the value.

let mut doc = toml_edit::DocumentMut::new();
doc["foo"] = "'bar'".parse::<toml_edit::Item>().unwrap();
let expected = r#"foo = 'bar'
"#;
assert_eq!(doc.to_string(), expected);

Limitations

Things it does not preserve:

• Order of dotted keys, see issue.

Modules

de

Deserializing TOML into Rust structures.

ser

Serializing Rust structures into TOML.

visit

Document tree traversal to walk a shared borrow of a document tree.

visit_mut

Document tree traversal to mutate an exclusive borrow of a document tree in place.

Structs

Array

A TOML Value that contains a sequence of Values

ArrayOfTables

A top-level sequence of Tables, each under their own header

Date

A parsed TOML date value

Datetime

A parsed TOML datetime value

DatetimeParseError

Error returned from parsing a Datetime in the FromStr implementation.

Decor

A prefix and suffix,

DocumentMut

The editable root TOML Table, containing Key/Value pairs and all other logic Tables

Formatted

A scalar TOML Value’s logical value and its representation in a &str

ImDocument

The root TOML Table, containing Key/Value pairs and all other logic Tables

InlineOccupiedEntry

A view into a single occupied location in an InlineTable.

InlineTable

A TOML Value that contains a collection of Key/Value pairs

InlineVacantEntry

A view into a single empty location in an InlineTable.

InternalString

Opaque string storage internal to toml_edit

Key

For Key/Value pairs under a Table header or inside an InlineTable

KeyMut

A mutable reference to a Key’s formatting

OccupiedEntry

A view into a single occupied location in a Table.

RawString

Opaque string storage for raw TOML; internal to toml_edit

Repr

A TOML Value encoded as a &str

Table

A TOML table, a top-level collection of key/Value pairs under a header and logical sub-tables

Time

A parsed TOML time value

TomlError

A TOML parse error

VacantEntry

A view into a single empty location in a Table.

Enums

Entry

A view into a single location in a Table, which may be vacant or occupied.

InlineEntry

A view into a single location in an InlineTable, which may be vacant or occupied.

Item

Type representing either a value, a table, an array of tables, or none.

Offset

A parsed TOML time offset

Value

For Key/Value pairs under a Table header or inside another Value

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 Aliases

ArrayIntoIter

An owned iterator type over Array’s Values

ArrayIter

An iterator type over Array’s Values

ArrayIterMut

An iterator type over Array’s Values

ArrayOfTablesIntoIter

An iterator type over ArrayOfTables’s Tables

ArrayOfTablesIter

An iterator type over ArrayOfTables’s Tables

ArrayOfTablesIterMut

An iterator type over ArrayOfTables’s Tables

DocumentDeprecated

Deprecated, replaced with DocumentMut

InlineTableIntoIter

An owned iterator type over an InlineTable’s Key/Value pairs

InlineTableIter

An iterator type over InlineTable’s Key/Value pairs

InlineTableIterMut

A mutable iterator type over InlineTable’s Key/Value pairs

IntoIter

An owned iterator type over Table’s Key/Item pairs

Iter

An iterator type over Table’s Key/Item pairs

IterMut

A mutable iterator type over Table’s Key/Item pairs