Skip to content

Commit 658aa2b

Browse files
ClaudenwClaudenw
committed
Updated documentation, added Supplier<String> as a default provider for getOptionValue
1 parent 0eee294 commit 658aa2b

3 files changed

Lines changed: 130 additions & 3 deletions

File tree

‎src/main/java/org/apache/commons/cli/CommandLine.java‎

Lines changed: 41 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,9 @@ Licensed to the Apache Software Foundation (ASF) under one or more
2424
import java.util.Iterator;
2525
import java.util.LinkedList;
2626
import java.util.List;
27+
import java.util.Objects;
2728
import java.util.Properties;
29+
import java.util.function.Supplier;
2830

2931
/**
3032
* Represents list of arguments parsed against a {@link Options} descriptor.
@@ -254,6 +256,18 @@ public String getOptionValue(final char opt) {
254256
* @return Value of the argument if option is set, and has an argument, otherwise {@code defaultValue}.
255257
*/
256258
public String getOptionValue(final char opt, final String defaultValue) {
259+
return getOptionValue(String.valueOf(opt), ()->defaultValue);
260+
}
261+
262+
/**
263+
* Gets the argument, if any, of an option.
264+
*
265+
* @param opt character name of the option
266+
* @param defaultValue is a supplier for the default value to be returned if the option is not specified.
267+
* @return Value of the argument if option is set, and has an argument, otherwise {@code defaultValue}.
268+
* @since 1.7.0
269+
*/
270+
public String getOptionValue(final char opt, final Supplier<String> defaultValue) {
257271
return getOptionValue(String.valueOf(opt), defaultValue);
258272
}
259273

