Struct Document 

pub struct Document { /* private fields */ }

Available on crate feature std only.

A YAML document with byte-faithful source preservation, typed data access, and path-targeted edits.

Document carries three coordinated views of the same input: an immutable green tree that reproduces the source byte-for-byte, a typed Value for data access, and an internal span tree that maps any Value-shaped path back to a byte range. Edits flow through Document::replace_span (the primitive) and Document::set (the path-shaped wrapper); untouched bytes — indentation, comments, blank lines, sibling entries — are preserved verbatim.

Examples

Read-only round-trip:

use noyalib::cst::parse_document;

let src = "name: noyalib  # the project\nversion: 0.0.1\n";
let doc = parse_document(src).unwrap();
assert_eq!(doc.to_string(), src);

Path-targeted edit:

use noyalib::cst::parse_document;

let mut doc = parse_document("name: foo\nversion: 0.0.1\n").unwrap();
doc.set("version", "0.0.2").unwrap();
assert_eq!(doc.to_string(), "name: foo\nversion: 0.0.2\n");

Implementations

impl Document

pub fn anchors(&self) -> Vec<AnchorInfo>

Every &name declaration in this document, in source order.

Examples

use noyalib::cst::parse_document;

let doc = parse_document(
    "defaults: &cfg\n  port: 8080\nserver:\n  <<: *cfg\n",
).unwrap();
let anchors = doc.anchors();
assert_eq!(anchors.len(), 1);
assert_eq!(anchors[0].name, "cfg");

pub fn aliases(&self) -> Vec<AliasInfo>

Every *name reference in this document, in source order.

Examples

use noyalib::cst::parse_document;

let doc = parse_document("a: &x 1\nb: *x\nc: *x\n").unwrap();
let aliases = doc.aliases();
assert_eq!(aliases.len(), 2);

pub fn aliases_of(&self, name: &str) -> Vec<AliasInfo>

Aliases whose name matches name, in source order.

Examples

use noyalib::cst::parse_document;

let doc = parse_document("a: &x 1\nb: &y 2\nc: *x\nd: *y\n").unwrap();
let xs = doc.aliases_of("x");
assert_eq!(xs.len(), 1);
assert_eq!(xs[0].name, "x");

pub fn materialise_alias_at(&mut self, position: usize) -> Result<()>

Replace the *name alias whose mark begins at byte position with the source text of the matching &name’s scalar value.

After the splice, the alias’s site holds an independent copy of the anchored scalar — subsequent edits to the anchored value do not propagate to it.

Errors

• position does not start an *name token.
• The named anchor is not declared earlier in source order.
• The anchored value is not a scalar (multi-line block collections require manual handling — read the anchor’s span via Self::anchors and splice with Self::replace_span).
• The same parse-after-edit errors as Self::replace_span.

Examples

use noyalib::cst::parse_document;

let mut doc = parse_document("a: &x 7\nb: *x\n").unwrap();
let alias = doc.aliases()[0].clone();
doc.materialise_alias_at(alias.mark_span.0).unwrap();
assert!(!doc.to_string().contains("*x"));
assert!(doc.to_string().contains("b: 7"));

pub fn materialise_aliases_of(&mut self, name: &str) -> Result<usize>

Materialise every alias whose name matches name. Returns the count of aliases replaced.

Aliases are processed in reverse source order so each splice’s offsets stay valid for later (earlier in source) aliases.

Errors

As Self::materialise_alias_at. The first failing alias aborts the batch — already-materialised aliases stay materialised, the rest are unchanged.

Examples

use noyalib::cst::parse_document;

let mut doc = parse_document("a: &x 7\nb: *x\nc: *x\n").unwrap();
let n = doc.materialise_aliases_of("x").unwrap();
assert_eq!(n, 2);
assert!(!doc.to_string().contains('*'));

pub fn rename_anchor(&mut self, old: &str, new: &str) -> Result<usize>

Rename every &old anchor declaration and every *old alias reference to new in one atomic pass. Returns the total number of touched sites (anchors + aliases).

Splices run in reverse source order so each successive splice’s offsets stay valid for earlier sites. The whole rename is byte-faithful outside the touched marks — comments, blank lines, and sibling formatting survive verbatim.

Errors

• new is empty or contains characters that would not be accepted as a YAML anchor name (any of the flow indicators ,[]{} or whitespace per YAML 1.2 §6.9.2).
• old does not match any anchor or alias in the document (so the call is a no-op the user probably did not intend) — surfaced as an error rather than a silent zero-count.
• The same parse-after-edit errors as crate::cst::Document::replace_span for any individual splice. The first failing splice aborts the batch; already-renamed sites stay renamed, so callers should treat a partial-failure error as a recoverable state and inspect the document.

