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_derive::{Serialize, Deserialize};
46//! use serde::{Serialize, Deserialize};
47//!
48//! #[derive(Serialize, Deserialize, PartialEq, Debug)]
49//! struct Point {
50//! x: f64,
51//! y: f64,
52//! }
53//!
54//! fn main() -> Result<(), serde_yaml::Error> {
55//! let point = Point { x: 1.0, y: 2.0 };
56//!
57//! let yaml = serde_yaml::to_string(&point)?;
58//! assert_eq!(yaml, "x: 1.0\ny: 2.0\n");
59//!
60//! let deserialized_point: Point = serde_yaml::from_str(&yaml)?;
61//! assert_eq!(point, deserialized_point);
62//! Ok(())
63//! }
64//! ```
65//!
66//! Enums serialize using YAML's `!tag` syntax to identify the variant name.
67//!
68//! ```
69//! # use serde_derive::{Serialize, Deserialize};
70//! use serde::{Serialize, Deserialize};
71//!
72//! #[derive(Serialize, Deserialize, PartialEq, Debug)]
73//! enum Enum {
74//! Unit,
75//! Newtype(usize),
76//! Tuple(usize, usize, usize),
77//! Struct { x: f64, y: f64 },
78//! }
79//!
80//! fn main() -> Result<(), serde_yaml::Error> {
81//! let yaml = "
82//! - !Newtype 1
83//! - !Tuple [0, 0, 0]
84//! - !Struct {x: 1.0, y: 2.0}
85//! ";
86//! let values: Vec<Enum> = serde_yaml::from_str(yaml).unwrap();
87//! assert_eq!(values[0], Enum::Newtype(1));
88//! assert_eq!(values[1], Enum::Tuple(0, 0, 0));
89//! assert_eq!(values[2], Enum::Struct { x: 1.0, y: 2.0 });
90//!
91//! // The last two in YAML's block style instead:
92//! let yaml = "
93//! - !Tuple
94//! - 0
95//! - 0
96//! - 0
97//! - !Struct
98//! x: 1.0
99//! y: 2.0
100//! ";
101//! let values: Vec<Enum> = serde_yaml::from_str(yaml).unwrap();
102//! assert_eq!(values[0], Enum::Tuple(0, 0, 0));
103//! assert_eq!(values[1], Enum::Struct { x: 1.0, y: 2.0 });
104//!
105//! // Variants with no data can be written using !Tag or just the string name.
106//! let yaml = "
107//! - Unit # serialization produces this one
108//! - !Unit
109//! ";
110//! let values: Vec<Enum> = serde_yaml::from_str(yaml).unwrap();
111//! assert_eq!(values[0], Enum::Unit);
112//! assert_eq!(values[1], Enum::Unit);
113//!
114//! Ok(())
115//! }
116//! ```
117
118#![doc(html_root_url = "https://docs.rs/serde_yaml/0.9.34+deprecated")]
119#![deny(missing_docs, unsafe_op_in_unsafe_fn)]
120// Suppressed clippy_pedantic lints
121#![allow(
122 // buggy
123 clippy::iter_not_returning_iterator, // https://github.com/rust-lang/rust-clippy/issues/8285
124 clippy::ptr_arg, // https://github.com/rust-lang/rust-clippy/issues/9218
125 clippy::question_mark, // https://github.com/rust-lang/rust-clippy/issues/7859
126 // private Deserializer::next
127 clippy::should_implement_trait,
128 // things are often more readable this way
129 clippy::cast_lossless,
130 clippy::checked_conversions,
131 clippy::if_not_else,
132 clippy::manual_assert,
133 clippy::match_like_matches_macro,
134 clippy::match_same_arms,
135 clippy::module_name_repetitions,
136 clippy::needless_pass_by_value,
137 clippy::redundant_else,
138 clippy::single_match_else,
139 // code is acceptable
140 clippy::blocks_in_conditions,
141 clippy::cast_possible_truncation,
142 clippy::cast_possible_wrap,
143 clippy::cast_precision_loss,
144 clippy::cast_sign_loss,
145 clippy::derive_partial_eq_without_eq,
146 clippy::derived_hash_with_manual_eq,
147 clippy::doc_markdown,
148 clippy::items_after_statements,
149 clippy::let_underscore_untyped,
150 clippy::manual_map,
151 clippy::missing_panics_doc,
152 clippy::never_loop,
153 clippy::return_self_not_must_use,
154 clippy::too_many_lines,
155 clippy::uninlined_format_args,
156 clippy::unsafe_removed_from_name,
157 clippy::wildcard_in_or_patterns,
158 // noisy
159 clippy::missing_errors_doc,
160 clippy::must_use_candidate,
161)]
162
163pub use crate::de::{from_reader, from_slice, from_str, Deserializer};
164pub use crate::error::{Error, Location, Result};
165pub use crate::ser::{to_string, to_writer, Serializer};
166#[doc(inline)]
167pub use crate::value::{from_value, to_value, Index, Number, Sequence, Value};
168
169#[doc(inline)]
170pub use crate::mapping::Mapping;
171
172mod de;
173mod error;
174mod libyaml;
175mod loader;
176pub mod mapping;
177mod number;
178mod path;
179mod ser;
180pub mod value;
181pub mod with;
182
183// Prevent downstream code from implementing the Index trait.
184mod private {
185 pub trait Sealed {}
186 impl Sealed for usize {}
187 impl Sealed for str {}
188 impl Sealed for String {}
189 impl Sealed for crate::Value {}
190 impl<'a, T> Sealed for &'a T where T: ?Sized + Sealed {}
191}