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: */package org.apache.commons.cli;
017:
018: /**
019: * <p>OptionBuilder allows the user to create Options using descriptive
020: * methods.</p>
021: * <p>Details on the Builder pattern can be found at
022: * <a href="http://c2.com/cgi-bin/wiki?BuilderPattern">
023: * http://c2.com/cgi-bin/wiki?BuilderPattern</a>.</p>
024: *
025: * @author John Keyes (john at integralsource.com)
026: * @since 1.0
027: */
028: public class OptionBuilder {
029:
030: /** long option */
031: private static String longopt;
032:
033: /** option description */
034: private static String description;
035:
036: /** argument name */
037: private static String argName;
038:
039: /** is required? */
040: private static boolean required;
041:
042: /** the number of arguments */
043: private static int numberOfArgs = Option.UNINITIALIZED;
044:
045: /** option type */
046: private static Object type;
047:
048: /** option can have an optional argument value */
049: private static boolean optionalArg;
050:
051: /** value separator for argument value */
052: private static char valuesep;
053:
054: /** option builder instance */
055: private static OptionBuilder instance = new OptionBuilder();
056:
057: /**
058: * private constructor to prevent instances being created
059: */
060: private OptionBuilder() {
061: // hide the constructor
062: }
063:
064: /**
065: * Resets the member variables to their default values.
066: */
067: private static void reset() {
068: description = null;
069: argName = "arg";
070: longopt = null;
071: type = null;
072: required = false;
073: numberOfArgs = Option.UNINITIALIZED;
074:
075: // PMM 9/6/02 - these were missing
076: optionalArg = false;
077: valuesep = (char) 0;
078: }
079:
080: /**
081: * The next Option created will have the following long option value.
082: *
083: * @param newLongopt the long option value
084: * @return the OptionBuilder instance
085: */
086: public static OptionBuilder withLongOpt(String newLongopt) {
087: OptionBuilder.longopt = newLongopt;
088:
089: return instance;
090: }
091:
092: /**
093: * The next Option created will require an argument value.
094: *
095: * @return the OptionBuilder instance
096: */
097: public static OptionBuilder hasArg() {
098: OptionBuilder.numberOfArgs = 1;
099:
100: return instance;
101: }
102:
103: /**
104: * The next Option created will require an argument value if
105: * <code>hasArg</code> is true.
106: *
107: * @param hasArg if true then the Option has an argument value
108: * @return the OptionBuilder instance
109: */
110: public static OptionBuilder hasArg(boolean hasArg) {
111: OptionBuilder.numberOfArgs = (hasArg == true) ? 1
112: : Option.UNINITIALIZED;
113:
114: return instance;
115: }
116:
117: /**
118: * The next Option created will have the specified argument value
119: * name.
120: *
121: * @param name the name for the argument value
122: * @return the OptionBuilder instance
123: */
124: public static OptionBuilder withArgName(String name) {
125: OptionBuilder.argName = name;
126:
127: return instance;
128: }
129:
130: /**
131: * The next Option created will be required.
132: *
133: * @return the OptionBuilder instance
134: */
135: public static OptionBuilder isRequired() {
136: OptionBuilder.required = true;
137:
138: return instance;
139: }
140:
141: /**
142: * The next Option created uses <code>sep</code> as a means to
143: * separate argument values.
144: *
145: * <b>Example:</b>
146: * <pre>
147: * Option opt = OptionBuilder.withValueSeparator(':')
148: * .create('D');
149: *
150: * CommandLine line = parser.parse(args);
151: * String propertyName = opt.getValue(0);
152: * String propertyValue = opt.getValue(1);
153: * </pre>
154: *
155: * @param sep The value separator to be used for the argument values.
156: *
157: * @return the OptionBuilder instance
158: */
159: public static OptionBuilder withValueSeparator(char sep) {
160: OptionBuilder.valuesep = sep;
161:
162: return instance;
163: }
164:
165: /**
166: * The next Option created uses '<code>=</code>' as a means to
167: * separate argument values.
168: *
169: * <b>Example:</b>
170: * <pre>
171: * Option opt = OptionBuilder.withValueSeparator()
172: * .create('D');
173: *
174: * CommandLine line = parser.parse(args);
175: * String propertyName = opt.getValue(0);
176: * String propertyValue = opt.getValue(1);
177: * </pre>
178: *
179: * @return the OptionBuilder instance
180: */
181: public static OptionBuilder withValueSeparator() {
182: OptionBuilder.valuesep = '=';
183:
184: return instance;
185: }
186:
187: /**
188: * The next Option created will be required if <code>required</code>
189: * is true.
190: *
191: * @param newRequired if true then the Option is required
192: * @return the OptionBuilder instance
193: */
194: public static OptionBuilder isRequired(boolean newRequired) {
195: OptionBuilder.required = newRequired;
196:
197: return instance;
198: }
199:
200: /**
201: * The next Option created can have unlimited argument values.
202: *
203: * @return the OptionBuilder instance
204: */
205: public static OptionBuilder hasArgs() {
206: OptionBuilder.numberOfArgs = Option.UNLIMITED_VALUES;
207:
208: return instance;
209: }
210:
211: /**
212: * The next Option created can have <code>num</code>
213: * argument values.
214: *
215: * @param num the number of args that the option can have
216: * @return the OptionBuilder instance
217: */
218: public static OptionBuilder hasArgs(int num) {
219: OptionBuilder.numberOfArgs = num;
220:
221: return instance;
222: }
223:
224: /**
225: * The next Option can have an optional argument.
226: *
227: * @return the OptionBuilder instance
228: */
229: public static OptionBuilder hasOptionalArg() {
230: OptionBuilder.numberOfArgs = 1;
231: OptionBuilder.optionalArg = true;
232:
233: return instance;
234: }
235:
236: /**
237: * The next Option can have an unlimited number of
238: * optional arguments.
239: *
240: * @return the OptionBuilder instance
241: */
242: public static OptionBuilder hasOptionalArgs() {
243: OptionBuilder.numberOfArgs = Option.UNLIMITED_VALUES;
244: OptionBuilder.optionalArg = true;
245:
246: return instance;
247: }
248:
249: /**
250: * The next Option can have the specified number of
251: * optional arguments.
252: *
253: * @param numArgs - the maximum number of optional arguments
254: * the next Option created can have.
255: * @return the OptionBuilder instance
256: */
257: public static OptionBuilder hasOptionalArgs(int numArgs) {
258: OptionBuilder.numberOfArgs = numArgs;
259: OptionBuilder.optionalArg = true;
260:
261: return instance;
262: }
263:
264: /**
265: * The next Option created will have a value that will be an instance
266: * of <code>type</code>.
267: *
268: * @param newType the type of the Options argument value
269: * @return the OptionBuilder instance
270: */
271: public static OptionBuilder withType(Object newType) {
272: OptionBuilder.type = newType;
273:
274: return instance;
275: }
276:
277: /**
278: * The next Option created will have the specified description
279: *
280: * @param newDescription a description of the Option's purpose
281: * @return the OptionBuilder instance
282: */
283: public static OptionBuilder withDescription(String newDescription) {
284: OptionBuilder.description = newDescription;
285:
286: return instance;
287: }
288:
289: /**
290: * Create an Option using the current settings and with
291: * the specified Option <code>char</code>.
292: *
293: * @param opt the character representation of the Option
294: * @return the Option instance
295: * @throws IllegalArgumentException if <code>opt</code> is not
296: * a valid character. See Option.
297: */
298: public static Option create(char opt)
299: throws IllegalArgumentException {
300: return create(String.valueOf(opt));
301: }
302:
303: /**
304: * Create an Option using the current settings
305: *
306: * @return the Option instance
307: * @throws IllegalArgumentException if <code>longOpt</code> has
308: * not been set.
309: */
310: public static Option create() throws IllegalArgumentException {
311: if (longopt == null) {
312: throw new IllegalArgumentException("must specify longopt");
313: }
314:
315: return create(null);
316: }
317:
318: /**
319: * Create an Option using the current settings and with
320: * the specified Option <code>char</code>.
321: *
322: * @param opt the <code>java.lang.String</code> representation
323: * of the Option
324: * @return the Option instance
325: * @throws IllegalArgumentException if <code>opt</code> is not
326: * a valid character. See Option.
327: */
328: public static Option create(String opt)
329: throws IllegalArgumentException {
330: // create the option
331: Option option = new Option(opt, description);
332:
333: // set the option properties
334: option.setLongOpt(longopt);
335: option.setRequired(required);
336: option.setOptionalArg(optionalArg);
337: option.setArgs(numberOfArgs);
338: option.setType(type);
339: option.setValueSeparator(valuesep);
340: option.setArgName(argName);
341:
342: // reset the OptionBuilder properties
343: OptionBuilder.reset();
344:
345: // return the Option instance
346: return option;
347: }
348: }
|