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  /***
20   * <p>OptionBuilder allows the user to create Options using descriptive
21   * methods.</p>
22   * <p>Details on the Builder pattern can be found at 
23   * <a href="http://c2.com/cgi-bin/wiki?BuilderPattern">
24   * http://c2.com/cgi-bin/wiki?BuilderPattern</a>.</p>
25   *
26   * @author John Keyes (john at integralsource.com)
27   * @since 1.0
28   */
29  public class OptionBuilder {
30  
31      /*** long option */
32      private static String longopt;
33  
34      /*** option description */
35      private static String description;
36  
37      /*** argument name */
38      private static String argName;
39  
40      /*** is required? */
41      private static boolean required;
42  
43      /*** the number of arguments */
44      private static int numberOfArgs = Option.UNINITIALIZED;
45  
46      /*** option type */
47      private static Object type;
48  
49      /*** option can have an optional argument value */
50      private static boolean optionalArg;
51  
52      /*** value separator for argument value */
53      private static char valuesep;
54  
55      /*** option builder instance */
56      private static OptionBuilder instance = new OptionBuilder();
57  
58      /***
59       * private constructor to prevent instances being created
60       */
61      private OptionBuilder()
62      {
63          // hide the constructor
64      }
65  
66      /***
67       * Resets the member variables to their default values.
68       */
69      private static void reset()
70      {
71          description = null;
72          argName = "arg";
73          longopt = null;
74          type = null;
75          required = false;
76          numberOfArgs = Option.UNINITIALIZED;
77  
78  
79          // PMM 9/6/02 - these were missing
80          optionalArg = false;
81          valuesep = (char) 0;
82      }
83  
84      /***
85       * The next Option created will have the following long option value.
86       *
87       * @param newLongopt the long option value
88       * @return the OptionBuilder instance
89       */
90      public static OptionBuilder withLongOpt(String newLongopt)
91      {
92          OptionBuilder.longopt = newLongopt;
93  
94          return instance;
95      }
96  
97      /***
98       * The next Option created will require an argument value.
99       *
100      * @return the OptionBuilder instance
101      */
102     public static OptionBuilder hasArg()
103     {
104         OptionBuilder.numberOfArgs = 1;
105 
106         return instance;
107     }
108 
109     /***
110      * The next Option created will require an argument value if
111      * <code>hasArg</code> is true.
112      *
113      * @param hasArg if true then the Option has an argument value
114      * @return the OptionBuilder instance
115      */
116     public static OptionBuilder hasArg(boolean hasArg)
117     {
118         OptionBuilder.numberOfArgs = (hasArg == true) ? 1 : Option.UNINITIALIZED;
119 
120         return instance;
121     }
122 
123     /***
124      * The next Option created will have the specified argument value 
125      * name.
126      *
127      * @param name the name for the argument value
128      * @return the OptionBuilder instance
129      */
130     public static OptionBuilder withArgName(String name)
131     {
132         OptionBuilder.argName = name;
133 
134         return instance;
135     }
136 
137     /***
138      * The next Option created will be required.
139      *
140      * @return the OptionBuilder instance
141      */
142     public static OptionBuilder isRequired()
143     {
144         OptionBuilder.required = true;
145 
146         return instance;
147     }
148 
149     /***
150      * The next Option created uses <code>sep</code> as a means to
151      * separate argument values.
152      *
153      * <b>Example:</b>
154      * <pre>
155      * Option opt = OptionBuilder.withValueSeparator(':')
156      *                           .create('D');
157      *
158      * CommandLine line = parser.parse(args);
159      * String propertyName = opt.getValue(0);
160      * String propertyValue = opt.getValue(1);
161      * </pre>
162      *
163      * @param sep The value separator to be used for the argument values.
164      *
165      * @return the OptionBuilder instance
166      */
167     public static OptionBuilder withValueSeparator(char sep)
168     {
169         OptionBuilder.valuesep = sep;
170 
171         return instance;
172     }
173 
174     /***
175      * The next Option created uses '<code>=</code>' as a means to
176      * separate argument values.
177      *
178      * <b>Example:</b>
179      * <pre>
180      * Option opt = OptionBuilder.withValueSeparator()
181      *                           .create('D');
182      *
183      * CommandLine line = parser.parse(args);
184      * String propertyName = opt.getValue(0);
185      * String propertyValue = opt.getValue(1);
186      * </pre>
187      *
188      * @return the OptionBuilder instance
189      */
190     public static OptionBuilder withValueSeparator()
191     {
192         OptionBuilder.valuesep = '=';
193 
194         return instance;
195     }
196 
197     /***
198      * The next Option created will be required if <code>required</code>
199      * is true.
200      *
201      * @param newRequired if true then the Option is required
202      * @return the OptionBuilder instance
203      */
204     public static OptionBuilder isRequired(boolean newRequired)
205     {
206         OptionBuilder.required = newRequired;
207 
208         return instance;
209     }
210 
211     /***
212      * The next Option created can have unlimited argument values.
213      *
214      * @return the OptionBuilder instance
215      */
216     public static OptionBuilder hasArgs()
217     {
218         OptionBuilder.numberOfArgs = Option.UNLIMITED_VALUES;
219 
220         return instance;
221     }
222 
223     /***
224      * The next Option created can have <code>num</code> 
225      * argument values.
226      *
227      * @param num the number of args that the option can have
228      * @return the OptionBuilder instance
229      */
230     public static OptionBuilder hasArgs(int num)
231     {
232         OptionBuilder.numberOfArgs = num;
233 
234         return instance;
235     }
236 
237     /***
238      * The next Option can have an optional argument.
239      *
240      * @return the OptionBuilder instance
241      */
242     public static OptionBuilder hasOptionalArg()
243     {
244         OptionBuilder.numberOfArgs = 1;
245         OptionBuilder.optionalArg = true;
246 
247         return instance;
248     }
249 
250     /***
251      * The next Option can have an unlimited number of
252      * optional arguments.
253      *
254      * @return the OptionBuilder instance
255      */
256     public static OptionBuilder hasOptionalArgs()
257     {
258         OptionBuilder.numberOfArgs = Option.UNLIMITED_VALUES;
259         OptionBuilder.optionalArg = true;
260 
261         return instance;
262     }
263 
264     /***
265      * The next Option can have the specified number of 
266      * optional arguments.
267      *
268      * @param numArgs - the maximum number of optional arguments
269      * the next Option created can have.
270      * @return the OptionBuilder instance
271      */
272     public static OptionBuilder hasOptionalArgs(int numArgs)
273     {
274         OptionBuilder.numberOfArgs = numArgs;
275         OptionBuilder.optionalArg = true;
276 
277         return instance;
278     }
279 
280     /***
281      * The next Option created will have a value that will be an instance 
282      * of <code>type</code>.
283      *
284      * @param newType the type of the Options argument value
285      * @return the OptionBuilder instance
286      */
287     public static OptionBuilder withType(Object newType)
288     {
289         OptionBuilder.type = newType;
290 
291         return instance;
292     }
293 
294     /***
295      * The next Option created will have the specified description
296      *
297      * @param newDescription a description of the Option's purpose
298      * @return the OptionBuilder instance
299      */
300     public static OptionBuilder withDescription(String newDescription)
301     {
302         OptionBuilder.description = newDescription;
303 
304         return instance;
305     }
306 
307     /***
308      * Create an Option using the current settings and with 
309      * the specified Option <code>char</code>.
310      *
311      * @param opt the character representation of the Option
312      * @return the Option instance
313      * @throws IllegalArgumentException if <code>opt</code> is not
314      * a valid character.  See Option.
315      */
316     public static Option create(char opt)
317                          throws IllegalArgumentException
318     {
319         return create(String.valueOf(opt));
320     }
321 
322     /***
323      * Create an Option using the current settings
324      *
325      * @return the Option instance
326      * @throws IllegalArgumentException if <code>longOpt</code> has
327      * not been set.  
328      */
329     public static Option create()
330                          throws IllegalArgumentException
331     {
332         if (longopt == null)
333         {
334             throw new IllegalArgumentException("must specify longopt");
335         }
336 
337         return create(null);
338     }
339 
340     /***
341      * Create an Option using the current settings and with 
342      * the specified Option <code>char</code>.
343      *
344      * @param opt the <code>java.lang.String</code> representation 
345      * of the Option
346      * @return the Option instance
347      * @throws IllegalArgumentException if <code>opt</code> is not
348      * a valid character.  See Option.
349      */
350     public static Option create(String opt)
351                          throws IllegalArgumentException
352     {
353         // create the option
354         Option option = new Option(opt, description);
355 
356 
357         // set the option properties
358         option.setLongOpt(longopt);
359         option.setRequired(required);
360         option.setOptionalArg(optionalArg);
361         option.setArgs(numberOfArgs);
362         option.setType(type);
363         option.setValueSeparator(valuesep);
364         option.setArgName(argName);
365 
366 
367         // reset the OptionBuilder properties
368         OptionBuilder.reset();
369 
370         // return the Option instance
371         return option;
372     }
373 }