001package org.hamcrest;
002
003/**
004 * A description of a Matcher. A Matcher will describe itself to a description
005 * which can later be used for reporting.
006 *
007 * @see Matcher#describeTo(Description)
008 */
009public interface Description {
010  /**
011   * A description that consumes input but does nothing.
012   */
013  static final Description NONE = new NullDescription();
014  
015    /**
016     * Appends some plain text to the description.
017     */
018    Description appendText(String text);
019
020    /**
021     * Appends the description of a {@link SelfDescribing} value to this description.
022     */
023    Description appendDescriptionOf(SelfDescribing value);
024
025    /**
026     * Appends an arbitary value to the description.
027     */
028    Description appendValue(Object value);
029
030    /**
031     * Appends a list of values to the description.
032     */
033    <T> Description appendValueList(String start, String separator, String end,
034                                    T... values);
035
036    /**
037     * Appends a list of values to the description.
038     */
039    <T> Description appendValueList(String start, String separator, String end,
040                                    Iterable<T> values);
041
042    /**
043     * Appends a list of {@link org.hamcrest.SelfDescribing} objects
044     * to the description.
045     */
046    Description appendList(String start, String separator, String end,
047                           Iterable<? extends SelfDescribing> values);
048
049
050    public static final class NullDescription implements Description {
051      @Override
052      public Description appendDescriptionOf(SelfDescribing value) {
053        return this;
054      }
055
056      @Override
057      public Description appendList(String start, String separator,
058          String end, Iterable<? extends SelfDescribing> values) {
059        return this;
060      }
061
062      @Override
063      public Description appendText(String text) {
064        return this;
065      }
066
067      @Override
068      public Description appendValue(Object value) {
069        return this;
070      }
071
072      @Override
073      public <T> Description appendValueList(String start, String separator,
074          String end, T... values) {
075        return this;
076      }
077
078      @Override
079      public <T> Description appendValueList(String start, String separator,
080          String end, Iterable<T> values) {
081        return this;
082      }
083
084      @Override
085        public String toString() {
086          return "";
087        }
088    }
089}