| 148 |
lars |
1 |
<?php
|
|
|
2 |
namespace Hamcrest;
|
|
|
3 |
|
|
|
4 |
/*
|
|
|
5 |
Copyright (c) 2009 hamcrest.org
|
|
|
6 |
*/
|
|
|
7 |
|
|
|
8 |
/**
|
|
|
9 |
* A matcher over acceptable values.
|
|
|
10 |
* A matcher is able to describe itself to give feedback when it fails.
|
|
|
11 |
* <p/>
|
|
|
12 |
* Matcher implementations should <b>NOT directly implement this interface</b>.
|
|
|
13 |
* Instead, <b>extend</b> the {@link Hamcrest\BaseMatcher} abstract class,
|
|
|
14 |
* which will ensure that the Matcher API can grow to support
|
|
|
15 |
* new features and remain compatible with all Matcher implementations.
|
|
|
16 |
* <p/>
|
|
|
17 |
* For easy access to common Matcher implementations, use the static factory
|
|
|
18 |
* methods in {@link Hamcrest\CoreMatchers}.
|
|
|
19 |
*
|
|
|
20 |
* @see Hamcrest\CoreMatchers
|
|
|
21 |
* @see Hamcrest\BaseMatcher
|
|
|
22 |
*/
|
|
|
23 |
interface Matcher extends SelfDescribing
|
|
|
24 |
{
|
|
|
25 |
|
|
|
26 |
/**
|
|
|
27 |
* Evaluates the matcher for argument <var>$item</var>.
|
|
|
28 |
*
|
|
|
29 |
* @param mixed $item the object against which the matcher is evaluated.
|
|
|
30 |
*
|
|
|
31 |
* @return boolean <code>true</code> if <var>$item</var> matches,
|
|
|
32 |
* otherwise <code>false</code>.
|
|
|
33 |
*
|
|
|
34 |
* @see Hamcrest\BaseMatcher
|
|
|
35 |
*/
|
|
|
36 |
public function matches($item);
|
|
|
37 |
|
|
|
38 |
/**
|
|
|
39 |
* Generate a description of why the matcher has not accepted the item.
|
|
|
40 |
* The description will be part of a larger description of why a matching
|
|
|
41 |
* failed, so it should be concise.
|
|
|
42 |
* This method assumes that <code>matches($item)</code> is false, but
|
|
|
43 |
* will not check this.
|
|
|
44 |
*
|
|
|
45 |
* @param mixed $item The item that the Matcher has rejected.
|
|
|
46 |
* @param Description $description
|
|
|
47 |
* @return
|
|
|
48 |
*/
|
|
|
49 |
public function describeMismatch($item, Description $description);
|
|
|
50 |
}
|