Format-preserving TOML editing.

parse/2 keeps the original source text, so a document renders back byte for byte, including comments, whitespace, key order, and value formatting such as hex integers or literal strings. Edits only rewrite the value they change; the rest of the document is left as written.

{:ok, doc} = TomlElixir.Document.parse(File.read!("config.toml"))
{:ok, doc} = TomlElixir.Document.put(doc, ["server", "port"], 9090)
File.write!("config.toml", TomlElixir.Document.to_iodata(doc))

Paths list keys from the document root as strings, with integer indexes for array elements and arrays of tables, such as ["products", 0, "name"].

Where new values go

put/3 places a value that does not exist yet next to related content:

• A key in a table defined by a header, or in the root table, goes after the table's last key/value line, with the same indentation.
• A key in a table defined by dotted keys, such as a.b = 1, becomes another dotted key after its siblings.
• A key in an inline table becomes a new entry, and index length of an array appends an element, keeping the collection's layout.
• A new table or array of tables entry gets its own header after the last section of its nearest existing parent table, or at the end of the document. A table that only exists through subtables, like a in [a.b], gets a new [a] header.

New lines are inserted before trailing comments and blank lines, since those usually introduce what follows them. New text uses the default TomlElixir.encode/2 style.

Current limits

• Replaced values are written in the default encoder style, so a replaced hex integer becomes decimal and a map replacing a non-table value becomes an inline table.
• Arrays that are values, like ports = [80, 443], are replaced whole rather than element by element.

Every edit re-validates the whole document, so an edit cannot produce invalid TOML. This re-decodes the document on each edit; batch edits on very large documents may be slow.