Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Jakarta Commons Developers List" <commons-dev@jakarta.apache.org>
Date: 24 May 2003 13:43:29 -0000
Message-ID: <20030524134329.56890.qmail@icarus.apache.org>
From: jkeyes@apache.org
To: jakarta-commons-cvs@apache.org
Subject: cvs commit: jakarta-commons/cli/src/java/org/apache/commons/cli
 Options.java

jkeyes      2003/05/24 06:43:29

  Modified:    cli/src/java/org/apache/commons/cli Tag: cli_1_x
                        Options.java
  Log:
  added Javadoc
added license
replaced tabs with spaces
  
  Revision  Changes    Path
  No                   revision
  
  
  No                   revision
  
  
  1.19.2.2  +262 -82   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.19.2.1
  retrieving revision 1.19.2.2
  diff -u -r1.19.2.1 -r1.19.2.2
  --- Options.java	19 May 2003 20:59:44 -0000	1.19.2.1
  +++ Options.java	24 May 2003 13:43:29 -0000	1.19.2.2
  @@ -1,3 +1,63 @@
  +/*
  + * $Header$
  + * $Revision$
  + * $Date$
  + *
  + * ====================================================================
  + *
  + * The Apache Software License, Version 1.1
  + *
  + * Copyright (c) 1999-2003 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.HashMap;
  @@ -6,119 +66,239 @@
   import java.util.Map;
   import java.util.Set;
   
  +/**
  + * An Options instance defines the structure of a command
  + * line.  It can have three types of element, Option, Argument
  + * or OptionGroup.
  + * 
  + * TODO: consolidate the OptionGroup support
  + * TODO: consolidate the AnonymousArgument support
  + * 
  + * @author John Keyes
  + */
   public class Options {
   
  +    /** the child Options and Arguments */
       private Map options = new HashMap();
  +
  +    /** the required Options and Arguments */
       private Set required = new HashSet();
  +
  +    /** the OptionGroups */
       private Set groups = new HashSet();
   
  -	private Argument anonymousArgument;
  -	    
  -    public Options() {
  -    }
  -
  -    public void add( Option option ) {
  -    	if( option instanceof AnonymousArgumentImpl ) {
  -			this.anonymousArgument = (Argument)option;    		
  -    	}
  -		else if( option.getName() != null ) {
  -			if( options.get(option.getName()) != null ) {
  -				options.remove(option.getName());
  -			}
  -			options.put(option.getName(), option);
  -		}
  -		else if( option.getLongName() != null ) {
  -			if( options.get(option.getLongName()) != null ) {
  -				options.remove(option.getLongName());
  -			}
  -			options.put(option.getLongName(), option);
  -		}
  -		addIfRequired( option );
  +    /** the AnonymousArgument */
  +    private Argument anonymousArgument;
  +
  +    /**
  +     * Adds the specified Option to this definition
  +     * 
  +     * @param option
  +     *     a command line Option
  +     */
  +    public void add(Option option) {
  +        if (option instanceof AnonymousArgumentImpl) {
  +            this.anonymousArgument = (Argument) option;
  +        } else if (option.getName() != null) {
  +            if (options.get(option.getName()) != null) {
  +                options.remove(option.getName());
  +            }
  +            options.put(option.getName(), option);
  +        } else if (option.getLongName() != null) {
  +            if (options.get(option.getLongName()) != null) {
  +                options.remove(option.getLongName());
  +            }
  +            options.put(option.getLongName(), option);
  +        }
  +        addIfRequired(option);
   
       }
   
  -    public void addOptions( Set options ) {
  -        for(Iterator iter = options.iterator(); iter.hasNext(); ) {
  -        	Option opt = (Option)iter.next();
  -			add( opt );
  -			addIfRequired( opt );
  +    /**
  +     * Adds all of the Options in the specified Set to this definition
  +     *
  +     * @param options
  +     *     command line Options to be added to this definition
  +     */
  +    public void addOptions(Set options) {
  +        for (Iterator iter = options.iterator(); iter.hasNext();) {
  +            Option opt = (Option) iter.next();
  +            add(opt);
  +            addIfRequired(opt);
           }
       }
   
  -    private void addIfRequired( Option option ) {
  -    	if( option instanceof AnonymousArgumentImpl) {
  -    		return;
  -    	}
  -        if( option.isRequired() ) {
  -            required.add( option );
  -    	}
  -    }
  -
  -    public void setOptions( Set options ) {
  -    	this.options.clear();
  -    	addOptions( options );
  +    /**
  +     * Registers the specified Option if it is 'required'.
  +     * 
  +     * @param option
  +     *     the Option to register if it is 'required'
  +     */
  +    private void addIfRequired(Option option) {
  +        if (option instanceof AnonymousArgumentImpl) {
  +            return;
  +        }
  +        if (option.isRequired()) {
  +            required.add(option);
  +        }
       }
   
  +    /**
  +     * Removes any Options that have already been added 
  +     * and then adds all of the Options in the specified
  +     * Set.
  +     * 
  +     * @param options
  +     *     command line Options
  +     */
  +    public void setOptions(Set options) {
  +        this.options.clear();
  +        addOptions(options);
  +    }
  +
  +    /**
  +     * Returns the Options that this definition contains.  The
  +     * value that is returned is a new object so changes made 
  +     * to it do not modify this definition.
  +     * 
  +     * @return
  +     *     the Set of command line Options
  +     */
       public Set getOptions() {
           return new HashSet(options.values());
       }
   
  -	Option getOption(String name) {
  -		Option option = null;
  -		for( Iterator iter = options.keySet().iterator(); iter.hasNext() && option == null; ) {
  -			Option currentOption = (Option)options.get(iter.next());
  -			if( currentOption.getName() != null && ("-" + currentOption.getName()).equals(name)) {
  -				option = currentOption;
  -			}
  -			else if (currentOption.getLongName() != null && ("--" + currentOption.getLongName()).equals(name)) {
  -				option = currentOption;
  -			}
  -		}
  -		return option;
  -	}
  -	
  +    /**
  +     * Return the Option that whose name is the same as the
  +     * specified name.  If no Option exists then check for
  +     * the Option whose long name is the same as the specified
  +     * name.  If there is still no match, return null.
  +     * 
  +     * @param name
  +     *     the name of the Option to search for
  +     * 
  +     * @return
  +     *     the Option that matches the search criteria, otherwise null
  +     */
  +    Option getOption(String name) {
  +        Option option = null;
  +        for (Iterator iter = options.keySet().iterator();
  +            iter.hasNext() && option == null;
  +            ) {
  +            Option currentOption = (Option) options.get(iter.next());
  +            if (currentOption.getName() != null
  +                && ("-" + currentOption.getName()).equals(name)) {
  +                option = currentOption;
  +            } else if (
  +                currentOption.getLongName() != null
  +                    && ("--" + currentOption.getLongName()).equals(name)) {
  +                option = currentOption;
  +            }
  +        }
  +        return option;
  +    }
  +
  +    /**
  +     * Return the number of command line options in this definition
  +     * 
  +     * @return
  +     *     the number of Options
  +     */
       public int size() {
           return this.options.size();
       }
   
  +    /**
  +     * Returns the required Options that this definition contains.
  +     * The value that is returned is a new object so changes made 
  +     * to it do not modify this definition.
  +     * 
  +     * @return
  +     *     the Set of required command line Options
  +     */
       public Set getRequired() {
  -        return this.required;
  +        return new HashSet(required);
       }
   
  +    /**
  +     * Returns the OptionGroups that this definition contains.
  +     * The value that is returned is a new object so changes made 
  +     * to it do not modify this definition.
  +     * 
  +     * @return
  +     *     the Set of command line OptionGroups
  +     */
       public Set getOptionGroups() {
  -        return this.groups;
  +        return new HashSet(this.groups);
       }
   
  -    public void add( OptionGroup group ) {
  -        this.groups.add( group );
  -        addGroupOptions( group );
  -    }
  -
  -	public boolean hasAnonymousArgument() {
  -		return this.anonymousArgument != null;
  -	}
  -	
  -	public Argument getAnonymousArgument() {
  -		return this.anonymousArgument;
  -	}
  -	
  -    public void setOptionGroups( Set groups ) {
  +    /**
  +     * Adds the specified group to this definition.
  +     * 
  +     * @param group
  +     *     a command line OptionGroup
  +     */
  +    public void add(OptionGroup group) {
  +        this.groups.add(group);
  +        addGroupOptions(group);
  +    }
  +
  +    /**
  +     * Returns whether this definition has an AnonymousArgument
  +     * specified.
  +     * 
  +     * @return
  +     *     true if there is an AnonymousArgument specified, otherwise false
  +     */
  +    public boolean hasAnonymousArgument() {
  +        return this.anonymousArgument != null;
  +    }
  +
  +    /**
  +     * Return this definitions AnonymousArgument
  +     * 
  +     * @return
  +     *     the Argument if one was specified, otherwise null
  +     */
  +    public Argument getAnonymousArgument() {
  +        return this.anonymousArgument;
  +    }
  +
  +    /**
  +     * Removes any OptionGroups that have already been added 
  +     * and then adds all of the OptionGroups in the specified
  +     * Set.
  +     *
  +     * @param groups
  +     */
  +    public void setOptionGroups(Set groups) {
           this.groups = groups;
  -        for(Iterator iter = groups.iterator(); iter.hasNext(); ) {
  -            add( (OptionGroup)iter.next() );
  +        for (Iterator iter = groups.iterator(); iter.hasNext();) {
  +            add((OptionGroup) iter.next());
           }
       }
   
  -    private void addGroupOptions( OptionGroup group ) {
  -		for(Iterator iter = group.getOptions().iterator(); iter.hasNext(); ) {
  -			add( (Option)iter.next() );
  -		}
  -
  -		if( group instanceof ExclusiveOptionGroup) {
  -			ExclusiveOptionGroup excGroup = (ExclusiveOptionGroup)group;
  -			for(Iterator iter = excGroup.getOptionGroups().iterator(); iter.hasNext(); ) {
  -				addGroupOptions( (OptionGroup)iter.next() );
  -			}
  -		}
  +    /**
  +     * Adds the individual Options from the specified group
  +     * to the options definition.
  +     * 
  +     * TODO: review this behaviour as it corrupts the contract
  +     *       for getOptions.
  +     * 
  +     * @param group
  +     */
  +    private void addGroupOptions(OptionGroup group) {
  +        for (Iterator iter = group.getOptions().iterator(); iter.hasNext();) {
  +            add((Option) iter.next());
  +        }
  +
  +        if (group instanceof ExclusiveOptionGroup) {
  +            ExclusiveOptionGroup excGroup = (ExclusiveOptionGroup) group;
  +            for (Iterator iter = excGroup.getOptionGroups().iterator();
  +                iter.hasNext();
  +                ) {
  +                addGroupOptions((OptionGroup) iter.next());
  +            }
  +        }
       }
   }
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org