marked_yaml/
lib.rs

1//! Marked YAML
2//! ===========
3//!
4//! Currently this library only supports parsing YAML from strings,
5//! but this is sufficient for most users' purposes.  We would not
6//! recommend an un-streamed processing engine for massive data anyway.
7//!
8//! To parse some YAML you simply need to:
9//!
10//! ```
11//! let node = marked_yaml::parse_yaml(0, r#"
12//! toplevel: must be a mapping
13//! but:
14//!  - it
15//!  - may
16//!  - contain lists
17//! and:
18//!  mappings: are permitted
19//!  as: sub-mappings
20//! "#);
21//! assert!(node.is_ok());
22//! ```
23//!
24//! Parsing a valid YAML string may fail because `marked_yaml` adds some
25//! additional constraints:
26//!
27//! * The top level of the YAML **MUST** be a mapping or a sequence.
28//! * Mapping keys **MUST** be scalars (strings).
29//! * Aliases and anchors **MAY NOT** be used (though this limit may be lifted in the future).
30//!
31//! In addition, you can convert between `marked_yaml::Node` and `yaml_rust::Yaml`
32//! though doing so will not give you any useful markers.
33#![cfg_attr(
34    feature = "serde",
35    doc = r#"
36## Serde
37
38Should you so choose, you may use serde to deserialise YAML
39strings directly into structures, any amount of which could be annotated
40with the [`Spanned`] type to capture information about where the value came
41from in the input.
42
43```
44# use marked_yaml::{from_yaml, Marker, Spanned};
45# use std::collections::HashMap;
46let YAML = "Daniel: Author\nUser: Not Author\n";
47let roles: HashMap<Spanned<String>, Spanned<String>> = from_yaml(0, YAML).unwrap();
48
49assert_eq!(roles["Daniel"], "Author");
50assert_eq!(roles["User"].span().start().copied(), Some(Marker::new(0, 21, 2, 7)));
51```
52
53You do not have to have all values [`Spanned`], and you can deserialize from an already
54parsed set of nodes with [`from_node`] instead.
55
56Empty scalars can be deserialized to empty sequences, maps, the unit type `()`
57and structs with a `#[serde(default)]` attribute.
58
59### Error spans and paths
60
61If you want to have the error spans populated, along with string-form paths to
62errors in your YAML, then you can use the `serde-path` feature.
63"#
64)]
65#![deny(missing_docs)]
66#![cfg_attr(docsrs, feature(doc_cfg))]
67
68pub mod loader;
69pub mod types;
70
71#[doc(inline)]
72pub use loader::{parse_yaml, parse_yaml_with_options, LoadError, LoaderOptions};
73#[doc(inline)]
74pub use types::{Marker, Node, Span};
75
76#[cfg(feature = "serde")]
77#[doc(hidden)]
78pub mod spanned_serde;
79
80#[cfg(feature = "serde")]
81#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
82#[doc(inline)]
83pub use spanned_serde::{
84    from_node, from_yaml, from_yaml_with_options, Error, FromNodeError, FromYamlError, Spanned,
85};
marked_yaml/lib.rs

marked_yaml/
lib.rs
