make Matcher generic

[DartBot]

This issue was originally filed by @seaneagan

---

It would be nice if dart:unittest's Matcher was generic:

interface Matcher<T> {
  bool matches(T item);
  //...
}

//...

Matcher<num> closeTo(num value, num delta);
Matcher<Map<K, V>> containsPair<K, V>(K key, V value);
Matcher<Map<Dynamic, V>> containsValue<V>(V value);
Matcher<Map<K, Dynamic>> containsKey<K>(K key);
Matcher<String> startsWith(String str);
Matcher<String> endsWith(String str);
Matcher<String> matches(Pattern pattern);
Matcher<String> equalsIgnoringCase(String str);
Matcher<String> equalsIgnoringWhiteSpace(String str);
Matcher<T> lessThan<T extends Comparable<T>>(Comparable c);
Matcher<T> greaterThan<T extends Comparable<T>>(T c);
Matcher<T> lessThanOrEqualTo<T extends Comparable<T>>(T c);
Matcher<T> greaterThanOrEqualTo<T extends Comparable<T>>(T c);
Matcher<Collection<E>> every(Matcher<E>);
Matcher<Collection<E>> some(Matcher<E>);
Matcher<bool> get isTrue();
Matcher<bool> get isFalse();
Matcher<num> get isPositive();
Matcher<num> get isNegative();
Matcher<num> get isNonPositive();
Matcher<num> get isNonNegative();
Matcher<num> get isZero();
Matcher<num> get isNonZero();
Matcher<Function> get throws();
Matcher<Function> get returnsNormally();
Matcher<Future> get completes();
//etc.

If issue #4 were fixed, then "expect" could change to:

void expect<T>(T item, Matcher<T> matcher);
//...
expect<bool>(b, isTrue);
expect<num>(i, lessThan<num>(6));
expect<String>(s, matches(new Regexp(@­"\d+"));

a better option though might be to change expect to an instance method of Matcher, and rename it to "test":

isTrue.test(b);
isPositive.test(x);
matches(new Regexp(@­"\d+")).test(s);

[DartBot]

This comment was originally written by @seaneagan

---

If going the Matcher#test route, it would be nice to have it be a "final method" as in Java, either in BaseMatcher, or just rename BaseMatcher to Matcher and get rid of the explicit interface.

[anders-sandholm]

Added Area-Test, Triaged labels.

[anders-sandholm]

Removed Area-Test label.
Added Area-UnitTest label.

[gramster]

In many cases, the type of the argument is tested anyway and the matcher will fail with an appropriate error message if it is the wrong type. This could be done at compile time rather than run time using generics, but it adds developer pain to have to type every call to expect.

---

Added NotPlanned label.

[DartBot]

This comment was originally written by @seaneagan

---

Presumably if Dart added generic methods (issue #254) the type argument to the method call would be optional just like all other type annotations are. Also, type arguments could likely be inferred in many cases.

Even if generic methods aren't added this would still make it much easier to tell which types each matcher matches against, since you can tell merely by looking at the method signature or field definitition, as opposed to having to read the doc comments.

[kevmoo]

Added Pkg-Unittest label.

[kevmoo]

Removed Area-UnitTest label.
Added Area-Pkg label.

[DartBot]

This issue has been moved to dart-lang/test#136.