Struct YamlDoc

Source

pub struct YamlDoc { /* private fields */ }

Expand description

A source-preserving YAML document.

Implementations§

Source §

impl YamlDoc

Source

pub fn parse(input: &str) -> Result<YamlDoc, YamlError>

Parses a YAML stream into a round-trip document.

This bootstrap parser preserves the input text exactly and records a root stream node. Real lexing and parsing will replace this placeholder.

§Errors

Returns an error when source validation, CST parsing, or semantic view composition fails.

Source

pub fn parse_owned(input: String) -> Result<YamlDoc, YamlError>

Parses an owned YAML stream without copying its source buffer.

§Errors

Returns an error when source validation, CST parsing, or semantic view composition fails.

Source

pub fn commit_edits(&mut self) -> Result<(), YamlError>

Applies pending edits, reparses the rendered YAML, and clears the edit queue.

YamlDoc::to_string only previews the original source with queued byte patches applied. It does not prove that the patched stream is still valid YAML, because low-level edit APIs can replace arbitrary node spans or insert conservative-but-raw fragments. Reparse on commit is the point where the document regains a validated CST and semantic view.

§Errors

Returns an error when the patched YAML cannot be parsed.

Source

pub fn as_source(&self) -> &str

Returns the original source text.

Source

pub const fn source(&self) -> &Source

Returns the original source buffer and its line index.

Source

pub fn tokens(&self) -> Result<Vec<Token>, YamlError>

Returns a freshly owned copy of the lossless token stream.

The owned return type keeps this API stable when tokenization becomes on demand rather than retained by every document.

§Errors

Returns a lexer diagnostic if the source cannot be tokenized.

Source

pub fn root(&self) -> Option<NodeId>

Returns the root node identifier when present.

Source

pub fn events(&self) -> YamlEvents<'_> ⓘ

Derives the semantic event stream from CST-linked metadata.

Source

pub fn events_to_test_string(&self) -> String

Renders semantic events in the YAML Test Suite test.event format.

Source

pub fn document_count(&self) -> usize

Returns the number of documents in this YAML stream.

Source

pub fn append_document<T>(&mut self, value: &T) -> Result<(), YamlError>
where T: ToYamlFragment,

Queues an explicit document append at the end of this YAML stream.

The appended document becomes visible to document-indexed lookup after YamlDoc::commit_edits reparses the stream.

§Errors

Returns an error when value cannot be formatted as a YAML fragment or the append conflicts with another pending edit at the stream end.

Source

pub fn append_empty_mapping_document(&mut self) -> Result<(), YamlError>

Queues an explicit empty mapping document append.

§Errors

Returns an error when the append conflicts with another pending edit at the stream end.

Source

pub fn yaml_directive(&self) -> Option<YamlDirective>

Returns the %YAML directive when one is present in the stream prologue.

Source

pub fn tag_directives(&self) -> Vec<TagDirective>

Returns %TAG directives from the stream prologue in source order.

Source

pub fn reserved_directives(&self) -> Vec<ReservedDirective>

Returns reserved directives from the stream prologue in source order.

Source

pub fn set_yaml_directive(&mut self, version: &str) -> Result<(), YamlError>

Queues insertion or update of the stream %YAML directive.

§Errors

Returns an error when version is not valid YAML directive version syntax or when the edit overlaps an existing pending edit.

Source

pub fn set_tag_directive( &mut self, handle: &str, prefix: &str, ) -> Result<(), YamlError>

Queues insertion or update of a stream %TAG directive.

§Errors

Returns an error when handle or prefix is invalid or when the edit overlaps an existing pending edit.

Source

pub fn remove_yaml_directive(&mut self) -> Result<(), YamlError>

Queues removal of the stream %YAML directive when present.

§Errors

Returns an error when the removal edit overlaps an existing pending edit.

Source

pub fn remove_tag_directive(&mut self, handle: &str) -> Result<(), YamlError>

Queues removal of the stream %TAG directive with handle when present.

§Errors

Returns an error when the removal edit overlaps an existing pending edit.

Source

pub fn node(&self, node: NodeId) -> Option<&Node>

Returns a node by identifier.

Source

pub fn children(&self, node: NodeId) -> Children<'_> ⓘ

Iterates over a node’s children in source order.

Source

pub fn semantic_kind(&self, node: NodeId) -> Option<SemanticKind>

Returns a node’s semantic interpretation.

