Enum YamlData

pub enum YamlData<'input, Node>
where
    Node: Hash + Eq + From<Self> + AnnotatedNode,
{
    Representation(Cow<'input, str>, ScalarStyle, Option<Tag>),
    Value(Scalar<'input>),
    Sequence(AnnotatedSequence<Node>),
    Mapping(AnnotatedMapping<'input, Node>),
    Alias(usize),
    BadValue,
}

YAML data for nodes that will contain annotations.

If you want a YAML node without annotations, see Yaml. If you want a YAML node with annotations, see types using YamlData such as MarkedYaml

Unlike Yaml which only supports storing data, YamlData allows storing metadata alongside the YAML data. It is unlikely one would build it directly; it is mostly intended to be used, for instance, when parsing a YAML where retrieving markers / comments is relevant.

This definition is recursive. Each annotated node will be a structure storing the annotations and the YAML data. We need to have a distinct enumeration from Yaml because the type for the Array and Mapping variants is dependant on that structure.

If we had written YamlData as:

pub enum YamlData {
  // ...
  Sequence(Vec<Yaml>),
  Mapping(LinkedHashMap<Yaml, Yaml>),
  // ...
}

we would have stored metadata for the root node only. All subsequent nodes would be Yaml, which does not contain any annotation.

Variants

Representation(Cow<'input, str>, ScalarStyle, Option<Tag>)

The raw string from the input.

When the field is left in the Representation variant, methods that rely on the value (e.g.: is_boolean, as_integer, into_floating_point, …) will always return None.

This variant is only meant:

• As an optimization, when lazy-parsing is preferred.
• As a more generic way of handling keys in Mappings (if user-defined key duplication detection is required.

Value(Scalar<'input>)

The resolved value from the representation.

Sequence(AnnotatedSequence<Node>)

YAML sequence, can be accessed as a Vec.

Mapping(AnnotatedMapping<'input, Node>)

YAML mapping, can be accessed as a LinkedHashMap.

Iteration order will match the order of insertion into the map and that of the document.

If keys use the Representation variant, equality will be based on their representation. When comparing representations for equality, the string, scalar style and tags must match. This means that '100' and "100", although similar in their value, have different representations.

If keys use the Value variant, they will be compared by value. It is discouraged to use floating point values as keys. Scalar uses OrderedFloat for hash and equality. Refer to their documentation for details on float comparisons.

Comparison between Representation variants and Value variants will always fail. Users must ensure all keys in a map are of the same variant, as well as the query keys.

For complex keys, the Mapping and Sequence variants are compared for equality. Both these comparisons are sensitive to the order of insertions. For instance, in the following mapping, the two complex keys are considered different:

? { a: b, c: d }: foo
? { c: d, a: b }: bar

Alias(usize)

Alias, not fully supported yet.

BadValue

A variant used when parsing the representation of a scalar node fails.

The YAML is syntactically valid, but its contents are incoherent. See Scalar::parse_from_cow_and_metadata for details. This variant is also used when stealing the contents of self, meaning self should no longer be used. See Self::take for details

Implementations

impl<'input, Node> YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode + for<'a> PartialEq<Node::HashKey<'a>>,

pub fn as_bool(&self) -> Option<bool>

Get a copy of the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some($t) with a copy of the $t contained. Otherwise, return None.

pub fn as_integer(&self) -> Option<i64>

Get a copy of the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some($t) with a copy of the $t contained. Otherwise, return None.

pub fn as_floating_point(&self) -> Option<f64>

Get a copy of the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some($t) with a copy of the $t contained. Otherwise, return None.

pub fn as_str(&self) -> Option<&str>

Get a reference to the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some(&$t) with the $t contained. Otherwise, return None.

pub fn as_bool_mut(&mut self) -> Option<&mut bool>

Get a mutable reference to the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some(&mut $t) with the $t contained. Otherwise, return None.

pub fn as_integer_mut(&mut self) -> Option<&mut i64>

Get a mutable reference to the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some(&mut $t) with the $t contained. Otherwise, return None.

pub fn as_floating_point_mut(&mut self) -> Option<&mut f64>

Get a mutable reference to the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some(&mut $t) with the $t contained. Otherwise, return None.

pub fn into_bool(self) -> Option<bool>

Get the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some($t) with the $t contained. Otherwise, return None.

pub fn into_integer(self) -> Option<i64>

Get the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some($t) with the $t contained. Otherwise, return None.

pub fn into_floating_point(self) -> Option<f64>

Get the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some($t) with the $t contained. Otherwise, return None.

pub fn into_string(self) -> Option<String>

Get the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some($t) with the $t contained. Otherwise, return None.

pub fn as_mapping(&self) -> Option<&AnnotatedMapping<'input, Node>>

Get a reference to the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some(&$t) with the $t contained. Otherwise, return None.

pub fn as_sequence(&self) -> Option<&AnnotatedSequence<Node>>

Get a reference to the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some(&$t) with the $t contained. Otherwise, return None.

pub fn as_vec(&self) -> Option<&AnnotatedSequence<Node>>

Get a reference to the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some(&$t) with the $t contained. Otherwise, return None.

pub fn as_mapping_mut(&mut self) -> Option<&mut AnnotatedMapping<'input, Node>>

Get a mutable reference to the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some(&mut $t) with the $t contained. Otherwise, return None.

pub fn as_sequence_mut(&mut self) -> Option<&mut AnnotatedSequence<Node>>

Get a mutable reference to the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some(&mut $t) with the $t contained. Otherwise, return None.

pub fn as_vec_mut(&mut self) -> Option<&mut AnnotatedSequence<Node>>

Get a mutable reference to the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some(&mut $t) with the $t contained. Otherwise, return None.

pub fn into_mapping(self) -> Option<AnnotatedMapping<'input, Node>>

Get the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some($t) with the $t contained. Otherwise, return None.

pub fn into_vec(self) -> Option<AnnotatedSequence<Node>>

Get the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some($t) with the $t contained. Otherwise, return None.

pub fn into_sequence(self) -> Option<AnnotatedSequence<Node>>

Get the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some($t) with the $t contained. Otherwise, return None.

pub fn is_boolean(&self) -> bool

Check whether the YAML enum contains the given variant.

Return

If the variant of self is Self::$variant, return true. Otherwise, return false.

pub fn is_integer(&self) -> bool

Check whether the YAML enum contains the given variant.

Return

If the variant of self is Self::$variant, return true. Otherwise, return false.

pub fn is_null(&self) -> bool

Check whether the YAML enum contains the given variant.

Return

If the variant of self is Self::$variant, return true. Otherwise, return false.

pub fn is_floating_point(&self) -> bool

Check whether the YAML enum contains the given variant.

Return

If the variant of self is Self::$variant, return true. Otherwise, return false.

pub fn is_string(&self) -> bool

Check whether the YAML enum contains the given variant.

Return

If the variant of self is Self::$variant, return true. Otherwise, return false.

pub fn is_sequence(&self) -> bool

Check whether the YAML enum contains the given variant.

Return

If the variant of self is Self::$variant, return true. Otherwise, return false.

pub fn is_badvalue(&self) -> bool

Check whether the YAML enum contains the given variant.

Return

If the variant of self is Self::$variant, return true. Otherwise, return false.

pub fn is_mapping(&self) -> bool

Check whether the YAML enum contains the given variant.

Return

If the variant of self is Self::$variant, return true. Otherwise, return false.

pub fn is_alias(&self) -> bool

Check whether the YAML enum contains the given variant.

Return

If the variant of self is Self::$variant, return true. Otherwise, return false.

pub fn is_representation(&self) -> bool

Check whether the YAML enum contains the given variant.

Return

If the variant of self is Self::$variant, return true. Otherwise, return false.

pub fn is_value(&self) -> bool

Check whether the YAML enum contains the given variant.

Return

If the variant of self is Self::$variant, return true. Otherwise, return false.

pub fn parse_representation(&mut self) -> bool

If self is of the Self::Representation variant, parse it to the value.

If self was Self::Value, Self::Sequence, Self::Mapping or Self::Alias upon calling, this function does nothing and returns true.

If parsing fails, *self is assigned Self::BadValue.

Return

Returns true if self is successfully parsed, false otherwise.

pub fn parse_representation_recursive(&mut self) -> bool

Call Self::parse_representation on self and children nodes.

If self was Self::Value or Self::Alias upon calling, this function does nothing and returns true.

If Self::parse_representation fails on a descendent node, this function will not short circuit but still attempt to call Self::parse_representation on further nodes. Even if all further nodes succeed, this function will still return false.

Return

Returns true if all self and its children are successfully parsed, false otherwise.

pub fn or(self, other: Self) -> Self

If a value is null or otherwise bad (see variants), consume it and replace it with a given value other. Otherwise, return self unchanged.

assert_eq!(
    Yaml::Value(Scalar::Null).or(Yaml::Value(Scalar::Integer(3))),
    Yaml::Value(Scalar::Integer(3))
);
assert_eq!(
    Yaml::Value(Scalar::Integer(3)).or(Yaml::Value(Scalar::Integer(7))),
    Yaml::Value(Scalar::Integer(3))
);

pub fn borrowed_or<'a>(&'a self, other: &'a Self) -> &'a Self

See Self::or for behavior.

This performs the same operations, but with borrowed values for less linear pipelines.

pub fn contains_mapping_key(&self, key: &str) -> bool

Check whether self is a Self::Mapping and that it contains the given key.

This is equivalent to:

matches!(self, Self::Mapping(ref x) if x.contains_key(&Yaml::<'_>::String(key.into())))

Return

If the variant of self is Self::Mapping and the mapping contains the key, returns true. Otherwise, returns false.

pub fn as_mapping_get(&self, key: &str) -> Option<&Node>

Return the value associated to the given key if self is a Self::Mapping.

This is equivalent to:

self.as_mapping().and_then(|mapping| mapping.get(key))

Return

If the variant of self is Self::Mapping and the mapping contains the key, returns the value associated with it. Otherwise, returns None.

pub fn as_mapping_get_mut(&mut self, key: &str) -> Option<&mut Node>

Return the value associated to the given key if self is a Self::Mapping.

This is equivalent to:

self.as_mapping_mut().and_then(|mapping| mapping.get_mut(key))

Return

If the variant of self is Self::Mapping and the mapping contains the key, returns the value associated with it. Otherwise, returns None.

pub fn as_sequence_get(&self, idx: usize) -> Option<&Node>

Return the value at the given index if self is a Self::Sequence.

This is equivalent to:

self.as_sequence().and_then(|seq| seq.get(idx))

Return

If the variant of self is Self::Sequence and the index is not out of bounds, returns the value at the given index. Otherwise, returns None.

pub fn as_sequence_get_mut(&mut self, idx: usize) -> Option<&mut Node>

Return the value at the given index if self is a Self::Sequence.

This is equivalent to:

self.as_sequence_mut().and_then(|seq| seq.get_mut(idx))

Return

If the variant of self is Self::Sequence and the index is not out of bounds, returns the value at the given index. Otherwise, returns None.

impl<'input, Node> YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode + for<'a> PartialEq<Node::HashKey<'a>>,

pub fn as_cow(&self) -> Option<&Cow<'input, str>>

Get a reference to the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some(&$t) with the $t contained. Otherwise, return None.

pub fn as_cow_mut(&mut self) -> Option<&mut Cow<'input, str>>

Get a mutable reference to the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some(&mut $t) with the $t contained. Otherwise, return None.

pub fn into_cow(self) -> Option<Cow<'input, str>>

Get the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some($t) with the $t contained. Otherwise, return None.

pub fn as_str_mut(&mut self) -> Option<&mut str>

Get a mutable reference to the inner object in the YAML enum if it is a $t.

Return

If the variant of self is Self::$variant, return Some(&mut $t) with the $t contained. Otherwise, return None.

pub fn value_from_str(v: &'input str) -> Self

Convert a string to a scalar node.

YAML nodes do not implement std::str::FromStr since the trait requires that conversion does not fail. This function attempts to parse the given string as a scalar node, falling back to a Scalar::String.

Note: This attempts to resolve the content as a scalar node. This means that "a: b" gets resolved to Self::Value(Scalar::String("a: b")) and not a mapping. If you want to parse a YAML document, use load_from_str.

Examples

assert!(matches!(Yaml::value_from_str("42"),   Yaml::Value(Scalar::Integer(42))));
assert!(matches!(Yaml::value_from_str("0x2A"), Yaml::Value(Scalar::Integer(42))));
assert!(matches!(Yaml::value_from_str("0o52"), Yaml::Value(Scalar::Integer(42))));
assert!(matches!(Yaml::value_from_str("~"),    Yaml::Value(Scalar::Null)));
assert!(matches!(Yaml::value_from_str("null"), Yaml::Value(Scalar::Null)));
assert!(matches!(Yaml::value_from_str("true"), Yaml::Value(Scalar::Boolean(true))));
assert!(matches!(Yaml::value_from_str("3.14"), Yaml::Value(Scalar::FloatingPoint(_))));
assert!(matches!(Yaml::value_from_str("foo"),  Yaml::Value(Scalar::String(_))));

pub fn scalar_from_string(v: String) -> Self

Same as Self::value_from_str but uses a String instead.

pub fn value_from_cow(v: Cow<'input, str>) -> Self

Same as Self::value_from_str but uses a Cow instead.

pub fn value_from_cow_and_metadata( v: Cow<'input, str>, style: ScalarStyle, tag: Option<&Tag>, ) -> Self

Convert a string to a scalar node, abiding by the given metadata.

The variant returned by this function will always be a Self::Value, unless the tag forces a particular type and the representation cannot be parsed as this type, in which case it returns a Self::BadValue.

impl<'input, Node> YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode + for<'a> PartialEq<Node::HashKey<'a>>,

pub fn take(&mut self) -> Self

Take the contained node out of Self, leaving a BadValue in its place.

Trait Implementations

impl<'input, Node> Clone for YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode + Clone,

fn clone(&self) -> YamlData<'input, Node>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'input, Node> Debug for YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> From<YamlData<'a, MarkedYaml<'a>>> for MarkedYaml<'a>

fn from(value: YamlData<'a, MarkedYaml<'a>>) -> Self

Converts to this type from the input type.

impl<'input, Node> Hash for YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode + Hash,

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'key, 'input, Node> Index<&'key str> for YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode + for<'a> PartialEq<Node::HashKey<'a>>,

fn index(&self, idx: &'key str) -> &Node

Perform indexing if self is a mapping.

Panics

This function panics if the key given does not exist within self (as per Index).

This function also panics if self is not a [$t::Mapping].

type Output = Node

The returned type after indexing.

impl<'input, Node> Index<usize> for YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode + for<'a> PartialEq<Node::HashKey<'a>>,

fn index(&self, idx: usize) -> &Node

Perform indexing if self is a sequence or a mapping.

Panics

This function panics if the index given is out of range (as per Index). If self is a [$t::Sequence], this is when the index is bigger or equal to the length of the underlying Vec. If self is a [$t::Mapping], this is when the mapping sequence does not contain Scalar::Integer(idx) as a key.

This function also panics if self is not a [$t::Sequence] nor a [$t::Mapping].

type Output = Node

The returned type after indexing.

impl<'key, 'input, Node> IndexMut<&'key str> for YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode + for<'a> PartialEq<Node::HashKey<'a>>,

fn index_mut(&mut self, idx: &'key str) -> &mut Node

Perform indexing if self is a mapping.

Panics

This function panics if the key given does not exist within self (as per Index).

This function also panics if self is not a [$t::Mapping].

impl<'input, Node> IndexMut<usize> for YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode + for<'a> PartialEq<Node::HashKey<'a>>,

fn index_mut(&mut self, idx: usize) -> &mut Node

Perform indexing if self is a sequence or a mapping.

Panics

This function panics if the index given is out of range (as per IndexMut). If self is a [$t::Sequence], this is when the index is bigger or equal to the length of the underlying Vec. If self is a [$t::Mapping], this is when the mapping sequence does not contain Scalar::Integer(idx) as a key.

This function also panics if self is not a [$t::Sequence] nor a [$t::Mapping].

impl<'input, Node> IntoIterator for YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode + for<'a> PartialEq<Node::HashKey<'a>>,

type Item = Node

The type of the elements being iterated over.

type IntoIter = AnnotatedYamlIter<'input, Node>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'input, Node> Ord for YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode + Ord,

fn cmp(&self, other: &YamlData<'input, Node>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<'input, Node> PartialEq for YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode + PartialEq,

fn eq(&self, other: &YamlData<'input, Node>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'input, Node> PartialOrd for YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode + PartialOrd,

fn partial_cmp(&self, other: &YamlData<'input, Node>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'input, Node> Eq for YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode + Eq,

impl<'input, Node> StructuralPartialEq for YamlData<'input, Node>

where Node: Hash + Eq + From<Self> + AnnotatedNode,