diff --git a/src/kv/mod.rs b/src/kv/mod.rs index 8a0eb1a56..6d38dbe50 100644 --- a/src/kv/mod.rs +++ b/src/kv/mod.rs @@ -71,18 +71,18 @@ //! # } //! ``` //! -//! All key-values can also be enumerated using a [`source::Visitor`]: +//! All key-values can also be enumerated using a [`VisitSource`]: //! //! ``` //! # fn main() -> Result<(), log::kv::Error> { //! # let record = log::Record::builder().key_values(&[("a", 1), ("b", 2), ("c", 3)]).build(); //! use std::collections::BTreeMap; //! -//! use log::kv::{self, Source, Key, Value, source::Visitor}; +//! use log::kv::{self, Source, Key, Value, VisitSource}; //! //! struct Collect<'kvs>(BTreeMap, Value<'kvs>>); //! -//! impl<'kvs> Visitor<'kvs> for Collect<'kvs> { +//! impl<'kvs> VisitSource<'kvs> for Collect<'kvs> { //! fn visit_pair(&mut self, key: Key<'kvs>, value: Value<'kvs>) -> Result<(), kv::Error> { //! self.0.insert(key, value); //! @@ -125,17 +125,17 @@ //! # } //! ``` //! -//! Values also have their own [`value::Visitor`] type. Visitors are a lightweight +//! Values also have their own [`VisitValue`] type. Value visitors are a lightweight //! API for working with primitives types: //! //! ``` //! # fn main() -> Result<(), log::kv::Error> { -//! use log::kv::{self, Source, Key, value::Visitor}; +//! use log::kv::{self, Source, Key, VisitValue}; //! # let record = log::Record::builder().key_values(&[("a", 1)]).build(); //! //! struct IsNumeric(bool); //! -//! impl<'kvs> Visitor<'kvs> for IsNumeric { +//! impl<'kvs> VisitValue<'kvs> for IsNumeric { //! fn visit_any(&mut self, _value: kv::Value) -> Result<(), kv::Error> { //! self.0 = false; //! Ok(()) @@ -230,12 +230,9 @@ mod error; mod key; pub mod source; - pub mod value; pub use self::error::Error; pub use self::key::{Key, ToKey}; -pub use self::source::{Source, Visitor}; - -#[doc(inline)] -pub use self::value::{ToValue, Value}; +pub use self::source::{Source, VisitSource}; +pub use self::value::{ToValue, Value, VisitValue}; diff --git a/src/kv/source.rs b/src/kv/source.rs index 87d955417..df4fe1bd8 100644 --- a/src/kv/source.rs +++ b/src/kv/source.rs @@ -9,7 +9,7 @@ use std::fmt; /// A source of key-values. /// /// The source may be a single pair, a set of pairs, or a filter over a set of pairs. -/// Use the [`Visitor`](trait.Visitor.html) trait to inspect the structured data +/// Use the [`VisitSource`](trait.VisitSource.html) trait to inspect the structured data /// in a source. /// /// A source is like an iterator over its key-values, except with a push-based API @@ -21,13 +21,13 @@ use std::fmt; /// /// ``` /// # fn main() -> Result<(), log::kv::Error> { -/// use log::kv::{self, Source, Key, Value, source::Visitor}; +/// use log::kv::{self, Source, Key, Value, source::VisitSource}; /// -/// // A `Visitor` that prints all key-values -/// // Visitors are fed the key-value pairs of each key-values +/// // A `VisitSource` that prints all key-values +/// // VisitSources are fed the key-value pairs of each key-values /// struct Printer; /// -/// impl<'kvs> Visitor<'kvs> for Printer { +/// impl<'kvs> VisitSource<'kvs> for Printer { /// fn visit_pair(&mut self, key: Key<'kvs>, value: Value<'kvs>) -> Result<(), kv::Error> { /// println!("{key}: {value}"); /// @@ -43,7 +43,7 @@ use std::fmt; /// ("c", 3), /// ]; /// -/// // Pass an instance of the `Visitor` to a `Source` to visit it +/// // Pass an instance of the `VisitSource` to a `Source` to visit it /// source.visit(&mut Printer)?; /// # Ok(()) /// # } @@ -59,7 +59,7 @@ pub trait Source { /// /// A source should yield the same key-values to a subsequent visitor unless /// that visitor itself fails. - fn visit<'kvs>(&'kvs self, visitor: &mut dyn Visitor<'kvs>) -> Result<(), Error>; + fn visit<'kvs>(&'kvs self, visitor: &mut dyn VisitSource<'kvs>) -> Result<(), Error>; /// Get the value for a given key. /// @@ -95,7 +95,7 @@ fn get_default<'v>(source: &'v (impl Source + ?Sized), key: Key) -> Option>, } - impl<'k, 'kvs> Visitor<'kvs> for Get<'k, 'kvs> { + impl<'k, 'kvs> VisitSource<'kvs> for Get<'k, 'kvs> { fn visit_pair(&mut self, key: Key<'kvs>, value: Value<'kvs>) -> Result<(), Error> { if self.key == key { self.found = Some(value); @@ -115,7 +115,7 @@ fn get_default<'v>(source: &'v (impl Source + ?Sized), key: Key) -> Option usize { struct Count(usize); - impl<'kvs> Visitor<'kvs> for Count { + impl<'kvs> VisitSource<'kvs> for Count { fn visit_pair(&mut self, _: Key<'kvs>, _: Value<'kvs>) -> Result<(), Error> { self.0 += 1; @@ -132,7 +132,7 @@ impl<'a, T> Source for &'a T where T: Source + ?Sized, { - fn visit<'kvs>(&'kvs self, visitor: &mut dyn Visitor<'kvs>) -> Result<(), Error> { + fn visit<'kvs>(&'kvs self, visitor: &mut dyn VisitSource<'kvs>) -> Result<(), Error> { Source::visit(&**self, visitor) } @@ -150,7 +150,7 @@ where K: ToKey, V: ToValue, { - fn visit<'kvs>(&'kvs self, visitor: &mut dyn Visitor<'kvs>) -> Result<(), Error> { + fn visit<'kvs>(&'kvs self, visitor: &mut dyn VisitSource<'kvs>) -> Result<(), Error> { visitor.visit_pair(self.0.to_key(), self.1.to_value()) } @@ -171,7 +171,7 @@ impl Source for [S] where S: Source, { - fn visit<'kvs>(&'kvs self, visitor: &mut dyn Visitor<'kvs>) -> Result<(), Error> { + fn visit<'kvs>(&'kvs self, visitor: &mut dyn VisitSource<'kvs>) -> Result<(), Error> { for source in self { source.visit(visitor)?; } @@ -198,7 +198,7 @@ impl Source for [S; N] where S: Source, { - fn visit<'kvs>(&'kvs self, visitor: &mut dyn Visitor<'kvs>) -> Result<(), Error> { + fn visit<'kvs>(&'kvs self, visitor: &mut dyn VisitSource<'kvs>) -> Result<(), Error> { Source::visit(self as &[_], visitor) } @@ -215,7 +215,7 @@ impl Source for Option where S: Source, { - fn visit<'kvs>(&'kvs self, visitor: &mut dyn Visitor<'kvs>) -> Result<(), Error> { + fn visit<'kvs>(&'kvs self, visitor: &mut dyn VisitSource<'kvs>) -> Result<(), Error> { if let Some(source) = self { source.visit(visitor)?; } @@ -233,42 +233,42 @@ where } /// A visitor for the key-value pairs in a [`Source`](trait.Source.html). -pub trait Visitor<'kvs> { +pub trait VisitSource<'kvs> { /// Visit a key-value pair. fn visit_pair(&mut self, key: Key<'kvs>, value: Value<'kvs>) -> Result<(), Error>; } -impl<'a, 'kvs, T> Visitor<'kvs> for &'a mut T +impl<'a, 'kvs, T> VisitSource<'kvs> for &'a mut T where - T: Visitor<'kvs> + ?Sized, + T: VisitSource<'kvs> + ?Sized, { fn visit_pair(&mut self, key: Key<'kvs>, value: Value<'kvs>) -> Result<(), Error> { (**self).visit_pair(key, value) } } -impl<'a, 'b: 'a, 'kvs> Visitor<'kvs> for fmt::DebugMap<'a, 'b> { +impl<'a, 'b: 'a, 'kvs> VisitSource<'kvs> for fmt::DebugMap<'a, 'b> { fn visit_pair(&mut self, key: Key<'kvs>, value: Value<'kvs>) -> Result<(), Error> { self.entry(&key, &value); Ok(()) } } -impl<'a, 'b: 'a, 'kvs> Visitor<'kvs> for fmt::DebugList<'a, 'b> { +impl<'a, 'b: 'a, 'kvs> VisitSource<'kvs> for fmt::DebugList<'a, 'b> { fn visit_pair(&mut self, key: Key<'kvs>, value: Value<'kvs>) -> Result<(), Error> { self.entry(&(key, value)); Ok(()) } } -impl<'a, 'b: 'a, 'kvs> Visitor<'kvs> for fmt::DebugSet<'a, 'b> { +impl<'a, 'b: 'a, 'kvs> VisitSource<'kvs> for fmt::DebugSet<'a, 'b> { fn visit_pair(&mut self, key: Key<'kvs>, value: Value<'kvs>) -> Result<(), Error> { self.entry(&(key, value)); Ok(()) } } -impl<'a, 'b: 'a, 'kvs> Visitor<'kvs> for fmt::DebugTuple<'a, 'b> { +impl<'a, 'b: 'a, 'kvs> VisitSource<'kvs> for fmt::DebugTuple<'a, 'b> { fn visit_pair(&mut self, key: Key<'kvs>, value: Value<'kvs>) -> Result<(), Error> { self.field(&key); self.field(&value); @@ -289,7 +289,7 @@ mod std_support { where S: Source + ?Sized, { - fn visit<'kvs>(&'kvs self, visitor: &mut dyn Visitor<'kvs>) -> Result<(), Error> { + fn visit<'kvs>(&'kvs self, visitor: &mut dyn VisitSource<'kvs>) -> Result<(), Error> { Source::visit(&**self, visitor) } @@ -306,7 +306,7 @@ mod std_support { where S: Source + ?Sized, { - fn visit<'kvs>(&'kvs self, visitor: &mut dyn Visitor<'kvs>) -> Result<(), Error> { + fn visit<'kvs>(&'kvs self, visitor: &mut dyn VisitSource<'kvs>) -> Result<(), Error> { Source::visit(&**self, visitor) } @@ -323,7 +323,7 @@ mod std_support { where S: Source + ?Sized, { - fn visit<'kvs>(&'kvs self, visitor: &mut dyn Visitor<'kvs>) -> Result<(), Error> { + fn visit<'kvs>(&'kvs self, visitor: &mut dyn VisitSource<'kvs>) -> Result<(), Error> { Source::visit(&**self, visitor) } @@ -340,7 +340,7 @@ mod std_support { where S: Source, { - fn visit<'kvs>(&'kvs self, visitor: &mut dyn Visitor<'kvs>) -> Result<(), Error> { + fn visit<'kvs>(&'kvs self, visitor: &mut dyn VisitSource<'kvs>) -> Result<(), Error> { Source::visit(&**self, visitor) } @@ -353,9 +353,9 @@ mod std_support { } } - impl<'kvs, V> Visitor<'kvs> for Box + impl<'kvs, V> VisitSource<'kvs> for Box where - V: Visitor<'kvs> + ?Sized, + V: VisitSource<'kvs> + ?Sized, { fn visit_pair(&mut self, key: Key<'kvs>, value: Value<'kvs>) -> Result<(), Error> { (**self).visit_pair(key, value) @@ -368,7 +368,7 @@ mod std_support { V: ToValue, S: BuildHasher, { - fn visit<'kvs>(&'kvs self, visitor: &mut dyn Visitor<'kvs>) -> Result<(), Error> { + fn visit<'kvs>(&'kvs self, visitor: &mut dyn VisitSource<'kvs>) -> Result<(), Error> { for (key, value) in self { visitor.visit_pair(key.to_key(), value.to_value())?; } @@ -389,7 +389,7 @@ mod std_support { K: ToKey + Borrow + Ord, V: ToValue, { - fn visit<'kvs>(&'kvs self, visitor: &mut dyn Visitor<'kvs>) -> Result<(), Error> { + fn visit<'kvs>(&'kvs self, visitor: &mut dyn VisitSource<'kvs>) -> Result<(), Error> { for (key, value) in self { visitor.visit_pair(key.to_key(), value.to_value())?; } @@ -472,7 +472,7 @@ mod tests { #[test] fn visitor_is_object_safe() { - fn _check(_: &dyn Visitor) {} + fn _check(_: &dyn VisitSource) {} } #[test] @@ -483,7 +483,7 @@ mod tests { } impl Source for OnePair { - fn visit<'kvs>(&'kvs self, visitor: &mut dyn Visitor<'kvs>) -> Result<(), Error> { + fn visit<'kvs>(&'kvs self, visitor: &mut dyn VisitSource<'kvs>) -> Result<(), Error> { visitor.visit_pair(self.key.to_key(), self.value.to_value()) } } diff --git a/src/kv/value.rs b/src/kv/value.rs index 971bf6bbf..a4dd8f618 100644 --- a/src/kv/value.rs +++ b/src/kv/value.rs @@ -102,7 +102,7 @@ impl<'v> ToValue for Value<'v> { /// /// For basic types the [`Value::visit`] method can be used to extract the /// underlying typed value. However this is limited in the amount of types -/// supported (see the [`Visitor`] trait methods). +/// supported (see the [`VisitValue`] trait methods). /// /// For more complex types one of the following traits can be used: /// * `sval::Value`, requires the `kv_unstable_sval` feature. @@ -213,7 +213,7 @@ impl<'v> Value<'v> { /// /// When the `kv_unstable_serde` or `kv_unstable_sval` features are enabled, you can also /// serialize a value using its `Serialize` or `Value` implementation. - pub fn visit(&self, visitor: impl Visitor<'v>) -> Result<(), Error> { + pub fn visit(&self, visitor: impl VisitValue<'v>) -> Result<(), Error> { inner::visit(&self.inner, visitor) } } @@ -436,20 +436,20 @@ mod std_support { /// A visitor for a [`Value`]. /// -/// Also see [`Value`'s documentation on seralization]. Visitors are a simple alternative -/// to a more fully-featured serialization framework like `serde` or `sval`. A visitor -/// can differentiate primitive types through methods like [`Visitor::visit_bool`] and -/// [`Visitor::visit_str`], but more complex types like maps and sequences -/// will fallthrough to [`Visitor::visit_any`]. +/// Also see [`Value`'s documentation on seralization]. Value visitors are a simple alternative +/// to a more fully-featured serialization framework like `serde` or `sval`. A value visitor +/// can differentiate primitive types through methods like [`VisitValue::visit_bool`] and +/// [`VisitValue::visit_str`], but more complex types like maps and sequences +/// will fallthrough to [`VisitValue::visit_any`]. /// /// If you're trying to serialize a value to a format like JSON, you can use either `serde` /// or `sval` directly with the value. You don't need a visitor. /// /// [`Value`'s documentation on seralization]: Value#serialization -pub trait Visitor<'v> { +pub trait VisitValue<'v> { /// Visit a `Value`. /// - /// This is the only required method on `Visitor` and acts as a fallback for any + /// This is the only required method on `VisitValue` and acts as a fallback for any /// more specific methods that aren't overridden. /// The `Value` may be formatted using its `fmt::Debug` or `fmt::Display` implementation, /// or serialized using its `sval::Value` or `serde::Serialize` implementation. @@ -522,9 +522,9 @@ pub trait Visitor<'v> { } } -impl<'a, 'v, T: ?Sized> Visitor<'v> for &'a mut T +impl<'a, 'v, T: ?Sized> VisitValue<'v> for &'a mut T where - T: Visitor<'v>, + T: VisitValue<'v>, { fn visit_any(&mut self, value: Value) -> Result<(), Error> { (**self).visit_any(value) @@ -607,12 +607,12 @@ pub(in crate::kv) mod inner { inner.to_test_token() } - pub fn visit<'v>(inner: &Inner<'v>, visitor: impl Visitor<'v>) -> Result<(), crate::kv::Error> { - struct InnerVisitor(V); + pub fn visit<'v>(inner: &Inner<'v>, visitor: impl VisitValue<'v>) -> Result<(), crate::kv::Error> { + struct InnerVisitValue(V); - impl<'v, V> value_bag::visit::Visit<'v> for InnerVisitor + impl<'v, V> value_bag::visit::Visit<'v> for InnerVisitValue where - V: Visitor<'v>, + V: VisitValue<'v>, { fn visit_any(&mut self, value: value_bag::ValueBag) -> Result<(), Error> { self.0 @@ -700,7 +700,7 @@ pub(in crate::kv) mod inner { } inner - .visit(&mut InnerVisitor(visitor)) + .visit(&mut InnerVisitValue(visitor)) .map_err(crate::kv::Error::from_value) } } @@ -717,7 +717,7 @@ pub(in crate::kv) mod inner { the same `value_bag`-based conversion must also. Of particular note here are floats to ints; they're based on the standard library's `TryInto` conversions, which need to be convert to `i32` or `u32`, and then to `f64`. - 2. Visitors should always be called in the same way. If a particular type of value calls `visit_i64`, + 2. VisitValues should always be called in the same way. If a particular type of value calls `visit_i64`, then the same `value_bag`-based visitor must also. */ use super::*; @@ -1018,7 +1018,7 @@ pub(in crate::kv) mod inner { pub fn visit<'v>( inner: &Inner<'v>, - mut visitor: impl Visitor<'v>, + mut visitor: impl VisitValue<'v>, ) -> Result<(), crate::kv::Error> { match inner { Inner::None => visitor.visit_null(), @@ -1216,7 +1216,7 @@ pub(crate) mod tests { fn test_visit_integer() { struct Extract(Option); - impl<'v> Visitor<'v> for Extract { + impl<'v> VisitValue<'v> for Extract { fn visit_any(&mut self, value: Value) -> Result<(), Error> { unimplemented!("unexpected value: {value:?}") } @@ -1238,7 +1238,7 @@ pub(crate) mod tests { fn test_visit_borrowed_str() { struct Extract<'v>(Option<&'v str>); - impl<'v> Visitor<'v> for Extract<'v> { + impl<'v> VisitValue<'v> for Extract<'v> { fn visit_any(&mut self, value: Value) -> Result<(), Error> { unimplemented!("unexpected value: {value:?}") } diff --git a/src/lib.rs b/src/lib.rs index e0577ce97..8abbfcb2e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1760,13 +1760,13 @@ mod tests { #[cfg(feature = "kv_unstable")] fn test_record_key_values_builder() { use super::Record; - use crate::kv::{self, Visitor}; + use crate::kv::{self, VisitSource}; - struct TestVisitor { + struct TestVisitSource { seen_pairs: usize, } - impl<'kvs> Visitor<'kvs> for TestVisitor { + impl<'kvs> VisitSource<'kvs> for TestVisitSource { fn visit_pair( &mut self, _: kv::Key<'kvs>, @@ -1780,7 +1780,7 @@ mod tests { let kvs: &[(&str, i32)] = &[("a", 1), ("b", 2)]; let record_test = Record::builder().key_values(&kvs).build(); - let mut visitor = TestVisitor { seen_pairs: 0 }; + let mut visitor = TestVisitSource { seen_pairs: 0 }; record_test.key_values().visit(&mut visitor).unwrap();