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 open_capped(
path: impl AsRef<Path>,
format_override: Option<Format>,
max_bytes: u64,
) -> DocumentResult<DocumentFile>
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.
Sourcepub fn value(&self) -> &Value
pub fn value(&self) -> &Value
Borrow the currently parsed value (reflects the last successful edit, if any).
Sourcepub fn value_at(&self, path: &str) -> DocumentResult<Value>
pub fn value_at(&self, path: &str) -> DocumentResult<Value>
Resolve a dotted path against the parsed document and return the value
at that address.
One-call read counterpart to set: equivalent to
value followed by
crate::document::get_path, for callers that only need to read one
address out of a file.
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.