Module cst 

Side-table CST (concrete syntax tree) for lossless round-tripping.

This module is the implementation of the design described in docs/design/green-tree.md. It exposes a Document type that parses YAML byte-faithfully — every byte of the input is retained as a green-tree leaf — so that parse_document(s).unwrap().to_string() is byte-identical to s for any input the parser accepts.

The Document API depends on the parser’s SpanTree, which lives under the std feature.

The Value API (from_str, to_string, StreamingDeserializer) is unchanged. Trivia capture is enabled only on this path; the fast path pays no extra cost.

Current scope

• Read access. Document::as_value for a typed view, Document::span_at / Document::get for byte-range lookups by path, and Document::syntax for the green tree itself.

• Mutation. Document::replace_span (primitive byte replacement) and Document::set (path-targeted, the wrapper most callers want). Both re-parse on edit and reject the change if the spliced source is invalid YAML, leaving the document untouched. Document::edit creates an EditSession that batches independent byte-range replacements and validates the assembled result once.

• Comments. Document::comments_at classifies the comments decorating a node into a CommentBundle, and Document::set_comment / Document::remove_comment write them back, addressed by CommentPosition. A leading block is written at the node’s own indentation. Both go through replace_span, so they inherit its guard.

• Auto-formatting. Emit turns a typed value into the YAML spelling that re-parses to exactly that value at a given site, so Document::insert_entry_value, Document::push_back_value and Document::insert_after_value quote and escape what the fragment-taking mutators splice verbatim.

The green tree itself is still a flat sequence of leaves under a single Document parent — sufficient for byte-faithful round-tripping and for the span-based edit primitive. Hierarchical nesting (per-mapping / per-sequence parent nodes) is tracked as a follow-up in docs/design/green-tree.md.

Examples

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

Parser configuration

parse_document and parse_stream run under the default ParserConfig, the same limits as from_str. parse_document_with_config and parse_stream_with_config take one, mirroring from_str_with_config; the returned Document keeps it for every later re-parse of its own source, so an edit never falls back to the defaults.

Multi-document streams

Use parse_stream for inputs containing --- / ... separators — one Document per logical YAML document, with each slice covering the exact bytes of that document so concatenation reproduces the input verbatim:

use noyalib::cst::{parse_stream, Document};

let src = "---\nfoo: 1\n...\n---\nbar: 2\n";
let docs = parse_stream(src).unwrap();
assert_eq!(docs.len(), 2);
assert_eq!(docs[0].as_value()["foo"].as_i64(), Some(1));
assert_eq!(docs[1].as_value()["bar"].as_i64(), Some(2));
let joined: String = docs.iter().map(Document::source).collect();
assert_eq!(joined, src);

Structs

AliasInfo

A *name alias reference discovered in the document source.

AnchorInfo

An &name anchor declaration discovered in the document source.

CommentBundle

Comments that decorate a single node, organised by their position relative to the node.

Document

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

EditSession

A deferred, atomic batch of byte-range edits to a Document.

EmitCtx

The site an emitted fragment will be spliced into.

Entry

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

FormatConfig

Configuration for the formatter.

GreenNode

An immutable, byte-faithful syntax-tree node.

Enums

CommentPosition

Where a comment sits relative to the node it decorates.

GreenChild

A leaf-or-node child of a GreenNode.

RepairScope

The scope at which the most recent edit was repaired.

SyntaxKind

Kind of a green-tree node or token.

Traits

Emit

A value that can be spliced into a document by the auto-formatting mutators.

Functions

coerce_to_schema

Apply schema-driven type coercions to doc losslessly: only the bytes of the coerced scalars are rewritten; comments, indentation, and sibling entries survive byte-faithfully.

format

Auto-formats a messy YAML file into a canonical style based on the CST.

format_with_config

Auto-formats a messy YAML file into a canonical style based on the CST, using the provided configuration.

format_with_parser_config

Auto-formats a YAML stream under the given formatter and parser configuration.

parse_document

Parse a YAML stream into an editable Document.

parse_document_with_config

Parse one YAML document into an editable Document under config, mirroring crate::from_str_with_config.

parse_stream

Parse a YAML stream and return one Document per logical document.

parse_stream_with_config

Parse a YAML stream into one Document per logical document under config, mirroring crate::load_all_with_config.