Source

pub fn raw_tag(&self, node: NodeId) -> Option<&str>

Returns the explicit tag spelling, including its leading !.

Source

pub fn resolved_tag( &self, node: NodeId, ) -> Result<Option<Cow<'_, str>>, YamlError>

Resolves an explicit tag through the built-in or document-local handle table.

§Errors

Returns an error when the tag spelling or its document-local handle is invalid.

Source

pub fn anchor(&self, node: NodeId) -> Option<&str>

Returns an anchor name without its leading &.

Source

pub fn alias_name(&self, node: NodeId) -> Option<&str>

Returns an alias name without its leading *.

Source

pub fn resolve_alias(&self, node: NodeId) -> Option<NodeId>

Resolves an alias to the most recent matching anchor in its document.

Source

pub fn documents(&self) -> impl Iterator<Item = NodeId>

Iterates over semantic document CST nodes in stream order.

Source

pub fn document_root(&self, index: usize) -> Result<Option<NodeId>, YamlError>

Returns the semantic root value of a selected document.

Empty documents have no root value and return Ok(None). Unlike YamlDoc::document_root_mapping, this method accepts scalar, sequence, mapping, and alias roots.

§Errors

Returns an error when index is outside the YAML stream.

Source

pub fn mapping_entries( &self, mapping: NodeId, ) -> impl Iterator<Item = (NodeId, NodeId)>

Iterates over mapping key/value CST node pairs in source order.

Source

pub fn sequence_items(&self, sequence: NodeId) -> impl Iterator<Item = NodeId>

Iterates over sequence item CST nodes in source order.

Source

pub fn root_mapping(&self) -> Result<NodeId, YamlError>

Returns the root-level mapping in the document.

§Errors

Returns an error when no root mapping exists or when the semantic root mapping is not linked back to a CST node.

Source

pub fn document_root_mapping(&self, index: usize) -> Result<NodeId, YamlError>

Returns the root-level mapping in a selected document.

§Errors

Returns an error when the selected document does not exist, has no mapping root, or the root mapping is not linked back to the CST.

Source

pub fn read_document<T>(&self, index: usize) -> Result<T, YamlError>
where T: FromYamlDoc,

Reads a typed overlay from a selected document.

§Errors

Returns an error when the selected document is missing or empty, or the typed overlay cannot be read.

Source

pub fn write_document<T>( &mut self, index: usize, value: &T, ) -> Result<(), YamlError>
where T: ToYamlDoc,

Writes a typed overlay to a selected document.

§Errors

Returns an error when the selected document is missing or empty, or the typed overlay cannot be written.

Source

pub fn get_mapping_entry( &self, mapping: NodeId, key: &str, ) -> Result<Option<NodeId>, YamlError>

Looks up a mapping entry by key inside mapping.

§Errors

Returns an error when a scalar key cannot be decoded.

Source

pub fn get_mapping_value( &self, mapping: NodeId, key: &str, ) -> Result<Option<NodeId>, YamlError>

Looks up a mapping value by key inside mapping.

§Errors

Returns an error when a scalar key cannot be decoded.

Source

pub fn get_path(&self, path: &[&str]) -> Result<Option<NodeId>, YamlError>

Looks up a nested path of mapping keys.

§Errors

Returns an error when semantic path lookup cannot decode a mapping key.

Source

pub fn get_path_in_document( &self, index: usize, path: &[&str], ) -> Result<Option<NodeId>, YamlError>

Looks up a nested path of mapping keys in a selected document.

§Errors

Returns an error when semantic path lookup fails while resolving the graph path.

Source

pub fn scalar_text(&self, node: NodeId) -> Result<&str, YamlError>

Returns the source text for a scalar node.

§Errors

Returns an error when node is unknown or does not identify a plain CST scalar node.

Source

pub fn scalar_value(&self, node: NodeId) -> Result<Cow<'_, str>, YamlError>

Returns the decoded value text for a scalar node.

Plain scalars have trailing inline comments stripped, single-quoted scalars unescape doubled apostrophes, and double-quoted scalars unescape the common JSON/YAML escapes used by typed overlays.

§Errors

Returns an error when node is unknown, is not a scalar node, has malformed node properties, or contains unsupported scalar escape syntax.

Source

pub fn borrowable_scalar_span( &self, node: NodeId, ) -> Result<Option, YamlError>

