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, 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)]
60#![deny(missing_docs)]
61#![cfg_attr(docsrs, feature(doc_cfg))]
62
63pub mod loader;
64pub mod types;
65
66#[doc(inline)]
67pub use loader::{parse_yaml, parse_yaml_with_options, LoadError, LoaderOptions};
68#[doc(inline)]
69pub use types::{Marker, Node, Span};
70
71#[cfg(feature = "serde")]
72#[doc(hidden)]
73pub mod spanned_serde;
74
75#[cfg(feature = "serde")]
76#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
77#[doc(inline)]
78pub use spanned_serde::{
79    from_node, from_yaml, from_yaml_with_options, Error, FromNodeError, FromYamlError, Spanned,
80};