1 /*
2 Licensed to the Apache Software Foundation (ASF) under one or more
3 contributor license agreements. See the NOTICE file distributed with
4 this work for additional information regarding copyright ownership.
5 The ASF licenses this file to You under the Apache License, Version 2.0
6 (the "License"); you may not use this file except in compliance with
7 the License. You may obtain a copy of the License at
8
9 https://www.apache.org/licenses/LICENSE-2.0
10
11 Unless required by applicable law or agreed to in writing, software
12 distributed under the License is distributed on an "AS IS" BASIS,
13 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 See the License for the specific language governing permissions and
15 limitations under the License.
16 */
17 package org.apache.commons.cli.help;
18
19 import java.io.IOException;
20 import java.util.Collection;
21 import java.util.Formatter;
22 import java.util.IllegalFormatException;
23
24 /**
25 * 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
26 * a Heading.
27 * <p>
28 * 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
29 * by two line breaks, while an XHTML output would print the text surrounded by <p> and </p>.
30 * </p>
31 * <p>
32 * Note the {@link Appendable} documentation on the topics of Unicode and threading, these comments also apply here.
33 * </p>
34 *
35 * @since 1.10.0
36 */
37 public interface HelpAppendable extends Appendable {
38
39 /**
40 * Appends a formatted string using the specified format string and arguments.
41 * <p>
42 * Short-hand for calling:
43 * </p>
44 *
45 * <pre>
46 * helpAppendable.{@link #append(CharSequence) append.}({@link String#format(String, Object...) String.format}(format, args));
47 * </pre>
48 *
49 * @param format The format string for {@link String#format(String, Object...)}.
50 * @param args Arguments to {@link String#format(String, Object...)}.
51 * @throws IllegalFormatException See {@link String#format(String, Object...)}.
52 * @throws IOException If an output error occurs.
53 * @see String#format(String, Object...)
54 * @see Formatter
55 * @see #append(CharSequence)
56 */
57 default void appendFormat(final String format, final Object... args) throws IOException {
58 append(String.format(format, args));
59 }
60
61 /**
62 * Appends a header.
63 *
64 * @param level the level of the header. This is equivalent to the "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
65 * @param text the text for the header, null is a noop.
66 * @throws IOException If an output error occurs.
67 */
68 void appendHeader(int level, CharSequence text) throws IOException;
69
70 /**
71 * Appends a list.
72 *
73 * @param ordered {@code true} if the list should be ordered.
74 * @param list the list to write, null is a noop.
75 * @throws IOException If an output error occurs.
76 */
77 void appendList(boolean ordered, Collection<CharSequence> list) throws IOException;
78
79 /**
80 * Appends a paragraph.
81 *
82 * @param paragraph the paragraph to write, null is a noop.
83 * @throws IOException If an output error occurs.
84 */
85 void appendParagraph(CharSequence paragraph) throws IOException;
86
87 /**
88 * Appends a formatted string as a paragraph.
89 *
90 * <pre>
91 * helpAppendable.{@link #appendParagraph(CharSequence) appendParagraph.}({@link String#format(String, Object...) String.format}(format, args));
92 * </pre>
93 *
94 * @param format The format string for {@link String#format(String, Object...)}.
95 * @param args Arguments to {@link String#format(String, Object...)}.
96 * @throws IllegalFormatException See {@link String#format(String, Object...)}.
97 * @throws IOException If an output error occurs.
98 * @see String#format(String, Object...)
99 * @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 }