Parameterize Matcher::matches and Matcher::explain_match.

This allows the use of smart pointers for the actual value when invoking
`Matcher::matches` and `Matcher::explain_match`. The Protobuf
implementation namely uses a
[kind of smart pointer](https://github.com/protocolbuffers/protobuf/blob/62d5d9bf67d27d3b0084dabcf67bff2f8238162b/rust/proxied.rs#L113).
The lifetime on that smart pointer has no a priori relation to that of
the parameter `actual`, causing the borrow checker to complain whenever
invoking an inner matcher on the output of `as_view`.

This commit addresses the problem by allowing the `ViewProxy` -- rather
than a reference to it -- to be passed directly to `Matcher::matches`
and `Matcher::explain_match`. It does this by making those two methods
generic with respect to the input type. They must only implement
`Deref<Target = Self::ActualT>`.

The new test `googletest/tests/arena_test.rs` illustrates this with a
simplified example.

Introducing these generics unfortunately makes `Matcher` no longer
object-safe. Since several matchers construct trait objts on `Matcher`,
this also introduces an internal-only wrapper trait `ObjectSafeMatcher`
which every `Matcher` auto-implements.

While this makes some changes to how `Matcher` is defined and
implemented, it should have no effect on how it is _used_, other than
to fix the aforementioned problem. So it should not affect compatibility
for most users of the crate.

Fixes #323.

Author: hovinen

googletest/crate_docs.md

@@ -214,7 +214,7 @@ a struct holding the matcher's data and have it implement the trait
 
 ```no_run
 use googletest::{description::Description, matcher::{Matcher, MatcherResult}};
-use std::fmt::Debug;
+use std::{fmt::Debug, ops::Deref};
 
 struct MyEqMatcher<T> {
     expected: T,
@@ -223,7 +223,10 @@ struct MyEqMatcher<T> {
 impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
     type ActualT = T;
 
-    fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
+    fn matches<ActualRefT: Deref<Target = Self::ActualT>>(
+        &self,
+        actual: ActualRefT,
+    ) -> MatcherResult {
         if self.expected == *actual {
             MatcherResult::Match
         } else {
@@ -248,7 +251,7 @@ impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
 
  ```no_run
  # use googletest::{description::Description, matcher::{Matcher, MatcherResult}};
- # use std::fmt::Debug;
+ # use std::{fmt::Debug, ops::Deref};
  #
  # struct MyEqMatcher<T> {
  #    expected: T,
@@ -257,7 +260,10 @@ impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
  # impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
  #    type ActualT = T;
  #
- #    fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
+ #    fn matches<ActualRefT: Deref<Target = Self::ActualT>>(
+ #        &self,
+ #        actual: ActualRefT,
+ #    ) -> MatcherResult {
  #        if self.expected == *actual {
  #            MatcherResult::Match
  #        } else {
@@ -287,7 +293,7 @@ impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
 ```
 # use googletest::prelude::*;
 # use googletest::{description::Description, matcher::{Matcher, MatcherResult}};
-# use std::fmt::Debug;
+# use std::{fmt::Debug, ops::Deref};
 #
 # struct MyEqMatcher<T> {
 #    expected: T,
@@ -296,7 +302,10 @@ impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
 # impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
 #    type ActualT = T;
 #
-#    fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
+#    fn matches<ActualRefT: Deref<Target = Self::ActualT>>(
+#        &self,
+#        actual: ActualRefT,
+#    ) -> MatcherResult {
 #        if self.expected == *actual {
 #            MatcherResult::Match
 #        } else {

googletest/src/matcher.rs

@@ -20,6 +20,7 @@ use crate::internal::test_outcome::TestAssertionFailure;
 use crate::matchers::__internal_unstable_do_not_depend_on_these::ConjunctionMatcher;
 use crate::matchers::__internal_unstable_do_not_depend_on_these::DisjunctionMatcher;
 use std::fmt::Debug;
+use std::ops::Deref;
 
 /// An interface for checking an arbitrary condition on a datum.
 pub trait Matcher {
@@ -32,7 +33,10 @@ pub trait Matcher {
     /// matching condition is based on data stored in the matcher. For example,
     /// `eq` matches when its stored expected value is equal (in the sense of
     /// the `==` operator) to the value `actual`.
-    fn matches(&self, actual: &Self::ActualT) -> MatcherResult;
+    fn matches<ActualRefT: Deref<Target = Self::ActualT> + Clone>(
+        &self,
+        actual: ActualRefT,
+    ) -> MatcherResult;
 
     /// Returns a description of `self` or a negative description if
     /// `matcher_result` is `DoesNotMatch`.
@@ -133,7 +137,10 @@ pub trait Matcher {
     ///         .nested(self.expected.explain_match(actual.deref()))
     /// }
     /// ```
-    fn explain_match(&self, actual: &Self::ActualT) -> Description {
+    fn explain_match<ActualRefT: Deref<Target = Self::ActualT> + Clone>(
+        &self,
+        actual: ActualRefT,
+    ) -> Description {
         format!("which {}", self.describe(self.matches(actual))).into()
     }
 
@@ -201,6 +208,46 @@ pub trait Matcher {
     }
 }
 
+/// Functionality used by macros within this crate.
+///
+/// For internal use only. API stablility is not guaranteed!
+#[doc(hidden)]
+pub mod __internal_unstable_do_not_depend_on_these {
+    use super::{Matcher, MatcherResult};
+    use crate::description::Description;
+    use std::fmt::Debug;
+
+    /// A variant of [`Matcher`] which is object-safe.
+    ///
+    /// This is used in contexts where a `dyn Matcher` is required. It supplies all methods of
+    /// [`Matcher`] but without any generics on the methods.
+    pub trait ObjectSafeMatcher {
+        type ActualT: Debug + ?Sized;
+
+        fn obj_matches(&self, actual: &Self::ActualT) -> MatcherResult;
+
+        fn obj_describe(&self, matcher_result: MatcherResult) -> Description;
+
+        fn obj_explain_match(&self, actual: &Self::ActualT) -> Description;
+    }
+
+    impl<MatcherT: Matcher> ObjectSafeMatcher for MatcherT {
+        type ActualT = <Self as Matcher>::ActualT;
+
+        fn obj_matches(&self, actual: &Self::ActualT) -> MatcherResult {
+            Matcher::matches(self, actual)
+        }
+
+        fn obj_describe(&self, matcher_result: MatcherResult) -> Description {
+            Matcher::describe(self, matcher_result)
+        }
+
+        fn obj_explain_match(&self, actual: &Self::ActualT) -> Description {
+            Matcher::explain_match(self, actual)
+        }
+    }
+}
+
 /// Any actual value whose debug length is greater than this value will be
 /// pretty-printed. Otherwise, it will have normal debug output formatting.
 const PRETTY_PRINT_LENGTH_THRESHOLD: usize = 60;
@@ -245,7 +292,11 @@ pub enum MatcherResult {
 
 impl From<bool> for MatcherResult {
     fn from(b: bool) -> Self {
-        if b { MatcherResult::Match } else { MatcherResult::NoMatch }
+        if b {
+            MatcherResult::Match
+        } else {
+            MatcherResult::NoMatch
+        }
     }
 }
 

googletest/src/matchers/all_matcher.rs

@@ -65,34 +65,40 @@ macro_rules! __all {
 #[doc(hidden)]
 pub mod internal {
     use crate::description::Description;
-    use crate::matcher::{Matcher, MatcherResult};
+    use crate::matcher::{
+        Matcher, MatcherResult, __internal_unstable_do_not_depend_on_these::ObjectSafeMatcher,
+    };
     use crate::matchers::anything;
     use std::fmt::Debug;
+    use std::ops::Deref;
 
     /// A matcher which matches an input value matched by all matchers in the
     /// array `components`.
     ///
     /// For internal use only. API stablility is not guaranteed!
     #[doc(hidden)]
     pub struct AllMatcher<'a, T: Debug + ?Sized, const N: usize> {
-        components: [Box<dyn Matcher<ActualT = T> + 'a>; N],
+        components: [Box<dyn ObjectSafeMatcher<ActualT = T> + 'a>; N],
     }
 
     impl<'a, T: Debug + ?Sized, const N: usize> AllMatcher<'a, T, N> {
         /// Constructs an [`AllMatcher`] with the given component matchers.
         ///
         /// Intended for use only by the [`all`] macro.
-        pub fn new(components: [Box<dyn Matcher<ActualT = T> + 'a>; N]) -> Self {
+        pub fn new(components: [Box<dyn ObjectSafeMatcher<ActualT = T> + 'a>; N]) -> Self {
             Self { components }
         }
     }
 
     impl<'a, T: Debug + ?Sized, const N: usize> Matcher for AllMatcher<'a, T, N> {
         type ActualT = T;
 
-        fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
+        fn matches<ActualRefT: Deref<Target = Self::ActualT> + Clone>(
+            &self,
+            actual: ActualRefT,
+        ) -> MatcherResult {
             for component in &self.components {
-                match component.matches(actual) {
+                match component.obj_matches(actual.deref()) {
                     MatcherResult::NoMatch => {
                         return MatcherResult::NoMatch;
                     }
@@ -102,25 +108,28 @@ pub mod internal {
             MatcherResult::Match
         }
 
-        fn explain_match(&self, actual: &Self::ActualT) -> Description {
+        fn explain_match<ActualRefT: Deref<Target = Self::ActualT> + Clone>(
+            &self,
+            actual: ActualRefT,
+        ) -> Description {
             match N {
                 0 => anything::<T>().explain_match(actual),
-                1 => self.components[0].explain_match(actual),
+                1 => self.components[0].obj_explain_match(actual.deref()),
                 _ => {
                     let failures = self
                         .components
                         .iter()
-                        .filter(|component| component.matches(actual).is_no_match())
+                        .filter(|component| component.obj_matches(actual.deref()).is_no_match())
                         .collect::<Vec<_>>();
 
                     if failures.len() == 1 {
-                        failures[0].explain_match(actual)
+                        failures[0].obj_explain_match(actual.deref())
                     } else {
                         Description::new()
                             .collect(
                                 failures
                                     .into_iter()
-                                    .map(|component| component.explain_match(actual)),
+                                    .map(|component| component.obj_explain_match(actual.deref())),
                             )
                             .bullet_list()
                     }
@@ -131,17 +140,17 @@ pub mod internal {
         fn describe(&self, matcher_result: MatcherResult) -> Description {
             match N {
                 0 => anything::<T>().describe(matcher_result),
-                1 => self.components[0].describe(matcher_result),
+                1 => self.components[0].obj_describe(matcher_result),
                 _ => {
                     let header = if matcher_result.into() {
                         "has all the following properties:"
                     } else {
                         "has at least one of the following properties:"
                     };
                     Description::new().text(header).nested(
-                        Description::new()
-                            .bullet_list()
-                            .collect(self.components.iter().map(|m| m.describe(matcher_result))),
+                        Description::new().bullet_list().collect(
+                            self.components.iter().map(|m| m.obj_describe(matcher_result)),
+                        ),
                     )
                 }
             }

googletest/src/matchers/any_matcher.rs

@@ -67,54 +67,65 @@ macro_rules! __any {
 #[doc(hidden)]
 pub mod internal {
     use crate::description::Description;
-    use crate::matcher::{Matcher, MatcherResult};
+    use crate::matcher::{
+        Matcher, MatcherResult, __internal_unstable_do_not_depend_on_these::ObjectSafeMatcher,
+    };
     use crate::matchers::anything;
     use std::fmt::Debug;
+    use std::ops::Deref;
 
     /// A matcher which matches an input value matched by all matchers in the
     /// array `components`.
     ///
     /// For internal use only. API stablility is not guaranteed!
     #[doc(hidden)]
     pub struct AnyMatcher<'a, T: Debug + ?Sized, const N: usize> {
-        components: [Box<dyn Matcher<ActualT = T> + 'a>; N],
+        components: [Box<dyn ObjectSafeMatcher<ActualT = T> + 'a>; N],
     }
 
     impl<'a, T: Debug + ?Sized, const N: usize> AnyMatcher<'a, T, N> {
         /// Constructs an [`AnyMatcher`] with the given component matchers.
         ///
         /// Intended for use only by the [`all`] macro.
-        pub fn new(components: [Box<dyn Matcher<ActualT = T> + 'a>; N]) -> Self {
+        pub fn new(components: [Box<dyn ObjectSafeMatcher<ActualT = T> + 'a>; N]) -> Self {
             Self { components }
         }
     }
 
     impl<'a, T: Debug + ?Sized, const N: usize> Matcher for AnyMatcher<'a, T, N> {
         type ActualT = T;
 
-        fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
-            MatcherResult::from(self.components.iter().any(|c| c.matches(actual).is_match()))
+        fn matches<ActualRefT: Deref<Target = Self::ActualT>>(
+            &self,
+            actual: ActualRefT,
+        ) -> MatcherResult {
+            MatcherResult::from(
+                self.components.iter().any(|c| c.obj_matches(actual.deref()).is_match()),
+            )
         }
 
-        fn explain_match(&self, actual: &Self::ActualT) -> Description {
+        fn explain_match<ActualRefT: Deref<Target = Self::ActualT>>(
+            &self,
+            actual: ActualRefT,
+        ) -> Description {
             match N {
                 0 => format!("which {}", anything::<T>().describe(MatcherResult::NoMatch)).into(),
-                1 => self.components[0].explain_match(actual),
+                1 => self.components[0].obj_explain_match(actual.deref()),
                 _ => {
                     let failures = self
                         .components
                         .iter()
-                        .filter(|component| component.matches(actual).is_no_match())
+                        .filter(|component| component.obj_matches(actual.deref()).is_no_match())
                         .collect::<Vec<_>>();
 
                     if failures.len() == 1 {
-                        failures[0].explain_match(actual)
+                        failures[0].obj_explain_match(actual.deref())
                     } else {
                         Description::new()
                             .collect(
                                 failures
                                     .into_iter()
-                                    .map(|component| component.explain_match(actual)),
+                                    .map(|component| component.obj_explain_match(actual.deref())),
                             )
                             .bullet_list()
                     }
@@ -125,12 +136,12 @@ pub mod internal {
         fn describe(&self, matcher_result: MatcherResult) -> Description {
             match N {
                 0 => anything::<T>().describe(matcher_result),
-                1 => self.components[0].describe(matcher_result),
+                1 => self.components[0].obj_describe(matcher_result),
                 _ => {
                     let properties = self
                         .components
                         .iter()
-                        .map(|m| m.describe(matcher_result))
+                        .map(|m| m.obj_describe(matcher_result))
                         .collect::<Description>()
                         .bullet_list()
                         .indent();

googletest/src/matchers/anything_matcher.rs

@@ -16,7 +16,7 @@ use crate::{
     description::Description,
     matcher::{Matcher, MatcherResult},
 };
-use std::{fmt::Debug, marker::PhantomData};
+use std::{fmt::Debug, marker::PhantomData, ops::Deref};
 
 /// Matches anything. This matcher always succeeds.
 ///
@@ -41,7 +41,7 @@ struct Anything<T: ?Sized>(PhantomData<T>);
 impl<T: Debug + ?Sized> Matcher for Anything<T> {
     type ActualT = T;
 
-    fn matches(&self, _: &T) -> MatcherResult {
+    fn matches<ActualRefT: Deref<Target = Self::ActualT>>(&self, _: ActualRefT) -> MatcherResult {
         MatcherResult::Match
     }