View Javadoc

1   /***
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  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 org.apache.commons.cli;
18  
19  import java.util.Collection;
20  import java.util.Iterator;
21  import java.util.LinkedList;
22  import java.util.List;
23  import java.util.Set;
24  import java.util.HashSet;
25  
26  /*** 
27   * <p>Represents list of arguments parsed against
28   * a {@link Options} descriptor.<p>
29   *
30   * <p>It allows querying of a boolean {@link #hasOption(String opt)},
31   * in addition to retrieving the {@link #getOptionValue(String opt)}
32   * for options requiring arguments.</p>
33   *
34   * <p>Additionally, any left-over or unrecognized arguments,
35   * are available for further processing.</p>
36   *
37   * @author bob mcwhirter (bob @ werken.com)
38   * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
39   * @author John Keyes (john at integralsource.com)
40   */
41  public class CommandLine {
42  
43      /*** the unrecognised options/arguments */
44      private List args = new LinkedList();
45  
46      /*** the processed options */
47      private Set options = new HashSet();
48  
49      /*** Map of unique options for ease to get complete list of options */
50  //    private Set allOptions = new HashSet();
51  
52      /***
53       * Creates a command line.
54       */
55      CommandLine()
56      {
57          // nothing to do
58      }
59  
60      /*** 
61       * Query to see if an option has been set.
62       *
63       * @param opt Short name of the option
64       * @return true if set, false if not
65       */
66      public boolean hasOption(String opt)
67      {
68          return options.contains( resolveOption(opt));
69      }
70  
71      /*** 
72       * Query to see if an option has been set.
73       *
74       * @param opt character name of the option
75       * @return true if set, false if not
76       */
77      public boolean hasOption(char opt)
78      {
79          return hasOption(String.valueOf(opt));
80      }
81  
82      /***
83       * Return the <code>Object</code> type of this <code>Option</code>.
84       *
85       * @param opt the name of the option
86       * @return the type of this <code>Option</code>
87       */
88      public Object getOptionObject(String opt)
89      {
90          String res = getOptionValue(opt);
91  
92          Option option = resolveOption(opt);
93          if (option == null)
94          {
95              return null;
96          }
97  
98          Object type = option.getType();
99  
100         return (res == null)        ? null : TypeHandler.createValue(res, type);
101     }
102 
103     /***
104      * Return the <code>Object</code> type of this <code>Option</code>.
105      *
106      * @param opt the name of the option
107      * @return the type of opt
108      */
109     public Object getOptionObject(char opt)
110     {
111         return getOptionObject(String.valueOf(opt));
112     }
113 
114     /*** 
115      * Retrieve the argument, if any, of this option.
116      *
117      * @param opt the name of the option
118      * @return Value of the argument if option is set, and has an argument,
119      * otherwise null.
120      */
121     public String getOptionValue(String opt)
122     {
123         String[] values = getOptionValues(opt);
124 
125         return (values == null) ? null : values[0];
126     }
127 
128     /*** 
129      * Retrieve the argument, if any, of this option.
130      *
131      * @param opt the character name of the option
132      * @return Value of the argument if option is set, and has an argument,
133      * otherwise null.
134      */
135     public String getOptionValue(char opt)
136     {
137         return getOptionValue(String.valueOf(opt));
138     }
139 
140     /*** 
141      * Retrieves the array of values, if any, of an option.
142      *
143      * @param opt string name of the option
144      * @return Values of the argument if option is set, and has an argument,
145      * otherwise null.
146      */
147     public String[] getOptionValues(String opt)
148     {
149         Option key = resolveOption( opt );
150 
151         if (options.contains(key))
152         {
153             return key.getValues();
154         }
155 
156         return null;
157         }
158 
159     /***
160      * <p>Retrieves the option object given the long or short option as a String</p>
161      * @param opt short or long name of the option
162      * @return Canonicalized option
163      */
164     private Option resolveOption( String opt )
165     {
166         opt = Util.stripLeadingHyphens(opt);
167         for ( Iterator it = options.iterator(); it.hasNext(); )
168         {
169             Option option = (Option) it.next();
170             if (opt.equals(option.getOpt()))
171             {
172                 return option;
173             }
174             if (opt.equals( option.getLongOpt()))
175             {
176                 return option;
177         }
178 
179         }
180         return null;
181     }
182 
183     /*** 
184      * Retrieves the array of values, if any, of an option.
185      *
186      * @param opt character name of the option
187      * @return Values of the argument if option is set, and has an argument,
188      * otherwise null.
189      */
190     public String[] getOptionValues(char opt)
191     {
192         return getOptionValues(String.valueOf(opt));
193     }
194 
195     /*** 
196      * Retrieve the argument, if any, of an option.
197      *
198      * @param opt name of the option
199      * @param defaultValue is the default value to be returned if the option 
200      * is not specified
201      * @return Value of the argument if option is set, and has an argument,
202      * otherwise <code>defaultValue</code>.
203      */
204     public String getOptionValue(String opt, String defaultValue)
205     {
206         String answer = getOptionValue(opt);
207 
208         return (answer != null) ? answer : defaultValue;
209     }
210 
211     /*** 
212      * Retrieve the argument, if any, of an option.
213      *
214      * @param opt character name of the option
215      * @param defaultValue is the default value to be returned if the option 
216      * is not specified
217      * @return Value of the argument if option is set, and has an argument,
218      * otherwise <code>defaultValue</code>.
219      */
220     public String getOptionValue(char opt, String defaultValue)
221     {
222         return getOptionValue(String.valueOf(opt), defaultValue);
223     }
224 
225     /*** 
226      * Retrieve any left-over non-recognized options and arguments
227      *
228      * @return remaining items passed in but not parsed as an array
229      */
230     public String[] getArgs()
231     {
232         String[] answer = new String[args.size()];
233 
234         args.toArray(answer);
235 
236         return answer;
237     }
238 
239     /*** 
240      * Retrieve any left-over non-recognized options and arguments
241      *
242      * @return remaining items passed in but not parsed as a <code>List</code>.
243      */
244     public List getArgList()
245     {
246         return args;
247     }
248 
249     /*** 
250      * jkeyes
251      * - commented out until it is implemented properly
252      * <p>Dump state, suitable for debugging.</p>
253      *
254      * @return Stringified form of this object
255      */
256 
257     /*
258     public String toString() {
259         StringBuffer buf = new StringBuffer();
260             
261         buf.append("[ CommandLine: [ options: ");
262         buf.append(options.toString());
263         buf.append(" ] [ args: ");
264         buf.append(args.toString());
265         buf.append(" ] ]");
266             
267         return buf.toString();
268     }
269     */
270 
271     /***
272      * Add left-over unrecognized option/argument.
273      *
274      * @param arg the unrecognised option/argument.
275      */
276     void addArg(String arg)
277     {
278         args.add(arg);
279     }
280 
281     /***
282      * Add an option to the command line.  The values of 
283      * the option are stored.
284      *
285      * @param opt the processed option
286      */
287     void addOption(Option opt)
288     {
289         options.add(opt);
290     }
291 
292     /***
293      * Returns an iterator over the Option members of CommandLine.
294      *
295      * @return an <code>Iterator</code> over the processed {@link Option} 
296      * members of this {@link CommandLine}
297      */
298     public Iterator iterator()
299     {
300         return options.iterator();
301     }
302 
303     /***
304      * Returns an array of the processed {@link Option}s.
305      *
306      * @return an array of the processed {@link Option}s.
307      */
308     public Option[] getOptions()
309     {
310         Collection processed = options;
311 
312         // reinitialise array
313         Option[] optionsArray = new Option[processed.size()];
314 
315         // return the array
316         return (Option[]) processed.toArray(optionsArray);
317     }
318 }