rename diagnostic --> report, add into_owned

src/assign.rs

@@ -37,7 +37,7 @@
 //!
 
 use crate::{
-    diagnostic::{impl_diagnostic_url, IntoDiagnostic, Label},
+    diagnostic::{impl_diagnostic_url, Diagnostic, Label},
     index::{OutOfBoundsError, ParseIndexError},
     Pointer,
 };
@@ -228,7 +228,7 @@ impl fmt::Display for Error {
     }
 }
 
-impl<'s> IntoDiagnostic<'s> for Error {
+impl<'s> Diagnostic<'s> for Error {
     type Subject = Cow<'s, Pointer>;
 
     fn url() -> &'static str {

src/diagnostic.rs

@@ -2,14 +2,14 @@
 
 use core::fmt;
 
-/// Implemented by errors which can be converted into a [`Diagnostic`].
-pub trait IntoDiagnostic<'s>: Sized + private::Sealed {
+/// Implemented by errors which can be converted into a [`Report`].
+pub trait Diagnostic<'s>: Sized + private::Sealed {
     /// The value which caused the error.
-    type Subject;
+    type Subject: private::IntoOwned;
 
-    /// Enrich the error with its subject.
-    fn enrich(self, subject: impl Into<Self::Subject>) -> Diagnostic<'s, Self> {
-        Diagnostic::new(self, subject)
+    /// Combine the error with its subject to generate a [`Report`].
+    fn into_report(self, subject: impl Into<Self::Subject>) -> Report<'s, Self> {
+        Report::new(self, subject)
     }
 
     /// The docs.rs URL for this error
@@ -41,15 +41,14 @@ impl From<Label> for miette::LabeledSpan {
     }
 }
 
-/// An error wrapper which includes the [`String`] which failed to parse or the
-/// [`PointerBuf`] being used.
+/// An error wrapper which includes the subject of the failure.
 #[derive(Clone, PartialEq, Eq)]
-pub struct Diagnostic<'s, S: IntoDiagnostic<'s>> {
+pub struct Report<'s, S: Diagnostic<'s>> {
     source: S,
     subject: S::Subject,
 }
 
-impl<'s, S: IntoDiagnostic<'s>> Diagnostic<'s, S> {
+impl<'s, S: Diagnostic<'s>> Report<'s, S> {
     /// Create a new `Report` with the given subject and error.
     fn new(source: S, subject: impl Into<S::Subject>) -> Self {
         Self {
@@ -68,15 +67,36 @@ impl<'s, S: IntoDiagnostic<'s>> Diagnostic<'s, S> {
         &self.source
     }
 
-    /// The original parts of the [`Diagnostic`].
+    /// The original parts of the [`Report`].
     pub fn decompose(self) -> (S, S::Subject) {
         (self.source, self.subject)
     }
 }
 
-impl<'s, S> core::ops::Deref for Diagnostic<'s, S>
+impl<'s, S> Report<'s, S>
 where
-    S: IntoDiagnostic<'s>,
+    S: Diagnostic<'s>,
+{
+    /// Converts the Report into an owned instance (generally by cloning the subject).
+    pub fn into_owned<O>(self) -> Report<'static, O>
+    where
+        S: Into<O>,
+        O: Diagnostic<'static, Subject = <S::Subject as private::IntoOwned>::Owned>,
+    {
+        use private::IntoOwned;
+
+        Report {
+            // TODO: is there a way to avoid the `Into` here? We really want `S == O`,
+            // but I'm strugggling to express that without a bound predicate cycle
+            source: self.source.into(),
+            subject: self.subject.into_owned(),
+        }
+    }
+}
+
+impl<'s, S> core::ops::Deref for Report<'s, S>
+where
+    S: Diagnostic<'s>,
 {
     type Target = S;
 
@@ -85,18 +105,18 @@ where
     }
 }
 
-impl<'s, S> fmt::Display for Diagnostic<'s, S>
+impl<'s, S> fmt::Display for Report<'s, S>
 where
-    S: IntoDiagnostic<'s> + fmt::Display,
+    S: Diagnostic<'s> + fmt::Display,
 {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         fmt::Display::fmt(&self.source, f)
     }
 }
 
-impl<'s, S> fmt::Debug for Diagnostic<'s, S>
+impl<'s, S> fmt::Debug for Report<'s, S>
 where
-    S: IntoDiagnostic<'s> + fmt::Debug,
+    S: Diagnostic<'s> + fmt::Debug,
     S::Subject: fmt::Debug,
 {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
@@ -108,9 +128,9 @@ where
 }
 
 #[cfg(feature = "std")]
-impl<'s, S> std::error::Error for Diagnostic<'s, S>
+impl<'s, S> std::error::Error for Report<'s, S>
 where
-    S: IntoDiagnostic<'s> + fmt::Debug + std::error::Error + 'static,
+    S: Diagnostic<'s> + fmt::Debug + std::error::Error + 'static,
     S::Subject: fmt::Debug,
 {
     fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
@@ -119,9 +139,9 @@ where
 }
 
 #[cfg(feature = "miette")]
-impl<'s, S> miette::Diagnostic for Diagnostic<'s, S>
+impl<'s, S> miette::Diagnostic for Report<'s, S>
 where
-    S: IntoDiagnostic<'s> + fmt::Debug + std::error::Error + 'static,
+    S: Diagnostic<'s> + fmt::Debug + std::error::Error + 'static,
     S::Subject: fmt::Debug + miette::SourceCode,
 {
     fn url<'a>(&'a self) -> Option<Box<dyn core::fmt::Display + 'a>> {
