139 lines
3.7 KiB
Markdown
139 lines
3.7 KiB
Markdown
# yaml-rust
|
|
|
|
The missing YAML 1.2 implementation for Rust.
|
|
|
|
[](https://travis-ci.org/chyh1990/yaml-rust)
|
|
[](https://ci.appveyor.com/project/chyh1990/yaml-rust)
|
|
[](https://crates.io/crates/yaml-rust/)
|
|
[](https://crates.io/crates/yaml-rust/)
|
|
|
|
`yaml-rust` is a pure Rust YAML 1.2 implementation without
|
|
any external dependencies, which enjoys the memory safety
|
|
property and other benefits from the Rust language.
|
|
The parser is heavily influenced by `libyaml` and `yaml-cpp`.
|
|
|
|
This crate works on all Rust supported platforms and
|
|
Rust 1.0.0 and nightly!
|
|
|
|
See [Document](http://chyh1990.github.io/yaml-rust/doc/yaml_rust/)
|
|
|
|
> NOTE: This library is still under heavy development.
|
|
|
|
> WARNING: This library needs more tests and it is NOT ready for
|
|
> parsing arbitrary user input from *untrusted source*.
|
|
|
|
## Quick Start
|
|
|
|
Add the following to the Cargo.toml of your project:
|
|
|
|
```toml
|
|
[dependencies]
|
|
yaml-rust = "*"
|
|
```
|
|
|
|
or
|
|
|
|
```toml
|
|
[dependencies.yaml-rust]
|
|
git = "https://github.com/chyh1990/yaml-rust.git"
|
|
```
|
|
|
|
and import using *extern crate*:
|
|
|
|
```rust
|
|
extern crate yaml_rust;
|
|
```
|
|
|
|
Use `yaml::YamlLoader` to load the YAML documents and access it
|
|
as Vec/HashMap:
|
|
|
|
```rust
|
|
extern crate yaml_rust;
|
|
use yaml_rust::{YamlLoader, YamlEmitter};
|
|
|
|
fn main() {
|
|
let s =
|
|
"
|
|
foo:
|
|
- list1
|
|
- list2
|
|
bar:
|
|
- 1
|
|
- 2.0
|
|
";
|
|
let docs = YamlLoader::load_from_str(s).unwrap();
|
|
|
|
// Multi document support, doc is a yaml::Yaml
|
|
let doc = &docs[0];
|
|
|
|
// Debug support
|
|
println!("{:?}", doc);
|
|
|
|
// Index access for map & array
|
|
assert_eq!(doc["foo"][0].as_str().unwrap(), "list1");
|
|
assert_eq!(doc["bar"][1].as_f64().unwrap(), 2.0);
|
|
|
|
// Chained key/array access is checked and won't panic,
|
|
// return BadValue if they are not exist.
|
|
assert!(doc["INVALID_KEY"][100].is_badvalue());
|
|
|
|
// Dump the YAML object
|
|
let mut out_str = String::new();
|
|
{
|
|
let mut emitter = YamlEmitter::new(&mut out_str);
|
|
emitter.dump(doc).unwrap(); // dump the YAML object to a String
|
|
}
|
|
println!("{}", out_str);
|
|
}
|
|
```
|
|
|
|
Note that `yaml_rust::Yaml` implements `Index<&'a str>` & `Index<usize>`:
|
|
|
|
* `Index<usize>` assumes the container is an Array
|
|
* `Index<&'a str>` assumes the container is a string to value Map
|
|
* otherwise, `Yaml::BadValue` is returned
|
|
|
|
If your document does not conform to this convention (e.g. map with
|
|
complex type key), you can use the `Yaml::as_XXX` family API to access your
|
|
documents.
|
|
|
|
## Features
|
|
|
|
* Pure Rust
|
|
* Ruby-like Array/Hash access API
|
|
* Low-level YAML events emission
|
|
|
|
## Specification Compliance
|
|
|
|
This implementation aims to provide YAML parser fully compatible with
|
|
the YAML 1.2 specification. The parser can correctly parse almost all
|
|
examples in the specification, except for the following known bugs:
|
|
|
|
* Empty plain scalar in certain contexts
|
|
|
|
However, the widely used library `libyaml` also fails to parse these examples,
|
|
so it may not be a huge problem for most users.
|
|
|
|
## Goals
|
|
|
|
* Encoder
|
|
* Tag directive
|
|
* Alias while desearilization
|
|
|
|
## License
|
|
|
|
Licensed under either of
|
|
|
|
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
|
|
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
|
|
|
|
at your option.
|
|
|
|
## Contribution
|
|
|
|
Fork & PR on Github.
|
|
|
|
Unless you explicitly state otherwise, any contribution intentionally submitted
|
|
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
|
|
additional terms or conditions.
|
|
|