Examples

use noyalib::cst::parse_document;

let mut doc = parse_document(
    "defaults: &cfg\n  port: 8080\nservice:\n  <<: *cfg\nbackup: *cfg\n",
).unwrap();

// Rename `cfg` → `defaults`. The single `&cfg` declaration
// and both `*cfg` references are updated in one call.
let n = doc.rename_anchor("cfg", "defaults").unwrap();
assert_eq!(n, 3); // 1 anchor + 2 aliases
let out = doc.to_string();
assert!(!out.contains("&cfg"));
assert!(!out.contains("*cfg"));
assert!(out.contains("&defaults"));
assert!(out.contains("*defaults"));

impl Document

pub fn comments_at(&self, path: &str) -> CommentBundle

Comments decorating the node at path, classified by position.

Returns an empty CommentBundle when path does not resolve. Path syntax matches Document::span_at — foo.bar, items[0], items[0].name. Wildcard / recursive-descent segments are not supported (a non-singular span has no canonical “above” line).

Examples

use noyalib::cst::parse_document;

let src = "# A multi-line\n# leading block\nport: 8080  # inline\n";
let doc = parse_document(src).unwrap();

let b = doc.comments_at("port");
assert_eq!(b.before.len(), 2);
assert_eq!(b.inline.as_ref().unwrap().text, " inline");

impl Document

pub fn syntax(&self) -> &GreenNode

Borrow the root GreenNode.

Examples

use noyalib::cst::{parse_document, SyntaxKind};

let doc = parse_document("foo: 1\n").unwrap();
assert_eq!(doc.syntax().kind(), SyntaxKind::Document);

pub fn as_value(&self) -> Ref<'_, Value>

Borrow the typed Value view of the document.

On the first call after an edit (or a fresh parse), this triggers a one-shot parse of the current source into the internal Value / SpanTree cache. Subsequent calls on the same document are O(1) until the next edit invalidates the cache. Code that batches many edits without reading the typed view in between never pays the typed-tree cost.

Examples

use noyalib::cst::parse_document;

let doc = parse_document("name: noyalib\n").unwrap();
assert_eq!(doc.as_value()["name"].as_str(), Some("noyalib"));

pub fn source(&self) -> &str

The original source bytes for this document. After an edit reflects the current source.

Examples

use noyalib::cst::parse_document;

let src = "key: 1\n";
let doc = parse_document(src).unwrap();
assert_eq!(doc.source(), src);

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

Resolve a path to the byte range of the value at that path, if any.

Path syntax matches the rest of the crate (foo.bar, items[0], items[0].name). Wildcard / recursive-descent segments are not supported here — they have no single span.

Examples

use noyalib::cst::parse_document;

let doc = parse_document("name: noyalib\nversion: 0.0.1\n").unwrap();
let (s, e) = doc.span_at("version").unwrap();
assert_eq!(&doc.source()[s..e], "0.0.1");

pub fn validate(&self) -> Result<()>

Verify that the current source re-parses cleanly.

