Struct YamlFile

Source

pub struct YamlFile(/* private fields */);

Expand description

A YAML file containing one or more documents

Note: This type uses interior mutability through the rowan library. Mutation methods work even when called through &self. See the crate-level documentation for details on the mutability model.

Implementations§

Source §

impl YamlFile

Source

pub fn snapshot(&self) -> Self

Capture an independent snapshot of this YAML file.

The returned value shares the underlying immutable green-node data with self at the time of the call, but lives in its own mutable tree: subsequent mutations to self do not propagate to the snapshot. Pair with Self::tree_eq to detect later mutations.

Source

pub fn tree_eq(&self, other: &Self) -> bool

Returns true iff the syntax trees of self and other are value-equal. An O(1) pointer-identity fast path makes this free for trees that still share state with a recent snapshot().

Source §

impl YamlFile

Source

pub fn new() -> YamlFile

Create a new empty YAML document.

Source

pub fn parse(text: &str) -> Parse<YamlFile>

Parse YAML text, returning a Parse result

Source

pub fn from_path<P: AsRef<Path>>(path: P) -> Result<YamlFile, YamlError>

Parse YAML from a file path

Source

pub fn from_str_relaxed(s: &str) -> (YamlFile, Vec<String>)

Parse YAML text, allowing syntax errors.

Returns the parsed tree even if there are parse errors, along with a list of error messages. This allows for error-resilient tooling that can work with partial or invalid input.

§Example

use yaml_edit::YamlFile;

let (yaml_file, errors) = YamlFile::from_str_relaxed("key: [unclosed");
// Tree is usable even with errors
assert!(!errors.is_empty());
assert!(yaml_file.document().is_some());

Source

pub fn from_path_relaxed<P: AsRef<Path>>( path: P, ) -> Result<(YamlFile, Vec<String>), Error>

Parse YAML from a file path, allowing syntax errors.

Returns the parsed tree even if there are parse errors, along with a list of error messages. I/O errors are still returned as Err.

Source

pub fn read_relaxed<R: Read>(r: R) -> Result<(YamlFile, Vec<String>), Error>

Read YAML from a Read object, allowing syntax errors.

Returns the parsed tree even if there are parse errors, along with a list of error messages. I/O errors are still returned as Err.

Source

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

Get all documents in this YAML file

Source

pub fn comments(&self) -> impl Iterator<Item = Comment>

Iterate over the comments in this file, in source order.

This includes comments inside documents as well as any comments between or outside documents.

§Example

use yaml_edit::YamlFile;
use std::str::FromStr;

let file = YamlFile::from_str("# header\nkey: value # trailing\n").unwrap();
let comments: Vec<_> = file.comments().map(|c| c.content().to_string()).collect();
assert_eq!(comments, vec!["header", "trailing"]);

Source

pub fn document(&self) -> Option<Document>

Get the first document in this YAML file, or None if there are none.

Most YAML files have exactly one document. Use documents to iterate over all documents in a multi-document file.

Source

pub fn ensure_document(&self) -> Document

Ensure this YamlFile contains at least one document, creating an empty mapping document if needed.

Returns the first document.

Source

pub fn directives(&self) -> impl Iterator<Item = Directive>

Iterate over all YAML directives (e.g. %YAML 1.2) in this file.

Source

pub fn add_directive(&self, directive_text: &str)

Prepend a YAML directive to this file.

directive_text should be the full directive line without a trailing newline, e.g. "%YAML 1.2" or "%TAG ! tag:example.com,2000:app/". The directive is inserted before all existing content.

Note: the parser does not currently enforce that directives appear before any document node; callers are responsible for ordering.

Source

pub fn push_document(&self, document: Document)

Add a new document to the end of this YAML file

Source

pub fn set(&self, key: impl AsYaml, value: impl AsYaml)

Set a key-value pair in the first document’s mapping.

If the key exists its value is replaced; if not, a new entry is appended. Does nothing if the YamlFile contains no documents or the first document is not a mapping. Use ensure_document first if you need to guarantee a document exists.