Merge branch 'feat/kv-cleanup' of https://github.com/rust-lang/log in…

…to feat/kv-cleanup

Cargo.toml

@@ -57,15 +57,15 @@ kv_unstable_serde = ["kv_unstable_std", "value-bag/serde", "serde"]
 serde = { version = "1.0", optional = true, default-features = false }
 sval = { version = "2.1", optional = true, default-features = false }
 sval_ref = { version = "2.1", optional = true, default-features = false }
-value-bag = { version = "1.4", optional = true, default-features = false }
+value-bag = { version = "1.7", optional = true, default-features = false, features = ["inline-i128"] }
 
 [dev-dependencies]
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 serde_test = "1.0"
 sval = { version = "2.1" }
 sval_derive = { version = "2.1" }
-value-bag = { version = "1.4", features = ["test"] }
+value-bag = { version = "1.7", features = ["test"] }
 
 # NOTE: log doesn't actually depent on this crate. However our dependencies,
 # serde and sval, dependent on version 1.0 of the crate, which has problem fixed

src/kv/error.rs

@@ -1,7 +1,5 @@
 use std::fmt;
 
-use crate::kv::value;
-
 /// An error encountered while working with structured data.
 #[derive(Debug)]
 pub struct Error {
@@ -13,7 +11,8 @@ enum Inner {
     #[cfg(feature = "std")]
     Boxed(std_support::BoxedError),
     Msg(&'static str),
-    Value(value::inner::Error),
+    #[cfg(feature = "value-bag")]
+    Value(crate::kv::value::inner::Error),
     Fmt,
 }
 
@@ -25,21 +24,23 @@ impl Error {
         }
     }
 
-    // Not public so we don't leak the `value::inner` API
-    pub(super) fn from_value(err: value::inner::Error) -> Self {
+    // Not public so we don't leak the `crate::kv::value::inner` API
+    #[cfg(feature = "value-bag")]
+    pub(super) fn from_value(err: crate::kv::value::inner::Error) -> Self {
         Error {
             inner: Inner::Value(err),
         }
     }
 
-    // Not public so we don't leak the `value::inner` API
-    pub(super) fn into_value(self) -> value::inner::Error {
+    // Not public so we don't leak the `crate::kv::value::inner` API
+    #[cfg(feature = "value-bag")]
+    pub(super) fn into_value(self) -> crate::kv::value::inner::Error {
         match self.inner {
             Inner::Value(err) => err,
             #[cfg(feature = "kv_unstable_std")]
-            _ => value::inner::Error::boxed(self),
+            _ => crate::kv::value::inner::Error::boxed(self),
             #[cfg(not(feature = "kv_unstable_std"))]
-            _ => value::inner::Error::msg("error inspecting a value"),
+            _ => crate::kv::value::inner::Error::msg("error inspecting a value"),
         }
     }
 }
@@ -50,6 +51,7 @@ impl fmt::Display for Error {
         match &self.inner {
             #[cfg(feature = "std")]
             Boxed(err) => err.fmt(f),
+            #[cfg(feature = "value-bag")]
             Value(err) => err.fmt(f),
             Msg(msg) => msg.fmt(f),
             Fmt => fmt::Error.fmt(f),

src/kv/mod.rs

@@ -27,11 +27,31 @@
 //!
 //! ## Adding key-values to log records
 //!
-//! Key-values appear after the message format in the `log!` macros:
+//! Key-values appear before the message format in the `log!` macros:
 //!
 //! ```
-//! ..
+//! # use log::info;
+//! info!(a = 1; "Something of interest");
 //! ```
+//! 
+//! Values are capturing using the [`ToValue`] trait by default. To capture a value
+//! using a different trait implementation, use a modifier after its key. Here's how
+//! the same example can capture `a` using its `Debug` implementation instead:
+//! 
+//! ```
+//! # use log::info;
+//! info!(a:? = 1; "Something of interest");
+//! ```
+//! 
+//! The following capturing modifiers are supported:
+//! 
+//! - `:?`: `Debug`.
+//! - `:debug`: `Debug`.
+//! - `:%`: `Display`.
+//! - `:display`: `Display`.
+//! - `:error`: `std::error::Error` (requires the `kv_unstable_error` feature).
+//! - `:sval`: `sval::Value` (requires the `kv_unstable_sval` feature).
+//! - `:serde`: `serde::Serialize` (requires the `kv_unstable_serde` feature).
 //!
 //! ## Working with key-values on log records
 //!
@@ -44,7 +64,8 @@
 //! use log::kv::{Source, Key, Value};
 //! # let record = log::Record::builder().key_values(&[("a", 1)]).build();
 //!
-//! // info!("Something of interest"; a = 1);
+//! // info!(a = 1; "Something of interest");
+//!
 //! let a: Value = record.key_values().get(Key::from("a")).unwrap();
 //! # Ok(())
 //! # }
@@ -71,7 +92,8 @@
 //!
 //! let mut visitor = Collect(BTreeMap::new());
 //!
-//! // info!("Something of interest"; a = 1, b = 2, c = 3);
+//! // info!(a = 1, b = 2, c = 3; "Something of interest");
+//!
 //! record.key_values().visit(&mut visitor)?;
 //!
 //! let collected = visitor.0;
@@ -94,7 +116,8 @@
 //! use log::kv::{Source, Key};
 //! # let record = log::Record::builder().key_values(&[("a", 1)]).build();
 //!
-//! // info!("Something of interest"; a = 1);
+//! // info!(a = 1; "Something of interest");
+//!
 //! let a = record.key_values().get(Key::from("a")).unwrap();
 //!
 //! assert_eq!(1, a.to_i64().unwrap());
@@ -144,7 +167,8 @@
 //!     }
 //! }
 //!
-//! // info!("Something of interest"; a = 1);
+//! // info!(a = 1; "Something of interest");
+//!
 //! let a = record.key_values().get(Key::from("a")).unwrap();
 //!
 //! let mut visitor = IsNumeric(false);
@@ -170,7 +194,8 @@
 //! # let source = [("a", log::kv::Value::from_serde(&data))];
 //! # let record = log::Record::builder().key_values(&source).build();
 //!
-//! // info!("Something of interest"; a = data);
+//! // info!(a = data; "Something of interest");
+//!
 //! let a = record.key_values().get(Key::from("a")).unwrap();
 //!
 //! assert_eq!("{\"a\":1,\"b\":true,\"c\":\"Some data\"}", serde_json::to_string(&a)?);
@@ -195,7 +220,8 @@
 //! # let source = [("a", log::kv::Value::from_debug(&data))];
 //! # let record = log::Record::builder().key_values(&source).build();
 //!
-//! // info!("Something of interest"; a = data);
+//! // info!(a = data; "Something of interest");
+//!
 //! let a = record.key_values().get(Key::from("a")).unwrap();
 //!
 //! assert_eq!("Data { a: 1, b: true, c: \"Some data\" }", format!("{a:?}"));