Document::set (and the rest of the path-shaped edit API) uses a localised-repair fast path that gates each splice on the fragment’s own scanner-level validation but commits optimistically: a structurally invalid splice across the whole document — for example, a value like [ that opens a flow collection never closed at end-of-input — passes the fragment check and only surfaces when the typed view is next read. as_value, span_at, get, and any path-shaped API panic on first access in that state.

validate is the non-panicking eager check: call it after an edit (or before handing the document to a downstream consumer) to surface any document-level parse error as a regular Result. On success, the typed cache is populated as a side-effect so a subsequent as_value call is free.

Errors

Returns the underlying parse error if the source no longer parses as a single YAML document.

Examples

Eagerly validate after an edit that may not be safe:

use noyalib::cst::parse_document;

let mut doc = parse_document("name: foo\n").unwrap();
// `[` opens a flow seq that is never closed — the local
// repair commits optimistically, but the document is now
// structurally broken. `validate` surfaces that as an
// error rather than waiting for the next typed-view read.
doc.set("name", "[").unwrap();
assert!(doc.validate().is_err());

Validate a freshly-parsed document — always succeeds:

use noyalib::cst::parse_document;

let doc = parse_document("name: foo\n").unwrap();
assert!(doc.validate().is_ok());

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

Return the source slice of the value at path.

Examples

use noyalib::cst::parse_document;

let doc = parse_document("items:\n  - one\n  - two\n").unwrap();
assert_eq!(doc.get("items[1]"), Some("two"));

pub fn replace_span( &mut self, start: usize, end: usize, replacement: &str, ) -> Result<()>

Replace the bytes in start..end with replacement and re-parse. The caller is responsible for replacement being a syntactically valid fragment in that position; if the spliced source fails to parse, the original document is left unchanged and the parse error is returned.

Errors

• Error::Parse if the resulting source is not valid YAML.
• Error::Parse if start..end is out of bounds or not a character boundary.

Examples

use noyalib::cst::parse_document;

let mut doc = parse_document("a: 1\n").unwrap();
let (s, e) = doc.span_at("a").unwrap();
doc.replace_span(s, e, "42").unwrap();
assert_eq!(doc.to_string(), "a: 42\n");

pub fn last_repair_scope(&self) -> Option<RepairScope>

Last successful repair scope, if any. Useful for tests and instrumentation; returns None for a freshly-parsed document or when the most recent edit fell back to a full re-parse.

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

Replace the value at path with fragment.

fragment is spliced verbatim into the source — the caller supplies the YAML representation. This deliberately matches no scalar style automatically; choose double-quoted, plain, or block style to suit. Auto-formatting (the Emit trait from the design doc) is a follow-up.

Errors

• Error::Parse(...) with “path not found” if path does not resolve in the current document.
• The same errors as Document::replace_span otherwise.

Examples

use noyalib::cst::parse_document;

let mut doc = parse_document("name: foo\nversion: 0.0.1\n").unwrap();
doc.set("version", "0.0.2").unwrap();
assert_eq!(doc.to_string(), "name: foo\nversion: 0.0.2\n");

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

Replace the value at path with a typed Value, formatting the YAML fragment to match the existing scalar style at the target site.

Style matching:

• PlainScalar — emit plain when safe, double-quoted otherwise.
• SingleQuotedScalar — wrap in '…' (only string values).
• DoubleQuotedScalar — wrap in "…" with standard escapes (only string values).
• LiteralScalar / FoldedScalar — currently rejected; block scalar formatting is a follow-up.

Non-string values (numbers, booleans, null) are emitted plain regardless of the existing style — quoting them would change the parsed type round-trip.

Errors

• Path not found.
• Target is a collection or block scalar.
• Caller passed a Sequence / Mapping (use set with a pre-formatted fragment for those — set_value is scalar-only for now).
• The same errors as Document::replace_span otherwise.

Examples

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

let mut doc = parse_document("name: noyalib\nversion: 0.0.1\n").unwrap();
doc.set_value("version", &Value::String("0.0.2".into())).unwrap();
assert_eq!(doc.to_string(), "name: noyalib\nversion: 0.0.2\n");

pub fn remove(&mut self, path: &str) -> Result<()>

Remove the value at path along with its surrounding entry (key + colon for mappings, - indicator for sequences). Trailing whitespace and the line break are removed too so the surrounding entries close up with no orphan blank line.

Restrictions in this phase:

• Block context only — flow-collection entry removal ([a, b, c] → [a, c]) is a follow-up.
• The value must end on the line where its key / - indicator appears (single-line scalars). Multi-line values and nested collections are deferred to the same follow-up that handles block-scalar replacement in set_value.
• Removing the only entry of a block mapping or sequence is rejected — the result would parse differently (an empty block becomes null), and the caller needs to express that intent explicitly.

Errors

• Path not found.
• Restrictions above.
• The same parse-after-edit errors as Document::replace_span; on failure the document is left unchanged.

Examples

use noyalib::cst::parse_document;

let mut doc = parse_document("a: 1\nb: 2\nc: 3\n").unwrap();
doc.remove("b").unwrap();
assert_eq!(doc.to_string(), "a: 1\nc: 3\n");

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

Append a new item to the block sequence at path.

fragment is the YAML representation of the value — the - indicator and the surrounding indentation are synthesized from the existing items so the new line matches the file’s shape. Block sequences only in this phase; flow sequences ([…]) and empty sequences are rejected.

Errors

• path does not resolve to a sequence.
• The sequence is a flow collection ([…]).
• The sequence has no existing items to anchor indentation on.
• The same parse-after-edit errors as Document::replace_span.

Examples

use noyalib::cst::parse_document;

let mut doc = parse_document("items:\n  - one\n  - two\n").unwrap();
doc.push_back("items", "three").unwrap();
assert_eq!(doc.to_string(), "items:\n  - one\n  - two\n  - three\n");

pub fn indent_unit(&self) -> usize

Detect the indentation unit (in spaces) used by this document.

Walks the source line-by-line, looks for any pair of consecutive non-empty/non-comment lines where the second is more deeply indented than the first, and returns the smallest such delta — that is the file’s “indent step”, typically 2 or 4 spaces. A document with no nested structure (or only top-level keys) has no detectable step; the default 2 is returned in that case.

Used internally by the crate::cst::Entry insertion paths to keep the inserted YAML’s inner indentation consistent with what the rest of the file already uses (2-space file → 2-space inserts; 4-space file → 4-space inserts). Exposed publicly so callers building their own emission paths can match the same convention.

Examples

use noyalib::cst::parse_document;

let two_space = parse_document(
    "metadata:\n  labels:\n    app: noyalib\n",
).unwrap();
assert_eq!(two_space.indent_unit(), 2);

let four_space = parse_document(
    "metadata:\n    labels:\n        app: noyalib\n",
).unwrap();
assert_eq!(four_space.indent_unit(), 4);

// No nested structure — defaults to 2.
let flat = parse_document("a: 1\nb: 2\n").unwrap();
assert_eq!(flat.indent_unit(), 2);

pub fn dominant_quote_style(&self) -> ScalarStyle

Inspect the document and return the dominant scalar quote style — Plain, SingleQuoted, or DoubleQuoted. Used by the crate::cst::Entry insert helpers to make new scalars adopt the file’s existing convention rather than the serializer’s hard-coded default.

The detection scans every plain / single-quoted / double-quoted scalar leaf in the green tree, picks the majority, and breaks ties in favour of the simpler form (Plain > SingleQuoted > DoubleQuoted). Empty documents and documents with no string-shaped scalars default to Plain.

Examples

use noyalib::cst::parse_document;
use noyalib::ScalarStyle;

let single = parse_document("a: 'one'\nb: 'two'\n").unwrap();
assert_eq!(single.dominant_quote_style(), ScalarStyle::SingleQuoted);

let double = parse_document("a: \"one\"\nb: \"two\"\n").unwrap();
assert_eq!(double.dominant_quote_style(), ScalarStyle::DoubleQuoted);

let plain = parse_document("a: one\nb: two\n").unwrap();
assert_eq!(plain.dominant_quote_style(), ScalarStyle::Plain);

pub fn dominant_flow_style(&self) -> FlowStyle

Inspect the document and return the dominant collection style — FlowStyle::Block or FlowStyle::Auto (equivalent to “flow”). Used by Entry::insert_value to decide whether a typed mapping / sequence emission should use block or flow form.

The detection counts top-level BlockMapping / BlockSequence vs FlowMapping / FlowSequence leaves and picks the majority. Empty / scalar-only documents default to Block.

Examples

use noyalib::cst::parse_document;
use noyalib::FlowStyle;

let block = parse_document("a:\n  - 1\n  - 2\n").unwrap();
assert_eq!(block.dominant_flow_style(), FlowStyle::Block);

let flow = parse_document("a: [1, 2, 3]\nb: [4, 5]\n").unwrap();
assert_eq!(flow.dominant_flow_style(), FlowStyle::Auto);

pub fn insert_entry( &mut self, mapping_path: &str, key: &str, fragment: &str, ) -> Result<()>

Insert a new key: fragment entry into the block mapping at mapping_path. The mapping-side analogue of Document::push_back.

Behaves like set when the key already exists (the value is replaced losslessly). When the key is new, a sibling line is spliced after the last existing entry, with the indent matched to the last entry’s key column so the file stays canonical. Block mappings only in this phase; flow mappings ({…}) and empty mappings are rejected.

Errors

• mapping_path does not resolve to a mapping.
• The mapping is empty (no anchor for indentation; use set with a fragment instead).
• The same parse-after-edit errors as Document::replace_span.

Examples

use noyalib::cst::parse_document;

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

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

Insert a new sequence item immediately after the item at item_path (e.g. "items[1]").

fragment is the YAML representation of the value; the - indicator and indentation are derived from the item at item_path.

Errors

• item_path does not end in an index.
• The path does not resolve to a sequence item in a block sequence.
• The same parse-after-edit errors as Document::replace_span.

Examples

use noyalib::cst::parse_document;

let mut doc = parse_document("items:\n  - one\n  - three\n").unwrap();
doc.insert_after("items[0]", "two").unwrap();
assert_eq!(
    doc.to_string(),
    "items:\n  - one\n  - two\n  - three\n",
);

impl Document

pub fn entry<'a>(&'a mut self, path: &str) -> Entry<'a>

Return a path-shaped mutable handle to the node at path.

The handle is the “pro” mutation interface — chainable, composable, ergonomic for nested edits — that complements the functional Document::set / Document::remove / Document::push_back / Document::insert_after methods (all of which remain available for direct one-shot operations).

entry itself is infallible — the path is recorded but not resolved at this point. Operations on the returned entry surface path-resolution and splice-failure errors via their own Result.

Examples

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"));

Trait Implementations

impl Clone for Document

fn clone(&self) -> Self

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.

impl Display for Document

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

Re-emit the document. For any input that parses successfully, the result equals the original bytes verbatim. Display drives Document::to_string() via the standard ToString blanket impl.