README.md
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