@@ -167,44 +187,69 @@ macro_rules! impl_diagnostic_url {
 pub(crate) use impl_diagnostic_url;
 
 mod private {
+    use crate::Pointer;
+    use alloc::borrow::Cow;
+
     pub trait Sealed {}
     impl Sealed for crate::pointer::ParseError {}
     impl Sealed for crate::assign::Error {}
+
+    pub trait IntoOwned {
+        type Owned: 'static;
+
+        fn into_owned(self) -> Self::Owned;
+    }
+
+    impl<'s> IntoOwned for Cow<'s, str> {
+        type Owned = Cow<'static, str>;
+
+        fn into_owned(self) -> Cow<'static, str> {
+            Cow::Owned(self.into_owned())
+        }
+    }
+
+    impl<'s> IntoOwned for Cow<'s, Pointer> {
+        type Owned = Cow<'static, Pointer>;
+
+        fn into_owned(self) -> Cow<'static, Pointer> {
+            Cow::Owned(self.into_owned())
+        }
+    }
 }
 
 pub trait Diagnose<'s, T> {
-    type Error: IntoDiagnostic<'s>;
+    type Error: Diagnostic<'s>;
 
     #[allow(clippy::missing_errors_doc)]
     fn diagnose(
         self,
-        subject: impl Into<<Self::Error as IntoDiagnostic<'s>>::Subject>,
-    ) -> Result<T, Diagnostic<'s, Self::Error>>;
+        subject: impl Into<<Self::Error as Diagnostic<'s>>::Subject>,
+    ) -> Result<T, Report<'s, Self::Error>>;
 
     #[allow(clippy::missing_errors_doc)]
-    fn diagnose_with<F, S>(self, f: F) -> Result<T, Diagnostic<'s, Self::Error>>
+    fn diagnose_with<F, S>(self, f: F) -> Result<T, Report<'s, Self::Error>>
     where
         F: FnOnce() -> S,
-        S: Into<<Self::Error as IntoDiagnostic<'s>>::Subject>;
+        S: Into<<Self::Error as Diagnostic<'s>>::Subject>;
 }
 
 impl<'s, T, E> Diagnose<'s, T> for Result<T, E>
 where
-    E: IntoDiagnostic<'s>,
+    E: Diagnostic<'s>,
 {
     type Error = E;
 
     fn diagnose(
         self,
-        subject: impl Into<<Self::Error as IntoDiagnostic<'s>>::Subject>,
-    ) -> Result<T, Diagnostic<'s, Self::Error>> {
-        self.map_err(|error| error.enrich(subject.into()))
+        subject: impl Into<<Self::Error as Diagnostic<'s>>::Subject>,
+    ) -> Result<T, Report<'s, Self::Error>> {
+        self.map_err(|error| error.into_report(subject.into()))
     }
 
-    fn diagnose_with<F, S>(self, f: F) -> Result<T, Diagnostic<'s, Self::Error>>
+    fn diagnose_with<F, S>(self, f: F) -> Result<T, Report<'s, Self::Error>>
     where
         F: FnOnce() -> S,
-        S: Into<<Self::Error as IntoDiagnostic<'s>>::Subject>,
+        S: Into<<Self::Error as Diagnostic<'s>>::Subject>,
     {
         self.diagnose(f())
     }
@@ -213,7 +258,7 @@ where
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::{Pointer, PointerBuf};
+    use crate::{ParseError, Pointer, PointerBuf};
 
     #[test]
     #[cfg(all(
@@ -246,4 +291,22 @@ mod tests {
         let report = miette::Report::from(report);
         println!("{report:?}");
     }
+
+    #[test]
+    fn into_owned() {
+        // NOTE: the type has to be fully specified here because of the `S: Into<O>` bound
+        // in `Report::into_owned`. Ideally we'd express `S == O` so that the output can
+        // be automatically inferred.
+        let owned_report: Report<'static, ParseError> = {
+            // creating owned string to ensure its lifetime is local
+            // (could also coerce a static reference, but this is less brittle)
+            let invalid = "/foo/bar/invalid~3~encoding/cannot/reach".to_string();
+            let report = Pointer::parse(&invalid)
+                .diagnose(invalid.as_str())
+                .unwrap_err();
+            report.into_owned()
+        };
+
+        println!("{owned_report}");
+    }
 }

src/pointer.rs

@@ -1,5 +1,5 @@
 use crate::{
-    diagnostic::{impl_diagnostic_url, Diagnostic, IntoDiagnostic, Label},
+    diagnostic::{impl_diagnostic_url, Diagnostic, Label, Report},
     token::InvalidEncodingError,
     Components, Token, Tokens,
 };
@@ -942,11 +942,11 @@ impl PointerBuf {
     ///
     /// ## Errors
     /// Returns a [`RichParseError`] if the string is not a valid JSON Pointer.
-    pub fn parse<'s>(s: impl Into<Cow<'s, str>>) -> Result<Self, Diagnostic<'s, ParseError>> {
+    pub fn parse<'s>(s: impl Into<Cow<'s, str>>) -> Result<Self, RichParseError<'s>> {
         let s = s.into();
         match validate(&s) {
             Ok(_) => Ok(Self(s.into_owned())),
-            Err(err) => Err(err.enrich(s)),
+            Err(err) => Err(err.into_report(s)),
         }
     }
 
@@ -1277,7 +1277,7 @@ impl ParseError {
     }
 }
 
-impl<'s> IntoDiagnostic<'s> for ParseError {
+impl<'s> Diagnostic<'s> for ParseError {
     type Subject = Cow<'s, str>;
 
     fn url() -> &'static str {
@@ -1387,6 +1387,8 @@ impl std::error::Error for ParseError {
     }
 }
 
+pub type RichParseError<'s> = Report<'s, ParseError>;
+
 /*
 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
 ╔══════════════════════════════════════════════════════════════════════════════╗