Crate toml_edit

Expand description

§`toml_edit`

This crate allows you to parse and modify toml documents, while preserving comments, spaces and relative order or 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: Type representing a TOML array, payload of the Value::Array variant’s value
ArrayOfTables: Type representing a TOML array of tables
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: Type representing a TOML document
Formatted: A value together with its to_string representation, including surrounding it whitespaces and comments.
ImDocument: Type representing a parsed TOML document
InlineOccupiedEntry: A view into a single occupied location in a IndexMap.
InlineTable: Type representing a TOML inline table, payload of the Value::InlineTable variant
InlineVacantEntry: A view into a single empty location in a IndexMap.
InternalString: Opaque string storage internal to toml_edit
Key: Key as part of a Key/Value Pair or a table header.
KeyMut: A mutable reference to a Key’s formatting
OccupiedEntry: A view into a single occupied location in a IndexMap.
RawString: Opaque string storage for raw TOML; internal to toml_edit
Repr: TOML-encoded value
Table: Type representing a TOML non-inline table
Time: A parsed TOML time value
TomlError: Type representing a TOML parse error
VacantEntry: A view into a single empty location in a IndexMap.

Enums§

Entry: A view into a single location in a map, which may be vacant or occupied.
InlineEntry: A view into a single location in a map, 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: 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 Aliases§

ArrayIntoIter: An owned iterator type over Table’s key/value pairs.
ArrayIter: An iterator type over Array’s values.
ArrayIterMut: An iterator type over Array’s values.
ArrayOfTablesIntoIter: An iterator type over ArrayOfTables’s values.
ArrayOfTablesIter: An iterator type over ArrayOfTables’s values.
ArrayOfTablesIterMut: An iterator type over ArrayOfTables’s values.
DocumentDeprecated: Deprecated, replaced with DocumentMut
InlineTableIntoIter: An owned iterator type over key/value pairs of an inline table.
InlineTableIter: An iterator type over key/value pairs of an inline table.
InlineTableIterMut: A mutable iterator type over key/value pairs of an inline table.
IntoIter: An owned iterator type over Table’s key/value pairs.
Iter: An iterator type over Table’s key/value pairs.
IterMut: A mutable iterator type over Table’s key/value pairs.

Crate toml_editCopy item path

§toml_edit