Simplify the Matcher trait

Now matchers need to implement a single `description` method, which will
return all the necessary information to build any kind of failure
message.

This removes the duplication between the old `failure_message` and
`negated_failure_message` and leaves the formatting logic for failure
messages in one single place, the `Expectation`.

I anticipate `Description` becoming more and more complex to accomodate
all sorts of failures, but we should be able to make it flexible enough
to accomodate all matchers.

Author: gcapizzi

src/lib.rs

@@ -21,32 +21,29 @@
 //! [`Matcher`]: trait.Matcher.html
 pub mod matchers;
 
+pub struct Description {
+    pub verb: String,
+    pub object: Option<String>,
+}
+
 /// The contract implemented by matchers.
 pub trait Matcher<T> {
     /// Should return `true` if `actual` is a match.
     fn match_value(&self, actual: &T) -> bool;
 
-    /// Should return an appropriate message for a failure to match `actual`, i.e. a failure caused
-    /// by `match_value` returning `false`.
-    ///
-    /// # Example
+    /// Should return a [`Description`] of the matcher, to be used for reporting. `actual` _should
+    /// not_ be necessary here, but is still passed for type-checking reasons.
     ///
-    /// ```
-    /// # use expect::{Matcher, matchers::equal};
-    /// assert_eq!(equal(2).failure_message(&3), String::from("\tExpected:\n\t\t3\n\tto equal:\n\t\t2"));
-    /// ```
-    fn failure_message(&self, actual: &T) -> String;
-
-    /// Should return an appropriate message for a failure *not* to match `actual`, i.e. a failure
-    /// caused by `match_value` returning `true`.
+    /// [`Expectation`]: struct.Description.html
     ///
     /// # Example
     ///
     /// ```
-    /// # use expect::{Matcher, matchers::equal};
-    /// assert_eq!(equal(2).negated_failure_message(&2), String::from("\tExpected:\n\t\t2\n\tnot to equal:\n\t\t2"));
+    /// # use expect::{Description, Matcher, matchers::EqualMatcher, matchers::equal};
+    /// assert_eq!(equal(2).description(&2).verb, String::from("equal"));
+    /// assert_eq!(equal(2).description(&2).object, Some(String::from("2")));
     /// ```
-    fn negated_failure_message(&self, actual: &T) -> String;
+    fn description(&self, actual: &T) -> Description;
 }
 
 /// Creates an [`Expectation`].
@@ -63,42 +60,61 @@ pub struct Expectation<'a, T> {
     actual: &'a T,
 }
 
