Struct DocumentFile 

pub struct DocumentFile { /* private fields */ }

A file-backed Document: the in-memory document plus the path it was read from.

All reads and source-preserving edits come from Document through [Deref]/[DerefMut]; DocumentFile adds only the file boundary — reading on open and an atomic, symlink-guarded commit on save / edit.

Implementations

impl DocumentFile

pub fn open( path: impl AsRef<Path>, format_override: Option<Format>, ) -> DocumentResult<DocumentFile>

Open and parse path.

format_override takes precedence; otherwise the format is detected from the file extension via Format::detect. Reading is always allowed — this does not run the mutation guard.

pub fn open_capped( path: impl AsRef<Path>, format_override: Option<Format>, max_bytes: u64, ) -> DocumentResult<DocumentFile>

Open and parse path like DocumentFile::open, but first reject any non-regular file, or any file larger than max_bytes, without reading its contents.

Use this over open when reading untrusted or secret-bearing config, where an unbounded read of an arbitrary path is a denial-of-service risk.

pub fn path(&self) -> &Path

The file path this document was opened from.

pub fn ensure_mutable(&self, operation: &str) -> DocumentResult<()>

Preflight-check that this file is safe to mutate — not a symlink, and on unix not hardlinked — without performing any write.

save runs this same guard before it writes, so calling it directly is only useful to front-run a separate side effect with the same guarantee — e.g. a CLI reading a secret from stdin for a set should refuse an unsafe target before consuming that input.

impl DocumentFile

pub fn edit<F>(&mut self, edit: F) -> DocumentResult<()>

where F: FnOnce(&mut Document) -> DocumentResult<()>,

Run edit against the in-memory Document, then commit once with save. The single-call form of stage-then-save: the edits either all land (on Ok) or none reach disk (on Err, nothing is written), and the commit can’t be forgotten.

pub fn save(&self) -> DocumentResult<()>

Persist the document — every edit staged since open — to its path in a single atomic write.

The mutation verbs (set/unset/add/remove) stage their source-preserving edit in memory and do not touch disk; this is the one commit point. That lets a caller apply several edits and inspect the result via value (e.g. deserialize-and-validate) before any bytes are written, and makes a multi-edit change atomic — all edits land together or none do.

Methods from Deref<Target = Document>

pub fn value(&self) -> &Value

Borrow the parsed value (reflects the last successful edit).

pub fn source(&self) -> &str

Borrow the current source text — the original bytes with every source-preserving edit applied. This is what DocumentFile::save writes.

pub fn format(&self) -> Format

The format this document was parsed from.

pub fn value_at(&self, path: &str) -> DocumentResult<Value>

Resolve a dotted path against the parsed document and return the value at that address.

pub fn value_at_typed( &self, path: &str, expected: ValueType, ) -> DocumentResult<Value>

value_at that also asserts the value at path satisfies expected, returning a DocumentError::TypeMismatch otherwise.

pub fn set_typed( &mut self, key: &str, raw: Option<&str>, value_type: ValueType, ) -> DocumentResult<()>

Build a value from the CLI string raw per an explicit ValueType and set it.

pub fn encode(&self) -> DocumentResult<String>

Re-render the current value in its format via Format::save.

This is a fresh, non-source-preserving render: comments and original formatting are not retained. Use source after source-preserving edits to keep the original formatting.

pub fn set(&mut self, key: &str, value: Value) -> DocumentResult<()>

Set key to the typed value, preserving the rest of the source document. The edit is staged in memory — call save to persist it.

Backend capability mirrors crate::document::set_path where the source editor allows it: the JSON backend replaces an existing value (scalar or collection) and creates missing intermediate parent objects; the TOML backend creates missing parent tables. Backends that cannot express an edit source-preserving (e.g. YAML collection mutation) return DocumentError::UnsupportedOperation.

pub fn add( &mut self, key: &str, slug: &str, slug_field: &str, fields: &[(String, Value)], ) -> DocumentResult<()>

Add a new element to the keyed list at key, identified by slug/slug_field, with the given fields. Preserves the rest of the source document.

Only JSON and YAML backends implement a source-preserving keyed-collection editor today; other formats return DocumentError::UnsupportedOperation.

pub fn remove( &mut self, key: &str, slug: &str, slug_field: &str, ) -> DocumentResult<()>

Remove the element identified by slug/slug_field from the keyed list at key. Preserves the rest of the source document.

Only JSON and YAML backends implement a source-preserving keyed-collection editor today; other formats return DocumentError::UnsupportedOperation.

pub fn unset(&mut self, key: &str) -> DocumentResult<bool>

Remove the entry at key entirely, preserving the rest of the source document. The edit is staged in memory — call DocumentFile::save to persist it.

Idempotent, like HashSet::remove: returns Ok(false) when key is already absent (nothing is staged) and Ok(true) when it was removed.

Trait Implementations

impl Clone for DocumentFile

fn clone(&self) -> DocumentFile

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DocumentFile

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

Formats the value using the given formatter.

impl Deref for DocumentFile

type Target = Document

The resulting type after dereferencing.

fn deref(&self) -> &Document

Dereferences the value.

impl DerefMut for DocumentFile

fn deref_mut(&mut self) -> &mut Document

Mutably dereferences the value.