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     */
017    package org.apache.commons.cli2;
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    public 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    }