Crate toml_edit

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§

deserde: Deserializing TOML into Rust structures.
serserde: 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

Crate toml_editCopy item path

§toml_edit