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 or items.

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

Example

use toml_edit::{Document, value};

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

  • Scattered array of tables (tables are reordered by default, see test).
  • Order of dotted keys, see issue.

Modules

Deserializing TOML into Rust structures.
Serializing Rust structures into TOML.
Document tree traversal to walk a shared borrow of a document tree.
Document tree traversal to mutate an exclusive borrow of a document tree in place.

Structs

Type representing a TOML array, payload of the Value::Array variant’s value
Type representing a TOML array of tables
A parsed TOML date value
A parsed TOML datetime value
Error returned from parsing a Datetime in the FromStr implementation.
A prefix and suffix,
Type representing a TOML document
A value together with its to_string representation, including surrounding it whitespaces and comments.
A view into a single occupied location in a IndexMap.
Type representing a TOML inline table, payload of the Value::InlineTable variant
A view into a single empty location in a IndexMap.
Opaque string storage internal to toml_edit
Key as part of a Key/Value Pair or a table header.
A mutable reference to a Key
A view into a single occupied location in a IndexMap.
Opaque string storage for raw TOML; internal to toml_edit
TOML-encoded value
Type representing a TOML non-inline table
A parsed TOML time value
Type representing a TOML parse error
A view into a single empty location in a IndexMap.

Enums

A view into a single location in a map, which may be vacant or occupied.
A view into a single location in a map, which may be vacant or occupied.
Type representing either a value, a table, an array of tables, or none.
A parsed TOML time offset
Representation of a TOML Value (as part of a Key/Value Pair).

Traits

This trait represents either a Table, or an InlineTable.

Functions

Returns an empty array of tables.
Returns an empty table.
Returns a formatted value.

Type Definitions

An owned iterator type over Table’s key/value pairs.
An iterator type over Array’s values.
An iterator type over Array’s values.
An iterator type over ArrayOfTables’s values.
An iterator type over ArrayOfTables’s values.
An iterator type over ArrayOfTables’s values.
An owned iterator type over key/value pairs of an inline table.
An iterator type over key/value pairs of an inline table.
A mutable iterator type over key/value pairs of an inline table.
An owned iterator type over Table’s key/value pairs.
An iterator type over Table’s key/value pairs.
A mutable iterator type over Table’s key/value pairs.