Added a new Matcher, FeatureMatcher, that is a useful abstract base class

pkg/unittest/core_matchers.dart

Index: pkg/unittest/core_matchers.dart
===================================================================
--- pkg/unittest/core_matchers.dart	(revision 13752)
+++ pkg/unittest/core_matchers.dart	(working copy)
@@ -625,3 +625,54 @@
   Description describe(Description description) =>
       description.add(_description);
 }
+
+/**
+ * A useful utility class for implementing other matchers through inheritance.
+ * Derived classes should call the base constructor with a feature name and
+ * description, and an instance matcher, and should implement the
+ * [featureValueOf] abstract method.
+ *
+ * The feature description will typically describe the item and the feature,
+ * while the feature name will just name the feature. For example, we may
+ * have a Widget class where each Widget has a price; we could make a
+ * FeatureMatcher that can make assertions about prices with:
+ *
+ *     class HasPrice extends FeatureMatcher {
+ *       const HasPrice(matcher) :
+ *           super("Widget with price that is", "price", matcher);
+ *       featureValueOf(actual) => actual.price;
+ *     }
+ *
+ * and then use this for example like:
+ *
+ *      expect(inventoryItem, HasPrice(greaterThan(0)));

[Siggi Cherem (dart-lang), 2012/10/17 19:53:05]

HasPrice => new HasPrice?

+ */
+abstract class FeatureMatcher extends BaseMatcher {

[Siggi Cherem (dart-lang), 2012/10/17 19:54:01]

an alternative name: CustomMatcher?

+  final String _featureDescription;
+  final String _featureName;
+  final Matcher _matcher;
+
+  const FeatureMatcher(this._featureDescription, this._featureName,
+      this._matcher);
+
+  /** Implement this to extract the interesting feature.*/
+  featureValueOf(actual);
+
+  bool matches(item, MatchState matchState) {
+    var f = featureValueOf(item);
+    if (_matcher.matches(f, matchState)) return true;
+    matchState.state = { 'innerState': matchState.state, 'feature': f };
+    return false;
+  }
+
+  Description describe(Description description) =>
+      description.add(_featureDescription).add(' ').addDescriptionOf(_matcher);
+
+  Description describeMismatch(item, Description mismatchDescription,
+                               MatchState matchState, bool verbose) {
+    mismatchDescription.add(_featureName).add(' ');
+    _matcher.describeMismatch(matchState.state['feature'], mismatchDescription,
+        matchState.state['innerState'], verbose);
+    return mismatchDescription;
+  }
+}