Struct Document 

pub struct Document { /* private fields */ }

A TOML document together with what its file looked like.

The tree is toml_edit’s, reached through Document::tree_mut for the operations in this crate to work on. What this adds is the byte order mark, the line ending and the final newline, which toml_edit does not keep, and a baseline for saying whether anything has been edited.

Implementations

impl Document

pub fn from_bytes(bytes: &[u8]) -> Result<Self, Error>

Parse a file’s bytes.

Errors

When the bytes are not UTF-8, or the text is not TOML.

pub fn parse(text: &str) -> Result<Self, Error>

Parse text, which may begin with a byte order mark.

Errors

When the text is not TOML.

pub fn from_path(path: &Path) -> Result<Self, Error>

Read and parse a file.

Errors

When the file cannot be read, is not UTF-8, or is not TOML.

pub fn save_to(&mut self, path: &Path) -> Result<(), Error>

Write what Document::render gives to a file, and mark the document saved.

Written beside the file and renamed over it, so that a failure at any point leaves the original as it was and never a file half written. The rename is what makes it one step, and it needs the two on one file system, which a sibling is. A platform whose sandbox refuses a sibling, which macOS’s does for a file a dialog granted, needs its own arm here; PROMPT.md carries that under Phase 3.

A rename needs only the directory to be writable, so two things an in-place write would do for free are done here on purpose: a file marked read-only is refused rather than replaced, and the file keeps the permissions it had rather than the staged file’s. Both were found by hand on 2026-09-07, when a read-only fixture saved without a word and came back mode 0600.

Errors

When the file is read-only, or the sibling cannot be created, written, or renamed over the file. The document is not marked saved then.

pub fn tree(&self) -> &DocumentMut

The tree, to read.

pub fn tree_mut(&mut self) -> &mut DocumentMut

The tree, to edit.

pub fn newline(&self) -> Newline

The line ending the file was written with.

pub fn has_bom(&self) -> bool

Whether the file began with a byte order mark.

pub fn render(&self) -> String

What a save writes: the document, with the byte order mark, the line ending and the final newline the file had.

pub fn edited(&self) -> bool

Whether the document differs from what was parsed or last saved.

pub fn mark_saved(&mut self)

Record that what the document now holds is what is on disk.

pub fn record(&mut self, group: Option<&[String]>) -> bool

Record whatever changed since the last call as a step, and say whether anything did.

group names the row the change was made in, where there is one. A change in the same row as the step before joins that step rather than starting another, so a word typed into a field undoes as a word; a change with no row, or in another row, is a step of its own. Any change empties the redo stack, since what was undone no longer follows from what is there.

pub fn can_undo(&self) -> bool

Whether there is a step to undo.

pub fn can_redo(&self) -> bool

Whether there is a step to redo.

pub fn undo(&mut self) -> bool

Put the document back as it was before the last step.

Anything changed since the last Document::record is recorded first, so that it can be redone rather than lost.

pub fn redo(&mut self) -> bool

Put back the last step undone.

pub fn lines_of(&self, path: &[String]) -> Option<Range<usize>>

The lines of the rendered text that the item at a path occupies, counted from zero, the end exclusive: a row from its key to the end of its value, a table or an array-of-tables element its header line. None for a path that names nothing.

The tree keeps no positions once it can be edited, so this parses the rendered text again, which does. That is a full parse per call, and a caller asks only when the selection or the document has changed.

Trait Implementations

impl Clone for Document

fn clone(&self) -> Document

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Document

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.