001/*
002  Licensed to the Apache Software Foundation (ASF) under one or more
003  contributor license agreements.  See the NOTICE file distributed with
004  this work for additional information regarding copyright ownership.
005  The ASF licenses this file to You under the Apache License, Version 2.0
006  (the "License"); you may not use this file except in compliance with
007  the License.  You may obtain a copy of the License at
008
009      https://www.apache.org/licenses/LICENSE-2.0
010
011  Unless required by applicable law or agreed to in writing, software
012  distributed under the License is distributed on an "AS IS" BASIS,
013  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014  See the License for the specific language governing permissions and
015  limitations under the License.
016 */
017package org.apache.commons.cli.help;
018
019import java.io.IOException;
020import java.util.Collection;
021import java.util.Formatter;
022import java.util.IllegalFormatException;
023
024/**
025 * Defines a semantic scribe. The semantic scribe appends text to an output based on the semantic meaning of the type of string. For example, a Paragraph versus
026 * a Heading.
027 * <p>
028 * The representation of the semantics is dependent upon the format being output. For example, the plain text output for a paragraph may print the text followed
029 * by two line breaks, while an XHTML output would print the text surrounded by &lt;p&gt; and &lt;/p&gt;.
030 * </p>
031 * <p>
032 * Note the {@link Appendable} documentation on the topics of Unicode and threading, these comments also apply here.
033 * </p>
034 *
035 * @since 1.10.0
036 */
037public interface HelpAppendable extends Appendable {
038
039    /**
040     * Appends a formatted string using the specified format string and arguments.
041     * <p>
042     * Short-hand for calling:
043     * </p>
044     *
045     * <pre>
046     * helpAppendable.{@link #append(CharSequence) append.}({@link String#format(String, Object...) String.format}(format, args));
047     * </pre>
048     *
049     * @param format The format string for {@link String#format(String, Object...)}.
050     * @param args   Arguments to {@link String#format(String, Object...)}.
051     * @throws IllegalFormatException See {@link String#format(String, Object...)}.
052     * @throws IOException            If an output error occurs.
053     * @see String#format(String, Object...)
054     * @see Formatter
055     * @see #append(CharSequence)
056     */
057    default void appendFormat(final String format, final Object... args) throws IOException {
058        append(String.format(format, args));
059    }
060
061    /**
062     * Appends a header.
063     *
064     * @param level the level of the header. This is equivalent to the "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
065     * @param text  the text for the header, null is a noop.
066     * @throws IOException If an output error occurs.
067     */
068    void appendHeader(int level, CharSequence text) throws IOException;
069
070    /**
071     * Appends a list.
072     *
073     * @param ordered {@code true} if the list should be ordered.
074     * @param list    the list to write, null is a noop.
075     * @throws IOException If an output error occurs.
076     */
077    void appendList(boolean ordered, Collection<CharSequence> list) throws IOException;
078
079    /**
080     * Appends a paragraph.
081     *
082     * @param paragraph the paragraph to write, null is a noop.
083     * @throws IOException If an output error occurs.
084     */
085    void appendParagraph(CharSequence paragraph) throws IOException;
086
087    /**
088     * Appends a formatted string as a paragraph.
089     *
090     * <pre>
091     * helpAppendable.{@link #appendParagraph(CharSequence) appendParagraph.}({@link String#format(String, Object...) String.format}(format, args));
092     * </pre>
093     *
094     * @param format The format string for {@link String#format(String, Object...)}.
095     * @param args   Arguments to {@link String#format(String, Object...)}.
096     * @throws IllegalFormatException See {@link String#format(String, Object...)}.
097     * @throws IOException            If an output error occurs.
098     * @see String#format(String, Object...)
099     * @see Formatter
100     * @see #append(CharSequence)
101     */
102    default void appendParagraphFormat(final String format, final Object... args) throws IOException {
103        appendParagraph(String.format(format, args));
104    }
105
106    /**
107     * Appends a table.
108     *
109     * @param table the table definition to write, null is a noop.
110     * @throws IOException If an output error occurs.
111     */
112    void appendTable(TableDefinition table) throws IOException;
113
114    /**
115     * Appends a title.
116     *
117     * @param title the title to write, null is a noop.
118     * @throws IOException If an output error occurs.
119     */
120    void appendTitle(CharSequence title) throws IOException;
121
122}