integrated PatternBuilder

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

Author: John Keyes

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

@@ -163,7 +163,7 @@ private boolean isValidChar( char c )
     public Option(String opt, boolean hasArg, String description) 
     throws IllegalArgumentException
     {
-        this(opt, null, hasArg, description, false, false);
+        this(opt, null, hasArg, description);
     }
 
     /**
@@ -176,69 +176,13 @@ public Option(String opt, boolean hasArg, String description)
      */
     public Option(String opt, String longOpt, boolean hasArg, String description) 
     throws IllegalArgumentException
-    {
-        this(opt, longOpt, hasArg, description, false, false );
-    }
-
-    /**
-     * Creates an Option using the specified parameters.
-     *
-     * @param opt short representation of the option
-     * @param longOpt the long representation of the option
-     * @param hasArg specifies whether the Option takes an argument or not
-     * @param description describes the function of the option
-     * @param required specifies whether the option is required or not
-     */
-    public Option(String opt, String longOpt, boolean hasArg, String description,
-                  boolean required ) 
-    throws IllegalArgumentException
-    {
-        this(opt, longOpt, hasArg, description, required, false );
-    }
-
-    /**
-     * Creates an Option using the specified parameters.
-     *
-     * @param opt short representation of the option
-     * @param longOpt the long representation of the option
-     * @param hasArg specifies whether the Option takes an argument or not
-     * @param description describes the function of the option
-     * @param required specifies whether the option is required or not
-     * @param multipleArgs specifies whether the option has multiple argument 
-     * values
-     */
-    public Option(String opt, String longOpt, boolean hasArg, String description, 
-                  boolean required, boolean multipleArgs ) 
-    throws IllegalArgumentException
-    {
-        this(opt, longOpt, hasArg, description, required, multipleArgs, null );
-    }
-
-    /**
-     * Creates an Option using the specified parameters.
-     *
-     * @param opt short representation of the option
-     * @param longOpt the long representation of the option
-     * @param hasArg specifies whether the Option takes an argument or not
-     * @param description describes the function of the option
-     * @param required specifies whether the option is required or not
-     * @param multipleArgs specifies whether the option has multiple argument 
-     * values
-     * @param type specifies the type of the option
-     */
-    public Option(String opt, String longOpt, boolean hasArg, String description, 
-                  boolean required, boolean multipleArgs, Object type ) 
-    throws IllegalArgumentException
     {
         validateOption( opt );
 
         this.opt          = opt;
         this.longOpt      = longOpt;
         this.hasArg       = hasArg;
         this.description  = description;
-        this.required     = required;
-        this.multipleArgs = multipleArgs;
-        this.type         = type;
     }
 
     /** <p>Retrieve the name of this Option</p>

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

@@ -1,20 +1,100 @@
+/*
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//cli/src/java/org/apache/commons/cli/OptionBuilder.java,v 1.2 2002/07/30 23:06:21 jkeyes Exp $
+ * $Revision: 1.2 $
+ * $Date: 2002/07/30 23:06:21 $
+ *
+ * ====================================================================
+ *
+ * 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;
 
+/**
+ * <p>OptionBuilder allows the user to create Options using descriptive
+ * methods.</p>
+ * <p>Details on the Builder pattern can be found at 
+ * <a href="http://">http://</a>.</p>
+ *
+ * @author John Keyes ( jbjk at mac.com )
+ * @since 1.0
+ */
 public class OptionBuilder {
 
+    /** long option */
     private static String longopt;
+    /** option description */
     private static String description;
+    /** has an argument? */
     private static boolean arg;
+    /** is required? */
     private static boolean required;
+    /** has multiple arguments */
     private static boolean multipleArgs;
+    /** option type */
     private static Object type;
 
+    /** option builder instance */
     private static OptionBuilder instance = new OptionBuilder();
 
     // private constructor
     private OptionBuilder() {
     }
 
+    /**
+     * <p>Resets the member variables to their default values.</p>
+     */
     private static void reset() {
         description = null;
         longopt = null;
@@ -24,51 +104,135 @@ private static void reset() {
         multipleArgs = false;
     }
 
+    /**
+     * <p>The next Option created will have the following long option value.</p>
+     *
+     * @param longopt the long option value
+     * @return the OptionBuilder instance
+     */
     public static OptionBuilder withLongOpt( String longopt ) {
         instance.longopt = longopt;
         return instance;
     }
 
+    /**
+     * <p>The next Option created will require an argument value.</p>
+     *
+     * @return the OptionBuilder instance
+     */
     public static OptionBuilder hasArg( ) {
         instance.arg = true;
         return instance;
     }
 
+    /**
+     * <p>The next Option created will require an argument value if
+     * <code>hasArg</code> is true.</p>
+     *
+     * @param hasArg if true then the Option has an argument value
+     * @return the OptionBuilder instance
+     */
+    public static OptionBuilder hasArg( boolean hasArg ) {
+        instance.arg = hasArg;
+        return instance;
+    }
+
+    /**
+     * <p>The next Option created will be required.</p>
+     *
+     * @return the OptionBuilder instance
+     */
     public static OptionBuilder isRequired( ) {
         instance.required = true;
         return instance;
     }
 
+    /**
+     * <p>The next Option created will be required if <code>required</code>
+     * is true.</p>
+     *
+     * @param required if true then the Option is required
+     * @return the OptionBuilder instance
+     */
+    public static OptionBuilder isRequired( boolean required ) {
+        instance.required = required;
+        return instance;
+    }
+
+    /**
+     * <p>The next Option created can have multiple argument values.</p>
+     *
+     * @return the OptionBuilder instance
+     */
     public static OptionBuilder hasMultipleArgs( ) {
         instance.multipleArgs = true;
         return instance;
     }
 
+    /**
+     * <p>The next Option created will have a value that will be an instance 
+     * of <code>type</code>.</p>
+     *
+     * @param type the type of the Options argument value
+     * @return the OptionBuilder instance
+     */
     public static OptionBuilder withType( Object type ) {
         instance.type = type;
         return instance;
     }
 
+    /**
+     * <p>The next Option created will have the specified description</p>
+     *
+     * @param description a description of the Option's purpose
+     * @return the OptionBuilder instance
+     */
     public static OptionBuilder withDescription( String description ) {
         instance.description = description;
         return instance;
     }
 
+    /**
+     * <p>Create an Option using the current settings and with 
+     * the specified Option <code>char</code>.</p>
+     *
+     * @param opt the character representation of the Option
+     * @return the Option instance
+     * @throws IllegalArgumentException if <code>opt</code> is not
+     * a valid character.  See Option.
+     */
     public static Option create( char opt )
     throws IllegalArgumentException
     {
         return create( String.valueOf( opt ) );
     }
 
+    /**
+     * <p>Create an Option using the current settings and with 
+     * the specified Option <code>char</code>.</p>
+     *
+     * @param opt the <code>java.lang.String</code> representation 
+     * of the Option
+     * @return the Option instance
+     * @throws IllegalArgumentException if <code>opt</code> is not
+     * a valid character.  See Option.
+     */
     public static Option create( String opt ) 
     throws IllegalArgumentException
     {
+        // create the option
         Option option = new Option( opt, arg, description );
+
+        // set the option properties
         option.setLongOpt( longopt );
         option.setRequired( required );
         option.setMultipleArgs( multipleArgs );
         option.setType( type );
+
+        // reset the OptionBuilder properties
         instance.reset();
+
+        // return the Option instance
         return option;
     }
 }

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

@@ -128,7 +128,7 @@ public Options addOptionGroup( OptionGroup group ) {
      * @return the resulting Options instance
      */
     public Options addOption(String opt, boolean hasArg, String description) {
-        addOption( opt, null, hasArg, description, false );
+        addOption( opt, null, hasArg, description );
         return this;
     }
 
@@ -142,58 +142,7 @@ public Options addOption(String opt, boolean hasArg, String description) {
      * @return the resulting Options instance
      */
     public Options addOption(String opt, String longOpt, boolean hasArg, String description) {
-        addOption( opt, longOpt, hasArg, description, false );        
-        return this;
-    }
-
-    /** <p>Add an option that contains a short-name and a long-name</p>
-     * <p>It may be specified as requiring an argument.</p>
-     *
-     * @param opt Short single-character name of the option.
-     * @param longOpt Long multi-character name of the option.
-     * @param hasArg flag signally if an argument is required after this option
-     * @param description Self-documenting description
-     * @param required specifies if this option is required
-     * @return the resulting Options instance
-     */
-    public Options addOption(String opt, String longOpt, boolean hasArg, String description,
-                             boolean required) {
-        addOption( new Option(opt, longOpt, hasArg, description, required) );        
-        return this;
-    }
-
-    /** <p>Add an option that contains a short-name and a long-name</p>
-     * <p>It may be specified as requiring an argument.</p>
-     *
-     * @param opt Short single-character name of the option.
-     * @param longOpt Long multi-character name of the option.
-     * @param hasArg flag signally if an argument is required after this option
-     * @param description Self-documenting description
-     * @param required specifies if this option is required
-     * @param multipleArgs specifies if this option can accept multiple argument values
-     * @return the resulting Options instance
-     */
-    public Options addOption(String opt, String longOpt, boolean hasArg, String description,
-                             boolean required, boolean multipleArgs) {
-        addOption( new Option(opt, longOpt, hasArg, description, required, multipleArgs) );        
-        return this;
-    }
-
-    /** <p>Add an option that contains a short-name and a long-name</p>
-     * <p>It may be specified as requiring an argument.</p>
-     *
-     * @param opt Short single-character name of the option.
-     * @param longOpt Long multi-character name of the option.
-     * @param hasArg flag signally if an argument is required after this option
-     * @param description Self-documenting description
-     * @param required specifies if this option is required
-     * @param multipleArgs specifies if this option can accept multiple argument values
-     * @param type specifies the type for the value of the option
-     * @return the resulting Options instance
-     */
-    public Options addOption(String opt, String longOpt, boolean hasArg, String description,
-                             boolean required, boolean multipleArgs, Object type) {
-        addOption( new Option(opt, longOpt, hasArg, description, required, multipleArgs, type) );        
+        addOption( new Option( opt, longOpt, hasArg, description ) );        
         return this;
     }