Struct Entry 

pub struct Entry<'a> { /* private fields */ }

A path-shaped mutable handle to a node in a Document.

Created by Document::entry. Every method routes through the same CST splice the functional API uses, so edits are byte-faithful outside the touched span.

Examples

Single-level edit, equivalent to Document::set:

use noyalib::cst::parse_document;

let mut doc = parse_document("port: 8080\n").unwrap();
doc.entry("port").set("9090").unwrap();
assert_eq!(doc.to_string(), "port: 9090\n");

Nested edit by chained drill-down — no string concatenation:

use noyalib::cst::parse_document;

let mut doc = parse_document(
    "server:\n  host: localhost\n  port: 8080\n",
).unwrap();
doc.entry("server").entry("port").set("9090").unwrap();
assert!(doc.to_string().contains("port: 9090"));

Insert into a mapping by key without manual path strings:

use noyalib::cst::parse_document;

let mut doc = parse_document(
    "metadata:\n  labels:\n    app: noyalib\n",
).unwrap();
doc.entry("metadata.labels").insert("env", "prod").unwrap();
let out = doc.to_string();
assert!(out.contains("app: noyalib"));
assert!(out.contains("env: prod"));

Implementations

impl<'a> Entry<'a>

pub fn path(&self) -> &str

The path this entry represents, as a dotted/indexed string.

pub fn exists(&self) -> bool

true if a node currently exists at this path.

pub fn get(&self) -> Option<&str>

The current source slice at this path, or None if the path does not resolve. Forwards to Document::get.

pub fn span_at(&self) -> Option<(usize, usize)>

The byte range (start, end) at this path, or None if the path does not resolve. Forwards to Document::span_at.

pub fn comments(&self) -> CommentBundle

Comments that decorate this node. Forwards to Document::comments_at.

pub fn set(self, fragment: &str) -> Result<()>

Replace the value at this path with fragment. Forwards to Document::set.

Consumes the entry. Returns the Document’s reference back via the borrow expiring; chain a fresh doc.entry(...) for the next edit.

Errors

Same as Document::set — invalid path, parse-after-splice failure, etc.

pub fn set_value(self, value: &Value) -> Result<()>

Replace the value at this path with the YAML emission of value. Forwards to Document::set_value.

Errors

Same as Document::set_value.

pub fn remove(self) -> Result<()>

Remove the entry at this path. Forwards to Document::remove.

Errors

Same as Document::remove.

pub fn insert(self, key: &str, fragment: &str) -> Result<()>

Insert a key: value pair into the mapping at this path. If the key already exists, the value is replaced losslessly; if it is new, a sibling line is spliced after the last existing entry with matching indent. Forwards to Document::insert_entry.

Errors

• The mapping at self.path does not exist.
• The mapping is empty (no anchor for indent — use Self::set with a fragment to give the mapping its first entry).
• The same parse-after-splice errors as the underlying replace_span.

pub fn insert_value(self, key: &str, value: &Value) -> Result<()>

Insert a key: value pair where the value is a typed Value, auto-formatting both halves.

Forwards to Document::insert_entry_value: the value is emitted so it re-parses to exactly value — quoted when the plain spelling would not — the key is quoted when it needs to be, indentation follows the file’s detected unit, and the splice is held to a re-parse plus typed-value check that rolls back on any mismatch.

Errors

As Document::insert_entry_value.

pub fn push_back_value(self, value: &Value) -> Result<()>

Append a typed Value to the sequence at this path. Forwards to Document::push_back_value.

Errors

As Document::push_back_value — the path must point to a non-empty block sequence.

pub fn insert_after_value(self, value: &Value) -> Result<()>

Insert a typed Value as a new sequence item immediately after the item at this path. Forwards to Document::insert_after_value.

Errors

As Document::insert_after_value — the path must end in an index and resolve to an item of a block sequence.

pub fn push_back(self, fragment: &str) -> Result<()>

Append fragment as a new item to the sequence at this path. Forwards to Document::push_back.

Errors

Same as Document::push_back — the path must point to a non-empty block sequence.

pub fn insert_after(self, fragment: &str) -> Result<()>

Insert fragment as a new sequence item immediately after the item at this path. Forwards to Document::insert_after.

Errors

Same as Document::insert_after — the path must end in an index and resolve to a sequence item in a block sequence.

