serde_yaml/lib.rs
1//! [![github]](https://github.com/dtolnay/serde-yaml) [![crates-io]](https://crates.io/crates/serde-yaml) [![docs-rs]](https://docs.rs/serde-yaml)
2//!
3//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
4//! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust
5//! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
6//!
7//! <br>
8//!
9//! Rust library for using the [Serde] serialization framework with data in
10//! [YAML] file format. _(This project is no longer maintained.)_
11//!
12//! [Serde]: https://github.com/serde-rs/serde
13//! [YAML]: https://yaml.org/
14//!
15//! # Examples
16//!
17//! ```
18//! use std::collections::BTreeMap;
19//!
20//! fn main() -> Result<(), serde_yaml::Error> {
21//! // You have some type.
22//! let mut map = BTreeMap::new();
23//! map.insert("x".to_string(), 1.0);
24//! map.insert("y".to_string(), 2.0);
25//!
26//! // Serialize it to a YAML string.
27//! let yaml = serde_yaml::to_string(&map)?;
28//! assert_eq!(yaml, "x: 1.0\ny: 2.0\n");
29//!
30//! // Deserialize it back to a Rust type.
31//! let deserialized_map: BTreeMap<String, f64> = serde_yaml::from_str(&yaml)?;
32//! assert_eq!(map, deserialized_map);
33//! Ok(())
34//! }
35//! ```
36//!
37//! ## Using Serde derive
38//!
39//! It can also be used with Serde's derive macros to handle structs and enums
40//! defined in your program.
41//!
42//! Structs serialize in the obvious way:
43//!
44//! ```
45//! use serde::{Serialize, Deserialize};
46//!
47//! #[derive(Serialize, Deserialize, PartialEq, Debug)]
48//! struct Point {
49//! x: f64,
50//! y: f64,
51//! }
52//!
53//! fn main() -> Result<(), serde_yaml::Error> {
54//! let point = Point { x: 1.0, y: 2.0 };
55//!
56//! let yaml = serde_yaml::to_string(&point)?;
57//! assert_eq!(yaml, "x: 1.0\ny: 2.0\n");
58//!
59//! let deserialized_point: Point = serde_yaml::from_str(&yaml)?;
60//! assert_eq!(point, deserialized_point);
61//! Ok(())
62//! }
63//! ```
64//!
65//! Enums serialize using YAML's `!tag` syntax to identify the variant name.
66//!
67//! ```
68//! use serde::{Serialize, Deserialize};
69//!
70//! #[derive(Serialize, Deserialize, PartialEq, Debug)]
71//! enum Enum {
72//! Unit,
73//! Newtype(usize),
74//! Tuple(usize, usize, usize),
75//! Struct { x: f64, y: f64 },
76//! }
77//!
78//! fn main() -> Result<(), serde_yaml::Error> {
79//! let yaml = "
80//! - !Newtype 1
81//! - !Tuple [0, 0, 0]
82//! - !Struct {x: 1.0, y: 2.0}
83//! ";
84//! let values: Vec<Enum> = serde_yaml::from_str(yaml).unwrap();
85//! assert_eq!(values[0], Enum::Newtype(1));
86//! assert_eq!(values[1], Enum::Tuple(0, 0, 0));
87//! assert_eq!(values[2], Enum::Struct { x: 1.0, y: 2.0 });
88//!
89//! // The last two in YAML's block style instead:
90//! let yaml = "
91//! - !Tuple
92//! - 0
93//! - 0
94//! - 0
95//! - !Struct
96//! x: 1.0
97//! y: 2.0
98//! ";
99//! let values: Vec<Enum> = serde_yaml::from_str(yaml).unwrap();
100//! assert_eq!(values[0], Enum::Tuple(0, 0, 0));
101//! assert_eq!(values[1], Enum::Struct { x: 1.0, y: 2.0 });
102//!
103//! // Variants with no data can be written using !Tag or just the string name.
104//! let yaml = "
105//! - Unit # serialization produces this one
106//! - !Unit
107//! ";
108//! let values: Vec<Enum> = serde_yaml::from_str(yaml).unwrap();
109//! assert_eq!(values[0], Enum::Unit);
110//! assert_eq!(values[1], Enum::Unit);
111//!
112//! Ok(())
113//! }
114//! ```
115
116#![doc(html_root_url = "https://docs.rs/serde_yaml/0.9.34+deprecated")]
117#![deny(missing_docs, unsafe_op_in_unsafe_fn)]
118// Suppressed clippy_pedantic lints
119#![allow(
120 // buggy
121 clippy::iter_not_returning_iterator, // https://github.com/rust-lang/rust-clippy/issues/8285
122 clippy::ptr_arg, // https://github.com/rust-lang/rust-clippy/issues/9218
123 clippy::question_mark, // https://github.com/rust-lang/rust-clippy/issues/7859
124 // private Deserializer::next
125 clippy::should_implement_trait,
126 // things are often more readable this way
127 clippy::cast_lossless,
128 clippy::checked_conversions,
129 clippy::if_not_else,
130 clippy::manual_assert,
131 clippy::match_like_matches_macro,
132 clippy::match_same_arms,
133 clippy::module_name_repetitions,
134 clippy::needless_pass_by_value,
135 clippy::redundant_else,
136 clippy::single_match_else,
137 // code is acceptable
138 clippy::blocks_in_conditions,
139 clippy::cast_possible_truncation,
140 clippy::cast_possible_wrap,
141 clippy::cast_precision_loss,
142 clippy::cast_sign_loss,
143 clippy::derive_partial_eq_without_eq,
144 clippy::derived_hash_with_manual_eq,
145 clippy::doc_markdown,
146 clippy::items_after_statements,
147 clippy::let_underscore_untyped,
148 clippy::manual_map,
149 clippy::missing_panics_doc,
150 clippy::never_loop,
151 clippy::return_self_not_must_use,
152 clippy::too_many_lines,
153 clippy::uninlined_format_args,
154 clippy::unsafe_removed_from_name,
155 clippy::wildcard_in_or_patterns,
156 // noisy
157 clippy::missing_errors_doc,
158 clippy::must_use_candidate,
159)]
160
161#[doc(inline)]
162pub use crate::mapping::Mapping;
163#[doc(inline)]
164pub use crate::value::{Index, Number, Sequence, Value, from_value, to_value};
165pub use crate::{
166 de::{Deserializer, from_reader, from_slice, from_str},
167 error::{Error, Location, Result},
168 ser::{Serializer, to_string, to_writer},
169};
170
171mod de;
172mod error;
173mod libyaml;
174mod loader;
175pub mod mapping;
176mod number;
177mod path;
178mod ser;
179pub mod value;
180pub mod with;
181
182// Prevent downstream code from implementing the Index trait.
183mod private {
184 pub trait Sealed {}
185 impl Sealed for usize {}
186 impl Sealed for str {}
187 impl Sealed for String {}
188 impl Sealed for crate::Value {}
189 impl<'a, T> Sealed for &'a T where T: ?Sized + Sealed {}
190}