README.md
1# yaml-rust
2
3The missing YAML 1.2 implementation for Rust.
4
5[](https://travis-ci.org/chyh1990/yaml-rust)
6[](https://ci.appveyor.com/project/chyh1990/yaml-rust)
7[](https://crates.io/crates/yaml-rust)
8[](https://docs.rs/yaml-rust)
9
10`yaml-rust` is a pure Rust YAML 1.2 implementation,
11which enjoys the memory safety
12property and other benefits from the Rust language.
13The parser is heavily influenced by `libyaml` and `yaml-cpp`.
14
15## Quick Start
16
17Add the following to the Cargo.toml of your project:
18
19```toml
20[dependencies]
21yaml-rust = "0.4"
22```
23
24and import:
25
26```rust
27extern crate yaml_rust;
28```
29
30Use `yaml::YamlLoader` to load the YAML documents and access it
31as Vec/HashMap:
32
33```rust
34extern crate yaml_rust;
35use yaml_rust::{YamlLoader, YamlEmitter};
36
37fn main() {
38 let s =
39"
40foo:
41 - list1
42 - list2
43bar:
44 - 1
45 - 2.0
46";
47 let docs = YamlLoader::load_from_str(s).unwrap();
48
49 // Multi document support, doc is a yaml::Yaml
50 let doc = &docs[0];
51
52 // Debug support
53 println!("{:?}", doc);
54
55 // Index access for map & array
56 assert_eq!(doc["foo"][0].as_str().unwrap(), "list1");
57 assert_eq!(doc["bar"][1].as_f64().unwrap(), 2.0);
58
59 // Chained key/array access is checked and won't panic,
60 // return BadValue if they are not exist.
61 assert!(doc["INVALID_KEY"][100].is_badvalue());
62
63 // Dump the YAML object
64 let mut out_str = String::new();
65 {
66 let mut emitter = YamlEmitter::new(&mut out_str);
67 emitter.dump(doc).unwrap(); // dump the YAML object to a String
68 }
69 println!("{}", out_str);
70}
71```
72
73Note that `yaml_rust::Yaml` implements `Index<&'a str>` & `Index<usize>`:
74
75* `Index<usize>` assumes the container is an Array
76* `Index<&'a str>` assumes the container is a string to value Map
77* otherwise, `Yaml::BadValue` is returned
78
79If your document does not conform to this convention (e.g. map with
80complex type key), you can use the `Yaml::as_XXX` family API to access your
81documents.
82
83## Features
84
85* Pure Rust
86* Ruby-like Array/Hash access API
87* Low-level YAML events emission
88
89## Specification Compliance
90
91This implementation aims to provide YAML parser fully compatible with
92the YAML 1.2 specification. The parser can correctly parse almost all
93examples in the specification, except for the following known bugs:
94
95* Empty plain scalar in certain contexts
96
97However, the widely used library `libyaml` also fails to parse these examples,
98so it may not be a huge problem for most users.
99
100## Goals
101
102* Encoder
103* Tag directive
104* Alias while deserialization
105
106## Minimum Rust version policy
107
108This crate's minimum supported `rustc` version is 1.31 (released with Rust 2018, after v0.4.3), as this is the currently known minimum version for [`regex`](https://crates.io/crates/regex#minimum-rust-version-policy) as well.
109
110## License
111
112Licensed under either of
113
114 * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
115 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
116
117at your option.
118
119## Contribution
120
121Fork & PR on Github.
122
123Unless you explicitly state otherwise, any contribution intentionally submitted
124for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
125additional terms or conditions.
126
){kind=link}
){kind=link}
){kind=link}