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    }