001 /**
002 * Copyright 2003-2004 The Apache Software Foundation
003 * Copyright 2005 Stephen McConnell
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package net.dpml.cli;
018
019 import java.util.List;
020 import java.util.Set;
021
022 /**
023 * Instances of CommandLine represent a command line that has been processed
024 * according to the definition supplied to the parser.
025 *
026 * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
027 * @version 1.0.0
028 */
029 public interface CommandLine
030 {
031
032 /**
033 * Detects the presence of an option with the specified trigger in this
034 * CommandLine.
035 *
036 * @param trigger the trigger to search for
037 * @return true iff an option with this trigger is present
038 */
039 boolean hasOption( String trigger );
040
041 /**
042 * Detects the presence of an option in this CommandLine.
043 *
044 * @param option the Option to search for
045 * @return true iff the option is present
046 */
047 boolean hasOption( Option option );
048
049 /**
050 * Finds the Option with the specified trigger
051 *
052 * @param trigger the name of the option to retrieve
053 * @return the Option matching the trigger or null if none exists
054 */
055 Option getOption( String trigger );
056
057 /**
058 * Retrieves the Argument values associated with the specified Option
059 *
060 * @param trigger a trigger used to lookup the Option
061 * @return a list of values or an empty List if none are found
062 */
063 List getValues( String trigger );
064
065 /**
066 * Retrieves the Argument values associated with the specified Option
067 *
068 * @param trigger a trigger used to lookup the Option
069 * @param defaultValues the result to return if no values are found
070 * @return a list of values or defaultValues if none are found
071 */
072 List getValues( String trigger, List defaultValues );
073
074 /**
075 * Retrieves the Argument values associated with the specified Option
076 *
077 * @param option the Option associated with the values
078 * @return a list of values or an empty List if none are found
079 */
080 List getValues( Option option );
081
082 /**
083 * Retrieves the Argument values associated with the specified Option
084 *
085 * @param option the Option associated with the values
086 * @param defaultValues the result to return if no values are found
087 * @return a list of values or defaultValues if none are found
088 */
089 List getValues( Option option, List defaultValues );
090
091 /**
092 * Retrieves the single Argument value associated with the specified Option
093 *
094 * @param trigger a trigger used to lookup the Option
095 * @return the matching value or null if none exists
096 * @throws IllegalStateException if more than one values are found
097 */
098 Object getValue( String trigger ) throws IllegalStateException;
099
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 }