@@ -281,10 +295,22 @@ public String getOptionValue(final Option option) {
281295
* @since 1.5.0
282296
*/
283297
public String getOptionValue(final Option option, final String defaultValue) {
284-
final String answer = getOptionValue(option);
285-
return answer != null ? answer : defaultValue;
298+
return getOptionValue(option, ()->defaultValue);
286299
}
287300

301+
/**
302+
* Gets the first argument, if any, of an option.
303+
*
304+
* @param option name of the option.
305+
* @param defaultValue is a supplier for the default value to be returned if the option is not specified.
306+
* @return Value of the argument if option is set, and has an argument, otherwise {@code defaultValue}.
307+
* @since 1.7.0
308+
*/
309+
public String getOptionValue(final Option option, final Supplier<String> defaultValue) {
310+
final String answer = getOptionValue(option);
311+
return answer != null ? answer : defaultValue.get();
312+
}
313+
288314
/**
289315
* Gets the first argument, if any, of this option.
290316
*
@@ -303,9 +329,22 @@ public String getOptionValue(final String opt) {
303329
* @return Value of the argument if option is set, and has an argument, otherwise {@code defaultValue}.
304330
*/
305331
public String getOptionValue(final String opt, final String defaultValue) {
332+
return getOptionValue(resolveOption(opt), ()->defaultValue);
333+
}
334+
335+
/**
336+
* Gets the first argument, if any, of an option.
337+
*
338+
* @param opt name of the option.
339+
* @param defaultValue is a supplier for the default value to be returned if the option is not specified.
340+
* @return Value of the argument if option is set, and has an argument, otherwise {@code defaultValue}.
341+
* @since 1.7.0
342+
*/
343+
public String getOptionValue(final String opt, final Supplier<String> defaultValue) {
306344
return getOptionValue(resolveOption(opt), defaultValue);
307345
}
308346

347+
309348
/**
310349
* Gets the array of values, if any, of an option.
311350
*

‎src/site/xdoc/usage.xml‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -384,5 +384,93 @@ catch (ParseException exp) {
384384
System.out.println("Unexpected exception:" + exp.getMessage());
385385
}</source>
386386
</section>
387+
<section name="Converting (Parsing) Option Values">
388+
<p>
389+
By in most cases the values on the command line are retrieved as Strings via the
390+
<code>commandLine.getOptionValue(key)</code> command. However, it is possible for
391+
the CLI library to convert the string into a different object. For example to specify
392+
that the "count" option should reutrn an Integer the following code could be used:
393+
</p>
394+
<source>
395+
public static void main(String[] args) {
396+
Option count = Option.builder("count")
397+
.hasArg()
398+
.desc("the number of things")
399+
.type(Integer.class)
400+
.build();
401+
Options options = new Options().addOption(cound);
402+
// create the parser
403+
CommandLineParser parser = new DefaultParser();
404+
try {
405+
// parse the command line arguments
406+
CommandLine line = parser.parse(options, args);
407+
}
408+
catch (ParseException exp) {
409+
// oops, something went wrong
410+
System.err.println("Parsing failed. Reason: " + exp.getMessage());
411+
}
412+
413+
try {
414+
Integer value = line.getParsedOptionValue(count);
415+
System.out.format("The value is %s\m", value );
416+
} catch (ParseException e) {
417+
e.printStackTrace();
418+
}
419+
}</source>
420+
<p>
421+
The value types natively supported by commons-cli are:
422+
<ul>
423+
<li>Object.class - The string value must be the name of a class with a no argument constructor</li>
424+
<li>Class.class - The string value must be the name of a class</li>
425+
<li>Date.class - The string value must be a date parsable by <code>new SimpleDateFormat("EEE MMM dd HH:mm:ss zzz yyyy")</code></li>
426+
<li>File.class - The string value is the name of the file.</li>
427+
<li>Number.class - The string value is a number representation can can be converted into an Integer or a Double.</li>
428+
<li>URL.class - The string value is the textual representation of a URL</li>
429+
<li>FileInputStream.class - The string value is passed to <code>new FileInputStream(s)</code>.</li>
430+
<li>Long.class - The string value is a valid argument to <code>Long.parseLong()</code>.</li>
431+
<li>Integer.class - The string value is a valid argument to <code>Integer.parseInt()</code>.</li>
432+
<li>Short.class - The string value is a valid argument to <code>Short.parseShort()</code>.</li>
433+
<li>Byte.class - The string value is a valid argument to <code>Byte.parseByte()</code>.</li>
434+
<li>Character.class - The string value is either a UTF-8 encoding for a character (e.g. "\\u0124") or the first character from the String."</li>
435+
<li>Double.class - The string value is a valid argument to <code>Double.parseDouble()</code>.</li>
436+
<li>Float.class - The string value is a valid argument to <code>Float.parseFloat()</code>.</li>
437+
<li>BigInteger.class - The string value is a valid argument to <code>new BigInteger(s)</code>.</li>
438+
<li>BigDecimal.class - The string value is a valid argument to <code>new BigDecimal(s)</code>.</li>
439+
</ul>
440+
Additional types may be added to the automatic parsing system by calling <code>TypeHandler.register(Class&lt;T&gt; clazz, Converter&lt;T&gt; converter)</code>.
441+
The <code>Class&lt;T&gt;</code> can be any defined class. The converter is a function that takes a <code>String</code> argument and returns an instance of
442+
the class. Any expection thrown by the constructor will be caught and reported as a <code>ParseException</code>
443+
</p>
444+
<p>
445+
Conversions can be specified without using the <code>TypeHandler</code> class by specifying the converter
446+
directly during the option build. For example:
447+
<source>
448+
Option fooOpt = Option.builder("foo")
449+
.hasArg()
450+
.desc("the foo arg")
451+
.converter((s) -> new Foo(s))
452+
.build();
453+
</source>
454+
The above will create an option that passes the string value to the Foo constructor when <code>commandLine.getParsedOptionValue(fooOpt)</code> is called.
455+
</p>
456+
</section>
457+
<section name="Restricting values">
458+
<p>
459+
Acceptable values for options may be specified by using <code>Option.Builder.verifier()</code> to specify a <code>java.util.function.Predicate</code>
460+
to verify the input text. There are a few examples in the <code>Verifier</code> source file. Verifier also provides a method to construct a verifier
461+
to test <code>enum</code> values. For example:
462+
<source>
463+
public enum MyEnum {ONE, TWO, THREE};
464+
465+
Option enumOpt = Option.builder("enumValue")
466+
.hasArg()
467+
.desc("the enum arg")
468+
.varifier(Verifier.enumVerifier(MyEnum.ONE))
469+
.build();
470+
</source>
471+
The above will create an option that verifies any argument passed to <code>enumOpt</code> matches a name from <code>MyEnum</code>.
472+
The initial verification occures when the option string is set during the execution of <code>CommandLine line = parser.parse(options, args)</code>.
473+
</p>
474+
</section>
387475
</body>
388476
</document>

‎src/test/java/org/apache/commons/cli/bug/BugsTest.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ public void test11680() throws Exception {
137137
cmd.getOptionValue("f", "default f");
138138
cmd.getOptionValue("m", "default m");
139139
//
140-
assertNull(cmd.getOptionValue((String) null, null));
140+
assertNull(cmd.getOptionValue((String) null, (String)null));
141141
assertEquals("default", cmd.getOptionValue((String) null, "default"));
142142
}
143143

0 commit comments

Comments
 (0)