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="[EMAIL PROTECTED]">John Keyes</author> - <title>Option</title> + <author email="[EMAIL PROTECTED]">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="[EMAIL PROTECTED]">John Keyes</author> - <title>Usage Scenario's</title> + <author email="[EMAIL PROTECTED]">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: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>