    001    package 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     */
    009    public 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    }