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

pkg/matcher/lib/src/expect.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 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 {
   final String message;
 
   TestFailure(this.message);
 
   String toString() => message;
 }
 
-/// Useful utility for nesting match states.
+/// 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);
 
-void addStateInfo(Map matchState, Map values) {
-  var innerState = new Map.from(matchState);
-  matchState.clear();
-  matchState['state'] = innerState;
-  matchState.addAll(values);
+  /// 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
 /// such exceptions. The [wrapAsync] property is a function that
 /// can wrap callbacks used by these Matchers so that they can be
 /// used safely. For example, the unittest library will set this
 /// to be `expectAsync`. By default this is an identity function.
 Function wrapAsync = (Function f, [id]) => f;
 
 /// This is the main assertion function. It asserts that [actual]
@@ skipping 35 matching lines @@
   }
 }
 
 void fail(String message, {FailureHandler failureHandler}) {
   if (failureHandler == null) {
     failureHandler = getOrCreateExpectFailureHandler();
   }
   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;
 
 // The default failure handler that throws [TestFailure]s.
 class DefaultFailureHandler implements FailureHandler {
   DefaultFailureHandler() {
     if (_assertErrorFormatter == null) {
       _assertErrorFormatter = _defaultErrorFormatter;
     }
   }
@@ skipping 50 matching lines @@
 /// [formatter] is a reference to the new formatter; if this is omitted or
 /// null then the failure formatter is reset to the default. The new
 /// formatter is returned; this allows custom expect handlers to easily
 /// get a reference to the default formatter.
 ErrorFormatter configureExpectFormatter([ErrorFormatter formatter = null]) {
   if (formatter == null) {
     formatter = _defaultErrorFormatter;
   }
   return _assertErrorFormatter = formatter;
 }