Trait YamlPath 

pub trait YamlPath {
    // Required methods
    fn try_get_path_with(
        &self,
        path: &str,
        policy: AliasPolicy,
    ) -> Result<YamlNode, PathError>;
    fn try_set_path_with(
        &self,
        path: &str,
        value: impl AsYaml,
        policy: AliasPolicy,
    ) -> Result<(), PathError>;
    fn try_remove_path_with(
        &self,
        path: &str,
        policy: AliasPolicy,
    ) -> Result<YamlNode, PathError>;

    // Provided methods
    fn try_get_path(&self, path: &str) -> Result<YamlNode, PathError> { ... }
    fn try_set_path(
        &self,
        path: &str,
        value: impl AsYaml,
    ) -> Result<(), PathError> { ... }
    fn try_remove_path(&self, path: &str) -> Result<YamlNode, PathError> { ... }
    fn get_path(&self, path: &str) -> Option<YamlNode> { ... }
    fn set_path(&self, path: &str, value: impl AsYaml) { ... }
    fn remove_path(&self, path: &str) -> bool { ... }
}

Trait for YAML types that support path-based access.

Path syntax uses dots (.) as separators to navigate nested mappings. For example, "server.database.host" accesses:

server:
  database:
    host: value

A segment names a string key, or failing that the first scalar key of another type written the same way: m.1 reaches 1: one and m.true reaches true: t. Setting a key that does not exist yet creates a string key.

The try_ methods (try_get_path, try_set_path, try_remove_path) return Result<_, PathError> and are the recommended API. The older get_path / set_path / remove_path methods are deprecated wrappers that discard the error and silently no-op.

Required Methods

fn try_get_path_with( &self, path: &str, policy: AliasPolicy, ) -> Result<YamlNode, PathError>

Like try_get_path, but with an explicit AliasPolicy for segments that land on an alias.

Errors

As try_get_path, plus PathError::AliasRefused under AliasPolicy::Refuse and PathError::UndefinedAlias when an alias names an anchor that is not defined in the document.

fn try_set_path_with( &self, path: &str, value: impl AsYaml, policy: AliasPolicy, ) -> Result<(), PathError>

Like try_set_path, but with an explicit AliasPolicy for intermediate segments that land on an alias.

Writing through an alias changes the anchored node, and therefore every other alias that references it; that is why the default is AliasPolicy::Refuse and this opt-in exists.

Errors

As try_set_path, plus PathError::AliasRefused under AliasPolicy::Refuse and PathError::UndefinedAlias when an alias names an anchor that is not defined in the document.

fn try_remove_path_with( &self, path: &str, policy: AliasPolicy, ) -> Result<YamlNode, PathError>

Like try_remove_path, but with an explicit AliasPolicy for intermediate segments that land on an alias.

Removal is a mutation, so it defaults to AliasPolicy::Refuse for the same reason as try_set_path.

Errors

As try_remove_path, plus PathError::AliasRefused and PathError::UndefinedAlias.

Provided Methods

fn try_get_path(&self, path: &str) -> Result<YamlNode, PathError>

Get a value at a nested path, returning a specific PathError on failure instead of None.

A tagged collection (key: !custom over a block mapping, say) is descended into as the collection it wraps; the tag stays put.

Errors

• PathError::Parse for a malformed path.
• PathError::EmptyPath when the path is empty.
• PathError::NoRoot when the receiver has no value to descend into.
• PathError::TypeMismatch when a segment tries to descend into a value of the wrong container type.
• PathError::NotFound when a segment addresses a key/index that does not exist.
• PathError::UndefinedAlias or PathError::InvalidMergeOperand when a key is not found directly and a << merge operand of the mapping is an undefined alias or not a mapping.

fn try_set_path(&self, path: &str, value: impl AsYaml) -> Result<(), PathError>

Set a value at a nested path, creating intermediate mappings / sequences as needed. Returns a specific PathError on failure instead of silently no-oping.

Errors

• PathError::Parse for a malformed path.
• PathError::EmptyPath when the path is empty.
• PathError::NoRoot when the receiver’s root is not a mapping (Document with a scalar or sequence root). A Document with no root gets a root mapping, as with Document::set.
• PathError::TypeMismatch when an intermediate segment lands on a scalar that cannot be turned into a container.

fn try_remove_path(&self, path: &str) -> Result<YamlNode, PathError>

Remove a value at a nested path. Returns the removed YamlNode on success, or a specific PathError describing why the removal did not happen.

One entry is removed. Duplicate keys are legal YAML, so a path can still resolve afterwards; use Mapping::remove_nth_occurrence to choose between them.

Errors

Same shape as try_get_path.

fn get_path(&self, path: &str) -> Option<YamlNode>

👎Deprecated since 0.4.0:

use try_get_path; get_path swallows PathError as None

Get a value at a nested path.

This is a lossy wrapper around try_get_path: every error becomes None, so callers cannot distinguish “path parsed but nothing found” from “path was malformed” or “descended through the wrong container type.”

Examples

use yaml_edit::{Document, path::YamlPath};
use std::str::FromStr;

let yaml = Document::from_str("server:\n  host: localhost\n").unwrap();
#[allow(deprecated)]
let host = yaml.get_path("server.host");
assert_eq!(host.unwrap().to_string(), "localhost");
#[allow(deprecated)]
let missing = yaml.get_path("server..host");
assert!(missing.is_none());

fn set_path(&self, path: &str, value: impl AsYaml)

👎Deprecated since 0.4.0:

use try_set_path; set_path silently ignores PathError

Set a value at a nested path.

Lossy wrapper around try_set_path: every error is silently ignored. Callers get no signal that the write failed (bad path, no root, descending through a scalar, …).

Examples

use yaml_edit::{Document, path::YamlPath};
use std::str::FromStr;

let yaml = Document::from_str("name: test\n").unwrap();
#[allow(deprecated)]
yaml.set_path("server.host", "localhost");
#[allow(deprecated)]
yaml.set_path("server.port", 8080);
assert_eq!(
    yaml.to_string(),
    "name: test\nserver:\n  host: localhost\n  port: 8080\n"
);
// A failed write is not reported.
#[allow(deprecated)]
yaml.set_path("name.first", "x");
assert_eq!(yaml.try_get_path("name").unwrap().to_string(), "test");

fn remove_path(&self, path: &str) -> bool

👎Deprecated since 0.4.0:

use try_remove_path; remove_path swallows PathError as false

Remove a value at a nested path. Returns true if a value was removed.

Lossy wrapper around try_remove_path: every error is reported as false, indistinguishable from “path was well-formed but key not present.”

Examples

use yaml_edit::{Document, path::YamlPath};
use std::str::FromStr;

let yaml = Document::from_str("server:\n  host: localhost\n  port: 8080\n").unwrap();
#[allow(deprecated)]
{
    assert_eq!(yaml.remove_path("server.port"), true);
    assert_eq!(yaml.remove_path("server.missing"), false);
}

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl YamlPath for Document

impl YamlPath for Mapping