serde_yaml/
lib.rs

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

serde_yaml/
lib.rs
