1Serde YAML
2==========
3
4[<img alt="github" src="https://img.shields.io/badge/github-dtolnay/serde--yaml-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20">](https://github.com/dtolnay/serde-yaml)
5[<img alt="crates.io" src="https://img.shields.io/crates/v/serde_yaml.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/serde_yaml)
6[<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-serde__yaml-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="20">](https://docs.rs/serde_yaml)
7[<img alt="build status" src="https://img.shields.io/github/actions/workflow/status/dtolnay/serde-yaml/ci.yml?branch=master&style=for-the-badge" height="20">](https://github.com/dtolnay/serde-yaml/actions?query=branch%3Amaster)
8
9This crate is a Rust library for using the [Serde] serialization framework with
10data in [YAML] file format.
11
12[Serde]: https://github.com/serde-rs/serde
13[YAML]: https://yaml.org/
14
15## Dependency
16
17```toml
18[dependencies]
19serde = "1.0"
20serde_yaml = "0.9"
21```
22
23Release notes are available under [GitHub releases].
24
25[GitHub releases]: https://github.com/dtolnay/serde-yaml/releases
26
27## Using Serde YAML
28
29[API documentation is available in rustdoc form][docs.rs] but the general idea
30is:
31
32[docs.rs]: https://docs.rs/serde_yaml
33
34```rust
35use std::collections::BTreeMap;
36
37fn main() -> Result<(), serde_yaml::Error> {
38    // You have some type.
39    let mut map = BTreeMap::new();
40    map.insert("x".to_string(), 1.0);
41    map.insert("y".to_string(), 2.0);
42
43    // Serialize it to a YAML string.
44    let yaml = serde_yaml::to_string(&map)?;
45    assert_eq!(yaml, "x: 1.0\ny: 2.0\n");
46
47    // Deserialize it back to a Rust type.
48    let deserialized_map: BTreeMap<String, f64> = serde_yaml::from_str(&yaml)?;
49    assert_eq!(map, deserialized_map);
50    Ok(())
51}
52```
53
54It can also be used with Serde's derive macros to handle structs and enums
55defined in your program.
56
57```toml
58[dependencies]
59serde = { version = "1.0", features = ["derive"] }
60serde_yaml = "0.9"
61```
62
63Structs serialize in the obvious way:
64
65```rust
66use serde::{Serialize, Deserialize};
67
68#[derive(Debug, PartialEq, Serialize, Deserialize)]
69struct Point {
70    x: f64,
71    y: f64,
72}
73
74fn main() -> Result<(), serde_yaml::Error> {
75    let point = Point { x: 1.0, y: 2.0 };
76
77    let yaml = serde_yaml::to_string(&point)?;
78    assert_eq!(yaml, "x: 1.0\ny: 2.0\n");
79
80    let deserialized_point: Point = serde_yaml::from_str(&yaml)?;
81    assert_eq!(point, deserialized_point);
82    Ok(())
83}
84```
85
86Enums serialize using YAML's `!tag` syntax to identify the variant name.
87
88```rust
89use serde::{Serialize, Deserialize};
90
91#[derive(Serialize, Deserialize, PartialEq, Debug)]
92enum Enum {
93    Unit,
94    Newtype(usize),
95    Tuple(usize, usize, usize),
96    Struct { x: f64, y: f64 },
97}
98
99fn main() -> Result<(), serde_yaml::Error> {
100    let yaml = "
101        - !Newtype 1
102        - !Tuple [0, 0, 0]
103        - !Struct {x: 1.0, y: 2.0}
104    ";
105    let values: Vec<Enum> = serde_yaml::from_str(yaml).unwrap();
106    assert_eq!(values[0], Enum::Newtype(1));
107    assert_eq!(values[1], Enum::Tuple(0, 0, 0));
108    assert_eq!(values[2], Enum::Struct { x: 1.0, y: 2.0 });
109
110    // The last two in YAML's block style instead:
111    let yaml = "
112        - !Tuple
113          - 0
114          - 0
115          - 0
116        - !Struct
117          x: 1.0
118          y: 2.0
119    ";
120    let values: Vec<Enum> = serde_yaml::from_str(yaml).unwrap();
121    assert_eq!(values[0], Enum::Tuple(0, 0, 0));
122    assert_eq!(values[1], Enum::Struct { x: 1.0, y: 2.0 });
123
124    // Variants with no data can be written using !Tag or just the string name.
125    let yaml = "
126        - Unit  # serialization produces this one
127        - !Unit
128    ";
129    let values: Vec<Enum> = serde_yaml::from_str(yaml).unwrap();
130    assert_eq!(values[0], Enum::Unit);
131    assert_eq!(values[1], Enum::Unit);
132
133    Ok(())
134}
135```
136
137<br>
138
139#### License
140
141<sup>
142Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
1432.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
144</sup>
145
146<br>
147
148<sub>
149Unless you explicitly state otherwise, any contribution intentionally submitted
150for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
151be dual licensed as above, without any additional terms or conditions.
152</sub>
153