1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
use PhantomData;
use Deserializer;
use DeserializeSeed;
use crate::;
/// A value that can be deserialized while collecting the issues in it: missing fields and broken rules together,
/// instead of stopping at the first.
///
/// [`#[derive(Deserialize)]`](macro@crate::Deserialize) implements it, and serde's own `Deserialize` through it, for a
/// struct with rules on its fields. It can also be implemented by hand. [`Deserialize::deserialize_at`] reads the value
/// at the location `at`, pushes every issue in it into `found`, and returns:
///
/// - `Ok(Some(value))` when the value could be built. Rules in it may still have been broken, and those issues are
/// in `found`.
/// - `Ok(None)` when the value couldn't be built, for example because a field inside it is missing. `found` has an
/// issue that says why.
/// - `Err` with the format's own error, such as a syntax error. It ends deserialization, as it would end serde's.
///
/// A value that could be built is returned even when `found` is already finished from
/// [failing fast](Report::failing_fast), because the value around it may still have to check it.
///
/// The crate implements the trait for the containers that hold a nested value, whenever what they hold implements it:
///
/// - `Option<T>` and `Box<T>`.
/// - `Box<[T]>`, `Vec<T>` and `VecDeque<T>`, whose elements are read at their index.
/// - `BTreeMap<K, V>` and `HashMap<K, V, S>`, whose values are read at their key.
///
/// A container is built only when everything in it could be built. A map reports its values' issues in the order it
/// iterates over them. When a key appears twice, the later value replaces the earlier one, along with its issues.
///
/// [`from_deserializer`] reads a value from the root, and returns it or every issue found.
///
/// ```
/// use annotated::{Report, Location, Problem};
/// use serde::Deserializer;
///
/// #[derive(Debug)]
/// struct Handle(String);
///
/// impl<'de> annotated::Deserialize<'de> for Handle {
/// fn deserialize_at<D: Deserializer<'de>>(
/// deserializer: D,
/// at: &Location<'_>,
/// found: &mut Report,
/// ) -> Result<Option<Self>, D::Error> {
/// let handle: String = serde::Deserialize::deserialize(deserializer)?;
/// if !handle.starts_with('@') {
/// found.push(at, Problem::custom("handle", "must start with @"));
/// }
/// Ok(Some(Self(handle)))
/// }
/// }
///
/// let mut deserializer = serde_json::Deserializer::from_str(r#""lucia""#);
/// let error = annotated::from_deserializer::<Handle, _>(&mut deserializer).unwrap_err();
///
/// assert_eq!(error.to_string(), "must start with @");
/// ```
/// A `DeserializeSeed` that reads a `T` at a location and pushes its issues into a report. A collection reads its
/// elements with it, and a struct its nested fields.
/// Reads a `T` from `deserializer`, collecting every issue in it.
///
/// # Errors
///
/// Returns [`DeserializeError::Issues`] with every issue found, in the order found, or
/// [`DeserializeError::Format`] with the format's own error, which ends deserialization at once.
/// Reads a `T` from `deserializer`, and returns only its first issue.
///
/// The value is read and checked as by [`from_deserializer`], so the issue returned is the one `from_deserializer`
/// would list first. The input is still read to its end, because a field is known to be missing only then. Once it is
/// read, checking stops at the first issue. A nested value is checked while it is read, so its rules may still run.
///
/// # Errors
///
/// Returns [`DeserializeError::Issues`] with the first issue found, alone, or [`DeserializeError::Format`] with
/// the format's own error.
pub