Source for net.dpml.cli.Option

   1: /*
   2:  * Copyright 2003-2005 The Apache Software Foundation
   3:  * Copyright 2005 Stephen McConnell
   4:  *
   5:  * Licensed under the Apache License, Version 2.0 (the "License");
   6:  * you may not use this file except in compliance with the License.
   7:  * You may obtain a copy of the License at
   8:  *
   9:  *     http://www.apache.org/licenses/LICENSE-2.0
  10:  *
  11:  * Unless required by applicable law or agreed to in writing, software
  12:  * distributed under the License is distributed on an "AS IS" BASIS,
  13:  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14:  * See the License for the specific language governing permissions and
  15:  * limitations under the License.
  16:  */
  17: package net.dpml.cli;
  18: 
  19: import java.util.Comparator;
  20: import java.util.List;
  21: import java.util.ListIterator;
  22: import java.util.Set;
  23: 
  24: /**
  25:  * The super type of all options representing a particular element of the
  26:  * command line interface.
  27:  *
  28:  * @author <a href="@PUBLISHER-URL@">@PUBLISHER-NAME@</a>
  29:  * @version @PROJECT-VERSION@
  30:  */
  31: public interface Option
  32: {
  33:     /**
  34:      * Processes String arguments into a CommandLine.
  35:      * 
  36:      * The iterator will initially point at the first argument to be processed
  37:      * and at the end of the method should point to the first argument not
  38:      * processed. This method MUST process at least one argument from the
  39:      * ListIterator.
  40:      * 
  41:      * @param commandLine the CommandLine object to store results in
  42:      * @param args the arguments to process
  43:      * @throws OptionException if any problems occur
  44:      */
  45:     void process(
  46:         final WriteableCommandLine commandLine,
  47:         final ListIterator args )
  48:         throws OptionException;
  49:     
  50:     /**
  51:      * Adds defaults to a CommandLine.
  52:      * 
  53:      * Any defaults for this option are applied as well as the defaults for 
  54:      * any contained options
  55:      * 
  56:      * @param commandLine the CommandLine object to store defaults in
  57:      */
  58:     void defaults( WriteableCommandLine commandLine );
  59: 
  60:     /**
  61:      * Indicates whether this Option will be able to process the particular
  62:      * argument.
  63:      * 
  64:      * @param commandLine the CommandLine object to store defaults in
  65:      * @param argument the argument to be tested
  66:      * @return true if the argument can be processed by this Option
  67:      */
  68:     boolean canProcess( WriteableCommandLine commandLine, String argument );
  69: 
  70:     /**
  71:      * Indicates whether this Option will be able to process the particular
  72:      * argument. The ListIterator must be restored to the initial state before
  73:      * returning the boolean.
  74:      * 
  75:      * @see #canProcess(WriteableCommandLine,String)
  76:      * @param commandLine the CommandLine object to store defaults in
  77:      * @param arguments the ListIterator over String arguments
  78:      * @return true if the argument can be processed by this Option
  79:      */
  80:     boolean canProcess( WriteableCommandLine commandLine, final ListIterator arguments );
  81: 
  82:     /**
  83:      * Identifies the argument prefixes that should trigger this option. This
  84:      * is used to decide which of many Options should be tried when processing
  85:      * a given argument string.
  86:      * 
  87:      * The returned Set must not be null.
  88:      * 
  89:      * @return The set of triggers for this Option
  90:      */
  91:     Set getTriggers();
  92: 
  93:     /**
  94:      * Identifies the argument prefixes that should be considered options. This
  95:      * is used to identify whether a given string looks like an option or an
  96:      * argument value. Typically an option would return the set [--,-] while
  97:      * switches might offer [-,+].
  98:      * 
  99:      * The returned Set must not be null.
 100:      * 
 101:      * @return The set of prefixes for this Option
 102:      */
 103:     Set getPrefixes();
 104: 
 105:     /**
 106:      * Checks that the supplied CommandLine is valid with respect to this
 107:      * option.
 108:      * 
 109:      * @param commandLine the CommandLine to check.
 110:      * @throws OptionException if the CommandLine is not valid.
 111:      */
 112:     void validate( WriteableCommandLine commandLine ) throws OptionException;
 113: 
 114:     /**
 115:      * Builds up a list of HelpLineImpl instances to be presented by HelpFormatter.
 116:      * 
 117:      * @see HelpLine
 118:      * @see net.dpml.cli.util.HelpFormatter
 119:      * @param depth the initial indent depth
 120:      * @param helpSettings the HelpSettings that should be applied
 121:      * @param comp a comparator used to sort options when applicable.
 122:      * @return a List of HelpLineImpl objects
 123:      */
 124:     List helpLines( int depth, Set helpSettings, Comparator comp );
 125: 
 126:     /**
 127:      * Appends usage information to the specified StringBuffer
 128:      * 
 129:      * @param buffer the buffer to append to
 130:      * @param helpSettings a set of display settings @see DisplaySetting
 131:      * @param comp a comparator used to sort the Options
 132:      */
 133:     void appendUsage( StringBuffer buffer, Set helpSettings, Comparator comp );
 134: 
 135:     /**
 136:      * The preferred name of an option is used for generating help and usage
 137:      * information.
 138:      * 
 139:      * @return The preferred name of the option
 140:      */
 141:     String getPreferredName();
 142: 
 143:     /**
 144:      * Returns a description of the option. This string is used to build help
 145:      * messages as in the HelpFormatter.
 146:      * 
 147:      * @see net.dpml.cli.util.HelpFormatter
 148:      * @return a description of the option.
 149:      */
 150:     String getDescription();
 151: 
 152:     /**
 153:      * Returns the id of the option.  This can be used in a loop and switch 
 154:      * construct:
 155:      * 
 156:      * <code>
 157:      * for(Option o : cmd.getOptions()){
 158:      *     switch(o.getId()){
 159:      *         case POTENTIAL_OPTION:
 160:      *             ...
 161:      *     }
 162:      * }
 163:      * </code> 
 164:      * 
 165:      * The returned value is not guarenteed to be unique.
 166:      * 
 167:      * @return the id of the option.
 168:      */
 169:     int getId();
 170: 
 171:    /**
 172:     * Recursively searches for an option with the supplied trigger.
 173:     *
 174:     * @param trigger the trigger to search for.
 175:     * @return the matching option or null.
 176:     */
 177:     Option findOption( String trigger );
 178: 
 179:     /**
 180:      * Indicates whether this option is required to be present.
 181:      * @return true if the CommandLine will be invalid without this Option
 182:      */
 183:     boolean isRequired();
 184: }