You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by ro...@apache.org on 2004/07/21 23:16:36 UTC
cvs commit: jakarta-commons/cli/xdocs usage.xml
roxspring 2004/07/21 14:16:35
Modified: cli/xdocs usage.xml
Log:
Documentation fixes
PR:30089
Submitted by: Dennis Lundberg
Reviewed by: roxspring
Revision Changes Path
1.6 +28 -25 jakarta-commons/cli/xdocs/usage.xml
Index: usage.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/cli/xdocs/usage.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- usage.xml 22 Apr 2004 23:00:13 -0000 1.5
+++ usage.xml 21 Jul 2004 21:16:35 -0000 1.6
@@ -32,7 +32,7 @@
<p>
A boolean option is represented on a command line by the presence
of the option, i.e. if the option is found then the option value
- is true, otherwise the value is false.
+ is <code>true</code>, otherwise the value is <code>false</code>.
</p>
<p>
The <code>DateApp</code> utility prints the current date to standard
@@ -43,7 +43,7 @@
<subsection name="Create the Options">
<p>
An <a href="apidocs/org/apache/commons/cli/Options.html">
- Options</a> object must be created and the<code>Option</code> must be
+ Options</a> object must be created and the <code>Option</code> must be
added to it.
</p>
<source>
@@ -55,10 +55,10 @@
<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
+ The second parameter 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
+ <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>
@@ -66,7 +66,9 @@
<subsection name="Parsing the command line arguments">
<p>
The <code>parse</code> methods of <code>CommandLineParser</code> are used
- to parse the command line arguments.
+ to parse the command line arguments. The <code>PosixPaser</code> is
+ great when you need to handle options that are one character long,
+ like the <code>t</code> option in this example.
</p>
<source>CommandLineParser parser = new PosixParser();
CommandLine cmd = parser.parse( options, args);</source>
@@ -75,9 +77,9 @@
this we will interrogate the
<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
+ <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
- it returns false.
+ it returns <code>false</code>.
</p>
<source>if(cmd.hasOption("t")) {
// print the date and time
@@ -96,7 +98,7 @@
<source>// add c option
options.addOption("c", true, "country code");</source>
<p>
- The second parameter is true this time. This specifies that the
+ The second parameter is <code>true</code> this time. This specifies that the
<code>c</code> option requires an argument value. If the required option
argument value is specified on the command line it is returned,
otherwise <code>null</code> is returned.
@@ -104,11 +106,11 @@
</subsection>
<subsection name="Retrieving the argument value">
<p>
- The <code>getOptionValue</code> methods of <code>Options</code> are
+ The <code>getOptionValue</code> methods of <code>CommandLine</code> are
used to retrieve the argument values of options.
</p>
<source>// get c option value
-String countryCode = options.getOptionValue("c");
+String countryCode = cmd.getOptionValue("c");
if(countryCode == null) {
// print default date
@@ -121,9 +123,9 @@
<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
+ One of the most ubiquitous Java applications
+ <a href="http://ant.apache.org/">Ant</a> will be used
+ here to illustrate how to create the <code>Options</code> required. The following
is the help output for Ant.
</p>
<source>ant [options] [target [target2 [target3] ...]]
@@ -145,8 +147,8 @@
<subsection name="Boolean Options">
<p>
Lets create the boolean options for the application as they
- are the easiest to create. For clarity the constructors on
- Option are used here.
+ are the easiest to create. For clarity the constructors for
+ <code>Option</code> are used here.
</p>
<source>Option help = new Option( "help", "print this message" );
Option projecthelp = new Option( "projecthelp", "print project help information" );
@@ -159,7 +161,7 @@
</subsection>
<subsection name="Argument Options">
<p>
- The argument options are created using the OptionBuilder.
+ The argument options are created using the <code>OptionBuilder</code>.
</p>
<source>Option logfile = OptionBuilder.withArgName( "file" )
.hasArg()
@@ -186,12 +188,12 @@
Option find = OptionBuilder.withArgName( "file" )
.hasArg()
.withDescription( "search for buildfile towards the "
- + "root of the filesystem and use it" )
+ + "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
+ The last option to create is the Java property and it is also created
using the OptionBuilder.
</p>
<source>Option property = OptionBuilder.withArgName( "property=value" )
@@ -207,7 +209,7 @@
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>
+ <a href="apidocs/org/apache/commons/cli/CommandLine.html#addOption(org.apache.commons.cli.Option)">addOption</a>
method of <code>Options</code>.
</p>
<source>Options options = new Options();
@@ -232,13 +234,15 @@
</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
+ We now need to create a <code>Parser</code>. This will parse the command
+ line arguments, using the rules specified by the <code>Options</code> and
return an instance of <a href="apidocs/org/apache/commons/cli/CommandLine.html">CommandLine</a>.
+ This time we will use a <a href="apidocs/org/apache/commons/cli/GnuParser.html">GnuParser</a>
+ which is able to handle options that are more than one character long.
</p>
<source>public static void main( String[] args ) {
// create the parser
- CommandLineParser parser = new PosixParser();
+ CommandLineParser parser = new GnuParser();
try {
// parse the command line arguments
CommandLine line = parser.parse( options, args );
@@ -251,7 +255,7 @@
</subsection>
<subsection name="Querying the commandline">
<p>
- To see if an option has been passed the<code>hasOption</code>
+ 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>
@@ -300,8 +304,7 @@
<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>.
+ we will use 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.
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org