You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by jk...@apache.org on 2002/08/26 22:15:03 UTC
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
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: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>