Returns the source span of a scalar whose decoded value can be borrowed byte-for-byte from the original input.

This currently returns a span only for single-line plain scalars. Quoted, escaped, folded, literal, and multiline scalars require decoding and return Ok(None).

§Errors

Returns an error when node is unknown, is not a scalar, or has malformed node properties.

Source

pub fn set_scalar( &mut self, path: &[&str], value: &str, ) -> Result<(), YamlError>

Queues a scalar value replacement at path while preserving the existing scalar style where the editor can do so safely.

Plain scalars remain plain, single-quoted scalars remain single-quoted, and double-quoted scalars remain double-quoted. Inline comments and trailing whitespace outside the scalar spelling are left untouched.

§Errors

Returns an error when path does not resolve to an existing scalar, the current scalar style cannot be rewritten safely, value cannot be represented in that style, or the queued edit conflicts with another pending edit.

Source

pub fn replace_node_text( &mut self, node: NodeId, text: impl Into<String>, ) -> Result<(), YamlError>

Queues a patch that replaces the exact source span covered by node.

The CST remains unchanged until the edited text is parsed again; callers can inspect the pending minimal-diff output through doc.to_string().

§Errors

Returns an error when node is unknown, text contains invalid YAML characters, or the replacement overlaps an existing pending edit.

Source

pub fn insert_mapping_entry( &mut self, mapping: NodeId, key: &str, value: &str, style: MappingEntryStyle, ) -> Result<(), YamlError>

Queues insertion of a plain key: value entry into a block mapping.

This low-level writer accepts raw plain scalar text. Use typed values or node fragments when quoting or schema-aware formatting is required.

§Errors

Returns an error when mapping is not a block mapping, key or value is not valid as a plain mapping fragment, or the insertion conflicts with another pending edit.

Source

pub fn insert_mapping_entry_with_comment( &mut self, mapping: NodeId, key: &str, value: &str, style: MappingEntryStyle, comment: Option<&str>, ) -> Result<(), YamlError>

Queues insertion of a plain key: value entry with optional preceding comment lines.

Comments are emitted only for inserted entries; existing YAML comments are never overwritten by this helper.

§Errors

Returns an error when mapping is not a block mapping, key, value, or comment cannot be emitted as valid YAML text, or the insertion conflicts with another pending edit.

Source

pub fn insert_mapping_value_with_comment<T>( &mut self, mapping: NodeId, key: &str, value: &T, style: MappingEntryStyle, comment: Option<&str>, ) -> Result<(), YamlError>
where T: ToYamlFragment,

Queues insertion of a typed YAML value under key in a block mapping.

§Errors

Returns an error when mapping is not a block mapping, the value cannot be formatted as a block YAML fragment, or the insertion conflicts with an existing pending edit.

Source

pub fn insert_mapping_value_ordered_with_comment<T>( &mut self, mapping: NodeId, key: &str, value: &T, style: MappingEntryStyle, comment: Option<&str>, ordered_keys: &[&str], ) -> Result<(), YamlError>
where T: ToYamlFragment,

Queues insertion of a typed YAML value according to declaration order.

§Errors

Returns an error when mapping lookup fails or the selected insertion cannot be formatted or queued.

Source

pub fn insert_mapping_entry_before_with_comment( &mut self, before_entry: NodeId, key: &str, value: &str, style: MappingEntryStyle, comment: Option<&str>, ) -> Result<(), YamlError>

Queues insertion of a plain key: value entry before before_entry.

§Errors

Returns an error when before_entry is not a mapping entry, key, value, or comment cannot be emitted as valid YAML text, or the insertion conflicts with another pending edit.

Source

pub fn insert_mapping_value_before_with_comment<T>( &mut self, before_entry: NodeId, key: &str, value: &T, style: MappingEntryStyle, comment: Option<&str>, ) -> Result<(), YamlError>
where T: ToYamlFragment,

Queues insertion of a typed YAML value before an existing mapping entry.

§Errors

Returns an error when the insertion target is invalid, the value cannot be formatted, or the insertion conflicts with an existing pending edit.

Source

pub fn insert_mapping_entry_ordered_with_comment( &mut self, mapping: NodeId, key: &str, value: &str, style: MappingEntryStyle, comment: Option<&str>, ordered_keys: &[&str], ) -> Result<(), YamlError>

Queues insertion according to a declaration-order key list.

