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 */
017package net.dpml.cli;
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 *
026 * @author <a href="@PUBLISHER-URL@">@PUBLISHER-NAME@</a>
027 * @version @PROJECT-VERSION@
028 */
029public 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}