pkg/matcher: refactored code around data-structure vs execution-based matchers

pkg/matcher/lib/src/expect.dart

Index: pkg/matcher/lib/src/expect.dart
diff --git a/pkg/matcher/lib/src/expect.dart b/pkg/matcher/lib/src/expect.dart
index 073ef34300b24116fd61506758bc6e5b6e3d2030..bd54747685403042ad7830864c949482ce78c9fc 100644
--- a/pkg/matcher/lib/src/expect.dart
+++ b/pkg/matcher/lib/src/expect.dart
@@ -7,6 +7,7 @@ library matcher.expect;
 import 'core_matchers.dart';
 import 'description.dart';
 import 'interfaces.dart';
+import 'util.dart';
 
 /// The objects thrown by the default failure handler.
 class TestFailure extends Error {
@@ -17,15 +18,33 @@ class TestFailure extends Error {
   String toString() => message;
 }
 
-/// Useful utility for nesting match states.
-
-void addStateInfo(Map matchState, Map values) {
-  var innerState = new Map.from(matchState);
-  matchState.clear();
-  matchState['state'] = innerState;
-  matchState.addAll(values);
+/// Failed matches are reported using a default IFailureHandler.
+/// The default implementation simply throws [TestFailure]s;
+/// this can be replaced by some other implementation of
+/// IFailureHandler by calling configureExpectHandler.
+abstract class FailureHandler {
+  /// This handles failures given a textual decription
+  void fail(String reason);
+
+  /// This handles failures given the actual [value], the [matcher]
+  /// the [reason] (argument from [expect]), some additonal [matchState]
+  /// generated by the [matcher], and a verbose flag which controls in
+  /// some cases how much [matchState] information is used. It will use
+  /// these to create a detailed error message (typically by calling
+  /// an [ErrorFormatter]) and then call [fail] with this message.
+  void failMatch(actual, Matcher matcher, String reason,
+                 Map matchState, bool verbose);
 }
 
+/// The ErrorFormatter type is used for functions that
+/// can be used to build up error reports upon [expect] failures.
+/// There is one built-in implementation ([defaultErrorFormatter])
+/// which is used by the default failure handler. If the failure handler
+/// is replaced it may be desirable to replace the [stringDescription]
+/// error formatter with another.
+typedef String ErrorFormatter(actual, Matcher matcher, String reason,
+  Map matchState, bool verbose);
+
 /// Some matchers, like those for Futures and exception testing,
 /// can fail in asynchronous sections, and throw exceptions.
 /// A user of this library will typically want to catch and handle
@@ -81,20 +100,6 @@ void fail(String message, {FailureHandler failureHandler}) {
   failureHandler.fail(message);
 }
 
-/// Takes an argument and returns an equivalent matcher.
-/// If the argument is already a matcher this does nothing,
-/// else if the argument is a function, it generates a predicate
-/// function matcher, else it generates an equals matcher.
-Matcher wrapMatcher(x) {
-  if (x is Matcher) {
-    return x;
-  } else if (x is Function) {
-    return predicate(x);
-  } else {
-    return equals(x);
-  }
-}
-
 // The handler for failed asserts.
 FailureHandler _assertFailureHandler = null;