yaml_merge_keys/
lib.rs

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
106mod merge_keys;
107#[cfg(feature = "saphyr")]
108mod merge_keys_saphyr;
109#[cfg(feature = "serde_yaml")]
110mod merge_keys_serde_yaml;
111#[cfg(feature = "serde_yml")]
112mod merge_keys_serde_yml;
113
114pub use merge_keys::merge_keys;
115pub use merge_keys::MergeKeyError;
116
117#[cfg(feature = "saphyr")]
118pub use merge_keys_saphyr::merge_keys_saphyr;
119#[cfg(feature = "saphyr")]
120pub use saphyr;
121
122#[cfg(feature = "serde_yaml")]
123pub use merge_keys_serde_yaml::merge_keys_serde;
124#[cfg(feature = "serde_yaml")]
125pub use serde_yaml;
126
127#[cfg(feature = "serde_yml")]
128#[deprecated(
129    since = "0.8.2",
130    note = "The serde_yml crate is unsound (https://github.com/rustsec/advisory-db/pull/2397)"
131)]
132pub use merge_keys_serde_yml::merge_keys_serde_yml;
133#[cfg(feature = "serde_yml")]
134pub use serde_yml;
135
136#[cfg(test)]
137mod test;
138#[cfg(all(test, feature = "saphyr"))]
139mod test_saphyr;
140#[cfg(all(test, feature = "serde_yaml"))]
141mod test_serde_yaml;
142#[cfg(all(test, feature = "serde_yml"))]
143mod test_serde_yml;
yaml_merge_keys/lib.rs

yaml_merge_keys/
lib.rs