If a later key from ordered_keys already exists in mapping, the new entry is inserted before that entry. Otherwise this falls back to append insertion. This is the primitive behind insert_order = "struct".

§Errors

Returns an error when mapping lookup fails, the selected insertion target has the wrong node kind, inserted text is invalid YAML, or the queued edit conflicts with another pending edit.

Source

pub fn remove_mapping_entry( &mut self, mapping: NodeId, key: &str, ) -> Result<(), YamlError>

Queues removal of the mapping entry with key from mapping when it exists.

The removal is line-wise, so comments and fields outside the selected entry remain byte-for-byte unchanged. Missing keys are a no-op.

§Errors

Returns an error when mapping lookup fails, the selected entry cannot be removed, or the removal overlaps an existing pending edit.

Source

pub fn retain_mapping_entries( &mut self, mapping: NodeId, allowed_keys: &[&str], ) -> Result<(), YamlError>

Queues line-wise removal edits for mapping entries whose keys are not allowed.

This is the patch-emitter primitive used by typed overlays that choose to prune unknown fields. It preserves the order and bytes of retained entries.

§Errors

Returns an error when mapping is not a block mapping, a retained entry cannot be inspected as a scalar key, or a removal edit conflicts with another pending edit.

Source

pub fn remove_node(&mut self, node: NodeId) -> Result<(), YamlError>

Queues removal of node from the rendered document.

Mapping and sequence entries are removed line-wise, including their line break when one is present. Other nodes use their exact source span.

§Errors

Returns an error when node is unknown or the removal overlaps an existing pending edit.

Source §

impl YamlDoc

Source

pub fn add_at( &mut self, document: usize, pointer: &JsonPointer, value: &YamlFragment, ) -> Result<(), YamlEditError>

Applies RFC 6902 add semantics at a JSON Pointer destination.

§Errors

Returns an error when the document or destination does not exist, the destination cannot accept the value, or the edit cannot be emitted.

Source

pub fn remove_at( &mut self, document: usize, pointer: &JsonPointer, ) -> Result<(), YamlEditError>

Removes an existing value. Removing a document root is unsupported.

§Errors

Returns an error when the document or target does not exist, the target is a document root, or removing it would invalidate the document.

Source

pub fn replace_at( &mut self, document: usize, pointer: &JsonPointer, value: &YamlFragment, ) -> Result<(), YamlEditError>

Replaces an existing value while preserving its surrounding syntax.

§Errors

Returns an error when the document or target does not exist or the replacement cannot be emitted at that location.

Source

pub fn move_at( &mut self, document: usize, from: &JsonPointer, path: &JsonPointer, ) -> Result<(), YamlEditError>

Moves a value using RFC 6902 remove-then-add semantics.

§Errors

Returns an error when either pointer is invalid for the document, the move would be recursive, or anchors, aliases, or syntax prevent it.

Source

pub fn copy_at( &mut self, document: usize, from: &JsonPointer, path: &JsonPointer, ) -> Result<(), YamlEditError>

Deep-copies a value using RFC 6902 copy semantics.

§Errors

Returns an error when either pointer is invalid for the document, the source contains an anchor, or the copied value cannot be inserted.

Source

pub fn test_at( &self, document: usize, pointer: &JsonPointer, value: &YamlFragment, ) -> Result<bool, YamlEditError>

Compares a pointer-selected target with a YAML value.

§Errors

Returns an error when the document or target does not exist or either value cannot be compared using RFC 6902 equality.

Source

pub fn rename_key_at( &mut self, document: usize, pointer: &JsonPointer, new_key: &str, ) -> Result<(), YamlEditError>

Renames the mapping key that owns a pointer-selected value.

The operation is transactional and changes only the key scalar spelling. The pointer must select a mapping member; document roots and sequence elements do not have a key to rename.

§Errors

Returns an error when the pointer does not select a supported string key, the destination key would collide with another mapping member, or the edited document cannot be emitted.

Source

pub fn rename_keys_at( &mut self, document: usize, pointers: &[JsonPointer], new_key: &str, ) -> Result<(), YamlEditError>

Renames the mapping keys that own several pointer-selected values.

Targets are resolved against the original document and duplicate source key nodes are edited once. All collision checks and edits are applied as one transaction. An empty pointer slice succeeds without changing the document.

§Errors

Returns an error when any pointer does not select a supported string key, any affected mapping would contain duplicate final keys, or the edited document cannot be emitted.

Source §