Picocli 3.8.0

The picocli community is pleased to announce picocli 3.8.0.

This release contains bugfixes and minor enhancements.

@Command methods now support @Mixin parameters. OverwrittenOptionException now has an accessor for the ArgSpec that was overwritten.

The ReflectionConfigGenerator tool in the picocli-codegen module now correctly generates configuration for @Mixin fields.

Many thanks to the many members of the picocli community who contributed!

This is the forty-second public release. Picocli follows semantic versioning. (This release could have been called 3.7.1 except that it has a minor additional API change, which means it cannot be called a patch release by semver rules.)

Table of Contents

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

New and Noteworthy

Mixin Support in @Command Methods

@Command methods now accept @Mixin parameters. All options and positional parameters defined in the mixin class are added to the command.

Example:

class CommonParams {
    @Option(names = "-x") int x;
    @Option(names = "-y") int y;
}

class App {
    @Command
    public void doit(@Mixin CommonParams params, @Option(names = "-z") int z) {}
}

In the above example, the -x and -y options are added to the other options of the doit command.

Fixed issues

• [#525] Enhancement: Allow @Mixin parameters in @Command methods. Thanks to Paul Horn for the pull request.
• [#532] Enhancement: OverwrittenOptionException now has an accessor for the ArgSpec that was overwritten. Thanks to Steven Fontaine for the pull request.
• [#524] Enhancement/Bugfix: ReflectionConfigGenerator in picocli-codegen should generate configuration for @Mixin fields. Thanks to Paul Horn for the pull request.
• [#301] Enhancement/Bugfix: The subcommand listing now correctly renders %n as line breaks in the brief description for each subcommand. Thanks to Vlad Topala for the pull request.
• [#523] Bugfix: Array should be initialized before calling setter method. Thanks to Paul Horn for the pull request.
• [#527] Bugfix: Quoting logic did not work for some Unicode code points.
• [#531] Bugfix: Usage help should not show space between short option name and parameter (for options that only have a short name).
• [#538] Bugfix: Command methods and interface methods should pass null for unmatched primitive wrapper options.
• [#547] Bugfix: Fix infinite loop when print help. Thanks to Patrick Kuo for the pull request.
• [#528] Doc: Javadoc for xxxHandler API referred to non-existant prototypeReturnValue.
• [#545] Doc: Include mention of command methods for options using collections. Thanks to Bob Tiernay for the pull request.

Deprecations

No features were deprecated in this release.

Potential breaking changes

Help Layout

The usage help no longer shows a space between short option names and the parameter (for options that only have a short name).
This may break tests that rely on the exact output format.

Before:

Usage: times [-l=<arg0>] [-r=<arg1>]
  -l= <arg0>
  -r= <arg1>

After:

Usage: times [-l=<arg0>] [-r=<arg1>]
  -l=<arg0>
  -r=<arg1>

Unmatched Primitive Wrapper Type Options

Another behavioral change is that command methods now pass in null for primitive wrapper options that were not matched on the command line.
This impacts methods annotated with @Command, and interface methods annotated with @Option. Classes annotated with @Command already behaved like this and this has not changed.

This behaviour is now consistent for all annotation-based and programmatic ways of defining commands.