Skip to content

Fix broken Javadoc links, replace deprecated methods in usage examples, and add a missing method to HelpFormatter #424

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DamnedElric wants to merge 1 commit into
base: master
Choose a base branch
from
+62 −29
Open

Fix broken Javadoc links, replace deprecated methods in usage examples, and add a missing method to HelpFormatter #424

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -284,6 +284,19 @@ public final String getSyntaxPrefix() {
*/
protected abstract TableDefinition getTableDefinition(Iterable<Option> options);

/**
* Prints the help for {@link Options} with the specified command line syntax,
* without printing a header, footer, or autoUsage.
*
* @param cmdLineSyntax the syntax for this application.
* @param options the collection of {@link Option} objects to print.
* @throws IOException If the output could not be written to the {@link HelpAppendable}.
*/
public void printHelp(final String cmdLineSyntax, final Options options)
throws IOException {
printHelp(cmdLineSyntax, null, options, null, false);
}

/**
* Prints the help for {@link Options} with the specified command line syntax.
*
Expand Down
58 changes: 29 additions & 29 deletions src/main/javadoc/overview.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,9 @@ <h2>Defining the CLI</h2>
to define the interface to the application.
</p>
<p>
CLI uses the <a href="javadocs/api-release/org/apache/commons/cli/Options.html">
CLI uses the <a href="org/apache/commons/cli/Options.html">
Options</a> class, as a container for
<a href="javadocs/api-release/org/apache/commons/cli/Option.html">
<a href="org/apache/commons/cli/Option.html">
Option</a> instances. There are two ways to create
<code>Option</code>s in CLI. One of them is via the constructors,
the other way is via the factory methods defined in
Expand All @@ -86,11 +86,11 @@ <h2>Parsing the CLI</h2>
</p>
<p>
The <code>parse</code> method defined on
<a href="javadocs/api-release/org/apache/commons/cli/CommandLineParser.html">
<a href="org/apache/commons/cli/CommandLineParser.html">
CommandLineParser</a> takes an <code>Options</code>
instance and a <code>String[]</code> of arguments and
returns a
<a href="javadocs/api-release/org/apache/commons/cli/CommandLine.html">
<a href="org/apache/commons/cli/CommandLine.html">
CommandLine</a>.
</p>
<p>
Expand Down Expand Up @@ -142,7 +142,7 @@ <h2>Using a boolean option</h2>
<section>
<h2>Creating the Options</h2>
<p>
An <a href="javadocs/api-release/org/apache/commons/cli/Options.html">
An <a href="org/apache/commons/cli/Options.html">
Options</a> object must be created and the <code>Option</code> must be
added to it.
</p>
Expand Down Expand Up @@ -177,7 +177,7 @@ <h2>Parsing the command line arguments</h2>
<p>
Now we need to check if the <code>t</code> option is present. To do
this we will interrogate the
<a href="javadocs/api-release/org/apache/commons/cli/CommandLine.html">CommandLine
<a href="org/apache/commons/cli/CommandLine.html">CommandLine
</a> object. The <code>hasOption</code> method takes a
<code>java.lang.String</code> parameter and returns <code>true</code> if the option
represented by the <code>java.lang.String</code> is present, otherwise
Expand Down Expand Up @@ -288,44 +288,44 @@ <h2>Defining Argument Options</h2>
.argName("file")
.hasArg()
.desc("use given file for log")
.build();
.get();

Option logger = Option.builder("logger")
.argName("classname")
.hasArg()
.desc("the class which it to perform logging")
.build();
.get();

Option listener = Option.builder("listener")
.argName("classname")
.hasArg()
.desc("add an instance of class as "
+ "a project listener")
.build();
.get();

Option buildFile = Option.builder("buildfile")
.argName("file")
.hasArg()
.desc("use given buildfile")
.build();
.get();

Option find = Option.builder("find")
.argName("file")
.hasArg()
.desc("search for buildfile towards the "
+ "root of the filesystem and use it")
.build();</code></pre>
.get();</code></pre>
</section>
<section>
<h2>Defining Java Property Option</h2>
<p>
The last option to create is the Java property, and it is also created
using the Option class' Builder.
</p>
<code>Option property = Option property = Option.builder("D")
<pre><code>Option property = Option.builder("D")
.hasArgs()
.valueSeparator('=')
.build();</code>
.get();</code></pre>
<p>
The map of properties specified by this option can later be retrieved by
calling <code>getOptionProperties("D")</code> on the <code>CommandLine</code>.
Expand All @@ -335,11 +335,11 @@ <h2>Defining Java Property Option</h2>
<h2>Creating the Options</h2>
<p>
Now that we have created each
<a href="javadocs/api-release/org/apache/commons/cli/Option.html">Option</a> we need
<a href="org/apache/commons/cli/Option.html">Option</a> we need
to create the
<a href="javadocs/api-release/org/apache/commons/cli/Options.html">Options</a>
<a href="org/apache/commons/cli/Options.html">Options</a>
instance. This is achieved using the
<a href="javadocs/api-release/org/apache/commons/cli/CommandLine.html#addOption(org.apache.commons.cli.Option)">addOption</a>
<a href="org/apache/commons/cli/CommandLine.html#addOption(org.apache.commons.cli.Option)">addOption</a>
method of <code>Options</code>.
</p>
<pre><code>Options options = new Options();
Expand All @@ -351,10 +351,10 @@ <h2>Creating the Options</h2>
options.addOption(verbose);
options.addOption(debug);
options.addOption(emacs);
options.addOption(logfile);
options.addOption(logFile);
options.addOption(logger);
options.addOption(listener);
options.addOption(buildfile);
options.addOption(buildFile);
options.addOption(find);
options.addOption(property);</code></pre>
<p>
Expand All @@ -367,7 +367,7 @@ <h2>Creating the Parser</h2>
<p>
We now need to create a <code>CommandLineParser</code>. This will parse the command
line arguments, using the rules specified by the <code>Options</code> and
return an instance of <a href="javadocs/api-release/org/apache/commons/cli/CommandLine.html">CommandLine</a>.
return an instance of <a href="org/apache/commons/cli/CommandLine.html">CommandLine</a>.
</p>
<pre><code>public static void main(String[] args) {
// create the parser
Expand Down Expand Up @@ -399,7 +399,7 @@ <h2>Displaying Usage and Help</h2>
<p>
CLI also provides the means to automatically generate usage
and help information. This is achieved with the
<a href="javadocs/api-release/org/apache/commons/cli/HelpFormatter.html">HelpFormatter</a>
<a href="apidocs/org/apache/commons/cli/help/HelpFormatter.html">HelpFormatter</a>
class.
</p>
<pre><code>// automatically generate the help statement
Expand Down Expand Up @@ -454,7 +454,7 @@ <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; pad
-C list entries by columns</code></pre>
<p>
The following is the code that is used to create the
<a href="javadocs/api-release/org/apache/commons/cli/Options.html">Options</a> for this example.
<a href="org/apache/commons/cli/Options.html">Options</a> for this example.
</p>
<pre><code>// create the command line parser
CommandLineParser parser = new DefaultParser();
Expand All @@ -468,7 +468,7 @@ <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; pad
options.addOption(Option.builder("SIZE").longOpt("block-size")
.desc("use SIZE-byte blocks")
.hasArg()
.build());
.get());
options.addOption("B", "ignore-backups", false, "do not list implied entries "
+ "ending with ~");
options.addOption("c", false, "with -lt: sort by, and show, ctime (time of last "
Expand Down Expand Up @@ -506,7 +506,7 @@ <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; pad
.hasArg()
.desc("the number of things")
.type(Integer.class)
.build();
.get();
Options options = new Options().addOption(count);
// create the parser
CommandLineParser parser = new DefaultParser();
Expand Down Expand Up @@ -561,7 +561,7 @@ <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; pad
.hasArg()
.desc("the foo arg")
.converter(Foo::new)
.build();</code></pre>
.get();</code></pre>
<p>
The above will create an option that passes the string value to the Foo constructor when <code>commandLine.getParsedOptionValue(fooOpt)</code> is called.
</p>
Expand Down Expand Up @@ -595,12 +595,12 @@ <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; pad
.hasArg()
.desc("the number of things")
.type(Integer.class)
.build();
.get();
Option count = Option.builder("count")
.hasArg()
.desc("the number of things")
.type(Integer.class)
.build();
.get();
Options options = new Options().addOption(n).addOption(count);

doSomething(options);
Expand Down Expand Up @@ -653,7 +653,7 @@ <h2>Changing Usage Announcement</h2>
}
System.err.printf("ERROR: Option %s: %s%n", buf, o.getDeprecated());
};
DefaultParser parser = DefaultParser.builder().setDeprecatedHandler(deprecatedUsageAnnouncement).build();
DefaultParser parser = DefaultParser.builder().setDeprecatedHandler(deprecatedUsageAnnouncement).get();
CommandLine line;
try {
// parse the command line arguments
Expand Down Expand Up @@ -728,10 +728,10 @@ <h2>Changing help format</h2>
<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>
<p>
The following are the properties that each
<a href="javadocs/api-release/org/apache/commons/cli/Option.html">Option</a> has. All of these
<a href="org/apache/commons/cli/Option.html">Option</a> has. All of these
can be set using the accessors or using the methods
defined in the
<a href="javadocs/api-release/org/apache/commons/cli/Option.Builder.html">Option.Builder</a>.
<a href="org/apache/commons/cli/Option.Builder.html">Option.Builder</a>.
</p>
<table>
<caption>Option Properties</caption>
Expand Down
20 changes: 20 additions & 0 deletions src/test/java/org/apache/commons/cli/help/HelpFormatterTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,26 @@ void testPrintHelp() throws IOException {
assertEquals(0, sb.length(), "Should not write to output");
}

@Test
void testPrintHelpWithDefaults() throws IOException {
final StringBuilder sb = new StringBuilder();
final TextHelpAppendable serializer = new TextHelpAppendable(sb);
HelpFormatter formatter = HelpFormatter.builder().setHelpAppendable(serializer).get();

final Options options = new Options().addOption(Option.builder("a").since("1853").hasArg().desc("aaaa aaaa aaaa aaaa aaaa").get());

List<String> expected = new ArrayList<>();
expected.add(" usage: commandSyntax");
expected.add("");
expected.add(" Options Since Description ");
expected.add(" -a <arg> 1853 aaaa aaaa aaaa aaaa aaaa");
expected.add("");

formatter.printHelp("commandSyntax", options);
List<String> actual = IOUtils.readLines(new StringReader(sb.toString()));
assertEquals(expected, actual);
}

/**
* Tests example from the mailing list that caused an infinite loop.
*
Expand Down