pub struct DocumentFile { /* private fields */ }Expand description
A file-backed document: owns the path, format, original source text, and parsed value.
Reading (open) is always allowed. Mutation methods guard against unsafe
targets (symlinks, hardlinked files) and write through a same-directory
temp file that is atomically renamed over the original — see
DocumentFile::save_atomic.
Implementations§
Source§impl DocumentFile
impl DocumentFile
Sourcepub fn open(
path: impl AsRef<Path>,
format_override: Option<Format>,
) -> DocumentResult<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.
Sourcepub fn value(&self) -> &Value
pub fn value(&self) -> &Value
Borrow the currently parsed value (reflects the last successful edit, if any).
Sourcepub fn source(&self) -> &str
pub fn source(&self) -> &str
Borrow the current source text (reflects the last successful edit, if any).
Sourcepub fn ensure_mutable(&self, operation: &str) -> DocumentResult<()>
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.
Every mutation method (DocumentFile::set and friends) already
runs this same guard itself before writing, so calling it directly is
only useful when a caller must front-run a separate side effect with
the same guarantee — for example, a CLI that reads a secret from stdin
for set should refuse an unsafe target before consuming that input,
not after.
Sourcepub fn set(&mut self, key: &str, value: Value) -> DocumentResult<()>
pub fn set(&mut self, key: &str, value: Value) -> DocumentResult<()>
Set key to the typed value, preserving the rest of the source
document.
Sourcepub fn add(
&mut self,
key: &str,
slug: &str,
slug_field: &str,
fields: &[(String, Value)],
) -> DocumentResult<()>
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.
Sourcepub fn remove(
&mut self,
key: &str,
slug: &str,
slug_field: &str,
) -> DocumentResult<()>
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.
Sourcepub fn unset(&mut self, key: &str) -> DocumentResult<()>
pub fn unset(&mut self, key: &str) -> DocumentResult<()>
Remove the entry at key entirely. Preserves the rest of the source
document.