Struct Document 

pub struct Document { /* private fields */ }

Represents a queryable YAML document.

Implementations

impl Document

pub fn new(source: impl Into<String>) -> Result<Self, QueryError>

Construct a new Document from the given YAML.

pub fn line_index(&self) -> &LineIndex

Returns a LineIndex for this document, which can be used to efficiently map between byte offsets and line coordinates.

pub fn source(&self) -> &str

Return a view of the original YAML source that this document was loaded from.

pub fn top_feature(&self) -> Result<Feature<'_>, QueryError>

Returns a Feature for the topmost semantic object in this document.

This is typically useful as a “fallback” feature, e.g. for positioning relative to the “top” of the document.

pub fn range_spanned_by_comment(&self, start: usize, end: usize) -> bool

Returns whether the given range is spanned by a comment node.

The comment node must fully span the range; a range that ends after the comment or starts before it will not be considered spanned.

pub fn offset_inside_comment(&self, offset: usize) -> bool

Returns whether the given offset is within a comment node’s span.

pub fn query_exists(&self, route: &Route<'_>) -> bool

Perform a route on the current document, returning true if the route succeeds (i.e. references an existing feature).

All errors become false.

pub fn query_pretty(&self, route: &Route<'_>) -> Result<Feature<'_>, QueryError>

Perform a route on the current document, returning a Feature if the route succeeds.

The feature is extracted in “pretty” mode, meaning that it’ll contain a subjectively relevant “pretty” span rather than the exact span of the route result.

For example, querying foo: bar for foo will return foo: bar instead of just bar.

pub fn query_exact( &self, route: &Route<'_>, ) -> Result<Option<Feature<'_>>, QueryError>

Perform a route on the current document, returning a Feature if the route succeeds. Returns None if the route succeeds, but matches an absent value (e.g. foo:).

The feature is extracted in “exact” mode, meaning that it’ll contain the exact span of the route result.

For example, querying foo: bar for foo will return just bar instead of foo: bar.

pub fn query_key_only( &self, route: &Route<'_>, ) -> Result<Feature<'_>, QueryError>

Perform a route on the current document, returning a Feature if the route succeeds.

The feature is extracted in “key only” mode, meaning that it’ll contain only the key of a mapping, rather than the key and value (“pretty”) or just the value (“exact”).

For example, querying foo: bar for foo will return just foo instead of foo: bar or bar.

pub fn removal_span( &self, route: &Route<'_>, ) -> Result<Range<usize>, QueryError>

Computes the byte range that should be deleted from the document’s Self::source in order to remove the value at route, together with the structural “affixes” appropriate to the value’s container.

This is aware of the value’s container kind as determined by the parse tree.

The affixes removed depend on the container:

• In block mappings and sequences, the value’s entire line (or lines, for multi-line values) is removed, including leading indentation, any trailing same-line comment, and the trailing newline.
• In flow mappings and sequences, the value is removed along with a single adjacent comma (the following one if present, otherwise the preceding one) and any whitespace separating it from its neighbor, so the surrounding flow collection stays well-formed. A sole remaining member collapses cleanly to {} or [].

The element is resolved at its own lexical site: a final alias is not followed, so removing b from {a: &x 1, b: *x} deletes b: *x rather than the anchor definition it points to.

When removing the sole member of a block container would leave a dangling null parent (e.g. removing the only key under env: would leave env: with a null value), the enclosing element is removed instead, repeating upward. Flow containers are left as explicit {}/[], which are valid, so they are not collapsed.

The returned range is a half-open [start, end) byte range into Self::source.

pub fn extract(&self, feature: &Feature<'_>) -> &str

Returns a string slice of the original document corresponding to the given Feature.

This function returns a slice corresponding to the Feature’s exact span, meaning that leading whitespace for the start point is not necessarily captured. See Self::extract_with_leading_whitespace for feature extraction with rudimentary whitespace handling.

Panics if the feature’s span is invalid.

pub fn extract_with_leading_whitespace<'a>( &'a self, feature: &Feature<'_>, ) -> &'a str

Returns a string slice of the original document corresponding to the given Feature, along with any leading (indentation-semantic) whitespace.

Important: The returned string here can be longer than the span identified in the Feature. In particular, this API will return a longer string if it identifies leading non-newline whitespace ahead of the captured Feature, since this indicates indentation not encapsulated by the feature itself.

Panics if the feature’s span is invalid.

pub fn feature_comments<'tree>( &'tree self, feature: &Feature<'tree>, ) -> Vec<Feature<'tree>>

Given a Feature, return all comments that span the same range as the feature does.

pub fn has_anchors(&self) -> bool

Returns whether this document contains any YAML anchors.

Trait Implementations

impl Clone for Document

fn clone(&self) -> Document

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.