Picocli 2.3.0

The picocli community is pleased to announce picocli 2.3.0.

This release contains bugfixes and new features.

This release introduces a new parser flag stopAtPositional to treat the first positional parameter as end-of-options, and a stopAtUnmatched parser flag to stop matching options and positional parameters as soon as an unmatched argument is encountered.

These flags are useful for applications that need to delegate part of the command line to third party commands.

This release offers better support for options with optional values, allowing applications to distinguish between cases where the option was not specified at all, and cases where the option was specified without a value.

This is the twentieth public release.
Picocli follows semantic versioning.

Table of Contents

• New and noteworthy
• Promoted features
• Fixed issues
• Deprecations
• Potential breaking changes

New and noteworthy

Stop At Positional

By default, positional parameters can be mixed with options on the command line, but this is not always desirable. From this release, applications can call CommandLine.setStopAtPositional(true) to force the parser to treat all values following the first positional parameter as positional parameters.

When this flag is set, the first positional parameter effectively serves as an "end of options" marker, without requiring a separate -- argument.

Stop At Unmatched

From this release, applications can call CommandLine.setStopAtUnmatched(true) to force the parser to stop interpreting options and positional parameters as soon as it encounters an unmatched argument.

When this flag is set, the first unmatched argument and all subsequent command line arguments are added to the unmatched arguments list returned by CommandLine.getUnmatchedArguments().

Optional Values

If an option is defined with arity = "0..1", it may or not have a parameter value. If such an option is specified without a value on the command line, it is assigned an empty String. If the option is not specified, it keeps its default value. For example:

class OptionalValueDemo implements Runnable {
    @Option(names = "-x", arity = "0..1", description = "optional parameter")
    String x;

    public void run() { System.out.printf("x = '%s'%n", x); }

    public static void main(String... args) {
       CommandLine.run(new OptionalValueDemo(), System.out, args);
    }
}

Gives the following results:

java OptionalValueDemo -x value
x = 'value'

java OptionalValueDemo -x
x = ''

java OptionalValueDemo
x = 'null'

Promoted features

Promoted features are features that were incubating in previous versions of picocli but are now supported and subject to backwards compatibility.

No features have been promoted in this picocli release.

Fixed issues

• [#215] API: stopAtUnmatched flag to stop parsing on first unmatched argument. Thanks to defnull for the request.
• [#284] API: stopAtPositional flag to treat first positional parameter as end-of-options. Thanks to defnull and pditommaso for the request.
• [#279] Enhancement: assign empty String when String option was specified without value. Thanks to pditommaso for the request.
• [#285] Bugfix: Vararg positional parameters should not consume options. Thanks to pditommaso for the bug report.
• [#286] Documentation: clarify when picocli instantiates fields for options and positional parameters. Thanks to JanMosigItemis for pointing this out.

Deprecations

This release has no additional deprecations.

Potential breaking changes

This release has no breaking changes.