pub fn entry(self, child: &str) -> Self

Drill down to a child path. The returned Entry represents self.path + "." + child, holding the same mutable borrow. A child that begins with [ — an index, or the quoted segment crate::path::quote_key spells for a key holding ., [, ], or * — is appended without the separator.

Examples

use noyalib::cst::parse_document;

let mut doc = parse_document(
    "a:\n  b:\n    c: 1\n",
).unwrap();
doc.entry("a").entry("b").entry("c").set("2").unwrap();
assert!(doc.to_string().contains("c: 2"));

pub fn or_insert(self, default: &str) -> Result<bool>

Ensure a value exists at this path: if the entry already resolves, leave it untouched; if it does not, splice default as the new value.

Mirrors the std::collections::hash_map::Entry::or_insert pattern adapted to the CST: the path is resolved through the green tree first, then the splice runs only on the vacant branch. The resolution is byte-faithful and skips the typed Value cache, so the call is cheap on already-occupied paths.

Returns Ok(true) when the splice ran (the entry was vacant), Ok(false) when the entry was already occupied (no-op).

Errors

• For mapping inserts: as Self::insert — the parent mapping must exist at the dotted-path prefix and must not be empty.
• For top-level inserts (no . in path): rejected with a clear message; use Document::set with a fresh document for that case.

Examples

use noyalib::cst::parse_document;

let mut doc = parse_document(
    "metadata:\n  labels:\n    app: noyalib\n",
).unwrap();

// First call: the path was vacant, so the splice ran.
let inserted = doc.entry("metadata.labels.env")
    .or_insert("prod")
    .unwrap();
assert!(inserted);
assert!(doc.to_string().contains("env: prod"));

// Second call on the same path: the entry is now occupied,
// so it returns `false` and leaves the value untouched.
let inserted = doc.entry("metadata.labels.env")
    .or_insert("staging")
    .unwrap();
assert!(!inserted);
assert!(doc.to_string().contains("env: prod"));

pub fn or_insert_with<F>(self, default: F) -> Result<bool>

where F: FnOnce() -> String,

Like Self::or_insert but constructs the default lazily — the closure runs only on the vacant branch.

Errors

As Self::or_insert.

Examples

use noyalib::cst::parse_document;

let mut doc = parse_document(
    "metadata:\n  labels:\n    app: noyalib\n",
).unwrap();
let _ = doc.entry("metadata.labels.env")
    .or_insert_with(|| "prod".to_owned())
    .unwrap();
assert!(doc.to_string().contains("env: prod"));

pub fn or_insert_value(self, default: &Value) -> Result<bool>

Like Self::or_insert but takes a typed Value. Honours the file’s detected indent unit (Document::indent_unit) when emitting the value.

Errors

As Self::or_insert, plus serializer errors when the value cannot be emitted as YAML.

Examples

use noyalib::cst::parse_document;
use noyalib::Value;

let mut doc = parse_document(
    "metadata:\n  labels:\n    app: noyalib\n",
).unwrap();
let _ = doc.entry("metadata.labels.replicas")
    .or_insert_value(&Value::Number(noyalib::Number::Integer(3)))
    .unwrap();
assert!(doc.to_string().contains("replicas: 3"));

pub fn and_modify<F>(self, f: F) -> Self

where F: FnOnce(&mut Document),

If the entry is occupied, run f and let it apply arbitrary mutations through a fresh sub-borrow of the document. No-op when the entry is vacant. The closure receives a Document reference so it can touch any path, not just self.path — useful for “if this exists, also update its sibling” patterns.

Returns self for further chaining (typically with Self::or_insert) — mirrors std::collections::hash_map::Entry::and_modify.

Examples

use noyalib::cst::parse_document;

let mut doc = parse_document(
    "service:\n  port: 8080\n",
).unwrap();

// Increment-style update: read, mutate, write — all under
// the same Entry handle. The closure only runs because the
// path is occupied.
let _ = doc.entry("service.port")
    .and_modify(|d| {
        let _ = d.set("service.port", "9090");
    })
    .or_insert("8080") // no-op now: path exists
    .unwrap();
assert!(doc.to_string().contains("port: 9090"));

Trait Implementations

impl<'a> Debug for Entry<'a>

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

Formats the value using the given formatter.