Skip to content

Commit 5fa27ca

Browse files
DamnedElricgarydgregory
DamnedElric
and
garydgregory
authored
Fix broken Javadoc links, replace deprecated methods in usage examples, and add a missing method to HelpFormatter (apache#424)
* Fix broken Javadoc links, replace deprecated methods in usage examples, and add a missing method to HelpFormatter * Formatting * Add missing Javadoc tag. --------- Co-authored-by: Gary Gregory <garydgregory@users.noreply.github.com>
1 parent 6ed9cde commit 5fa27ca

3 files changed

Lines changed: 62 additions & 29 deletions

File tree

‎src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -284,6 +284,19 @@ public final String getSyntaxPrefix() {
284284
*/
285285
protected abstract TableDefinition getTableDefinition(Iterable<Option> options);
286286

287+
/**
288+
* Prints the help for {@link Options} with the specified command line syntax,
289+
* without printing a header, footer, or autoUsage.
290+
*
291+
* @param cmdLineSyntax the syntax for this application.
292+
* @param options the collection of {@link Option} objects to print.
293+
* @throws IOException If the output could not be written to the {@link HelpAppendable}.
294+
* @since 1.12.0
295+
*/
296+
public void printHelp(final String cmdLineSyntax, final Options options) throws IOException {
297+
printHelp(cmdLineSyntax, null, options, null, false);
298+
}
299+
287300
/**
288301
* Prints the help for {@link Options} with the specified command line syntax.
289302
*

‎src/main/javadoc/overview.html‎

Lines changed: 29 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -58,9 +58,9 @@ <h2>Defining the CLI</h2>
5858
to define the interface to the application.
5959
</p>
6060
<p>
61-
CLI uses the <a href="javadocs/api-release/org/apache/commons/cli/Options.html">
61+
CLI uses the <a href="org/apache/commons/cli/Options.html">
6262
Options</a> class, as a container for
63-
<a href="javadocs/api-release/org/apache/commons/cli/Option.html">
63+
<a href="org/apache/commons/cli/Option.html">
6464
Option</a> instances. There are two ways to create
6565
<code>Option</code>s in CLI. One of them is via the constructors,
6666
the other way is via the factory methods defined in
@@ -86,11 +86,11 @@ <h2>Parsing the CLI</h2>
8686
</p>
8787
<p>
8888
The <code>parse</code> method defined on
89-
<a href="javadocs/api-release/org/apache/commons/cli/CommandLineParser.html">
89+
<a href="org/apache/commons/cli/CommandLineParser.html">
9090
CommandLineParser</a> takes an <code>Options</code>
9191
instance and a <code>String[]</code> of arguments and
9292
returns a
93-
<a href="javadocs/api-release/org/apache/commons/cli/CommandLine.html">
93+
<a href="org/apache/commons/cli/CommandLine.html">
9494
CommandLine</a>.
9595
</p>
9696
<p>
@@ -142,7 +142,7 @@ <h2>Using a boolean option</h2>
142142
<section>
143143
<h2>Creating the Options</h2>
144144
<p>
145-
An <a href="javadocs/api-release/org/apache/commons/cli/Options.html">
145+
An <a href="org/apache/commons/cli/Options.html">
146146
Options</a> object must be created and the <code>Option</code> must be
147147
added to it.
148148
</p>
@@ -177,7 +177,7 @@ <h2>Parsing the command line arguments</h2>
177177
<p>
178178
Now we need to check if the <code>t</code> option is present. To do
179179
this we will interrogate the
180-
<a href="javadocs/api-release/org/apache/commons/cli/CommandLine.html">CommandLine
180+
<a href="org/apache/commons/cli/CommandLine.html">CommandLine
181181
</a> object. The <code>hasOption</code> method takes a
182182
<code>java.lang.String</code> parameter and returns <code>true</code> if the option
183183
represented by the <code>java.lang.String</code> is present, otherwise
@@ -288,44 +288,44 @@ <h2>Defining Argument Options</h2>
288288
.argName("file")
289289
.hasArg()
290290
.desc("use given file for log")
291-
.build();
291+
.get();
292292

293293
Option logger = Option.builder("logger")
294294
.argName("classname")
295295
.hasArg()
296296
.desc("the class which it to perform logging")
297-
.build();
297+
.get();
298298

299299
Option listener = Option.builder("listener")
300300
.argName("classname")
301301
.hasArg()
302302
.desc("add an instance of class as "
303303
+ "a project listener")
304-
.build();
304+
.get();
305305

306306
Option buildFile = Option.builder("buildfile")
307307
.argName("file")
308308
.hasArg()
309309
.desc("use given buildfile")
310-
.build();
310+
.get();
311311

312312
Option find = Option.builder("find")
313313
.argName("file")
314314
.hasArg()
315315
.desc("search for buildfile towards the "
316316
+ "root of the filesystem and use it")
317-
.build();</code></pre>
317+
.get();</code></pre>
318318
</section>
319319
<section>
320320
<h2>Defining Java Property Option</h2>
321321
<p>
322322
The last option to create is the Java property, and it is also created
323323
using the Option class' Builder.
324324
</p>
325-
<code>Option property = Option property = Option.builder("D")
325+
<pre><code>Option property = Option.builder("D")
326326
.hasArgs()
327327
.valueSeparator('=')
328-
.build();</code>
328+
.get();</code></pre>
329329
<p>
330330
The map of properties specified by this option can later be retrieved by
331331
calling <code>getOptionProperties("D")</code> on the <code>CommandLine</code>.
@@ -335,11 +335,11 @@ <h2>Defining Java Property Option</h2>
335335
<h2>Creating the Options</h2>
336336
<p>
337337
Now that we have created each
338-
<a href="javadocs/api-release/org/apache/commons/cli/Option.html">Option</a> we need
338+
<a href="org/apache/commons/cli/Option.html">Option</a> we need
339339
to create the
340-
<a href="javadocs/api-release/org/apache/commons/cli/Options.html">Options</a>
340+
<a href="org/apache/commons/cli/Options.html">Options</a>
341341
instance. This is achieved using the
342-
<a href="javadocs/api-release/org/apache/commons/cli/CommandLine.html#addOption(org.apache.commons.cli.Option)">addOption</a>
342+
<a href="org/apache/commons/cli/CommandLine.html#addOption(org.apache.commons.cli.Option)">addOption</a>
343343
method of <code>Options</code>.
344344
</p>
345345
<pre><code>Options options = new Options();
@@ -351,10 +351,10 @@ <h2>Creating the Options</h2>
351351
options.addOption(verbose);
352352
options.addOption(debug);
353353
options.addOption(emacs);
354-
options.addOption(logfile);
354+
options.addOption(logFile);
355355
options.addOption(logger);
356356
options.addOption(listener);
357-
options.addOption(buildfile);
357+
options.addOption(buildFile);
358358
options.addOption(find);
359359
options.addOption(property);</code></pre>
360360
<p>
@@ -367,7 +367,7 @@ <h2>Creating the Parser</h2>
367367
<p>
368368
We now need to create a <code>CommandLineParser</code>. This will parse the command
369369
line arguments, using the rules specified by the <code>Options</code> and
370-
return an instance of <a href="javadocs/api-release/org/apache/commons/cli/CommandLine.html">CommandLine</a>.
370+
return an instance of <a href="org/apache/commons/cli/CommandLine.html">CommandLine</a>.
371371
</p>
372372
<pre><code>public static void main(String[] args) {
373373
// create the parser
@@ -399,7 +399,7 @@ <h2>Displaying Usage and Help</h2>
399399
<p>
400400
CLI also provides the means to automatically generate usage
401401
and help information. This is achieved with the
402-
<a href="javadocs/api-release/org/apache/commons/cli/HelpFormatter.html">HelpFormatter</a>
402+
<a href="apidocs/org/apache/commons/cli/help/HelpFormatter.html">HelpFormatter</a>
403403
class.
404404
</p>
405405
<pre><code>// automatically generate the help statement
@@ -454,7 +454,7 @@ <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; pad
454454
-C list entries by columns</code></pre>
455455
<p>
456456
The following is the code that is used to create the
457-
<a href="javadocs/api-release/org/apache/commons/cli/Options.html">Options</a> for this example.
457+
<a href="org/apache/commons/cli/Options.html">Options</a> for this example.
458458
</p>
459459
<pre><code>// create the command line parser
460460
CommandLineParser parser = new DefaultParser();
@@ -468,7 +468,7 @@ <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; pad
468468
options.addOption(Option.builder("SIZE").longOpt("block-size")
469469
.desc("use SIZE-byte blocks")
470470
.hasArg()
471-
.build());
471+
.get());
472472
options.addOption("B", "ignore-backups", false, "do not list implied entries "
473473
+ "ending with ~");
474474
options.addOption("c", false, "with -lt: sort by, and show, ctime (time of last "
@@ -506,7 +506,7 @@ <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; pad
506506
.hasArg()
507507
.desc("the number of things")
508508
.type(Integer.class)
509-
.build();
509+
.get();
510510
Options options = new Options().addOption(count);
511511
// create the parser
512512
CommandLineParser parser = new DefaultParser();
@@ -561,7 +561,7 @@ <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; pad
561561
.hasArg()
562562
.desc("the foo arg")
563563
.converter(Foo::new)
564-
.build();</code></pre>
564+
.get();</code></pre>
565565
<p>
566566
The above will create an option that passes the string value to the Foo constructor when <code>commandLine.getParsedOptionValue(fooOpt)</code> is called.
567567
</p>
@@ -595,12 +595,12 @@ <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; pad
595595
.hasArg()
596596
.desc("the number of things")
597597
.type(Integer.class)
598-
.build();
598+
.get();
599599
Option count = Option.builder("count")
600600
.hasArg()
601601
.desc("the number of things")
602602
.type(Integer.class)
603-
.build();
603+
.get();
604604
Options options = new Options().addOption(n).addOption(count);
605605

606606
doSomething(options);
@@ -653,7 +653,7 @@ <h2>Changing Usage Announcement</h2>
653653
}
654654
System.err.printf("ERROR: Option %s: %s%n", buf, o.getDeprecated());
655655
};
656-
DefaultParser parser = DefaultParser.builder().setDeprecatedHandler(deprecatedUsageAnnouncement).build();
656+
DefaultParser parser = DefaultParser.builder().setDeprecatedHandler(deprecatedUsageAnnouncement).get();
657657
CommandLine line;
658658
try {
659659
// parse the command line arguments
@@ -728,10 +728,10 @@ <h2>Changing help format</h2>
728728
<h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; padding-right: 0.25em" alt="leaf">7. Defining Option Properties</h1>
729729
<p>
730730
The following are the properties that each
731-
<a href="javadocs/api-release/org/apache/commons/cli/Option.html">Option</a> has. All of these
731+
<a href="org/apache/commons/cli/Option.html">Option</a> has. All of these
732732
can be set using the accessors or using the methods
733733
defined in the
734-
<a href="javadocs/api-release/org/apache/commons/cli/Option.Builder.html">Option.Builder</a>.
734+
<a href="org/apache/commons/cli/Option.Builder.html">Option.Builder</a>.
735735
</p>
736736
<table>
737737
<caption>Option Properties</caption>

‎src/test/java/org/apache/commons/cli/help/HelpFormatterTest.java‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,26 @@ void testPrintHelp() throws IOException {
147147
assertEquals(0, sb.length(), "Should not write to output");
148148
}
149149

150+
@Test
151+
void testPrintHelpWithDefaults() throws IOException {
152+
final StringBuilder sb = new StringBuilder();
153+
final TextHelpAppendable serializer = new TextHelpAppendable(sb);
154+
HelpFormatter formatter = HelpFormatter.builder().setHelpAppendable(serializer).get();
155+
156+
final Options options = new Options().addOption(Option.builder("a").since("1853").hasArg().desc("aaaa aaaa aaaa aaaa aaaa").get());
157+
158+
List<String> expected = new ArrayList<>();
159+
expected.add(" usage: commandSyntax");
160+
expected.add("");
161+
expected.add(" Options Since Description ");
162+
expected.add(" -a <arg> 1853 aaaa aaaa aaaa aaaa aaaa");
163+
expected.add("");
164+
165+
formatter.printHelp("commandSyntax", options);
166+
List<String> actual = IOUtils.readLines(new StringReader(sb.toString()));
167+
assertEquals(expected, actual);
168+
}
169+
150170
/**
151171
* Tests example from the mailing list that caused an infinite loop.
152172
*

0 commit comments

Comments
 (0)