001/**
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  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 */
017package org.apache.commons.cli2;
018
019import java.util.List;
020import 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 */
026public interface CommandLine {
027
028    /**
029     * Detects the presence of an option with the specified trigger in this
030     * CommandLine.
031     *
032     * @param trigger the trigger to search for
033     * @return true iff an option with this trigger is present
034     */
035    boolean hasOption(final String trigger);
036
037    /**
038     * Detects the presence of an option in this CommandLine.
039     *
040     * @param option the Option to search for
041     * @return true iff the option is present
042     */
043    boolean hasOption(final Option option);
044
045    /**
046     * Finds the Option with the specified trigger
047     *
048     * @param trigger the name of the option to retrieve
049     * @return the Option matching the trigger or null if none exists
050     */
051    Option getOption(final String trigger);
052
053    /**
054     * Retrieves the Argument values associated with the specified Option
055     *
056     * @param trigger a trigger used to lookup the Option
057     * @return a list of values or an empty List if none are found
058     */
059    List getValues(final String trigger);
060
061    /**
062     * Retrieves the Argument values associated with the specified Option
063     *
064     * @param trigger a trigger used to lookup the Option
065     * @param defaultValues the result to return if no values are found
066     * @return a list of values or defaultValues if none are found
067     */
068    List getValues(final String trigger, final List defaultValues);
069
070    /**
071     * Retrieves the Argument values associated with the specified Option
072     *
073     * @param option the Option associated with the values
074     * @return a list of values or an empty List if none are found
075     */
076    List getValues(final Option option);
077
078    /**
079     * Retrieves the Argument values associated with the specified Option
080     *
081     * @param option the Option associated with the values
082     * @param defaultValues the result to return if no values are found
083     * @return a list of values or defaultValues if none are found
084     */
085    List getValues(final Option option, final List defaultValues);
086
087    /**
088     * Retrieves the single Argument value associated with the specified Option
089     *
090     * @param trigger a trigger used to lookup the Option
091     * @return the matching value or null if none exists
092     * @throws IllegalStateException if more than one values are found
093     */
094    Object getValue(final String trigger) throws IllegalStateException;
095
096    /**
097     * Retrieves the single Argument value associated with the specified Option
098     *
099     * @param trigger a trigger used to lookup the Option
100     * @param defaultValue the result to use if no values are found
101     * @return the matching value or defaultValue if none exists
102     * @throws IllegalStateException if more than one values are found
103     */
104    Object getValue(final String trigger, final Object defaultValue) throws IllegalStateException;
105
106    /**
107     * Retrieves the single Argument value associated with the specified Option
108     *
109     * @param option the Option associated with the value
110     * @return the matching value or null if none exists
111     * @throws IllegalStateException if more than one values are found
112     */
113    Object getValue(final Option option) throws IllegalStateException;
114
115    /**
116     * Retrieves the single Argument value associated with the specified Option
117     *
118     * @param option the Option associated with the value
119     * @param defaultValue the result to use if no values are found
120     * @return the matching value or defaultValue if none exists
121     * @throws IllegalStateException if more than one values are found
122     */
123    Object getValue(final Option option, final Object defaultValue) throws IllegalStateException;
124
125    /**
126     * Retrieves the Boolean value associated with the specified Switch
127     *
128     * @param trigger a trigger used to lookup the Option
129     * @return the Boolean associated with trigger or null if none exists
130     */
131    Boolean getSwitch(final String trigger);
132
133    /**
134     * Retrieves the Boolean value associated with the specified Switch
135     *
136     * @param trigger a trigger used to lookup the Option
137     * @param defaultValue the Boolean to use if none match
138     * @return the Boolean associated with trigger or defaultValue if none exists
139     */
140    Boolean getSwitch(final String trigger, final Boolean defaultValue);
141
142    /**
143     * Retrieves the Boolean value associated with the specified Switch
144     *
145     * @param option the Option associated with the value
146     * @return the Boolean associated with option or null if none exists
147     */
148    Boolean getSwitch(final Option option);
149
150    /**
151     * Retrieves the Boolean value associated with the specified Switch
152     *
153     * @param option the Option associated with the value
154     * @param defaultValue the Boolean to use if none match
155     * @return the Boolean associated with option or defaultValue if none exists
156     */
157    Boolean getSwitch(final Option option, final Boolean defaultValue);
158
159
160    /**
161     * Retrieves the value associated with the specified property for the default property set
162     *
163     * @param property the property name to lookup
164     * @return the value of the property or null
165     */
166    String getProperty(final String property);
167
168    /**
169     * Retrieves the value associated with the specified property
170     *
171     * @param option the option i.e., -D
172     * @param property the property name to lookup
173     * @return the value of the property or null
174     */
175    String getProperty(final Option option, final String property);
176
177    /**
178     * Retrieves the value associated with the specified property
179     *
180     * @param option the option i.e., -D
181     * @param property the property name to lookup
182     * @param defaultValue the value to use if no other is found
183     * @return the value of the property or defaultValue
184     */
185    String getProperty(final Option option, final String property, final String defaultValue);
186
187    /**
188     * Retrieves the set of all property names associated with this option
189     *
190     * @param option the option i.e., -D
191     * @return a none null set of property names
192     */
193    Set getProperties(final Option option);
194
195    /**
196     * Retrieves the set of all property names associated with the default property option
197     *
198     * @return a none null set of property names
199     */
200    Set getProperties();
201
202    /**
203     * Retrieves the number of times the specified Option appeared in this
204     * CommandLine
205     *
206     * @param trigger a trigger used to lookup the Option
207     * @return the number of occurrences of the option
208     */
209    int getOptionCount(final String trigger);
210
211    /**
212     * Retrieves the number of times the specified Option appeared in this
213     * CommandLine
214     *
215     * @param option the Option associated to check
216     * @return the number of occurrences of the option
217     */
218    int getOptionCount(final Option option);
219
220    /**
221     * Retrieves a list of all Options found in this CommandLine
222     *
223     * @return a none null list of Options
224     */
225    List getOptions();
226
227    /**
228     * Retrieves a list of all Option triggers found in this CommandLine
229     *
230     * @return a none null list of Option triggers
231     */
232    Set getOptionTriggers();
233}