    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}