pkg/matcher: cleanup, updates, deprecations, fixes

pkg/matcher/lib/src/iterable_matchers.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.
 
-part of matcher;
+library matcher.iterable_matchers;
 
-/**
- * Returns a matcher which matches [Iterable]s in which all elements
- * match the given [matcher].
- */
+import 'core_matchers.dart';
+import 'description.dart';
+import 'expect.dart';
+import 'interfaces.dart';
+
+/// Returns a matcher which matches [Iterable]s in which all elements
+/// match the given [matcher].
 Matcher everyElement(matcher) => new _EveryElement(wrapMatcher(matcher));
 
 class _EveryElement extends _IterableMatcher {
-  Matcher _matcher;
+  final Matcher _matcher;
 
   _EveryElement(Matcher this._matcher);
 
   bool matches(item, Map matchState) {
     if (item is! Iterable) {
       return false;
     }
     var i = 0;
     for (var element in item) {
       if (!_matcher.matches(element, matchState)) {
         addStateInfo(matchState, {'index': i, 'element': element});
         return false;
       }
       ++i;
     }
     return true;
   }
 
   Description describe(Description description) =>
       description.add('every element(').addDescriptionOf(_matcher).add(')');
 
   Description describeMismatch(item, Description mismatchDescription,
                                Map matchState, bool verbose) {
     if (matchState['index'] != null) {
       var index = matchState['index'];
       var element = matchState['element'];
       mismatchDescription.add('has value ').addDescriptionOf(element).
           add(' which ');
       var subDescription = new StringDescription();
-      _matcher.describeMismatch(element, subDescription,
-            matchState['state'], verbose);
+      _matcher.describeMismatch(element, subDescription, matchState['state'],
+          verbose);
       if (subDescription.length > 0) {
-        mismatchDescription.add(subDescription);
+        mismatchDescription.add(subDescription.toString());
       } else {
         mismatchDescription.add("doesn't match ");
         _matcher.describe(mismatchDescription);
       }
       mismatchDescription.add(' at index $index');
       return mismatchDescription;
     }
     return super.describeMismatch(item, mismatchDescription,
           matchState, verbose);
   }
 }
 
-/**
- * Returns a matcher which matches [Iterable]s in which at least one
- * element matches the given [matcher].
- */
+/// Returns a matcher which matches [Iterable]s in which at least one
+/// element matches the given [matcher].
 Matcher anyElement(matcher) => new _AnyElement(wrapMatcher(matcher));
 
 class _AnyElement extends _IterableMatcher {
-  Matcher _matcher;
+  final Matcher _matcher;
 
   _AnyElement(this._matcher);
 
   bool matches(item, Map matchState) {
     return item.any((e) => _matcher.matches(e, matchState));
   }
 
   Description describe(Description description) =>
       description.add('some element ').addDescriptionOf(_matcher);
 }
 
-/**
- * Returns a matcher which matches [Iterable]s that have the same
- * length and the same elements as [expected], and in the same order.
- * This is equivalent to equals but does not recurse.
- */
+/// Returns a matcher which matches [Iterable]s that have the same
+/// length and the same elements as [expected], and in the same order.
+/// This is equivalent to equals but does not recurse.
 
 Matcher orderedEquals(Iterable expected) => new _OrderedEquals(expected);
 
 class _OrderedEquals extends Matcher {
   final Iterable _expected;
   Matcher _matcher;
 
   _OrderedEquals(this._expected) {
     _matcher = equals(_expected, 1);
   }
 
   bool matches(item, Map matchState) =>
       (item is Iterable) && _matcher.matches(item, matchState);
 
   Description describe(Description description) =>
       description.add('equals ').addDescriptionOf(_expected).add(' ordered');
 
   Description describeMismatch(item, Description mismatchDescription,
                                Map matchState, bool verbose) {
     if (item is !Iterable) {
       return mismatchDescription.add('is not an Iterable');
     } else {
       return _matcher.describeMismatch(item, mismatchDescription,
           matchState, verbose);
     }
   }
 }
 
