Skip to content

Commit 929f397

Browse files
author
John Keyes
committed
new documentation, modified addOption(Option)
git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/cli/trunk@129780 13f79535-47bb-0310-9956-ffa450edef68
1 parent d6bc8cd commit 929f397

7 files changed

Lines changed: 270 additions & 9 deletions

File tree

‎src/java/org/apache/commons/cli/Options.java‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -203,24 +203,27 @@ public Options addOption(String opt, String longOpt, boolean hasArg, String desc
203203
}
204204

205205
/**
206-
* <p>Adds the option to the necessary member lists</p>
206+
* <p>Adds an option instance</p>
207207
*
208208
* @param opt the option that is to be added
209209
*/
210-
private void addOption(Option opt) {
210+
public Options addOption(Option opt) {
211211
String shortOptStr = "-" + opt.getOpt();
212212

213+
// add it to the long option list
213214
if ( opt.hasLongOpt() ) {
214215
longOpts.put( "--" + opt.getLongOpt(), opt );
215216
}
216217

218+
// if the option is required add it to the required list
217219
if ( opt.isRequired() ) {
218220
requiredOpts.put( "-" + opt.getOpt(), opt );
219221
}
220222

221223
shortOpts.put( "-" + opt.getOpt(), opt );
222224

223225
options.add( opt );
226+
return this;
224227
}
225228

226229
/** <p>Retrieve a read-only list of options in this set</p>

‎xdocs/ant.xml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
<?xml version="1.0"?>
2+
<document>
3+
4+
<properties>
5+
<author email="jbjk@mac.com">John Keyes</author>
6+
<title>Processing Ants' Command Line</title>
7+
</properties>
8+
9+
<body>
10+
<section name="Introduction">
11+
<p>
12+
By default, CLI uses a POSIX style argument parser. This parser
13+
only provides support for single character options. To provide
14+
support for an application like <a href="http://jakarta.apache.org/ant">Ant</a>
15+
it is necessary to use the GNU style argument parser. This provides
16+
support for multi character options. Read on to discover how to
17+
configure this parser and also how to process the command line options.
18+
</p>
19+
</section>
20+
<section name="Configuring the GNU Parser">
21+
<p>
22+
CLI provides support for multiple parsers. The
23+
<code>org.apache.commons.cli.parser</code> system property is used
24+
to determine what parser to use. To change the parser set the
25+
system property to the class name of the required parser.
26+
</p>
27+
<source>
28+
// configure CLI to use the GNU Parser
29+
System.setProperty( "org.apache.commons.cli.parser",
30+
"org.apache.commons.cli.GnuParser" );</source>
31+
</section>
32+
<section name="Creating the Ant Options">
33+
<p>
34+
There are three types of Options used in Ant. They are:
35+
<ul>
36+
<li>boolean option - the option is either present or not</li>
37+
<li>value option - the option is present and requires a value</li>
38+
<li>property option - the same style as Java system properties.
39+
For example, "-Dproperty=value".</li>
40+
</ul>
41+
</p>
42+
</section>
43+
</body>
44+
</document>

‎xdocs/creation.xml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
<?xml version="1.0"?>
2+
<document>
3+
4+
<properties>
5+
<author email="jbjk@mac.com">John Keyes</author>
6+
<title>Option</title>
7+
</properties>
8+
9+
<body>
10+
<section name="Option Construction">
11+
<p>
12+
There are two ways to create an
13+
<a href="apidocs/org/apache/commons/cli/Option.html">Option</a>;
14+
with the Option constructors or with the factory methods
15+
defined in
16+
<a href="apidocs/org/apache/commons/cli/Options.html">Options</a>.
17+
The method signatures of both approaches are identical.
18+
</p>
19+
<p>
20+
The entries in the following table describe the method
21+
signatures of the constructors and of the factory methods
22+
using the names of the properties the parameters represent.
23+
</p>
24+
<table>
25+
<tr>
26+
<th>API</th>
27+
<th>API</th>
28+
<th>Parameter Order</th>
29+
</tr>
30+
<tr>
31+
<td><a href="apidocs/org/apache/commons/cli/Option.html#Option(java.lang.String, boolean, java.lang.String)">ctor</a></td>
32+
<td><a href="apidocs/org/apache/commons/cli/Options.html#addOption(java.lang.String, boolean, java.lang.String)">factory</a></td>
33+
<td>Opt, Arg, Description</td>
34+
</tr>
35+
<tr>
36+
<td><a href="apidocs/org/apache/commons/cli/Option.html#Option(java.lang.String, java.lang.String, boolean, java.lang.String)">ctor</a></td>
37+
<td><a href="apidocs/org/apache/commons/cli/Options.html#addOption(java.lang.String, java.lang.String, boolean, java.lang.String)">factory</a></td>
38+
<td>Opt, LongOpt, Arg, Description</td>
39+
</tr>
40+
<tr>
41+
<td><a href="apidocs/org/apache/commons/cli/Option.html#Option(java.lang.String, java.lang.String, boolean, java.lang.String, boolean)">ctor</a></td>
42+
<td><a href="apidocs/org/apache/commons/cli/Options.html#addOption(java.lang.String, java.lang.String, boolean, java.lang.String, boolean)">factory</a></td>
43+
<td>Opt, LongOpt, Arg, Description, Required</td>
44+
</tr>
45+
<tr>
46+
<td><a href="apidocs/org/apache/commons/cli/Option.html#Option(java.lang.String, java.lang.String, boolean, java.lang.String, boolean, boolean)">ctor</a></td>
47+
<td><a href="apidocs/org/apache/commons/cli/Options.html#addOption(java.lang.String, java.lang.String, boolean, java.lang.String, boolean, boolean)">factory</a></td>
48+
<td>Opt, LongOpt, Arg, Description, Required, MultipleArgs</td>
49+
</tr>
50+
<tr>
51+
<td><a href="apidocs/org/apache/commons/cli/Option.html#Option(java.lang.String, java.lang.String, boolean, java.lang.String, boolean, boolean, java.lang.Object)">ctor</a></td>
52+
<td><a href="apidocs/org/apache/commons/cli/Options.html#addOption(java.lang.String, java.lang.String, boolean, java.lang.String, boolean, boolean, java.lang.Object)">factory</a></td>
53+
<td>Opt, LongOpt, Arg, Description, Required, MultipleArgs, Type</td>
54+
</tr>
55+
</table>
56+
<p>
57+
To add an <a href="apidocs/org/apache/commons/cli/Option.html">Option</a>
58+
that has been created using a constructor the
59+
<a href="apidocs/org/apache/commons/cli/Options.html#addOption(org.apache.commons.cli.Option)">addOption</a>
60+
method must be used.
61+
</p>
62+
</section>
63+
</body>
64+
</document>

‎xdocs/introduction.xml‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,15 +22,15 @@
2222
</p>
2323
<p>
2424
CLI uses the <a href="apidocs/org/apache/commons/cli/Options.html">
25-
<code>Options</code></a> class, as a container for
25+
Options</a> class, as a container for
2626
<a href="apidocs/org/apache/commons/cli/Options.html">
27-
<code>Option</code></a> instances. There are two ways to create
27+
Option</a> instances. There are two ways to create
2828
<code>Option</code>s in CLI. One of them is via the constuctors,
2929
the other way is via the factory methods defined in
3030
<code>Options</code>.
3131
</p>
3232
<p>
33-
The <a href="usage.html">Simple Option</a> document provides examples
33+
The <a href="usage.html">Simple Example</a> document provides examples
3434
how to create an <code>Options</code> object.
3535
</p>
3636
<p>
@@ -48,11 +48,11 @@
4848
<p>
4949
The <code>parse</code> method defined on
5050
<a href="apidocs/org/apache/commons/cli/CommandLineParser.html">
51-
<code>CommandLineParser</code></a> takes an <code>Options</code>
51+
CommandLineParser</a> takes an <code>Options</code>
5252
instance and a <code>java.util.List</code> of arguments and
5353
returns a
5454
<a href="apidocs/org/apache/commons/cli/CommandLine.html">
55-
<code>CommandLine</code></a>.
55+
CommandLine</a>.
5656
</p>
5757
<p>
5858
The result of the parsing stage is a <code>CommandLine</code>
@@ -72,7 +72,7 @@
7272
to the user code.
7373
</p>
7474
<p>
75-
The <a href="usage.html">Simple Option</a> document provides examples
75+
The <a href="usage.html">Simple Example</a> document provides examples
7676
how to create an <code>Options</code> object.
7777
</p>
7878
<p>

‎xdocs/navigation.xml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,12 @@
66
<body>
77
<menu name="User Documentation">
88
<item name="Command Line Processing" href="/introduction.html"/>
9-
<item name="Simple Option" href="/usage.html"/>
9+
<item name="Option">
10+
<item name="Properties" href="/properties.html"/>
11+
<item name="Construction" href="/creation.html"/>
12+
<item name="Simple Example" href="/usage.html"/>
13+
</item>
14+
<item name="Command Line Parser" href="/parser.html"/>
1015
</menu>
1116
</body>
1217
</project>

‎xdocs/parser.xml‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
<?xml version="1.0"?>
2+
<document>
3+
4+
<properties>
5+
<author email="jbjk@mac.com">John Keyes</author>
6+
<title>Creating a command line parser</title>
7+
</properties>
8+
9+
<body>
10+
<section name="Creating a Parser">
11+
<p>
12+
The
13+
<a href="apidocs/org/apache/commons/cli/CommandLineParserFactory.html#newParser()">newParser</a>
14+
method on <a href="apidocs/org/apache/commons/cli/CommandLineParserFactory.html">
15+
CommandLineParserFactory</a> is used to create command line
16+
parser instances.
17+
</p>
18+
<source>
19+
// create a command line parser
20+
CommandLineParser parser = CommandLineParserFactory.newParser();</source>
21+
</section>
22+
<section name="The right tool for the job">
23+
<p>
24+
Different applications may require different parsing implementation
25+
strategies. CLI ships with two implementations: <a href="apidocs/org/apache/commons/cli/PosixParser.html">
26+
PosixParser</a> and <a href="apidocs/org/apache/commons/cli/GnuParser.html">
27+
GnuParser</a>. Both of these implement the <a href="apidocs/org/apache/commons/cli/CommandLineParser.html">
28+
CommandLineParser</a> interface.
29+
</p>
30+
<p>
31+
The parser implementation is specified using the
32+
<code>org.apache.commons.cli.parser</code> system property. This is set
33+
to be the <a href="apidocs/org/apache/commons/cli/PosixParser.html">PosixParser</a>
34+
by default.
35+
</p>
36+
<source>
37+
// parser is a PosixParser
38+
CommandLineParser parser = CommandLineParserFactory.newParser();
39+
40+
// configure CLI to use the GNU Parser
41+
System.setProperty( "org.apache.commons.cli.parser",
42+
"org.apache.commons.cli.GnuParser" );
43+
44+
// parser is a GnuParser
45+
parser = CommandLineParserFactory.newParser();
46+
47+
// configure CLI to use the Posix Parser
48+
System.setProperty( "org.apache.commons.cli.parser",
49+
"org.apache.commons.cli.PosixParser" );
50+
51+
// parser is a PosixParser
52+
parser = CommandLineParserFactory.newParser();
53+
</source>
54+
</section>
55+
<section name="Parse the command line">
56+
<p>
57+
Now that a parser has been created the command line tokens can be
58+
parsed. The two <code>parse</code> methods on
59+
<a href="apidocs/org/apache/commons/cli/CommandLineParser.html">CommandLineParser</a>
60+
perform this task.
61+
</p>
62+
<source>
63+
public static void main( String[] args ) {
64+
// create the options
65+
Options options = ...;
66+
67+
// create the parser
68+
CommandLine parser = ...;
69+
70+
// parse the command line tokens
71+
CommandLine cmd = parser.parse( options, args );
72+
}</source>
73+
</section>
74+
</body>
75+
</document>

‎xdocs/properties.xml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
<?xml version="1.0"?>
2+
<document>
3+
4+
<properties>
5+
<author email="jbjk@mac.com">John Keyes</author>
6+
<title>Option</title>
7+
</properties>
8+
9+
<body>
10+
<section name="Option Properties">
11+
<p>
12+
The following are the properties of an <a href="apidocs/org/apache/commons/cli/Option.html">Option</a>.
13+
</p>
14+
<table>
15+
<tr>
16+
<th>Name</th>
17+
<th>Type</th>
18+
<th>Description</th>
19+
</tr>
20+
<tr>
21+
<td>Opt</td>
22+
<td>java.lang.String</td>
23+
<td>the identification string</td>
24+
</tr>
25+
<tr>
26+
<td>LongOpt</td>
27+
<td>java.lang.String</td>
28+
<td>an alias and more descriptive identification string</td>
29+
</tr>
30+
<tr>
31+
<td>Description</td>
32+
<td>java.lang.String</td>
33+
<td>a description of the function of the option</td>
34+
</tr>
35+
<tr>
36+
<td>Required</td>
37+
<td>boolean</td>
38+
<td>a flag to say whether the option <b>must</b> appear on
39+
the command line.</td>
40+
</tr>
41+
<tr>
42+
<td>MultipleArgs</td>
43+
<td>boolean</td>
44+
<td>a flag to say whether the option takes multiple argument
45+
values</td>
46+
</tr>
47+
<tr>
48+
<td>Arg</td>
49+
<td>boolean</td>
50+
<td>a flag to say whether the option takes an argument</td>
51+
</tr>
52+
<tr>
53+
<td>Type</td>
54+
<td>java.lang.Object</td>
55+
<td>the type of the argument</td>
56+
</tr>
57+
<tr>
58+
<td>Value</td>
59+
<td>java.lang.String</td>
60+
<td>the value of the option</td>
61+
</tr>
62+
<tr>
63+
<td>Values</td>
64+
<td>java.lang.String[]</td>
65+
<td>the values of the option</td>
66+
</tr>
67+
</table>
68+
</section>
69+
</body>
70+
</document>

0 commit comments

Comments
 (0)