-impl<'a, T> Expectation<'a, T> {
+impl<'a, T: std::fmt::Debug> Expectation<'a, T> {
     /// Checks the actual value agains a [`Matcher`], looking for a match.
     ///
-    /// If [`Matcher::match_value`] returns `false`, this method will [`panic!`] using the failure
-    /// message returned by [`Matcher::failure_message`].
+    /// If [`Matcher::match_value`] returns `false`, this method will [`panic!`] with a failure
+    /// message based on the [`Matcher::description`].
     ///
     /// [`Matcher`]: trait.Matcher.html
     /// [`Matcher::match_value`]: trait.Matcher.html#tymethod.match_value
-    /// [`Matcher::failure_message`]: trait.Matcher.html#tymethod.failure_message
-    /// [`Matcher::negated_failure_message`]: trait.Matcher.html#tymethod.negated_failure_message
+    /// [`Matcher::description`]: trait.Matcher.html#tymethod.description
     /// [`panic!`]: https://doc.rust-lang.org/std/macro.panic.html
     pub fn to<M: Matcher<T>>(&self, matcher: M) {
         if !matcher.match_value(&self.actual) {
-            fail_test(matcher.failure_message(&self.actual))
+            fail_test(&self.actual, matcher.description(&self.actual))
         }
     }
 
     /// Checks the actual value agains a [`Matcher`], looking for the lack of a match.
     ///
-    /// If [`Matcher::match_value`] returns `true`, this method will [`panic!`] using the failure
-    /// message returned by [`Matcher::negated_failure_message`].
+    /// If [`Matcher::match_value`] returns `true`, this method will [`panic!`] with a failure
+    /// message based on the [`Matcher::description`].
     ///
     /// [`Matcher`]: trait.Matcher.html
     /// [`Matcher::match_value`]: trait.Matcher.html#tymethod.match_value
-    /// [`Matcher::failure_message`]: trait.Matcher.html#tymethod.failure_message
-    /// [`Matcher::negated_failure_message`]: trait.Matcher.html#tymethod.negated_failure_message
+    /// [`Matcher::description`]: trait.Matcher.html#tymethod.description
     /// [`panic!`]: https://doc.rust-lang.org/std/macro.panic.html
     pub fn not_to<M: Matcher<T>>(&self, matcher: M) {
         if matcher.match_value(&self.actual) {
-            fail_test(matcher.negated_failure_message(&self.actual))
+            fail_test_negated(&self.actual, matcher.description(&self.actual))
         }
     }
 }
 
-fn fail_test(message: String) {
-    panic!("Expectation failed:\n{}\n", message)
+fn fail_test<T: std::fmt::Debug>(actual: T, description: Description) {
+    panic!(failure_message(actual, description, "to"))
+}
+
+fn fail_test_negated<T: std::fmt::Debug>(actual: T, description: Description) {
+    panic!(failure_message(actual, description, "not to"))
+}
+
+fn failure_message<T: std::fmt::Debug>(
+    actual: T,
+    description: Description,
+    before_verb: &str,
+) -> String {
+    let predicate = if let Some(obj) = description.object {
+        format!("{}:\n\t\t{}", description.verb, obj)
+    } else {
+        description.verb
+    };
+
+    format!(
+        "Expectation failed:\n\tExpected:\n\t\t{:?}\n\t{} {}\n",
+        actual, before_verb, predicate
+    )
 }
 
 #[cfg(test)]

src/matchers.rs

@@ -4,7 +4,7 @@ pub mod path;
 pub mod result;
 pub mod string;
 
-use crate::Matcher;
+use crate::{Description, Matcher};
 
 /// Matches if `expected` is equal to the actual value.
 ///
@@ -23,23 +23,16 @@ pub struct EqualMatcher<T> {
     expected: T,
 }
 
-impl<E: std::fmt::Debug, A: PartialEq<E> + std::fmt::Debug> Matcher<A> for EqualMatcher<E> {
+impl<E: std::fmt::Debug, A: PartialEq<E>> Matcher<A> for EqualMatcher<E> {
     fn match_value(&self, actual: &A) -> bool {
         actual == &self.expected
     }
 
-    fn failure_message(&self, actual: &A) -> String {
-        format!(
-            "\tExpected:\n\t\t{:?}\n\tto equal:\n\t\t{:?}",
-            actual, self.expected,
-        )
-    }
-
-    fn negated_failure_message(&self, actual: &A) -> String {
-        format!(
-            "\tExpected:\n\t\t{:?}\n\tnot to equal:\n\t\t{:?}",
-            actual, self.expected
-        )
+    fn description(&self, _actual: &A) -> Description {
+        Description {
+            verb: String::from("equal"),
+            object: Some(format!("{:?}", self.expected)),
+        }
     }
 }
 
@@ -64,14 +57,9 @@ mod tests {
     }
 
     #[test]
-    fn failure_messages() {
-        assert_eq!(
-            equal("foo").failure_message(&"bar"),
-            String::from("\tExpected:\n\t\t\"bar\"\n\tto equal:\n\t\t\"foo\"")
-        );
-        assert_eq!(
-            equal("foo").negated_failure_message(&"foo"),
-            String::from("\tExpected:\n\t\t\"foo\"\n\tnot to equal:\n\t\t\"foo\"")
-        );
+    fn should_describe_itself() {
+        let description = equal("foo").description(&"bar");
+        assert_eq!(description.verb, String::from("equal"));
+        assert_eq!(description.object, Some(String::from("\"foo\"")));
     }
 }

src/matchers/collection.rs

@@ -1,4 +1,4 @@
-use crate::Matcher;
+use crate::{Description, Matcher};
 
 use std::marker::PhantomData;
 
@@ -29,23 +29,16 @@ pub struct ContainMatcher<T> {
     element: T,
 }
 
-impl<T: std::fmt::Debug, V: Collection<T> + std::fmt::Debug> Matcher<V> for ContainMatcher<T> {
+impl<T: std::fmt::Debug, V: Collection<T>> Matcher<V> for ContainMatcher<T> {
     fn match_value(&self, collection: &V) -> bool {
         collection.contains_element(&self.element)
     }
 
-    fn failure_message(&self, collection: &V) -> String {
-        format!(
-            "\tExpected:\n\t\t{:?}\n\tto contain:\n\t\t{:?}",
-            collection, self.element
-        )
-    }
-
-    fn negated_failure_message(&self, collection: &V) -> String {
-        format!(
-            "\tExpected:\n\t\t{:?}\n\tnot to contain:\n\t\t{:?}",
-            collection, self.element
-        )
+    fn description(&self, _: &V) -> Description {
+        Description {
+            verb: String::from("contain"),
+            object: Some(format!("{:?}", self.element)),
+        }
     }
 }
 
@@ -77,17 +70,16 @@ pub struct BeEmptyMatcher<T> {
     phantom: PhantomData<T>,
 }
 
-impl<T, V: Collection<T> + std::fmt::Debug> Matcher<V> for BeEmptyMatcher<T> {
+impl<T, V: Collection<T>> Matcher<V> for BeEmptyMatcher<T> {
     fn match_value(&self, collection: &V) -> bool {
         collection.empty()
     }
 
-    fn failure_message(&self, collection: &V) -> String {
-        format!("\tExpected:\n\t\t{:?}\n\tto be empty", collection)
-    }
-
-    fn negated_failure_message(&self, collection: &V) -> String {
-        format!("\tExpected:\n\t\t{:?}\n\tnot to be empty", collection)
+    fn description(&self, _: &V) -> Description {
+        Description {
+            verb: String::from("be empty"),
+            object: None,
+        }
     }
 }
 
@@ -195,15 +187,10 @@ mod tests {
     }
 
     #[test]
-    fn contain_matcher_failure_messages() {
-        assert_eq!(
-            contain("foo").failure_message(&vec!["bar"]),
-            String::from("\tExpected:\n\t\t[\"bar\"]\n\tto contain:\n\t\t\"foo\"")
-        );
-        assert_eq!(
-            contain("foo").negated_failure_message(&vec!["foo"]),
-            String::from("\tExpected:\n\t\t[\"foo\"]\n\tnot to contain:\n\t\t\"foo\"")
-        );
+    fn contain_matcher_should_describe_itself() {
+        let description = contain("foo").description(&vec!["bar"]);
+        assert_eq!(description.verb, String::from("contain"));
+        assert_eq!(description.object, Some(String::from("\"foo\"")));
     }
 
     #[test]
@@ -217,15 +204,10 @@ mod tests {
     }
 
     #[test]
-    fn be_empty_matcher_failure_messages() {
-        assert_eq!(
-            be_empty().failure_message(&vec!["bar"]),
-            String::from("\tExpected:\n\t\t[\"bar\"]\n\tto be empty")
-        );
-        assert_eq!(
-            be_empty().negated_failure_message(&std::vec::Vec::<i32>::new()),
-            String::from("\tExpected:\n\t\t[]\n\tnot to be empty")
-        );
+    fn be_empty_matcher_should_describe_itself() {
+        let description = be_empty().description(&vec!["foo"]);
+        assert_eq!(description.verb, String::from("be empty"));
+        assert_eq!(description.object, None);
     }
 
     #[test]

src/matchers/option.rs

@@ -1,4 +1,4 @@
-use crate::Matcher;
+use crate::{Description, Matcher};
 
 /// Matches if `actual` is an [`Option::Some`].
 ///
@@ -17,17 +17,16 @@ pub fn be_some() -> SomeMatcher {
 
 pub struct SomeMatcher {}
 
-impl<T: std::fmt::Debug> Matcher<Option<T>> for SomeMatcher {
+impl<T> Matcher<Option<T>> for SomeMatcher {
     fn match_value(&self, actual: &Option<T>) -> bool {
         actual.is_some()
     }
 
-    fn failure_message(&self, actual: &Option<T>) -> String {
-        format!("\tExpected:\n\t\t{:?}\n\tto be a Some", actual)
-    }
-
-    fn negated_failure_message(&self, actual: &Option<T>) -> String {
-        format!("\tExpected:\n\t\t{:?}\n\tnot to be a Some", actual)
+    fn description(&self, _: &Option<T>) -> Description {
+        Description {
+            verb: String::from("be a Some"),
+            object: None,
+        }
     }
 }
 
@@ -48,17 +47,16 @@ pub fn be_none() -> NoneMatcher {
 
 pub struct NoneMatcher {}
 
-impl<T: std::fmt::Debug> Matcher<Option<T>> for NoneMatcher {
+impl<T> Matcher<Option<T>> for NoneMatcher {
     fn match_value(&self, actual: &Option<T>) -> bool {
         actual.is_none()
     }
 
-    fn failure_message(&self, actual: &Option<T>) -> String {
-        format!("\tExpected:\n\t\t{:?}\n\tto be None", actual)
-    }
-
-    fn negated_failure_message(&self, actual: &Option<T>) -> String {
-        format!("\tExpected:\n\t\t{:?}\n\tnot to be None", actual)
+    fn description(&self, _: &Option<T>) -> Description {
+        Description {
+            verb: String::from("be None"),
+            object: None,
+        }
     }
 }
 
@@ -78,15 +76,10 @@ mod tests {
     }
 
     #[test]
-    fn some_matcher_failure_messages() {
-        assert_eq!(
-            be_some().failure_message(&None::<&str>),
-            String::from("\tExpected:\n\t\tNone\n\tto be a Some")
-        );
-        assert_eq!(
-            be_some().negated_failure_message(&Some("foo")),
-            String::from("\tExpected:\n\t\tSome(\"foo\")\n\tnot to be a Some")
-        );
+    fn some_matcher_should_describe_itself() {
+        let description = be_some().description(&Some("bar"));
+        assert_eq!(description.verb, String::from("be a Some"));
+        assert_eq!(description.object, None);
     }
 
     #[test]
@@ -100,14 +93,9 @@ mod tests {
     }
 
     #[test]
-    fn none_matcher_failure_messages() {
-        assert_eq!(
-            be_none().failure_message(&Some("foo")),
-            String::from("\tExpected:\n\t\tSome(\"foo\")\n\tto be None")
-        );
-        assert_eq!(
-            be_none().negated_failure_message(&None::<&str>),
-            String::from("\tExpected:\n\t\tNone\n\tnot to be None")
-        );
+    fn none_matcher_should_describe_itself() {
+        let description = be_none().description(&None::<&str>);
+        assert_eq!(description.verb, String::from("be None"));
+        assert_eq!(description.object, None);
     }
 }