1// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
2// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
3// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
4// option. This file may not be copied, modified, or distributed
5// except according to those terms.
6
7//! YAML Merge Keys
8//!
9//! The YAML Merge Key extension is not supported by the core YAML crate, but can be implemented
10//! after parsing. This crate transforms a parsed YAML document and merges dictionaries together.
11//!
12//! # Usage
13//!
14//! This crate provides a function which implements the [YAML Merge Key extension]. Given a YAML
15//! document from `yaml-rust` (or `serde_yaml` with the `serde_yaml` feature), it will return
16//! a YAML document with the merge keys removed and merged into their owning dictionaries.
17//!
18//! ```rust
19//! # extern crate yaml_rust;
20//! # extern crate yaml_merge_keys;
21//! # #[cfg(feature = "serde_yaml")]
22//! # extern crate serde_yaml;
23//! use yaml_rust::YamlLoader;
24//! use yaml_merge_keys::merge_keys;
25//!
26//! // YAML document contents.
27//! let raw = "\
28//! ref: &ref
29//! merged_key: merged
30//! added_key: merged
31//! dict:
32//! <<: *ref
33//! top_key: given
34//! merged_key: given
35//! ";
36//! let merged = "\
37//! ref:
38//! merged_key: merged
39//! added_key: merged
40//! dict:
41//! top_key: given
42//! merged_key: given
43//! added_key: merged
44//! ";
45//!
46//! // Parse the YAML documents.
47//! let raw_yaml = YamlLoader::load_from_str(raw).unwrap().remove(0);
48//! let merged_yaml = YamlLoader::load_from_str(merged).unwrap().remove(0);
49//!
50//! // Merge the keys.
51//! let merged_keys = merge_keys(raw_yaml).unwrap();
52//!
53//! // The keys have been merged.
54//! assert_eq!(merged_keys, merged_yaml);
55//!
56//! // Using `serde_yaml` is also supported with the feature.
57//! #[cfg(feature = "serde_yaml")]
58//! {
59//! use yaml_merge_keys::merge_keys_serde;
60//!
61//! let raw_yaml = serde_yaml::from_str(raw).unwrap();
62//! let merged_yaml: serde_yaml::Value = serde_yaml::from_str(merged).unwrap();
63//!
64//! let merged_keys = merge_keys_serde(raw_yaml).unwrap();
65//!
66//! assert_eq!(merged_keys, merged_yaml);
67//! }
68//! ```
69//!
70//! [YAML Merge Key extension]: http://yaml.org/type/merge.html
71//!
72//! # Example
73//!
74//! ```yaml
75//! ---
76//! - &CENTER { x: 1, y: 2 }
77//! - &LEFT { x: 0, y: 2 }
78//! - &BIG { r: 10 }
79//! - &SMALL { r: 1 }
80//!
81//! # All the following maps are equal:
82//!
83//! - # Explicit keys
84//! x: 1
85//! y: 2
86//! r: 10
87//! label: center/big
88//!
89//! - # Merge one map
90//! << : *CENTER
91//! r: 10
92//! label: center/big
93//!
94//! - # Merge multiple maps
95//! << : [ *CENTER, *BIG ]
96//! label: center/big
97//!
98//! - # Override
99//! << : [ *BIG, *LEFT, *SMALL ]
100//! x: 1
101//! label: center/big
102//! ```
103
104#![deny(missing_docs)]
105
106#[macro_use]
107extern crate lazy_static;
108
109mod crates {
110 // public
111 #[cfg(feature = "serde_yaml")]
112 pub extern crate serde_yaml;
113 pub extern crate yaml_rust;
114
115 // private
116 pub extern crate thiserror;
117}
118
119mod merge_keys;
120#[cfg(feature = "serde_yaml")]
121mod serde;
122
123pub use merge_keys::merge_keys;
124pub use merge_keys::MergeKeyError;
125#[cfg(feature = "serde_yaml")]
126pub use serde::merge_keys_serde;
127
128#[cfg(test)]
129mod test;
130#[cfg(all(test, feature = "serde_yaml"))]
131mod test_serde;
132