Source for net.dpml.cli.CommandLine

   1: /**
   2:  * Copyright 2003-2004 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.List;
  20: import java.util.Set;
  21: 
  22: /**
  23:  * Instances of CommandLine represent a command line that has been processed
  24:  * according to the definition supplied to the parser.
  25:  *
  26:  * @author <a href="@PUBLISHER-URL@">@PUBLISHER-NAME@</a>
  27:  * @version @PROJECT-VERSION@
  28:  */
  29: public interface CommandLine 
  30: {
  31:     
  32:     /**
  33:      * Detects the presence of an option with the specified trigger in this 
  34:      * CommandLine.
  35:      * 
  36:      * @param trigger the trigger to search for
  37:      * @return true iff an option with this trigger is present
  38:      */
  39:     boolean hasOption( String trigger );
  40:     
  41:     /**
  42:      * Detects the presence of an option in this CommandLine.
  43:      * 
  44:      * @param option the Option to search for
  45:      * @return true iff the option is present
  46:      */
  47:     boolean hasOption( Option option );
  48:     
  49:     /**
  50:      * Finds the Option with the specified trigger
  51:      * 
  52:      * @param trigger the name of the option to retrieve
  53:      * @return the Option matching the trigger or null if none exists
  54:      */
  55:     Option getOption( String trigger );
  56:     
  57:     /**
  58:      * Retrieves the Argument values associated with the specified Option
  59:      * 
  60:      * @param trigger a trigger used to lookup the Option
  61:      * @return a list of values or an empty List if none are found
  62:      */
  63:     List getValues( String trigger );
  64:     
  65:     /**
  66:      * Retrieves the Argument values associated with the specified Option
  67:      * 
  68:      * @param trigger a trigger used to lookup the Option
  69:      * @param defaultValues the result to return if no values are found
  70:      * @return a list of values or defaultValues if none are found
  71:      */
  72:     List getValues( String trigger, List defaultValues );
  73:     
  74:     /**
  75:      * Retrieves the Argument values associated with the specified Option
  76:      * 
  77:      * @param option the Option associated with the values
  78:      * @return a list of values or an empty List if none are found
  79:      */
  80:     List getValues( Option option );
  81:     
  82:     /**
  83:      * Retrieves the Argument values associated with the specified Option
  84:      * 
  85:      * @param option the Option associated with the values
  86:      * @param defaultValues the result to return if no values are found
  87:      * @return a list of values or defaultValues if none are found
  88:      */
  89:     List getValues( Option option, List defaultValues );
  90:     
  91:     /**
  92:      * Retrieves the single Argument value associated with the specified Option
  93:      * 
  94:      * @param trigger a trigger used to lookup the Option
  95:      * @return the matching value or null if none exists
  96:      * @throws IllegalStateException if more than one values are found
  97:      */
  98:     Object getValue( String trigger ) throws IllegalStateException;
  99:     
 100:     /**
 101:      * Retrieves the single Argument value associated with the specified Option
 102:      * 
 103:      * @param trigger a trigger used to lookup the Option
 104:      * @param defaultValue the result to use if no values are found
 105:      * @return the matching value or defaultValue if none exists
 106:      * @throws IllegalStateException if more than one values are found
 107:      */
 108:     Object getValue( String trigger, Object defaultValue ) throws IllegalStateException;
 109:     
 110:     /**
 111:      * Retrieves the single Argument value associated with the specified Option
 112:      * 
 113:      * @param option the Option associated with the value
 114:      * @return the matching value or null if none exists
 115:      * @throws IllegalStateException if more than one values are found
 116:      */
 117:     Object getValue( Option option ) throws IllegalStateException;
 118:     
 119:     /**
 120:      * Retrieves the single Argument value associated with the specified Option
 121:      * 
 122:      * @param option the Option associated with the value
 123:      * @param defaultValue the result to use if no values are found
 124:      * @return the matching value or defaultValue if none exists
 125:      * @throws IllegalStateException if more than one values are found
 126:      */
 127:     Object getValue( Option option, Object defaultValue ) throws IllegalStateException;
 128:     
 129:     /**
 130:      * Retrieves the Boolean value associated with the specified Switch
 131:      * 
 132:      * @param trigger a trigger used to lookup the Option
 133:      * @return the Boolean associated with trigger or null if none exists
 134:      */
 135:     Boolean getSwitch( String trigger );
 136:     
 137:     /**
 138:      * Retrieves the Boolean value associated with the specified Switch
 139:      * 
 140:      * @param trigger a trigger used to lookup the Option
 141:      * @param defaultValue the Boolean to use if none match
 142:      * @return the Boolean associated with trigger or defaultValue if none exists
 143:      */
 144:     Boolean getSwitch( String trigger, Boolean defaultValue );
 145:     
 146:     /**
 147:      * Retrieves the Boolean value associated with the specified Switch
 148:      * 
 149:      * @param option the Option associated with the value
 150:      * @return the Boolean associated with option or null if none exists
 151:      */
 152:     Boolean getSwitch( Option option );
 153:     
 154:     /**
 155:      * Retrieves the Boolean value associated with the specified Switch
 156:      * 
 157:      * @param option the Option associated with the value
 158:      * @param defaultValue the Boolean to use if none match
 159:      * @return the Boolean associated with option or defaultValue if none exists
 160:      */
 161:     Boolean getSwitch( Option option, Boolean defaultValue );
 162:     
 163:     /**
 164:      * Retrieves the value associated with the specified property 
 165:      * 
 166:      * @param property the property name to lookup
 167:      * @return the value of the property or null
 168:      */
 169:     String getProperty( String property );
 170:     
 171:     /**
 172:      * Retrieves the value associated with the specified property 
 173:      * 
 174:      * @param property the property name to lookup
 175:      * @param defaultValue the value to use if no other is found
 176:      * @return the value of the property or defaultValue
 177:      */
 178:     String getProperty( String property, String defaultValue );
 179:     
 180:     /**
 181:      * Retrieves the set of all property names associated with this CommandLine
 182:      * 
 183:      * @return a none null set of property names 
 184:      */
 185:     Set getProperties();
 186:     
 187:     /**
 188:      * Retrieves the number of times the specified Option appeared in this 
 189:      * CommandLine
 190:      * 
 191:      * @param trigger a trigger used to lookup the Option
 192:      * @return the number of occurrences of the option
 193:      */
 194:     int getOptionCount( String trigger );
 195:     
 196:     /**
 197:      * Retrieves the number of times the specified Option appeared in this 
 198:      * CommandLine
 199:      * 
 200:      * @param option the Option associated to check
 201:      * @return the number of occurrences of the option
 202:      */
 203:     int getOptionCount( Option option );
 204:     
 205:     /**
 206:      * Retrieves a list of all Options found in this CommandLine
 207:      * 
 208:      * @return a none null list of Options
 209:      */
 210:     List getOptions();
 211:     
 212:     /**
 213:      * Retrieves a list of all Option triggers found in this CommandLine
 214:      * 
 215:      * @return a none null list of Option triggers
 216:      */
 217:     Set getOptionTriggers();
 218: }