Crate saphyr

Expand description

YAML 1.2 implementation in pure Rust.

§Usage

This crate is on github and can be used by adding saphyr to the dependencies in your project’s Cargo.toml:

cargo add saphyr

§Examples

Parse a string into Vec<Yaml> and then serialize it as a YAML string.

use saphyr::{LoadableYamlNode, Yaml, YamlEmitter};

let docs = Yaml::load_from_str("[1, 2, 3]").unwrap();
let doc = &docs[0]; // select the first YAML document
assert_eq!(doc[0].as_integer().unwrap(), 1); // access elements by index

let mut out_str = String::new();
let mut emitter = YamlEmitter::new(&mut out_str);
emitter.dump(doc).unwrap(); // dump the YAML object to a String

§YAML object types

There are multiple YAML objects in this library which share most features but differ in usecase:

Yaml: The go-to YAML object. It contains YAML data and borrows from the input.
YamlOwned: An owned version of Yaml. It does not borrow from the input and can be used when tieing the object to the input is undesireable or would introduce unnecessary lifetimes.
MarkedYaml: A YAML object with added Markers for the beginning and end of the YAML object in the input.
MarkedYamlOwned: An owned version of MarkedYaml. It does not borrow from the input and can be used when tieing the object to the input is undesireable or would introduce unnecessary lifetimes.

All of these share the same inspection methods (is_boolean, as_str, into_vec, …) with some variants between owned and borrowing versions.

They also contain the same variants. Yaml and YamlOwned are enums, while annotated objects (MarkedYaml, MarkedYamlOwned) are structures with a .data enum (see YamlData, YamlDataOwned).

§YAML Tags

§YAML Core Schema tags (`!!str`, `!!int`, `!!float`, …)

saphyr is aware of the YAML Core Schema tags and will parse scalars accordingly. This is handled in Scalar::parse_from_cow_and_metadata. Should a scalar be explicitly tagged with a tag whose handle is that of the Core Schema, saphyr will attempt to parse it as the given type. If parsing fails (e.g.: !!int foo), a BadValue will be returned. If however the tag is unknown, the scalar will be parsed as a string (e.g.: !!unk 12).

Core Schema tags on collections are ignored, since the syntax disallows any ambiguity in parsing.

Upon parsing, the core schema tags are not preserved. If you need the tags on scalar preserved, you may disable early_parse. This will cause all scalars to use the Representation variant which preserves the tags. There is currently no way to preserve Core Schema tags on collections.

§User-defined tags

The YAML specification does not explicitly specify how user-defined tags should be parsed (10.4). saphyr is very conservative on this and will leave tags as-is. They are wrapped in a Tagged variant where you can freely inspect the tag alongside the tagged node.

The tagged node will be parsed as an untagged node. What this means is that 13 will be parsed as an integer, foo as a string, … etc. See the related discussion on Github for more context on the decision.

Examples:

assert!(matches!(parse("!custom 3"),     Yaml::Tagged(_tag, node) if node.is_integer()));
assert!(matches!(parse("!custom 'foo'"), Yaml::Tagged(_tag, node) if node.is_string()));
assert!(matches!(parse("!custom foo"),   Yaml::Tagged(_tag, node) if node.is_string()));
assert!(matches!(parse("!custom ~"),     Yaml::Tagged(_tag, node) if node.is_null()));
assert!(matches!(parse("!custom '3'"),   Yaml::Tagged(_tag, node) if node.is_string()));

User-defined tags can be applied to any node, whether a collection or a scalar. They do not change the resolution behavior of inner nodes.

assert!(matches!(parse("!custom [foo]"),     Yaml::Tagged(_tag, node) if node.is_sequence()));
assert!(matches!(parse("!custom {a:b}"),     Yaml::Tagged(_tag, node) if node.is_mapping()));

let node = parse("!custom [1, foo, !!str 3, !custom 3]");
let Yaml::Tagged(_, seq) = node else { panic!() };
assert!(seq.is_sequence());
assert!(seq[0].is_integer());
assert!(seq[1].is_string());
assert!(seq[2].is_string());
assert!(matches!(&seq[3], Yaml::Tagged(_tag, node) if node.is_integer()));

§Features

Note: With all features disabled, this crate’s MSRV is 1.65.0.

§`encoding` (enabled by default)

Enables encoding-aware decoding of Yaml documents.

The MSRV for this feature is 1.70.0.

Structs§

AnnotatedYamlIter: An iterator over a YamlData node.
MarkedYaml: A YAML node with Spans pointing to the start of the node.
MarkedYamlOwned: A YAML node with Spans pointing to the start of the node.
Marker: A location in a yaml document.
ScanError: An error that occurred while scanning.
Tag: A YAML tag.
YamlDecoder: A YamlLoader builder that allows you to supply your own encoding error trap.
YamlEmitter: The YAML serializer.
YamlIter: An iterator over a Yaml node.
YamlLoader: Main structure for parsing YAML.
YamlOwnedIter: An iterator over a YamlOwned node.

Enums§

EmitError: An error when emitting YAML.
LoadError: An error that happened when loading a YAML document.
Scalar: The resolved value of a scalar YAML node.
ScalarOwned: The resolved value of a scalar YAML node, freed from borrowing.
ScalarStyle: The style as which the scalar was written in the YAML document.
YAMLDecodingTrap: The behavior YamlDecoder must have when an decoding error occurs.
Yaml: A YAML node is stored as this Yaml enumeration, which provides an easy way to access your YAML document.
YamlData: YAML data for nodes that will contain annotations.
YamlDataOwned: YAML data for nodes that will contain annotations.
YamlOwned: A YAML node is stored as this Yaml enumeration, which provides an easy way to access your YAML document.

Traits§

AnnotatedNode: A trait allowing for introspection in the hash types of the YamlData::Mapping variant.
AnnotatedNodeOwned: A trait allowing for introspection in the hash types of the YamlData::Mapping variant.
LoadableYamlNode: A trait providing methods used by the YamlLoader.

Functions§

parse_core_schema_fp: Parse the given string as a floating point according to the core schema.

Type Aliases§

AnnotatedMapping: The type contained in the YamlData::Mapping variant. This corresponds to YAML mappings.
AnnotatedSequence: The type contained in the YamlData::Sequence variant. This corresponds to YAML sequences.
Mapping: The type contained in the Yaml::Mapping variant.
MappingOwned: The type contained in the YamlOwned::Mapping variant.
Sequence: The type contained in the Yaml::Sequence variant.
SequenceOwned: The type contained in the YamlOwned::Sequence variant.
YAMLDecodingTrapFn: The signature of the function to call when using YAMLDecodingTrap::Call.

Crate saphyrCopy item path