You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by jk...@apache.org on 2002/10/16 00:53:33 UTC
cvs commit: jakarta-commons/cli/xdocs introduction.xml navigation.xml properties.xml usage.xml ant.xml creation.xml parser.xml
jkeyes 2002/10/15 15:53:33
Modified: cli/xdocs introduction.xml navigation.xml properties.xml
usage.xml
Removed: cli/xdocs ant.xml creation.xml parser.xml
Log:
documentation updates in preperation for the release
Revision Changes Path
1.3 +4 -3 jakarta-commons/cli/xdocs/introduction.xml
Index: introduction.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/cli/xdocs/introduction.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- introduction.xml 8 Jul 2002 20:22:00 -0000 1.2
+++ introduction.xml 15 Oct 2002 22:53:32 -0000 1.3
@@ -30,8 +30,9 @@
<code>Options</code>.
</p>
<p>
- The <a href="usage.html">Simple Example</a> document provides examples
- how to create an <code>Options</code> object.
+ The <a href="usage.html">Usage Scenarios</a> document provides
+ examples how to create an <code>Options</code> object and also
+ provides some real world examples.
</p>
<p>
The result of the definition stage is an <code>Options</code>
@@ -72,7 +73,7 @@
to the user code.
</p>
<p>
- The <a href="usage.html">Simple Example</a> document provides examples
+ The <a href="usage.html">Usage Scenarios</a> document provides examples
how to create an <code>Options</code> object.
</p>
<p>
1.4 +3 -7 jakarta-commons/cli/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/cli/xdocs/navigation.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- navigation.xml 8 Jul 2002 20:22:00 -0000 1.3
+++ navigation.xml 15 Oct 2002 22:53:32 -0000 1.4
@@ -5,13 +5,9 @@
<body>
<menu name="User Documentation">
- <item name="Command Line Processing" href="/introduction.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"/>
+ <item name="Introduction" href="/introduction.html"/>
+ <item name="Usage Scenarios" href="/usage.html"/>
+ <item name="Option Properties" href="/properties.html"/>
</menu>
</body>
</project>
1.2 +40 -13 jakarta-commons/cli/xdocs/properties.xml
Index: properties.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/cli/xdocs/properties.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- properties.xml 8 Jul 2002 20:22:00 -0000 1.1
+++ properties.xml 15 Oct 2002 22:53:32 -0000 1.2
@@ -2,14 +2,18 @@
<document>
<properties>
- <author email="jbjk@mac.com">John Keyes</author>
- <title>Option</title>
+ <author email="john@integralsource.com">John Keyes</author>
+ <title>Option Properties</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>.
+ The following are the properties that each
+ <a href="apidocs/org/apache/commons/cli/Options.html">Option</a> has. All of these
+ can be set using the accessors or using the methods
+ defined on the
+ <a href="apidocs/org/apache/commons/cli/OptionBuilder.html">OptionBuilder</a>.
</p>
<table>
<tr>
@@ -18,49 +22,72 @@
<th>Description</th>
</tr>
<tr>
- <td>Opt</td>
+ <td>opt</td>
<td>java.lang.String</td>
- <td>the identification string</td>
+ <td>the identification string of the Option.</td>
</tr>
<tr>
- <td>LongOpt</td>
+ <td>longOpt</td>
<td>java.lang.String</td>
<td>an alias and more descriptive identification string</td>
</tr>
<tr>
- <td>Description</td>
+ <td>description</td>
<td>java.lang.String</td>
<td>a description of the function of the option</td>
</tr>
<tr>
- <td>Required</td>
+ <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>multipleArgs</td>
<td>boolean</td>
<td>a flag to say whether the option takes multiple argument
values</td>
</tr>
<tr>
- <td>Arg</td>
+ <td>arg</td>
<td>boolean</td>
<td>a flag to say whether the option takes an argument</td>
</tr>
<tr>
- <td>Type</td>
+ <td>args</td>
+ <td>boolean</td>
+ <td>a flag to say whether the option takes more than one argument</td>
+ </tr>
+ <tr>
+ <td>optionalArg</td>
+ <td>boolean</td>
+ <td>a flag to say whether the option's argument is optional</td>
+ </tr>
+ <tr>
+ <td>argName</td>
+ <td>java.lang.String</td>
+ <td>the name of the argument value for the usage statement</td>
+ </tr>
+ <tr>
+ <td>valueSeparator</td>
+ <td>char</td>
+ <td>the character value used to split the argument string, that
+ is used in conjunction with multipleArgs e.g.
+ if the separator is ',' and the argument string is 'a,b,c' then
+ there are three argument values, 'a', 'b' and 'c'.</td>
+ </tr>
+ <tr>
+ <td>type</td>
<td>java.lang.Object</td>
<td>the type of the argument</td>
</tr>
<tr>
- <td>Value</td>
+ <td>value</td>
<td>java.lang.String</td>
<td>the value of the option</td>
</tr>
<tr>
- <td>Values</td>
+ <td>values</td>
<td>java.lang.String[]</td>
<td>the values of the option</td>
</tr>
1.3 +269 -35 jakarta-commons/cli/xdocs/usage.xml
Index: usage.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/cli/xdocs/usage.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- usage.xml 20 Jun 2002 21:32:38 -0000 1.2
+++ usage.xml 15 Oct 2002 22:53:32 -0000 1.3
@@ -2,12 +2,12 @@
<document>
<properties>
- <author email="jbjk@mac.com">John Keyes</author>
- <title>Usage Scenario's</title>
+ <author email="john@integralsource.com">John Keyes</author>
+ <title>Usage Scenarios</title>
</properties>
<body>
- <section name="Usage Scenario's">
+ <section name="Usage Scenarios">
<p>
The following sections describe some example scenarios on how to
use CLI in applications.
@@ -20,15 +20,16 @@
is true, otherwise the value is false.
</p>
<p>
- The <code>DateApp</code> utility prints the current date to standard output. If the
- <code>-t</code> option is present the current time is also printed.
+ The <code>DateApp</code> utility prints the current date to standard
+ output. If the <code>-t</code> option is present the current time is
+ also printed.
</p>
- </subsection>
- <subsection name="Create the Options">
+ </subsection>
+ <subsection name="Create the Options">
<p>
An <a href="apidocs/org/apache/commons/cli/Options.html">
- <code>Options</code></a> object must be created and the <code>t</code>
- <code>Option</code> must be added to it.
+ Options</a> object must be created and the<code>Option</code> must be
+ added to it.
</p>
<source>
// create Options object
@@ -36,34 +37,33 @@
// add t option
options.addOption("t", false, "display current time");</source>
- <p>
- The <code>addOption</code> method has three parameters. The first
- parameter is a <code>java.lang.String</code> that represents the option. The
- second paramter is a <code>boolean</code> that specifies whether the
- option requires an argument or not. In the case of a boolean option
- (sometimes referred to as a flag) an argument value is not present so
- it <code>false</code> is passed. The third parameter is the description
- of the option. This description will be used in the usage text of the
- application.
- </p>
+ <p>
+ The <code>addOption</code> method has three parameters. The first
+ parameter is a <code>java.lang.String</code> that represents the option.
+ Thesecond paramter is a <code>boolean</code> that specifies whether the
+ option requires an argument or not. In the case of a boolean option
+ (sometimes referred to as a flag) an argument value is not present so
+ it <code>false</code> is passed. The third parameter is the description
+ of the option. This description will be used in the usage text of the
+ application.
+ </p>
</subsection>
<subsection name="Parsing the command line arguments">
<p>
The <code>parse</code> methods of <code>Options</code> are used to
parse the command line arguments.
</p>
- <source>
-CommandLine cmd = options.parse(args);</source>
+ <source>CommandLine cmd = options.parse(args);</source>
<p>
Now we need to check if the <code>t</code> option is present. To do
this we will interrogate the
- <a href="apidocs/org/apache/commons/cli/CommandLine.html"><code>CommandLine</code>
+ <a href="apidocs/org/apache/commons/cli/CommandLine.html">CommandLine
</a> object. The <code>hasOption</code> method takes a
- <code>java.lang.String</code> parameter and returns true if the option represented
- by the <code>java.lang.String</code> is present, otherwise it returns false.
+ <code>java.lang.String</code> parameter and returns true if the option
+ represented by the <code>java.lang.String</code> is present, otherwise
+ it returns false.
</p>
- <source>
-if(cmd.hasOption("t")) {
+ <source>if(cmd.hasOption("t")) {
// print the date and time
}
else {
@@ -77,8 +77,7 @@
date and time in any country in the world. To facilitate this a new
command line option, <code>c</code>, has been introduced.
</p>
- <source>
-// add c option
+ <source>// add c option
options.addOption("c", true, "country code");</source>
<p>
The second parameter is true this time. This specifies that the
@@ -92,8 +91,7 @@
The <code>getOptionValue</code> methods of <code>Options</code> are
used to retrieve the argument values of options.
</p>
- <source>
-// get c option value
+ <source>// get c option value
String countryCode = options.getOptionValue("c");
if(countryCode == null) {
@@ -103,14 +101,250 @@
// print date for country specified by countryCode
}</source>
</subsection>
- <subsection name="More Information">
+ </section>
+
+ <section name="Ant Example">
+ <p>
+ As one of the most ubquituous Java applications
+ <a href="http://jakarta.apache.org/ant">Ant</a> it will be used
+ here to illustrate how to create the Options required. The following
+ is the help output for Ant.
+ </p>
+ <source>ant [options] [target [target2 [target3] ...]]
+ Options:
+ -help print this message
+ -projecthelp print project help information
+ -version print the version information and exit
+ -quiet be extra quiet
+ -verbose be extra verbose
+ -debug print debugging information
+ -emacs produce logging information without adornments
+ -logfile <file> use given file for log
+ -logger <classname> the class which is to perform logging
+ -listener <classname> add an instance of class as a project listener
+ -buildfile <file> use given buildfile
+ -D<property>=<value> use value for given property
+ -find <file> search for buildfile towards the root of the
+ filesystem and use it</source>
+ <subsection name="Boolean Options">
<p>
- <ul>
- <li>CLI <a href="apidocs/index.html">javadoc</a></li>
- <li>CLI examples</li>
- </ul>
+ Lets create the boolean options for the application as they
+ are the easiest to create. For clarity the constructors on
+ Option are used here.
</p>
+ <source>Option help = new Option( "help", "print this message" );
+Option projecthelp = new Option( "projecthelp", "print project help information" );
+Option version = new Option( "version", "print the version information and exit" );
+Option quiet = new Option( "quiet", "be extra quiet" );
+Option verbose = new Option( "verbose", "be extra verbose" );
+Option debug = new Option( "debug", "print debugging information" );
+Option emacs = new Option( "emacs",
+ "produce logging information without adornments" );</source>
</subsection>
+ <subsection name="Argument Options">
+ <p>
+ The argument options are created using the OptionBuilder.
+ </p>
+ <source>Option logfile = OptionBuilder.withArgName( "file" )
+ .hasArg()
+ .withDescription( "use given file for log" )
+ .create( "file" );
+
+Option logger = OptionBuilder.withArgName( "classname" )
+ .hasArg()
+ .withDescription( "the class which it to perform "
+ + "logging" )
+ .create( "logger" );
+
+Option listener = OptionBuilder.withArgName( "classname" )
+ .hasArg()
+ .withDescription( "add an instance of class as "
+ + "a project listener" )
+ .create( "listener");
+
+Option buildfile = OptionBuilder.withArgName( "file" )
+ .hasArg()
+ .withDescription( "use given buildfile" )
+ .create( "buildfile");
+
+Option find = OptionBuilder.withArgName( "file" )
+ .hasArg()
+ .withDescription( "search for buildfile towards the "
+ + "root of the filesystem and use it" )
+ .create( "file" );</source>
+ </subsection>
+ <subsection name="Java Property Option">
+ <p>
+ The last option to create is the Java property and it too is created
+ using the OptionBuilder.
+ </p>
+ <source>Option property = OptionBuilder.withArgName( "property=value" )
+ .hasArg()
+ .withValueSeparator()
+ .withDescription( "use value for given property" )
+ .create( "D" );</source>
+ </subsection>
+ <subsection name="Create the Options">
+ <p>
+ Now that we have created each
+ <a href="apidocs/org/apache/commons/cli/Option.html">Option</a> we need
+ to create the
+ <a href="apidocs/org/apache/commons/cli/Options.html">Options</a>
+ instance. This is achieved using the
+ <a href="apidocs/org/apache/commons/cli/CommandLine.html#hasOption(java.lang.String)">addOption</a>
+ method of <code>Options</code>.
+ </p>
+ <source>Options options = new Options();
+
+options.addOption( help );
+options.addOption( projecthelp );
+options.addOption( version );
+options.addOption( quiet );
+options.addOption( verbose );
+options.addOption( debug );
+options.addOption( emacs );
+options.addOption( logfile );
+options.addOption( logger );
+options.addOption( listener );
+options.addOption( buildfile );
+options.addOption( find );
+options.addOption( property );</source>
+ <p>
+ All the preperation is now complete and we are now ready to
+ parse the command line arguments.
+ </p>
+ </subsection>
+ <subsection name="Create the Parser">
+ <p>
+ We now need to create a Parser. This will parse the command
+ line arguments, using the rules specified by the Options and
+ return an instance of <a href="apidocs/org/apache/commons/cli/CommandLine.html">CommandLine</a>.
+ </p>
+ <source>public static void main( String[] args ) {
+ // create the parser
+ CommandLineParser parser = new PosixParser();
+ try {
+ // parse the command line arguments
+ CommandLine line = parser.parse( options, args );
+ }
+ catch( ParseException exp ) {
+ // oops, something went wrong
+ System.err.println( "Parsing failed. Reason: " + exp.getMessage() );
+ }
+}</source>
+ </subsection>
+ <subsection name="Querying the commandline">
+ <p>
+ To see if an option has been passed the<code>hasOption</code>
+ method is used. The argument value can be retrieved using
+ the <code>getValue</code> method.
+ </p>
+ <source>// has the buildfile argument been passed?
+if( line.hasOption( "buildfile" ) ) {
+ // initialise the member variable
+ this.buildfile = line.getValue( "buildfile" );
+}</source>
+ </subsection>
+ <subsection name="Usage/Help">
+ <p>
+ CLI also provides the means to automatically generate usage
+ and help information. This is achieved with the
+ <a href="apidocs/org/apache/commons/cli/HelpFormatter.html">HelpFormatter</a>
+ class.
+ </p>
+ <source>// automatically generate the help statement
+HelpFormatter formatter = new HelpFormatter();
+formatter.printHelp( "ant", options );</source>
+ <p>
+ When executed the following output is produced:
+ </p>
+ <source>usage: ant
+-D <property=value> use value for given property
+-buildfile <file> use given buildfile
+-debug print debugging information
+-emacs produce logging information without adornments
+-file <file> search for buildfile towards the root of the
+ filesystem and use it
+-help print this message
+-listener <classname> add an instance of class as a project listener
+-logger <classname> the class which it to perform logging
+-projecthelp print project help information
+-quiet be extra quiet
+-verbose be extra verbose
+-version print the version information and exit</source>
+ <p>
+ If you also require to have a usage statement printed
+ then calling <code>formatter.printHelp( "ant", options, true )</code>
+ will generate a usage statment as well as the help information.
+ </p>
+ </subsection>
+ </section>
+
+ <section name="ls Example">
+ <p>
+ One of the most widely used command line applications in the *nix world
+ is <code>ls</code>. To parse a command line for an application like this
+ a different parser is required, the
+ <a href="apidocs/org/apache/commons/cli/PosixParser.html">PosixParser</a>.
+ Due to the large number of options required for <code>ls</code> this
+ example will only cover a small proportion of the options. The following
+ is a section of the help output.
+ </p>
+ <source>Usage: ls [OPTION]... [FILE]...
+List information about the FILEs (the current directory by default).
+Sort entries alphabetically if none of -cftuSUX nor --sort.
+
+-a, --all do not hide entries starting with .
+-A, --almost-all do not list implied . and ..
+-b, --escape print octal escapes for nongraphic characters
+ --block-size=SIZE use SIZE-byte blocks
+-B, --ignore-backups do not list implied entries ending with ~
+-c with -lt: sort by, and show, ctime (time of last
+ modification of file status information)
+ with -l: show ctime and sort by name
+ otherwise: sort by ctime
+-C list entries by columns</source>
+ <p>
+ The following is the code that is used to create the
+ <a href="apidocs/org/apache/commons/cli/Options.html">Options</a> for this example.
+ </p>
+ <source>// create the command line parser
+CommandLineParser parser = new PosixParser();
+
+// create the Options
+Options options = new Options();
+options.addOption( "a", "all", false, "do not hide entries starting with ." );
+options.addOption( "A", "almost-all", false, "do not list implied . and .." );
+options.addOption( "b", "escape", false, "print octal escapes for nongraphic "
+ + "characters" );
+options.addOption( OptionBuilder.withLongOpt( "block-size" )
+ .withDescription( "use SIZE-byte blocks" )
+ .withValueSeparator( '=' )
+ .hasArg()
+ .create() );
+options.addOption( "B", "ignore-backups", false, "do not list implied entried "
+ + "ending with ~");
+options.addOption( "c", false, "with -lt: sort by, and show, ctime (time of last "
+ + "modification of file status information) with "
+ + "-l:show ctime and sort by name otherwise: sort "
+ + "by ctime" );
+options.addOption( "C", false, "list entries by columns" );
+
+String[] args = new String[]{ "--block-size=10" };
+
+try {
+ // parse the command line arguments
+ CommandLine line = parser.parse( options, args );
+
+ // validate that block-size has been set
+ if( line.hasOption( "block-size" ) ) {
+ // print the value of block-size
+ System.out.println( line.getOptionValue( "block-size" ) );
+ }
+}
+catch( ParseException exp ) {
+ System.out.println( "Unexpected exception:" + exp.getMessage() );
+}</source>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>