1//! Value inspection.
2//!
3//! The [`Visit`] trait provides a simple visitor API that can be used to inspect
4//! the structure of primitives stored in a [`ValueBag`](../struct.ValueBag.html).
5//! More complex datatypes can then be handled using `std::fmt`, `sval`, or `serde`.
6//!
7//! ```
8//! # #[cfg(not(feature = "std"))] fn main() {}
9//! # #[cfg(feature = "std")]
10//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
11//! # fn escape(buf: &[u8]) -> &[u8] { buf }
12//! # fn itoa_fmt<T>(num: T) -> Vec<u8> { vec![] }
13//! # fn ryu_fmt<T>(num: T) -> Vec<u8> { vec![] }
14//! # use std::io::Write;
15//! use value_bag::{ValueBag, Error, visit::Visit};
16//!
17//! // Implement some simple custom serialization
18//! struct MyVisit(Vec<u8>);
19//! impl<'v> Visit<'v> for MyVisit {
20//! fn visit_any(&mut self, v: ValueBag) -> Result<(), Error> {
21//! // Fallback to `Debug` if we didn't visit the value specially
22//! write!(&mut self.0, "{:?}", v).map_err(|_| Error::msg("failed to write value"))
23//! }
24//!
25//! fn visit_u64(&mut self, v: u64) -> Result<(), Error> {
26//! self.0.extend_from_slice(itoa_fmt(v).as_slice());
27//! Ok(())
28//! }
29//!
30//! fn visit_i64(&mut self, v: i64) -> Result<(), Error> {
31//! self.0.extend_from_slice(itoa_fmt(v).as_slice());
32//! Ok(())
33//! }
34//!
35//! fn visit_f64(&mut self, v: f64) -> Result<(), Error> {
36//! self.0.extend_from_slice(ryu_fmt(v).as_slice());
37//! Ok(())
38//! }
39//!
40//! fn visit_str(&mut self, v: &str) -> Result<(), Error> {
41//! self.0.push(b'\"');
42//! self.0.extend_from_slice(escape(v.as_bytes()));
43//! self.0.push(b'\"');
44//! Ok(())
45//! }
46//!
47//! fn visit_bool(&mut self, v: bool) -> Result<(), Error> {
48//! self.0.extend_from_slice(if v { b"true" } else { b"false" });
49//! Ok(())
50//! }
51//! }
52//!
53//! let value = ValueBag::from(42i64);
54//!
55//! let mut visitor = MyVisit(vec![]);
56//! value.visit(&mut visitor)?;
57//! # Ok(())
58//! # }
59//! ```
60
61use crate::{
62 internal::{self, InternalVisitor},
63 Error, ValueBag,
64};
65
66/// A visitor for a `ValueBag`.
67pub trait Visit<'v> {
68 /// Visit a `ValueBag`.
69 ///
70 /// This is the only required method on `Visit` and acts as a fallback for any
71 /// more specific methods that aren't overridden.
72 /// The `ValueBag` may be formatted using its `fmt::Debug` or `fmt::Display` implementation,
73 /// or serialized using its `sval::Value` or `serde::Serialize` implementation.
74 fn visit_any(&mut self, value: ValueBag) -> Result<(), Error>;
75
76 /// Visit an empty value.
77 #[inline]
78 fn visit_empty(&mut self) -> Result<(), Error> {
79 self.visit_any(ValueBag::empty())
80 }
81
82 /// Visit an unsigned integer.
83 #[inline]
84 fn visit_u64(&mut self, value: u64) -> Result<(), Error> {
85 self.visit_any(value.into())
86 }
87
88 /// Visit a signed integer.
89 #[inline]
90 fn visit_i64(&mut self, value: i64) -> Result<(), Error> {
91 self.visit_any(value.into())
92 }
93
94 /// Visit a big unsigned integer.
95 #[inline]
96 fn visit_u128(&mut self, value: u128) -> Result<(), Error> {
97 self.visit_any((&value).into())
98 }
99
100 /// Visit a big signed integer.
101 #[inline]
102 fn visit_i128(&mut self, value: i128) -> Result<(), Error> {
103 self.visit_any((&value).into())
104 }
105
106 /// Visit a floating point.
107 #[inline]
108 fn visit_f64(&mut self, value: f64) -> Result<(), Error> {
109 self.visit_any(value.into())
110 }
111
112 /// Visit a boolean.
113 #[inline]
114 fn visit_bool(&mut self, value: bool) -> Result<(), Error> {
115 self.visit_any(value.into())
116 }
117
118 /// Visit a string.
119 #[inline]
120 fn visit_str(&mut self, value: &str) -> Result<(), Error> {
121 self.visit_any(value.into())
122 }
123
124 /// Visit a string.
125 #[inline]
126 fn visit_borrowed_str(&mut self, value: &'v str) -> Result<(), Error> {
127 self.visit_str(value)
128 }
129
130 /// Visit a Unicode character.
131 #[inline]
132 fn visit_char(&mut self, value: char) -> Result<(), Error> {
133 let mut b = [0; 4];
134 self.visit_str(&*value.encode_utf8(&mut b))
135 }
136
137 /// Visit an error.
138 #[inline]
139 #[cfg(feature = "error")]
140 fn visit_error(&mut self, err: &(dyn crate::std::error::Error + 'static)) -> Result<(), Error> {
141 self.visit_any(ValueBag::from_dyn_error(err))
142 }
143
144 /// Visit an error.
145 #[inline]
146 #[cfg(feature = "error")]
147 fn visit_borrowed_error(
148 &mut self,
149 err: &'v (dyn crate::std::error::Error + 'static),
150 ) -> Result<(), Error> {
151 self.visit_any(ValueBag::from_dyn_error(err))
152 }
153}
154
155impl<'a, 'v, T: ?Sized> Visit<'v> for &'a mut T
156where
157 T: Visit<'v>,
158{
159 #[inline]
160 fn visit_any(&mut self, value: ValueBag) -> Result<(), Error> {
161 (**self).visit_any(value)
162 }
163
164 #[inline]
165 fn visit_empty(&mut self) -> Result<(), Error> {
166 (**self).visit_empty()
167 }
168
169 #[inline]
170 fn visit_u64(&mut self, value: u64) -> Result<(), Error> {
171 (**self).visit_u64(value)
172 }
173
174 #[inline]
175 fn visit_i64(&mut self, value: i64) -> Result<(), Error> {
176 (**self).visit_i64(value)
177 }
178
179 #[inline]
180 fn visit_u128(&mut self, value: u128) -> Result<(), Error> {
181 (**self).visit_u128(value)
182 }
183
184 #[inline]
185 fn visit_i128(&mut self, value: i128) -> Result<(), Error> {
186 (**self).visit_i128(value)
187 }
188
189 #[inline]
190 fn visit_f64(&mut self, value: f64) -> Result<(), Error> {
191 (**self).visit_f64(value)
192 }
193
194 #[inline]
195 fn visit_bool(&mut self, value: bool) -> Result<(), Error> {
196 (**self).visit_bool(value)
197 }
198
199 #[inline]
200 fn visit_str(&mut self, value: &str) -> Result<(), Error> {
201 (**self).visit_str(value)
202 }
203
204 #[inline]
205 fn visit_borrowed_str(&mut self, value: &'v str) -> Result<(), Error> {
206 (**self).visit_borrowed_str(value)
207 }
208
209 #[inline]
210 fn visit_char(&mut self, value: char) -> Result<(), Error> {
211 (**self).visit_char(value)
212 }
213
214 #[inline]
215 #[cfg(feature = "error")]
216 fn visit_error(&mut self, err: &(dyn crate::std::error::Error + 'static)) -> Result<(), Error> {
217 (**self).visit_error(err)
218 }
219
220 #[inline]
221 #[cfg(feature = "error")]
222 fn visit_borrowed_error(
223 &mut self,
224 err: &'v (dyn crate::std::error::Error + 'static),
225 ) -> Result<(), Error> {
226 (**self).visit_borrowed_error(err)
227 }
228}
229
230impl<'v> ValueBag<'v> {
231 /// Visit this value using a simple visitor.
232 ///
233 /// The visitor isn't strictly required to inspect the contents of a value bag.
234 /// It's useful for simple cases where a full framework like `serde` or `sval`
235 /// isn't necessary.
236 pub fn visit(&self, visitor: impl Visit<'v>) -> Result<(), Error> {
237 struct Visitor<V>(V);
238
239 impl<'v, V> InternalVisitor<'v> for Visitor<V>
240 where
241 V: Visit<'v>,
242 {
243 fn fill(&mut self, v: &dyn crate::fill::Fill) -> Result<(), Error> {
244 v.fill(crate::fill::Slot::new(self))
245 }
246
247 fn debug(&mut self, v: &dyn internal::fmt::Debug) -> Result<(), Error> {
248 self.0.visit_any(ValueBag::from_dyn_debug(v))
249 }
250
251 fn display(&mut self, v: &dyn internal::fmt::Display) -> Result<(), Error> {
252 self.0.visit_any(ValueBag::from_dyn_display(v))
253 }
254
255 fn u64(&mut self, v: u64) -> Result<(), Error> {
256 self.0.visit_u64(v)
257 }
258
259 fn i64(&mut self, v: i64) -> Result<(), Error> {
260 self.0.visit_i64(v)
261 }
262
263 fn u128(&mut self, v: &u128) -> Result<(), Error> {
264 self.0.visit_u128(*v)
265 }
266
267 fn i128(&mut self, v: &i128) -> Result<(), Error> {
268 self.0.visit_i128(*v)
269 }
270
271 fn f64(&mut self, v: f64) -> Result<(), Error> {
272 self.0.visit_f64(v)
273 }
274
275 fn bool(&mut self, v: bool) -> Result<(), Error> {
276 self.0.visit_bool(v)
277 }
278
279 fn char(&mut self, v: char) -> Result<(), Error> {
280 self.0.visit_char(v)
281 }
282
283 fn str(&mut self, v: &str) -> Result<(), Error> {
284 self.0.visit_str(v)
285 }
286
287 fn borrowed_str(&mut self, v: &'v str) -> Result<(), Error> {
288 self.0.visit_borrowed_str(v)
289 }
290
291 fn none(&mut self) -> Result<(), Error> {
292 self.0.visit_empty()
293 }
294
295 #[cfg(feature = "error")]
296 fn error(&mut self, v: &(dyn internal::error::Error + 'static)) -> Result<(), Error> {
297 self.0.visit_error(v)
298 }
299
300 #[cfg(feature = "error")]
301 fn borrowed_error(
302 &mut self,
303 v: &'v (dyn internal::error::Error + 'static),
304 ) -> Result<(), Error> {
305 self.0.visit_borrowed_error(v)
306 }
307
308 #[cfg(feature = "sval2")]
309 fn sval2(&mut self, v: &dyn internal::sval::v2::Value) -> Result<(), Error> {
310 if internal::sval::v2::internal_visit(v, self) {
311 Ok(())
312 } else {
313 self.0.visit_any(ValueBag::from_dyn_sval2(v))
314 }
315 }
316
317 #[cfg(feature = "sval2")]
318 fn borrowed_sval2(
319 &mut self,
320 v: &'v dyn internal::sval::v2::Value,
321 ) -> Result<(), Error> {
322 if internal::sval::v2::borrowed_internal_visit(v, self) {
323 Ok(())
324 } else {
325 self.0.visit_any(ValueBag::from_dyn_sval2(v))
326 }
327 }
328
329 #[cfg(feature = "serde1")]
330 fn serde1(&mut self, v: &dyn internal::serde::v1::Serialize) -> Result<(), Error> {
331 if internal::serde::v1::internal_visit(v, self) {
332 Ok(())
333 } else {
334 self.0.visit_any(ValueBag::from_dyn_serde1(v))
335 }
336 }
337
338 #[cfg(feature = "seq")]
339 fn seq(&mut self, v: &dyn internal::seq::Seq) -> Result<(), Error> {
340 self.0.visit_any(ValueBag::from_dyn_seq(v))
341 }
342
343 fn poisoned(&mut self, msg: &'static str) -> Result<(), Error> {
344 Err(Error::msg(msg))
345 }
346 }
347
348 self.internal_visit(&mut Visitor(visitor))
349 }
350}
351
352#[cfg(test)]
353mod tests {
354 use super::*;
355 use crate::test::*;
356
357 #[cfg(target_arch = "wasm32")]
358 use wasm_bindgen_test::*;
359
360 #[test]
361 #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)]
362 fn visit_structured() {
363 ValueBag::from(42u64)
364 .visit(TestVisit::default())
365 .expect("failed to visit value");
366 ValueBag::from(-42i64)
367 .visit(TestVisit::default())
368 .expect("failed to visit value");
369 ValueBag::from(&42u128)
370 .visit(TestVisit::default())
371 .expect("failed to visit value");
372 ValueBag::from(&-42i128)
373 .visit(TestVisit::default())
374 .expect("failed to visit value");
375 ValueBag::from(11f64)
376 .visit(TestVisit::default())
377 .expect("failed to visit value");
378 ValueBag::from(true)
379 .visit(TestVisit::default())
380 .expect("failed to visit value");
381 ValueBag::from("some borrowed string")
382 .visit(TestVisit::default())
383 .expect("failed to visit value");
384 ValueBag::from('n')
385 .visit(TestVisit::default())
386 .expect("failed to visit value");
387 }
388
389 #[test]
390 #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)]
391 fn visit_empty() {
392 struct Visitor(bool);
393
394 impl<'v> Visit<'v> for Visitor {
395 fn visit_any(&mut self, _: ValueBag) -> Result<(), Error> {
396 Ok(())
397 }
398
399 fn visit_empty(&mut self) -> Result<(), Error> {
400 self.0 = true;
401 Ok(())
402 }
403 }
404
405 let mut visitor = Visitor(false);
406 ValueBag::empty().visit(&mut visitor).unwrap();
407
408 assert!(visitor.0);
409 }
410
411 #[test]
412 #[cfg(feature = "serde1")]
413 #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)]
414 fn visit_serde1() {
415 use crate::std::string::{String, ToString};
416
417 struct Data;
418
419 impl value_bag_serde1::lib::Serialize for Data {
420 fn serialize<S: value_bag_serde1::lib::Serializer>(
421 &self,
422 serializer: S,
423 ) -> Result<S::Ok, S::Error> {
424 use value_bag_serde1::lib::ser::SerializeStruct;
425
426 let mut s = serializer.serialize_struct("Data", 3)?;
427 s.serialize_field("a", &1)?;
428 s.serialize_field("b", &2)?;
429 s.serialize_field("c", &3)?;
430 s.end()
431 }
432 }
433
434 struct Visitor(String);
435
436 impl<'v> Visit<'v> for Visitor {
437 fn visit_any(&mut self, v: ValueBag) -> Result<(), Error> {
438 self.0 = v.to_string();
439
440 Ok(())
441 }
442 }
443
444 let mut visitor = Visitor("".into());
445 ValueBag::from_serde1(&Data).visit(&mut visitor).unwrap();
446
447 assert_eq!("Data { a: 1, b: 2, c: 3 }", visitor.0);
448 }
449
450 #[test]
451 #[cfg(feature = "sval2")]
452 #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)]
453 fn visit_sval2() {
454 use crate::std::string::{String, ToString};
455
456 struct Data;
457
458 impl value_bag_sval2::lib::Value for Data {
459 fn stream<'sval, S: value_bag_sval2::lib::Stream<'sval> + ?Sized>(
460 &'sval self,
461 stream: &mut S,
462 ) -> value_bag_sval2::lib::Result {
463 stream.map_begin(Some(3))?;
464
465 stream.map_key_begin()?;
466 stream.value("a")?;
467 stream.map_key_end()?;
468
469 stream.map_value_begin()?;
470 stream.value(&1)?;
471 stream.map_value_end()?;
472
473 stream.map_key_begin()?;
474 stream.value("b")?;
475 stream.map_key_end()?;
476
477 stream.map_value_begin()?;
478 stream.value(&2)?;
479 stream.map_value_end()?;
480
481 stream.map_key_begin()?;
482 stream.value("c")?;
483 stream.map_key_end()?;
484
485 stream.map_value_begin()?;
486 stream.value(&3)?;
487 stream.map_value_end()?;
488
489 stream.map_end()
490 }
491 }
492
493 struct Visitor(String);
494
495 impl<'v> Visit<'v> for Visitor {
496 fn visit_any(&mut self, v: ValueBag) -> Result<(), Error> {
497 self.0 = v.to_string();
498
499 Ok(())
500 }
501 }
502
503 let mut visitor = Visitor("".into());
504 ValueBag::from_sval2(&Data).visit(&mut visitor).unwrap();
505
506 assert_eq!("{ \"a\": 1, \"b\": 2, \"c\": 3 }", visitor.0);
507 }
508}
509