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/src/java/org/apache/commons/cli AlreadySelectedException.java BasicParser.java CommandLine.java CommandLineParser.java CommandLineParserFactory.java GnuParser.java MissingArgumentException.java MissingOptionException.java OptionBuilder.java OptionGroup.java Options.java ParseException.java Parser.java PosixParser.java UnrecognizedOptionException.java
Date Mon, 26 Aug 2002 20:15:03 GMT
jkeyes      2002/08/26 13:15:03

  Modified:    cli/src/java/org/apache/commons/cli
                        AlreadySelectedException.java BasicParser.java
                        CommandLine.java CommandLineParser.java
                        CommandLineParserFactory.java GnuParser.java
                        MissingArgumentException.java
                        MissingOptionException.java OptionBuilder.java
                        OptionGroup.java Options.java ParseException.java
                        Parser.java PosixParser.java
                        UnrecognizedOptionException.java
  Log:
  javadoc updates
  
  Revision  Changes    Path
  1.3       +8 -6      jakarta-commons/cli/src/java/org/apache/commons/cli/AlreadySelectedException.java
  
  Index: AlreadySelectedException.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/src/java/org/apache/commons/cli/AlreadySelectedException.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- AlreadySelectedException.java	4 Aug 2002 21:06:10 -0000	1.2
  +++ AlreadySelectedException.java	26 Aug 2002 20:15:02 -0000	1.3
  @@ -58,20 +58,22 @@
    * <http://www.apache.org/>.
    *
    */
  -
   package org.apache.commons.cli;
   
  -/** <p>Exception thrown when more than one option in an option group
  +/** 
  + * <p>Thrown when more than one option in an option group
    * has been provided.</p>
    *
  - * @author John Keyes (john @ integralsource.com)
  - * @version $Revision$
  + * @author John Keyes ( jbjk at mac.com )
  + * @see ParseException
    */
   public class AlreadySelectedException extends ParseException {
   
  -    /** Construct a new Exception with a message
  +    /** 
  +     * <p>Construct a new <code>AlreadySelectedException</code> 
  +     * with the specified detail message.</p>
        *
  -     * @param message Explanation of the exception
  +     * @param message the detail message
        */
       public AlreadySelectedException( String message ) {
           super( message );
  
  
  
  1.2       +78 -0     jakarta-commons/cli/src/java/org/apache/commons/cli/BasicParser.java
  
  Index: BasicParser.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/src/java/org/apache/commons/cli/BasicParser.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- BasicParser.java	24 Aug 2002 22:15:31 -0000	1.1
  +++ BasicParser.java	26 Aug 2002 20:15:02 -0000	1.2
  @@ -1,14 +1,92 @@
  +/*
  + * $Header$
  + * $Revision$
  + * $Date$
  + *
  + * ====================================================================
  + *
  + * The Apache Software License, Version 1.1
  + *
  + * Copyright (c) 1999-2001 The Apache Software Foundation.  All rights
  + * reserved.
  + *
  + * Redistribution and use in source and binary forms, with or without
  + * modification, are permitted provided that the following conditions
  + * are met:
  + *
  + * 1. Redistributions of source code must retain the above copyright
  + *    notice, this list of conditions and the following disclaimer.
  + *
  + * 2. Redistributions in binary form must reproduce the above copyright
  + *    notice, this list of conditions and the following disclaimer in
  + *    the documentation and/or other materials provided with the
  + *    distribution.
  + *
  + * 3. The end-user documentation included with the redistribution, if
  + *    any, must include the following acknowlegement:
  + *       "This product includes software developed by the
  + *        Apache Software Foundation (http://www.apache.org/)."
  + *    Alternately, this acknowlegement may appear in the software itself,
  + *    if and wherever such third-party acknowlegements normally appear.
  + *
  + * 4. The names "The Jakarta Project", "Commons", and "Apache Software
  + *    Foundation" must not be used to endorse or promote products derived
  + *    from this software without prior written permission. For written
  + *    permission, please contact apache@apache.org.
  + *
  + * 5. Products derived from this software may not be called "Apache"
  + *    nor may "Apache" appear in their names without prior written
  + *    permission of the Apache Group.
  + *
  + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  + * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  + * SUCH DAMAGE.
  + * ====================================================================
  + *
  + * This software consists of voluntary contributions made by many
  + * individuals on behalf of the Apache Software Foundation.  For more
  + * information on the Apache Software Foundation, please see
  + * <http://www.apache.org/>.
  + *
  + */
   package org.apache.commons.cli;
   
   /**
  + * The class BasicParser provides a very simple implementation of
  + * the {@link Parser#flatten(Options,String[],boolean) flatten} method.
  + *
    * @author John Keyes (jbjk at mac.com)
  + * @see Parser
    */
   public class BasicParser extends Parser {
   
  +    /**
  +     * <p>A simple implementation of {@link Parser}'s abstract
  +     * {@link Parser#flatten(Options,String[],boolean) flatten} method.</p>
  +     *
  +     * <p><b>Note:</b> <code>options</code> and <code>stopAtNonOption</code>
  +     * are not used in this <code>flatten</code> method.</p>
  +     *
  +     * @param options The command line {@link Options}
  +     * @param arguments The command line arguments to be parsed
  +     * @param stopAtNonOption Specifies whether to stop flattening
  +     * when an non option is found.
  +     * @return The <code>arguments</code> String array.
  +     */
       protected String[] flatten( Options options, 
                                   String[] arguments, 
                                   boolean stopAtNonOption )
       {
  +        // just echo the arguments
           return arguments;
       }
   }
  
  
  
  1.10      +41 -23    jakarta-commons/cli/src/java/org/apache/commons/cli/CommandLine.java
  
  Index: CommandLine.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/src/java/org/apache/commons/cli/CommandLine.java,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- CommandLine.java	18 Aug 2002 19:07:42 -0000	1.9
  +++ CommandLine.java	26 Aug 2002 20:15:02 -0000	1.10
  @@ -58,7 +58,6 @@
    * <http://www.apache.org/>.
    *
    */
  -
   package org.apache.commons.cli;
   
   import java.util.Collection;
  @@ -68,7 +67,8 @@
   import java.util.LinkedList;
   import java.util.Map;
   
  -/** <p>Represents list of arguments parsed against
  +/** 
  + * <p>Represents list of arguments parsed against
    * a {@link Options} descriptor.<p>
    *
    * <p>It allows querying of a boolean {@link #hasOption(String opt)},
  @@ -81,8 +81,6 @@
    * @author bob mcwhirter (bob @ werken.com)
    * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
    * @author John Keyes (jbjk at mac.com)
  - *
  - * @version $Revision$
    */
   public class CommandLine {
       
  @@ -104,7 +102,8 @@
       CommandLine() {
       }
       
  -    /** <p>Query to see if an option has been set.</p>
  +    /** 
  +     * <p>Query to see if an option has been set.</p>
        *
        * @param opt Short name of the option
        * @return true if set, false if not
  @@ -113,7 +112,8 @@
           return options.containsKey( opt );
       }
   
  -    /** <p>Query to see if an option has been set.</p>
  +    /** 
  +     * <p>Query to see if an option has been set.</p>
        *
        * @param opt character name of the option
        * @return true if set, false if not
  @@ -123,8 +123,10 @@
       }
   
       /**
  +     * <p>Return the <code>Object</code> type of this <code>Option</code>.</p>
  +     *
        * @param opt the name of the option
  -     * @return the type of opt
  +     * @return the type of this <code>Option</code>
        */
       public Object getOptionObject( String opt ) {
           String res = getOptionValue( opt );
  @@ -134,6 +136,8 @@
       }
   
       /**
  +     * <p>Return the <code>Object</code> type of this <code>Option</code>.</p>
  +     *
        * @param opt the name of the option
        * @return the type of opt
        */
  @@ -141,29 +145,35 @@
           return getOptionObject( String.valueOf( opt ) );
       }
   
  -    /** <p>Retrieve the argument, if any,  of an option.</p>
  +    /** 
  +     * <p>Retrieve the argument, if any, of this option.</p>
        *
        * @param opt the name of the option
  -     * @return Value of the argument if option is set, and has an argument, else null.
  +     * @return Value of the argument if option is set, and has an argument,
  +     * otherwise null.
        */
       public String getOptionValue( String opt ) {
           String[] values = getOptionValues(opt);
           return (values == null) ? null : values[0];
       }
   
  -    /** <p>Retrieve the argument, if any,  of an option.</p>
  +    /** 
  +     * <p>Retrieve the argument, if any, of this option.</p>
        *
        * @param opt the character name of the option
  -     * @return Value of the argument if option is set, and has an argument, else null.
  +     * @return Value of the argument if option is set, and has an argument,
  +     * otherwise null.
        */
       public String getOptionValue( char opt ) {
           return getOptionValue( String.valueOf( opt ) );
       }
   
  -    /** <p>Retrieves the array of values, if any, of an option.</p>
  +    /** 
  +     * <p>Retrieves the array of values, if any, of an option.</p>
        *
        * @param opt string name of the option
  -     * @return An array of values if the option is set, and has an argument, else null.
  +     * @return Values of the argument if option is set, and has an argument,
  +     * otherwise null.
        */
       public String[] getOptionValues( String opt ) {
           List values = new java.util.ArrayList();
  @@ -180,39 +190,46 @@
           return (values.size() == 0) ? null : (String[])values.toArray(new String[]{});
       }
   
  -    /** <p>Retrieves the array of values, if any, of an option.</p>
  +    /** 
  +     * <p>Retrieves the array of values, if any, of an option.</p>
        *
        * @param opt character name of the option
  -     * @return An array of values if the option is set, and has an argument, else null.
  +     * @return Values of the argument if option is set, and has an argument,
  +     * otherwise null.
        */
       public String[] getOptionValues( char opt ) {
           return getOptionValues( String.valueOf( opt ) );
       }
       
  -    /** <p>Retrieve the argument, if any, of an option.</p>
  +    /** 
  +     * <p>Retrieve the argument, if any, of an option.</p>
        *
        * @param opt name of the option
        * @param defaultValue is the default value to be returned if the option is not specified
  -     * @return Value of the argument if option is set, and has an argument, else null.
  +     * @return Value of the argument if option is set, and has an argument,
  +     * otherwise <code>defaultValue</code>.
        */
       public String getOptionValue( String opt, String defaultValue ) {
           String answer = getOptionValue( opt );
           return ( answer != null ) ? answer : defaultValue;
       }
       
  -    /** <p>Retrieve the argument, if any, of an option.</p>
  +    /** 
  +     * <p>Retrieve the argument, if any, of an option.</p>
        *
        * @param opt character name of the option
        * @param defaultValue is the default value to be returned if the option is not specified
  -     * @return Value of the argument if option is set, and has an argument, else null.
  +     * @return Value of the argument if option is set, and has an argument,
  +     * otherwise <code>defaultValue</code>.
        */
       public String getOptionValue( char opt, String defaultValue ) {
           return getOptionValue( String.valueOf( opt ), defaultValue );
       }
   
  -    /** <p>Retrieve any left-over non-recognized options and arguments</p>
  +    /** 
  +     * <p>Retrieve any left-over non-recognized options and arguments</p>
        *
  -     * @return an array of remaining items passed in but not parsed
  +     * @return remaining items passed in but not parsed as an array
        */
       public String[] getArgs() {
           String[] answer = new String[ args.size() ];
  @@ -220,9 +237,10 @@
           return answer;
       }
       
  -    /** <p>Retrieve any left-over non-recognized options and arguments</p>
  +    /** 
  +     * <p>Retrieve any left-over non-recognized options and arguments</p>
        *
  -     * @return List of remaining items passed in but not parsed
  +     * @return remaining items passed in but not parsed as a <code>List</code>.
        */
       public List getArgList() {
           return args;
  
  
  
  1.3       +7 -3      jakarta-commons/cli/src/java/org/apache/commons/cli/CommandLineParser.java
  
  Index: CommandLineParser.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/src/java/org/apache/commons/cli/CommandLineParser.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- CommandLineParser.java	4 Jul 2002 22:32:12 -0000	1.2
  +++ CommandLineParser.java	26 Aug 2002 20:15:02 -0000	1.3
  @@ -61,6 +61,10 @@
   package org.apache.commons.cli;
   
   /**
  + * A class that implements the <code>CommandLineParser</code> interface 
  + * can parse a String array according to the {@link Options} specified
  + * and return a {@link CommandLine}.
  + *
    * @author John Keyes (jbjk at mac.com)
    */
   public interface CommandLineParser {
  
  
  
  1.4       +6 -4      jakarta-commons/cli/src/java/org/apache/commons/cli/CommandLineParserFactory.java
  
  Index: CommandLineParserFactory.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/src/java/org/apache/commons/cli/CommandLineParserFactory.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- CommandLineParserFactory.java	24 Aug 2002 22:15:31 -0000	1.3
  +++ CommandLineParserFactory.java	26 Aug 2002 20:15:02 -0000	1.4
  @@ -73,13 +73,15 @@
       private static String DEFAULT_PARSER = "org.apache.commons.cli.PosixParser";
   
       /**
  -     * @return the CommandLineParser
  +     * @return the default CommandLineParser
        */
       public static CommandLineParser newParser() {
           return newParser( DEFAULT_PARSER );
       }
   
       /**
  +     * @param classname the name of the parser class
  +     * 
        * @return the CommandLineParser specified by <code>classname</code>.
        */
       public static CommandLineParser newParser( String classname ) {
  
  
  
  1.8       +83 -0     jakarta-commons/cli/src/java/org/apache/commons/cli/GnuParser.java
  
  Index: GnuParser.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/src/java/org/apache/commons/cli/GnuParser.java,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- GnuParser.java	24 Aug 2002 22:15:31 -0000	1.7
  +++ GnuParser.java	26 Aug 2002 20:15:02 -0000	1.8
  @@ -1,3 +1,63 @@
  +/*
  + * $Header$
  + * $Revision$
  + * $Date$
  + *
  + * ====================================================================
  + *
  + * The Apache Software License, Version 1.1
  + *
  + * Copyright (c) 1999-2001 The Apache Software Foundation.  All rights
  + * reserved.
  + *
  + * Redistribution and use in source and binary forms, with or without
  + * modification, are permitted provided that the following conditions
  + * are met:
  + *
  + * 1. Redistributions of source code must retain the above copyright
  + *    notice, this list of conditions and the following disclaimer.
  + *
  + * 2. Redistributions in binary form must reproduce the above copyright
  + *    notice, this list of conditions and the following disclaimer in
  + *    the documentation and/or other materials provided with the
  + *    distribution.
  + *
  + * 3. The end-user documentation included with the redistribution, if
  + *    any, must include the following acknowlegement:
  + *       "This product includes software developed by the
  + *        Apache Software Foundation (http://www.apache.org/)."
  + *    Alternately, this acknowlegement may appear in the software itself,
  + *    if and wherever such third-party acknowlegements normally appear.
  + *
  + * 4. The names "The Jakarta Project", "Commons", and "Apache Software
  + *    Foundation" must not be used to endorse or promote products derived
  + *    from this software without prior written permission. For written
  + *    permission, please contact apache@apache.org.
  + *
  + * 5. Products derived from this software may not be called "Apache"
  + *    nor may "Apache" appear in their names without prior written
  + *    permission of the Apache Group.
  + *
  + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  + * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  + * SUCH DAMAGE.
  + * ====================================================================
  + *
  + * This software consists of voluntary contributions made by many
  + * individuals on behalf of the Apache Software Foundation.  For more
  + * information on the Apache Software Foundation, please see
  + * <http://www.apache.org/>.
  + *
  + */
   package org.apache.commons.cli;
   
   import java.util.Arrays;
  @@ -8,16 +68,39 @@
   import java.util.Iterator;
   
   /**
  + * The class GnuParser provides an implementation of the 
  + * {@link Parser#flatten(Options,String[],boolean) flatten} method.
  + *
    * @author John Keyes (jbjk at mac.com)
  + * @see Parser
  + * @version $Revision$
    */
   public class GnuParser extends Parser {
   
  +    /** holder for flattened tokens */
       private ArrayList tokens = new ArrayList();
   
  +    /**
  +     * <p>Resets the members to their original state i.e. remove
  +     * all of <code>tokens</code> entries.
  +     */
       private void init() {
           tokens.clear();
       }
   
  +    /**
  +     * <p>This flatten method does so using the following rules:
  +     * <ol>
  +     *  <li>If an {@link Option} exists for the first character of 
  +     *  the <code>arguments</code> entry <b>AND</b> an {@link Option}

  +     *  does not exist for the whole <code>argument</code> then
  +     *  add the first character as an option to the processed tokens
  +     *  list e.g. "-D" and add the rest of the entry to the also.</li>
  +     *  <li>Otherwise just add the token to the processed tokens list.
  +     *  </li>
  +     * </ol>
  +     * </p>
  +     */
       protected String[] flatten( Options options, 
                                   String[] arguments, 
                                   boolean stopAtNonOption )
  
  
  
  1.2       +10 -7     jakarta-commons/cli/src/java/org/apache/commons/cli/MissingArgumentException.java
  
  Index: MissingArgumentException.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/src/java/org/apache/commons/cli/MissingArgumentException.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- MissingArgumentException.java	10 Jun 2002 18:01:15 -0000	1.1
  +++ MissingArgumentException.java	26 Aug 2002 20:15:02 -0000	1.2
  @@ -61,19 +61,22 @@
   
   package org.apache.commons.cli;
   
  -/** <p>Exception thrown when an option requiring an argument
  +/** 
  + * <p>Thrown when an option requiring an argument
    * is not provided with an argument.</p>
    *
  - * @author bob mcwhirter (bob @ werken.com)
  - * @version $Revision$
  + * @author John Keyes (jbjk at mac.com)
  + * @see ParseException
    */
   public class MissingArgumentException extends ParseException {
       
  -    /** Construct a new Exception with a message
  +    /** 
  +     * <p>Construct a new <code>MissingArgumentException</code> 
  +     * with the specified detail message.</p>
        *
  -     * @param msg Explanation of the exception
  +     * @param message the detail message
        */
  -    public MissingArgumentException(String msg) {
  -        super(msg);
  +    public MissingArgumentException( String message ) {
  +        super( message );
       }
   }
  
  
  
  1.2       +10 -8     jakarta-commons/cli/src/java/org/apache/commons/cli/MissingOptionException.java
  
  Index: MissingOptionException.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/src/java/org/apache/commons/cli/MissingOptionException.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- MissingOptionException.java	10 Jun 2002 18:01:15 -0000	1.1
  +++ MissingOptionException.java	26 Aug 2002 20:15:02 -0000	1.2
  @@ -61,19 +61,21 @@
   
   package org.apache.commons.cli;
   
  -/** <p>Exception thrown when an option requiring an argument
  - * is not provided with an argument.</p>
  +/** 
  + * <p>Thrown when a required option has not been provided.</p>
    *
  - * @author bob mcwhirter (bob @ werken.com)
  - * @version $Revision$
  + * @author John Keyes ( jbjk at mac.com )
  + * @see ParseException
    */
   public class MissingOptionException extends ParseException {
       
  -    /** Construct a new Exception with a message
  +    /** 
  +     * <p>Construct a new <code>MissingSelectedException</code> 
  +     * with the specified detail message.</p>
        *
  -     * @param msg Explanation of the exception
  +     * @param message the detail message
        */
  -    public MissingOptionException(String msg) {
  -        super(msg);
  +    public MissingOptionException( String message ) {
  +        super( message );
       }
   }
  
  
  
  1.7       +13 -4     jakarta-commons/cli/src/java/org/apache/commons/cli/OptionBuilder.java
  
  Index: OptionBuilder.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/src/java/org/apache/commons/cli/OptionBuilder.java,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- OptionBuilder.java	18 Aug 2002 19:07:42 -0000	1.6
  +++ OptionBuilder.java	26 Aug 2002 20:15:02 -0000	1.7
  @@ -82,8 +82,9 @@
       private static int numberOfArgs = Option.UNINITIALIZED;
       /** option type */
       private static Object type;
  -
  +    /** option can have an optional argument value */
       private static boolean optionalArg;
  +    /** value separator for argument value */
       private static char valuesep;
   
       /** option builder instance */
  @@ -301,6 +302,14 @@
           return option;
       }
   
  +    /**
  +     * <p>Create an Option using the current settings</p>
  +     *
  +     * @return the Option instance
  +     * @throws IllegalArgumentException if <code>longOpt</code> has
  +     * not been set.  
  +     * @see Option.
  +     */
       public static Option create() 
       throws IllegalArgumentException
       {
  
  
  
  1.4       +2 -1      jakarta-commons/cli/src/java/org/apache/commons/cli/OptionGroup.java
  
  Index: OptionGroup.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/src/java/org/apache/commons/cli/OptionGroup.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- OptionGroup.java	14 Aug 2002 22:27:39 -0000	1.3
  +++ OptionGroup.java	26 Aug 2002 20:15:02 -0000	1.4
  @@ -67,10 +67,11 @@
   
   /**
    * A group of mutually exclusive options.
  - * @author John Keyes ( john at integralsource.com )
  + * @author John Keyes ( jbjk at mac.com )
    * @version $Revision$
    */
   public class OptionGroup {
  +
       /** hold the options */
       private HashMap optionMap = new HashMap();
   
  
  
  
  1.10      +10 -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.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- Options.java	14 Aug 2002 22:27:39 -0000	1.9
  +++ Options.java	26 Aug 2002 20:15:02 -0000	1.10
  @@ -190,7 +190,7 @@
       
       /** <p>Retrieve the named {@link Option}</p>
        *
  -     * @param opt short single-character name of the {@link Option}
  +     * @param opt short or long name of the {@link Option}
        * @return the option represented by opt
        */
       public Option getOption( String opt ) {
  @@ -213,7 +213,15 @@
           return (option == null) ? null : (Option)option.clone();
       }
   
  -    boolean hasOption(String opt) {
  +    /** 
  +     * <p>Returns whether the named {@link Option} is a member
  +     * of this {@link Options}</p>
  +     *
  +     * @param opt short or long name of the {@link Option}
  +     * @return true if the named {@link Option} is a member
  +     * of this {@link Options}
  +     */
  +    public boolean hasOption( String opt ) {
   
           // short option
           if( opt.length() == 1 ) {
  
  
  
  1.2       +8 -5      jakarta-commons/cli/src/java/org/apache/commons/cli/ParseException.java
  
  Index: ParseException.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/src/java/org/apache/commons/cli/ParseException.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- ParseException.java	10 Jun 2002 18:01:15 -0000	1.1
  +++ ParseException.java	26 Aug 2002 20:15:02 -0000	1.2
  @@ -61,7 +61,8 @@
   
   package org.apache.commons.cli;
   
  -/** <p>Base for Exceptions thrown during parsing of a command-line<p>
  +/** 
  + * <p>Base for Exceptions thrown during parsing of a command-line.</p>
    *
    * @author bob mcwhirter (bob @ werken.com)
    * @version $Revision$
  @@ -69,11 +70,13 @@
   public class ParseException extends Exception 
   {
       
  -    /** Construct a new Exception with a message
  +    /** 
  +     * <p>Construct a new <code>ParseException</code> 
  +     * with the specified detail message.</p>
        *
  -     * @param msg Explanation of the exception
  +     * @param message the detail message
        */
  -    public ParseException(String msg) {
  -        super(msg);
  +    public ParseException( String message ) {
  +        super( message );
       }
   }
  
  
  
  1.2       +0 -1      jakarta-commons/cli/src/java/org/apache/commons/cli/Parser.java
  
  Index: Parser.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/src/java/org/apache/commons/cli/Parser.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- Parser.java	24 Aug 2002 22:15:31 -0000	1.1
  +++ Parser.java	26 Aug 2002 20:15:02 -0000	1.2
  @@ -88,7 +88,6 @@
                   buff.append( missing.getDescription() );
               }
   
  -            // throw the MissingOptionException
               throw new MissingOptionException( buff.toString() );
           }
       }
  
  
  
  1.9       +174 -4    jakarta-commons/cli/src/java/org/apache/commons/cli/PosixParser.java
  
  Index: PosixParser.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/src/java/org/apache/commons/cli/PosixParser.java,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- PosixParser.java	24 Aug 2002 22:15:31 -0000	1.8
  +++ PosixParser.java	26 Aug 2002 20:15:02 -0000	1.9
  @@ -1,3 +1,63 @@
  +/*
  + * $Header$
  + * $Revision$
  + * $Date$
  + *
  + * ====================================================================
  + *
  + * The Apache Software License, Version 1.1
  + *
  + * Copyright (c) 1999-2001 The Apache Software Foundation.  All rights
  + * reserved.
  + *
  + * Redistribution and use in source and binary forms, with or without
  + * modification, are permitted provided that the following conditions
  + * are met:
  + *
  + * 1. Redistributions of source code must retain the above copyright
  + *    notice, this list of conditions and the following disclaimer.
  + *
  + * 2. Redistributions in binary form must reproduce the above copyright
  + *    notice, this list of conditions and the following disclaimer in
  + *    the documentation and/or other materials provided with the
  + *    distribution.
  + *
  + * 3. The end-user documentation included with the redistribution, if
  + *    any, must include the following acknowlegement:
  + *       "This product includes software developed by the
  + *        Apache Software Foundation (http://www.apache.org/)."
  + *    Alternately, this acknowlegement may appear in the software itself,
  + *    if and wherever such third-party acknowlegements normally appear.
  + *
  + * 4. The names "The Jakarta Project", "Commons", and "Apache Software
  + *    Foundation" must not be used to endorse or promote products derived
  + *    from this software without prior written permission. For written
  + *    permission, please contact apache@apache.org.
  + *
  + * 5. Products derived from this software may not be called "Apache"
  + *    nor may "Apache" appear in their names without prior written
  + *    permission of the Apache Group.
  + *
  + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  + * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  + * SUCH DAMAGE.
  + * ====================================================================
  + *
  + * This software consists of voluntary contributions made by many
  + * individuals on behalf of the Apache Software Foundation.  For more
  + * information on the Apache Software Foundation, please see
  + * <http://www.apache.org/>.
  + *
  + */
   package org.apache.commons.cli;
   
   import java.util.Arrays;
  @@ -7,21 +67,73 @@
   import java.util.Map;
   
   /**
  + * The class PosixParser provides an implementation of the 
  + * {@link Parser#flatten(Options,String[],boolean) flatten} method.
  + *
    * @author John Keyes (jbjk at mac.com)
  + * @see Parser
  + * @version $Revision$
    */
   public class PosixParser extends Parser {
   
  +    /** holder for flattened tokens */
       private ArrayList tokens = new ArrayList();
  +    /** specifies if bursting should continue */
       private boolean eatTheRest;
  +    /** holder for the current option */
       private Option currentOption;
  +    /** the command line Options */
       private Options options;
   
  +    /**
  +     * <p>Resets the members to their original state i.e. remove
  +     * all of <code>tokens</code> entries, set <code>eatTheRest</code>
  +     * to false and set <code>currentOption</code> to null.</p>
  +     */
       private void init() {
           eatTheRest = false;
           tokens.clear();
           currentOption = null;
       }
   
  +    /**
  +     * <p>An implementation of {@link Parser}'s abstract
  +     * {@link Parser#flatten(Options,String[],boolean) flatten} method.</p>
  +     *
  +     * <p>The following are the rules used by this flatten method.
  +     * <ol>
  +     *  <li>if <code>stopAtNonOption</code> is <b>true</b>
then do not
  +     *  burst anymore of <code>arguments</code> entries, just add each
  +     *  successive entry without further processing.  Otherwise, ignore
  +     *  <code>stopAtNonOption</code>.</li>
  +     *  <li>if the current <code>arguments</code> entry is "<b>--</b>"
  +     *  just add the entry to the list of processed tokens</li>
  +     *  <li>if the current <code>arguments</code> entry is "<b>-</b>"
  +     *  just add the entry to the list of processed tokens</li>
  +     *  <li>if the current <code>arguments</code> entry is two characters
  +     *  in length and the first character is "<b>-</b>" then check if this
  +     *  is a valid {@link Option} id.  If it is a valid id, then add the
  +     *  entry to the list of processed tokens and set the current {@link Option}
  +     *  member.  If it is not a valid id and <code>stopAtNonOption</code>
  +     *  is true, then the remaining entries are copied to the list of 
  +     *  processed tokens.  Otherwise, the current entry is ignored.</li>
  +     *  <li>if the current <code>arguments</code> entry is more than
two
  +     *  characters in length and the first character is "<b>-</b>" then
  +     *  we need to burst the entry to determine its constituents.  For more
  +     *  information on the bursting algorithm see 
  +     *  {@link PosixParser#burstToken( String, boolean) burstToken}.</li>
  +     *  <li>if the current <code>arguments</code> entry is not handled

  +     *  by any of the previous rules, then the entry is added to the list
  +     *  of processed tokens.</li>
  +     * </ol>
  +     * </p>
  +     *
  +     * @param options The command line {@link Options}
  +     * @param arguments The command line arguments to be parsed
  +     * @param stopAtNonOption Specifies whether to stop flattening
  +     * when an non option is found.
  +     * @return The flattened <code>arguments</code> String array.
  +     */
       protected String[] flatten( Options options, 
                                   String[] arguments, 
                                   boolean stopAtNonOption )
  @@ -72,6 +184,11 @@
           return (String[])tokens.toArray( new String[] {} );
       }
   
  +    /**
  +     * <p>Adds the remaining tokens to the processed tokens list.</p>
  +     *
  +     * @param iter An iterator over the remaining tokens
  +     */
       private void gobble( Iterator iter ) {
           if( eatTheRest ) {
               while( iter.hasNext() ) {
  @@ -80,6 +197,19 @@
           }
       }
   
  +    /**
  +     * <p>If there is a current option and it can have an argument
  +     * value then add the token to the processed tokens list and 
  +     * set the current option to null.</p>
  +     * <p>If there is a current option and it can have argument
  +     * values then add the token to the processed tokens list.</p>
  +     * <p>If there is not a current option add the special token
  +     * "<b>--</b>" and the current <code>value</code> to the processed
  +     * tokens list.  The add all the remaining <code>argument</code>
  +     * values to the processed tokens list.</p>
  +     *
  +     * @param value The current token
  +     */
       private void process( String value ) {
           if( currentOption != null && currentOption.hasArg() ) {
               if( currentOption.hasArg() ) {
  @@ -97,21 +227,61 @@
           }
       }
   
  +    /**
  +     * <p>If it is a hyphen then add the hyphen directly to
  +     * the processed tokens list.</p>
  +     *
  +     * @param hyphen The hyphen token
  +     */
       private void processSingleHyphen( String hyphen ) {
           tokens.add( hyphen );
       }
   
  -    private void processOptionToken( String token, boolean stop ) {
  +    /**
  +     * <p>If an {@link Option} exists for <code>token</code> then
  +     * set the current option and add the token to the processed 
  +     * list.</p>
  +     * <p>If an {@link Option} does not exist and <code>stopAtNonOption</code>
  +     * is set then ignore the current token and add the remaining tokens
  +     * to the processed tokens list directly.</p>
  +     *
  +     * @param token The current option token
  +     * @param stopAtNonOption Specifies whether flattening should halt
  +     * at the first non option.
  +     */
  +    private void processOptionToken( String token, boolean stopAtNonOption ) {
           if( this.options.hasOption( token ) ) {
               currentOption = this.options.getOption( token );
               tokens.add( token );
           }
  -        else if( stop ) {
  +        else if( stopAtNonOption ) {
               eatTheRest = true;
           }
       }
   
  -    private void burstToken( String token, boolean stop ) {
  +    /**
  +     * <p>Breaks <code>token</code> into its constituent parts
  +     * using the following algorithm.
  +     * <ul>
  +     *  <li>ignore the first character ("<b>-</b>" )</li>
  +     *  <li>foreach remaining character check if an {@link Option}
  +     *  exists with that id.</li>
  +     *  <li>if an {@link Option} does exist then add that character
  +     *  prepended with "<b>-</b>" to the list of processed tokens.</li>
  +     *  <li>if the {@link Option} can have an argument value and there 
  +     *  are remaining characters in the token then add the remaining 
  +     *  characters as a token to the list of processed tokens.</li>
  +     *  <li>if an {@link Option} does <b>NOT</b> exist <b>AND</b>

  +     *  <code>stopAtNonOption</code> <b>IS</b> set then add the
special token
  +     *  "<b>--</b>" followed by the remaining characters and also 
  +     *  the remaining tokens directly to the processed tokens list.</li>
  +     *  <li>if an {@link Option} does <b>NOT</b> exist <b>AND</b>
  +     *  <code>stopAtNonOption</code> <b>IS NOT</b> set then add
that
  +     *  character prepended with "<b>-</b>".</li>
  +     * </ul>
  +     * </p>
  +     */
  +    protected void burstToken( String token, boolean stopAtNonOption ) {
           int tokenLength = token.length();
   
           for( int i = 1; i < tokenLength; i++) {
  @@ -126,7 +296,7 @@
                       break;
                   }
               }
  -            else if( stop ) {
  +            else if( stopAtNonOption ) {
                   process( token.substring( i ) );
               }
               else {
  
  
  
  1.2       +8 -6      jakarta-commons/cli/src/java/org/apache/commons/cli/UnrecognizedOptionException.java
  
  Index: UnrecognizedOptionException.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/src/java/org/apache/commons/cli/UnrecognizedOptionException.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- UnrecognizedOptionException.java	10 Jun 2002 18:01:15 -0000	1.1
  +++ UnrecognizedOptionException.java	26 Aug 2002 20:15:02 -0000	1.2
  @@ -61,20 +61,22 @@
   
   package org.apache.commons.cli;
   
  -/** <p>Exception thrown during parsing signalling an unrecognized
  +/** 
  + * <p>Exception thrown during parsing signalling an unrecognized
    * option was seen.<p>
    *
  - *
    * @author bob mcwhiter (bob @ werken.com)
    * @version $Revision$
    */
   public class UnrecognizedOptionException extends ParseException {
       
  -    /** Construct a new Exception with a message
  +    /** 
  +     * <p>Construct a new <code>UnrecognizedArgumentException</code>

  +     * with the specified detail message.</p>
        *
  -     * @param msg Explanation of the exception
  +     * @param message the detail message
        */
  -    public UnrecognizedOptionException(String msg) {
  -        super(msg);
  +    public UnrecognizedOptionException( String message ) {
  +        super( message );
       }
   }
  
  
  

--
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