jkeyes 2002/07/08 13:22:00
Modified: cli/src/java/org/apache/commons/cli Options.java
cli/xdocs introduction.xml navigation.xml
Added: cli/xdocs ant.xml creation.xml parser.xml properties.xml
Log:
new documentation, modified addOption(Option)
Revision Changes Path
1.6 +5 -2 jakarta-commons/cli/src/java/org/apache/commons/cli/Options.java
Index: Options.java
===================================================================
RCS file: /home/cvs/jakarta-commons/cli/src/java/org/apache/commons/cli/Options.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- Options.java 4 Jul 2002 22:32:12 -0000 1.5
+++ Options.java 8 Jul 2002 20:22:00 -0000 1.6
@@ -203,17 +203,19 @@
}
/**
- * <p>Adds the option to the necessary member lists</p>
+ * <p>Adds an option instance</p>
*
* @param opt the option that is to be added
*/
- private void addOption(Option opt) {
+ public Options addOption(Option opt) {
String shortOptStr = "-" + opt.getOpt();
+ // add it to the long option list
if ( opt.hasLongOpt() ) {
longOpts.put( "--" + opt.getLongOpt(), opt );
}
+ // if the option is required add it to the required list
if ( opt.isRequired() ) {
requiredOpts.put( "-" + opt.getOpt(), opt );
}
@@ -221,6 +223,7 @@
shortOpts.put( "-" + opt.getOpt(), opt );
options.add( opt );
+ return this;
}
/** <p>Retrieve a read-only list of options in this set</p>
1.2 +6 -6 jakarta-commons/cli/xdocs/introduction.xml
Index: introduction.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/cli/xdocs/introduction.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- introduction.xml 24 Jun 2002 20:38:26 -0000 1.1
+++ introduction.xml 8 Jul 2002 20:22:00 -0000 1.2
@@ -22,15 +22,15 @@
</p>
<p>
CLI uses the <a href="apidocs/org/apache/commons/cli/Options.html">
- <code>Options</code></a> class, as a container for
+ Options</a> class, as a container for
<a href="apidocs/org/apache/commons/cli/Options.html">
- <code>Option</code></a> instances. There are two ways to create
+ Option</a> instances. There are two ways to create
<code>Option</code>s in CLI. One of them is via the constuctors,
the other way is via the factory methods defined in
<code>Options</code>.
</p>
<p>
- The <a href="usage.html">Simple Option</a> document provides examples
+ The <a href="usage.html">Simple Example</a> document provides examples
how to create an <code>Options</code> object.
</p>
<p>
@@ -48,11 +48,11 @@
<p>
The <code>parse</code> method defined on
<a href="apidocs/org/apache/commons/cli/CommandLineParser.html">
- <code>CommandLineParser</code></a> takes an <code>Options</code>
+ CommandLineParser</a> takes an <code>Options</code>
instance and a <code>java.util.List</code> of arguments and
returns a
<a href="apidocs/org/apache/commons/cli/CommandLine.html">
- <code>CommandLine</code></a>.
+ CommandLine</a>.
</p>
<p>
The result of the parsing stage is a <code>CommandLine</code>
@@ -72,7 +72,7 @@
to the user code.
</p>
<p>
- The <a href="usage.html">Simple Option</a> document provides examples
+ The <a href="usage.html">Simple Example</a> document provides examples
how to create an <code>Options</code> object.
</p>
<p>
1.3 +6 -1 jakarta-commons/cli/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/cli/xdocs/navigation.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- navigation.xml 24 Jun 2002 20:38:26 -0000 1.2
+++ navigation.xml 8 Jul 2002 20:22:00 -0000 1.3
@@ -6,7 +6,12 @@
<body>
<menu name="User Documentation">
<item name="Command Line Processing" href="/introduction.html"/>
- <item name="Simple Option" href="/usage.html"/>
+ <item name="Option">
+ <item name="Properties" href="/properties.html"/>
+ <item name="Construction" href="/creation.html"/>
+ <item name="Simple Example" href="/usage.html"/>
+ </item>
+ <item name="Command Line Parser" href="/parser.html"/>
</menu>
</body>
</project>
1.1 jakarta-commons/cli/xdocs/ant.xml
Index: ant.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="jbjk@mac.com">John Keyes</author>
<title>Processing Ants' Command Line</title>
</properties>
<body>
<section name="Introduction">
<p>
By default, CLI uses a POSIX style argument parser. This parser
only provides support for single character options. To provide
support for an application like <a href="http://jakarta.apache.org/ant">Ant</a>
it is necessary to use the GNU style argument parser. This provides
support for multi character options. Read on to discover how to
configure this parser and also how to process the command line options.
</p>
</section>
<section name="Configuring the GNU Parser">
<p>
CLI provides support for multiple parsers. The
<code>org.apache.commons.cli.parser</code> system property is used
to determine what parser to use. To change the parser set the
system property to the class name of the required parser.
</p>
<source>
// configure CLI to use the GNU Parser
System.setProperty( "org.apache.commons.cli.parser",
"org.apache.commons.cli.GnuParser" );</source>
</section>
<section name="Creating the Ant Options">
<p>
There are three types of Options used in Ant. They are:
<ul>
<li>boolean option - the option is either present or not</li>
<li>value option - the option is present and requires a value</li>
<li>property option - the same style as Java system properties.
For example, "-Dproperty=value".</li>
</ul>
</p>
</section>
</body>
</document>
1.1 jakarta-commons/cli/xdocs/creation.xml
Index: creation.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="jbjk@mac.com">John Keyes</author>
<title>Option</title>
</properties>
<body>
<section name="Option Construction">
<p>
There are two ways to create an
<a href="apidocs/org/apache/commons/cli/Option.html">Option</a>;
with the Option constructors or with the factory methods
defined in
<a href="apidocs/org/apache/commons/cli/Options.html">Options</a>.
The method signatures of both approaches are identical.
</p>
<p>
The entries in the following table describe the method
signatures of the constructors and of the factory methods
using the names of the properties the parameters represent.
</p>
<table>
<tr>
<th>API</th>
<th>API</th>
<th>Parameter Order</th>
</tr>
<tr>
<td><a href="apidocs/org/apache/commons/cli/Option.html#Option(java.lang.String,
boolean, java.lang.String)">ctor</a></td>
<td><a href="apidocs/org/apache/commons/cli/Options.html#addOption(java.lang.String,
boolean, java.lang.String)">factory</a></td>
<td>Opt, Arg, Description</td>
</tr>
<tr>
<td><a href="apidocs/org/apache/commons/cli/Option.html#Option(java.lang.String,
java.lang.String, boolean, java.lang.String)">ctor</a></td>
<td><a href="apidocs/org/apache/commons/cli/Options.html#addOption(java.lang.String,
java.lang.String, boolean, java.lang.String)">factory</a></td>
<td>Opt, LongOpt, Arg, Description</td>
</tr>
<tr>
<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>
<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>
<td>Opt, LongOpt, Arg, Description, Required</td>
</tr>
<tr>
<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>
<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>
<td>Opt, LongOpt, Arg, Description, Required, MultipleArgs</td>
</tr>
<tr>
<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>
<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>
<td>Opt, LongOpt, Arg, Description, Required, MultipleArgs, Type</td>
</tr>
</table>
<p>
To add an <a href="apidocs/org/apache/commons/cli/Option.html">Option</a>
that has been created using a constructor the
<a href="apidocs/org/apache/commons/cli/Options.html#addOption(org.apache.commons.cli.Option)">addOption</a>
method must be used.
</p>
</section>
</body>
</document>
1.1 jakarta-commons/cli/xdocs/parser.xml
Index: parser.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="jbjk@mac.com">John Keyes</author>
<title>Creating a command line parser</title>
</properties>
<body>
<section name="Creating a Parser">
<p>
The
<a href="apidocs/org/apache/commons/cli/CommandLineParserFactory.html#newParser()">newParser</a>
method on <a href="apidocs/org/apache/commons/cli/CommandLineParserFactory.html">
CommandLineParserFactory</a> is used to create command line
parser instances.
</p>
<source>
// create a command line parser
CommandLineParser parser = CommandLineParserFactory.newParser();</source>
</section>
<section name="The right tool for the job">
<p>
Different applications may require different parsing implementation
strategies. CLI ships with two implementations: <a href="apidocs/org/apache/commons/cli/PosixParser.html">
PosixParser</a> and <a href="apidocs/org/apache/commons/cli/GnuParser.html">
GnuParser</a>. Both of these implement the <a href="apidocs/org/apache/commons/cli/CommandLineParser.html">
CommandLineParser</a> interface.
</p>
<p>
The parser implementation is specified using the
<code>org.apache.commons.cli.parser</code> system property. This is
set
to be the <a href="apidocs/org/apache/commons/cli/PosixParser.html">PosixParser</a>
by default.
</p>
<source>
// parser is a PosixParser
CommandLineParser parser = CommandLineParserFactory.newParser();
// configure CLI to use the GNU Parser
System.setProperty( "org.apache.commons.cli.parser",
"org.apache.commons.cli.GnuParser" );
// parser is a GnuParser
parser = CommandLineParserFactory.newParser();
// configure CLI to use the Posix Parser
System.setProperty( "org.apache.commons.cli.parser",
"org.apache.commons.cli.PosixParser" );
// parser is a PosixParser
parser = CommandLineParserFactory.newParser();
</source>
</section>
<section name="Parse the command line">
<p>
Now that a parser has been created the command line tokens can be
parsed. The two <code>parse</code> methods on
<a href="apidocs/org/apache/commons/cli/CommandLineParser.html">CommandLineParser</a>
perform this task.
</p>
<source>
public static void main( String[] args ) {
// create the options
Options options = ...;
// create the parser
CommandLine parser = ...;
// parse the command line tokens
CommandLine cmd = parser.parse( options, args );
}</source>
</section>
</body>
</document>
1.1 jakarta-commons/cli/xdocs/properties.xml
Index: properties.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="jbjk@mac.com">John Keyes</author>
<title>Option</title>
</properties>
<body>
<section name="Option Properties">
<p>
The following are the properties of an <a href="apidocs/org/apache/commons/cli/Option.html">Option</a>.
</p>
<table>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>Opt</td>
<td>java.lang.String</td>
<td>the identification string</td>
</tr>
<tr>
<td>LongOpt</td>
<td>java.lang.String</td>
<td>an alias and more descriptive identification string</td>
</tr>
<tr>
<td>Description</td>
<td>java.lang.String</td>
<td>a description of the function of the option</td>
</tr>
<tr>
<td>Required</td>
<td>boolean</td>
<td>a flag to say whether the option <b>must</b> appear on
the command line.</td>
</tr>
<tr>
<td>MultipleArgs</td>
<td>boolean</td>
<td>a flag to say whether the option takes multiple argument
values</td>
</tr>
<tr>
<td>Arg</td>
<td>boolean</td>
<td>a flag to say whether the option takes an argument</td>
</tr>
<tr>
<td>Type</td>
<td>java.lang.Object</td>
<td>the type of the argument</td>
</tr>
<tr>
<td>Value</td>
<td>java.lang.String</td>
<td>the value of the option</td>
</tr>
<tr>
<td>Values</td>
<td>java.lang.String[]</td>
<td>the values of the option</td>
</tr>
</table>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>
|