1# yaml-rust 2 3The missing YAML 1.2 implementation for Rust. 4 5[![Travis](https://travis-ci.org/chyh1990/yaml-rust.svg?branch=master)](https://travis-ci.org/chyh1990/yaml-rust) 6[![AppVeyor](https://ci.appveyor.com/api/projects/status/scf47535ckp4ylg4?svg=true)](https://ci.appveyor.com/project/chyh1990/yaml-rust) 7[![crates.io](https://img.shields.io/crates/v/yaml-rust.svg)](https://crates.io/crates/yaml-rust) 8[![docs.rs](https://img.shields.io/badge/api-rustdoc-blue.svg)](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