1package org.hamcrest;
2
3/**
4 * A description of a Matcher. A Matcher will describe itself to a description
5 * which can later be used for reporting.
6 *
7 * @see Matcher#describeTo(Description)
8 */
9public interface Description {
10  /**
11   * A description that consumes input but does nothing.
12   */
13  static final Description NONE = new NullDescription();
14
15    /**
16     * Appends some plain text to the description.
17     */
18    Description appendText(String text);
19
20    /**
21     * Appends the description of a {@link SelfDescribing} value to this description.
22     */
23    Description appendDescriptionOf(SelfDescribing value);
24
25    /**
26     * Appends an arbitrary value to the description.
27     */
28    Description appendValue(Object value);
29
30    /**
31     * Appends a list of values to the description.
32     */
33    <T> Description appendValueList(String start, String separator, String end,
34                                    T... values);
35
36    /**
37     * Appends a list of values to the description.
38     */
39    <T> Description appendValueList(String start, String separator, String end,
40                                    Iterable<T> values);
41
42    /**
43     * Appends a list of {@link org.hamcrest.SelfDescribing} objects
44     * to the description.
45     */
46    Description appendList(String start, String separator, String end,
47                           Iterable<? extends SelfDescribing> values);
48
49
50    public static final class NullDescription implements Description {
51      @Override
52      public Description appendDescriptionOf(SelfDescribing value) {
53        return this;
54      }
55
56      @Override
57      public Description appendList(String start, String separator,
58          String end, Iterable<? extends SelfDescribing> values) {
59        return this;
60      }
61
62      @Override
63      public Description appendText(String text) {
64        return this;
65      }
66
67      @Override
68      public Description appendValue(Object value) {
69        return this;
70      }
71
72      @Override
73      public <T> Description appendValueList(String start, String separator,
74          String end, T... values) {
75        return this;
76      }
77
78      @Override
79      public <T> Description appendValueList(String start, String separator,
80          String end, Iterable<T> values) {
81        return this;
82      }
83
84      @Override
85        public String toString() {
86          return "";
87        }
88    }
89}
90