Crate toml_edit

Source
Expand description

§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