-/**
- * Returns a matcher which matches [Iterable]s that have the same
- * length and the same elements as [expected], but not necessarily in
- * the same order. Note that this is O(n^2) so should only be used on
- * small objects.
- */
+/// Returns a matcher which matches [Iterable]s that have the same
+/// length and the same elements as [expected], but not necessarily in
+/// the same order. Note that this is O(n^2) so should only be used on
+/// small objects.
 Matcher unorderedEquals(Iterable expected) => new _UnorderedEquals(expected);
 
 class _UnorderedEquals extends _UnorderedMatches {
   final List _expectedValues;
 
   _UnorderedEquals(Iterable expected)
       : super(expected.map(equals)),
         _expectedValues = expected.toList();
 
   Description describe(Description description) =>
     description
         .add('equals ')
         .addDescriptionOf(_expectedValues)
         .add(' unordered');
 }
 
-/**
- * Iterable matchers match against [Iterable]s. We add this intermediate
- * class to give better mismatch error messages than the base Matcher class.
- */
+/// Iterable matchers match against [Iterable]s. We add this intermediate
+/// class to give better mismatch error messages than the base Matcher class.
 abstract class _IterableMatcher extends Matcher {
   const _IterableMatcher();
   Description describeMismatch(item, Description mismatchDescription,
                                Map matchState, bool verbose) {
     if (item is! Iterable) {
       return mismatchDescription.
           addDescriptionOf(item).
           add(' not an Iterable');
     } else {
       return super.describeMismatch(item, mismatchDescription, matchState,
           verbose);
     }
   }
 }
 
-/**
- * Returns a matcher which matches [Iterable]s whose elements match the matchers
- * in [expected], but not necessarily in the same order.
- *
- *  Note that this is `O(n^2)` and so should only be used on small objects.
- */
+/// Returns a matcher which matches [Iterable]s whose elements match the
+/// matchers in [expected], but not necessarily in the same order.
+///
+///  Note that this is `O(n^2)` and so should only be used on small objects.
 Matcher unorderedMatches(Iterable expected) => new _UnorderedMatches(expected);
 
 class _UnorderedMatches extends Matcher {
   final List<Matcher> _expected;
 
   _UnorderedMatches(Iterable expected)
       : _expected = expected.map(wrapMatcher).toList();
 
   String _test(item) {
     if (item is! Iterable) return 'not iterable';
@@ skipping 40 matching lines @@
     description
       .add('matches ')
       .addAll('[', ', ', ']', _expected)
       .add(' unordered');
 
   Description describeMismatch(item, Description mismatchDescription,
                                Map matchState, bool verbose) =>
       mismatchDescription.add(_test(item));
 }
 
-/**
- * A pairwise matcher for iterable. You can pass an arbitrary [comparator]
- * function that takes an expected and actual argument which will be applied
- * to each pair in order. [description]  should be a meaningful name for
- * the comparator.
- */
-Matcher pairwiseCompare(Iterable expected, Function comparator,
+/// A pairwise matcher for iterable. You can pass an arbitrary [comparator]
+/// function that takes an expected and actual argument which will be applied
+/// to each pair in order. [description]  should be a meaningful name for
+/// the comparator.
+Matcher pairwiseCompare(Iterable expected, bool comparator(a, b),
     String description) =>
         new _PairwiseCompare(expected, comparator, description);
 
+typedef bool _Comparator(a, b);
+
 class _PairwiseCompare extends _IterableMatcher {
-  Iterable _expected;
-  Function _comparator;
-  String _description;
+  final Iterable _expected;
+  final _Comparator _comparator;
+  final String _description;
 
   _PairwiseCompare(this._expected, this._comparator, this._description);
 
   bool matches(item, Map matchState) {
     if (item is! Iterable) return false;
     if (item.length != _expected.length) return false;
     var iterator = item.iterator;
     var i = 0;
     for (var e in _expected) {
       iterator.moveNext();
@@ skipping 20 matching lines @@
     } else {
       return mismatchDescription.
           add('has ').
           addDescriptionOf(matchState["actual"]).
           add(' which is not $_description ').
           addDescriptionOf(matchState["expected"]).
           add(' at index ${matchState["index"]}');
     }
   }
 }
-