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:
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.
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
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.