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

• 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