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 ant.xml creation.xml parser.xml properties.xml introduction.xml navigation.xml
Date Mon, 08 Jul 2002 20:22:00 GMT
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>


Mime
View raw message