allowed characters are now isJavaIdentifierPart, added javadoc to Parser, minor refactoring for required options

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/cli/trunk@129809 13f79535-47bb-0310-9956-ffa450edef68

Author: John Keyes

src/java/org/apache/commons/cli/Option.java

@@ -192,7 +192,7 @@ private boolean isValidOpt( char c ) {
      * @return true if <code>c</code> is a letter.
      */
     private boolean isValidChar( char c ) {
-        return Character.isLetter( c );
+        return Character.isJavaIdentifierPart( c );
     }
 
     /**

src/java/org/apache/commons/cli/Options.java

@@ -61,11 +61,13 @@
 
 package org.apache.commons.cli;
 
+import java.util.ArrayList;
 import java.util.Collection;
-import java.util.Map;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.Iterator;
-import java.util.Collections;
+import java.util.List;
+import java.util.Map;
 
 /** <p>Main entry-point into the library.</p>
  *
@@ -91,7 +93,7 @@ public class Options {
     private Map  longOpts     = new HashMap();
 
     /** a map of the required options */
-    private Map  requiredOpts = new HashMap();
+    private List requiredOpts = new ArrayList();
 
     /** a map of the option groups */
     private Map optionGroups  = new HashMap();
@@ -163,7 +165,7 @@ public Options addOption(Option opt)  {
 
         // if the option is required add it to the required list
         if ( opt.isRequired() ) {
-            requiredOpts.put( shortOpt, opt );
+            requiredOpts.add( shortOpt );
         }
 
         shortOpts.put( shortOpt, opt );
@@ -184,7 +186,7 @@ public Collection getOptions() {
      *
      * @return Collection of required options
      */
-    public Map getRequiredOptions() {
+    public List getRequiredOptions() {
         return requiredOpts;
     }
 

src/java/org/apache/commons/cli/Parser.java

@@ -1,3 +1,64 @@
+/*
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//cli/src/java/org/apache/commons/cli/Parser.java,v 1.4 2002/09/01 22:54:56 jkeyes Exp $
+ * $Revision: 1.4 $
+ * $Date: 2002/09/01 22:54:56 $
+ *
+ * ====================================================================
+ *
+ * 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;
@@ -6,67 +67,122 @@
 import java.util.ListIterator;
 import java.util.Map;
 
+/**
+ * <p><code>Parser</code> creates {@link CommandLine}s.</p>
+ *
+ * @author John Keyes (jbjk at mac.com)
+ * @see Parser
+ * @version $Revision: 1.4 $
+ */
 public abstract class Parser implements CommandLineParser {
 
+    /** commandline instance */
     private CommandLine cmd;
+    /** current Options */
     private Options options;
-    private Map requiredOptions;
+    /** list of required options strings */
+    private List requiredOptions;
 
+    /**
+     * <p>Subclasses must implement this method to reduce
+     * the <code>arguments</code> that have been passed to the parse 
+     * method.</p>
+     *
+     * @param opts The Options to parse the arguments by.
+     * @param args The arguments that have to be flattened.
+     * @param stopAtNonOption specifies whether to stop 
+     * flattening when a non option has been encountered
+     * @return a String array of the flattened arguments
+     */
     abstract protected String[] flatten( Options opts, 
-                                         String[] args, 
+                                         String[] arguments, 
                                          boolean stopAtNonOption );
 
-    public CommandLine parse( Options opts, String[] args ) 
+    /**
+     * <p>Parses the specified <code>arguments</code> 
+     * based on the specifed {@link Options}.</p>
+     *
+     * @param options the <code>Options</code>
+     * @param arguments the <code>arguments</code>
+     * @return the <code>CommandLine</code>
+     * @throws ParseException if an error occurs when parsing the
+     * arguments.
+     */
+    public CommandLine parse( Options options, String[] arguments ) 
     throws ParseException 
     {
-        return parse( opts, args, false );
+        return parse( options, arguments, false );
     }
 
+    /**
+     * <p>Parses the specified <code>arguments</code> 
+     * based on the specifed {@link Options}.</p>
+     *
+     * @param options the <code>Options</code>
+     * @param arguments the <code>arguments</code>
+     * @param stopAtNonOption specifies whether to stop 
+     * interpreting the arguments when a non option has 
+     * been encountered and to add them to the CommandLines
+     * args list.
+     * @return the <code>CommandLine</code>
+     * @throws ParseException if an error occurs when parsing the
+     * arguments.
+     */
     public CommandLine parse( Options opts, 
-                              String[] args, 
+                              String[] arguments, 
                               boolean stopAtNonOption ) 
     throws ParseException 
     {
+        // initialise members
         options = opts;
         requiredOptions = options.getRequiredOptions();
-        String[] tokens = flatten( opts, args, stopAtNonOption );
-        List tokenList = Arrays.asList( tokens );
-        ListIterator iterator = tokenList.listIterator();
         cmd = new CommandLine();
+
         boolean eatTheRest = false;
+
+        List tokenList = Arrays.asList( flatten( opts, arguments, stopAtNonOption ) );
+        ListIterator iterator = tokenList.listIterator();
+
+        // process each flattened token
         while( iterator.hasNext() ) {
             String t = (String)iterator.next();
+
+            // the value is the double-dash
             if( "--".equals( t ) ) {
                 eatTheRest = true;
             }
-            else if( t.startsWith( "-" ) ) {
-                if( t.length() == 1 ) {
-                    // not an option, so just drop it on the argument list
-                    if ( stopAtNonOption ) {
-                        eatTheRest = true;
-                    }
-                    else {
-                        cmd.addArg( t );
-                    }
+            // the value is a single dash
+            else if( "-".equals( t ) ) {
+                if( stopAtNonOption ) {
+                    eatTheRest = true;
+                }
+                else {
+                    cmd.addArg(t );
                 }
-                else if ( stopAtNonOption && !options.hasOption( t ) ) {
+            }
+            // the value is an option
+            else if( t.startsWith( "-" ) ) {
+                if ( stopAtNonOption && !options.hasOption( t ) ) {
                     eatTheRest = true;
                     cmd.addArg( t );
                 }
                 else {
                     processOption( t, iterator );
                 }
             }
+            // the value is an argument
             else {
                 cmd.addArg( t );
                 if( stopAtNonOption ) {
                     eatTheRest = true;
                 }
             }
 
+            // eat the remaining tokens
             if( eatTheRest ) {
                 while( iterator.hasNext() ) {
                     String str = (String)iterator.next();
+                    // ensure only one double-dash is added
                     if( !"--".equals( str ) ) {
                         cmd.addArg( str );
                     }
@@ -77,22 +193,23 @@ else if ( stopAtNonOption && !options.hasOption( t ) ) {
         return cmd;
     }
 
-    private void checkRequiredOptions( ) 
-    throws ParseException {
+    /**
+     * <p>Throws a {@link MissingOptionException} if all of the
+     * required options are no present.</p>
+     */
+    private void checkRequiredOptions()
+    throws MissingOptionException 
+    {
 
         // if there are required options that have not been
         // processsed
         if( requiredOptions.size() > 0 ) {
-            Iterator iter = requiredOptions.values().iterator();
+            Iterator iter = requiredOptions.iterator();
             StringBuffer buff = new StringBuffer();
 
             // loop through the required options
             while( iter.hasNext() ) {
-                Option missing = (Option)iter.next();
-                buff.append( "-" );
-                buff.append( missing.getOpt() );
-                buff.append( " " );
-                buff.append( missing.getDescription() );
+                buff.append( iter.next() );
             }
 
             throw new MissingOptionException( buff.toString() );

src/test/org/apache/commons/cli/BugsTest.java

@@ -5,7 +5,7 @@
  * version 1.1, a copy of which has been included with this distribution in
  * the LICENSE file.
  * 
- * $Id: BugsTest.java,v 1.5 2002/08/31 17:53:11 jkeyes Exp $
+ * $Id: BugsTest.java,v 1.6 2002/09/01 22:54:56 jkeyes Exp $
  */
 
 package org.apache.commons.cli;
@@ -179,7 +179,7 @@ public void test12210() {
 
         // Therefore, place them in an option group
 
-        String[] argv = new String[] { "-exec", "-execopto", "-execoptt" };
+        String[] argv = new String[] { "-exec", "-exec_opt1", "-exec_opt2" };
         OptionGroup grp = new OptionGroup();
 
         grp.addOption(new Option("exec",false,"description for this option"));
@@ -190,8 +190,8 @@ public void test12210() {
 
         // for the exec option, there are 2 options...
         Options execOptions = new Options();
-        execOptions.addOption("execopto",false," desc");
-        execOptions.addOption("execoptt",false," desc");
+        execOptions.addOption("exec_opt1",false," desc");
+        execOptions.addOption("exec_opt2",false," desc");
 
         // similarly, for rep there are 2 options...
         Options repOptions = new Options();
@@ -214,8 +214,8 @@ public void test12210() {
             if(cmd.hasOption("exec")){
                 cmd = parser.parse(execOptions,argv,false);
                 // process the exec_op1 and exec_opt2...
-                assertTrue( cmd.hasOption("execopto") );
-                assertTrue( cmd.hasOption("execoptt") );
+                assertTrue( cmd.hasOption("exec_opt1") );
+                assertTrue( cmd.hasOption("exec_opt2") );
             }
             else if(cmd.hasOption("rep")){
                 cmd = parser.parse(repOptions,argv,false);