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 root(&self) -> Feature<'_>

Returns a Feature for this document’s root node.

This is typically useful as a “fallback” feature, e.g. for capturing a span of the entire document.

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, query: &Query<'_>) -> bool

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

All errors become false.

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

Perform a query on the current document, returning a Feature if the query 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 query result.

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

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

Perform a query on the current document, returning a Feature if the query succeeds. Returns None if the query 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 query result.

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

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

Perform a query on the current document, returning a Feature if the query 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 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<&'tree str>

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