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

  • de
    Deserializing TOML into Rust structures.
  • ser
    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,
  • Document
    Type representing a TOML document
  • Formatted
    A value together with its to_string representation, including surrounding it whitespaces and comments.
  • 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
  • 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 Definitions