Expand description

toml_edit

This crate allows you to parse and modify toml documents, while preserving comments, spaces* and relative order* or items.

It is primarily tailored to the needs of cargo-edit.

If you also need the ease of a more traditional API, see the easy module.

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.

A TOML-parsing library

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.

Macros

Construct a toml_edit::easy::Value from TOML syntax.

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

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.

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.