commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jke...@apache.org
Subject cvs commit: jakarta-commons/cli/xdocs introduction.xml navigation.xml properties.xml usage.xml ant.xml creation.xml parser.xml
Date Tue, 15 Oct 2002 22:53:33 GMT
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 &lt;file&gt;        use given file for log
  +  -logger &lt;classname&gt;    the class which is to perform logging
  +  -listener &lt;classname&gt;  add an instance of class as a project listener
  +  -buildfile &lt;file&gt;      use given buildfile
  +  -D&lt;property>=&lt;value&gt;   use value for given property
  +  -find &lt;file&gt;           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 &lt;property=value&gt;     use value for given property
  +-buildfile &lt;file&gt;       use given buildfile
  +-debug                  print debugging information
  +-emacs                  produce logging information without adornments
  +-file &lt;file&gt;            search for buildfile towards the root of the
  +                        filesystem and use it
  +-help                   print this message
  +-listener &lt;classname&gt;   add an instance of class as a project listener
  +-logger &lt;classname&gt;     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:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message