Picocli 4.1.0

The picocli community is pleased to announce picocli 4.1.0.

This release contains bugfixes, and enhancements.

The library now provides functionality that previously required custom code:

PropertiesDefaultProvider - this release includes a built-in default provider allows end users to maintain their own default values for options and positional parameters, which may override the defaults that are hard-coded in the application.

AutoComplete.GenerateCompletion - this release includes a built-in generate-completion subcommand that end users can use to easily install Bash/ZSH completion for your application.

Help API improvements make it even easier to add custom sections to the usage help message.

This release also includes various bug fixes for ArgGroups, which were first introduced in picocli 4.0, and are still maturing.

This is the sixty-second public release.
Picocli follows semantic versioning.

Table of Contents

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

New and Noteworthy

PropertiesDefaultProvider

From picocli 4.1, applications can use the built-in PropertiesDefaultProvider implementation that loads default values from a properties file.

By default, this implementation tries to find a properties file named .${COMMAND-NAME}.properties in the user home directory, where ${COMMAND-NAME} is the name of the command. If a command has aliases in addition to its name, these aliases are also used to try to find the properties file. For example:

import picocli.CommandLine.PropertiesDefaultProvider;
// ...
@Command(name = "git", defaultValueProvider = PropertiesDefaultProvider.class)
class Git { }

The above will try to load default values from new File(System.getProperty("user.home"), ".git.properties").
The location of the properties file can also be controlled with system property "picocli.defaults.${COMMAND-NAME}.path" ("picocli.defaults.git.path" in this example), in which case the value of the property must be the path to the file containing the default values.

The location of the properties file may also be specified programmatically. For example:

CommandLine cmd = new CommandLine(new MyCommand());
File defaultsFile = new File("path/to/config/mycommand.properties");
cmd.setDefaultValueProvider(new PropertiesDefaultProvider(defaultsFile));
cmd.execute(args);

PropertiesDefaultProvider Format

The PropertiesDefaultProvider expects the properties file to be in the standard java .properties https://en.wikipedia.org/wiki/.properties[format].

For options, the key is either the descriptionKey, or the option's longest name, without the prefix. So, for an option --verbose, the key would be verbose, and for an option /F, the key would be F.

For positional parameters, the key is either the descriptionKey, or the positional parameter's param label.

End users may not know what the descriptionKey of your options and positional parameters are, so be sure to document that with your application.

Subcommands Default Values

The default values for options and positional parameters of subcommands can be included in the properties file for the top-level command, so that end users need to maintain only a single file.
This can be achieved by prefixing the keys for the options and positional parameters with their command's qualified name.
For example, to give the git commit command's --cleanup option a default value of strip, define a key of git.commit.cleanup and assign it a default value:

# /home/remko/.git.properties
git.commit.cleanup = strip

AutoComplete.GenerateCompletion

This release adds a built-in generate-completion subcommand that generates a completion script for its parent command.

Example usage:

@Command(name = "myapp",
        subcommands = picocli.AutoComplete.GenerateCompletion.class)
static class MyApp { //...
}

This allows users to install completion for the myapp command by running the following command:

source <(myapp generate-completion)

Autocompletion script improvements

The generated completion script itself now enables bash completion in zsh.

That means it is no longer necessary to run the below commands in ZSH before sourcing the completion script:

autoload -U +X compinit && compinit
autoload -U +X bashcompinit && bashcompinit

Help API improvements

The new Help.createHeading(String, Object...) and Help.createTextTable(Map<?, ?>) methods
facilitate creating tabular custom Help sections.

The below example shows how to add a custom Environment Variables section to the usage help message.

// help section keys
static final String SECTION_KEY_ENV_HEADING = "environmentVariablesHeading";
static final String SECTION_KEY_ENV_DETAILS = "environmentVariables";
// ...

// the data to display
Map<String, String> env = new LinkedHashMap<>();
env.put("FOO", "explanation of foo");
env.put("BAR", "explanation of bar");
env.put("XYZ", "xxxx yyyy zzz");

// register the custom section renderers
CommandLine cmd = new CommandLine(new MyApp());
cmd.getHelpSectionMap().put(SECTION_KEY_ENV_HEADING,
                            help -> help.createHeading("Environment Variables:%n"));
cmd.getHelpSectionMap().put(SECTION_KEY_ENV_DETAILS,
                            help -> help.createTextTable(env).toString());

// specify the location of the new sections
List<String> keys = new ArrayList<>(cmd.getHelpSectionKeys());
int index = keys.indexOf(CommandLine.Model.UsageMessageSpec.SECTION_KEY_FOOTER_HEADING);
keys.add(index, SECTION_KEY_ENV_HEADING);
keys.add(index + 1, SECTION_KEY_ENV_DETAILS);
cmd.setHelpSectionKeys(keys);

There are also new convenience methods Help.fullSynopsis() and CommandLine.getHelp().

ArgGroup improvements

• ArgGroups with @Option-annotated methods no longer fail with NullPointerException
• ArgGroups now match multiple occurrences of a multi-value @Option in the same group instance, and don't create a new group for each occurrence
• ArgGroups now don't validate when marked as validate = false
• ArgGroups now correctly validate that required options are present
• Non-validating ArgGroups are now automatically set to be non-exclusive

Fixed issues

• [#841] (API) Add JniConfigGenerator to picocli-codegen module.
• [#865] (API) Add Help.createHeading(String, Object...) and Help.createTextTable(Map<?, ?>) to facilitate creating tabular custom Help sections.
• [#829] (Bugfix) @ArgGroup with @Option-annotated methods fail with NullPointerException. Thanks to A2 Geek for raising this.
• [#828] (Bugfix/enhancement) Subcommands should not be parsed as option values for options with optional parameters. Thanks to Martin Paljak for raising this.
• [#811] (Bugfix) CommandLine.setResourceBundle did not propagate resource bundle to subcommands recursively. Thanks to thope for the pull request with the bug fix.
• [#850] (Bugfix) @Mixin-annotated fields were not included in reflect-config.json by picocli-codegen annotation processor. Thanks to Nikolaos Georgiou for raising this.
• [#826] (Enhancement) Suppress compiler warning "Supported source version 'RELEASE_6' from annotation processor... less than -source..." in picocli-codegen.
• [#815] (Enhancement) @ArgGroup should match multiple occurrences of a multi-value @Option in the same group instance, not create new group for each occurrence. Thanks to kacchi for raising this.
• [#810] (Bugfix) @ArgGroup should not validate when marked as validate = false. Thanks to Andreas Deininger for raising this.
• [#870] (Bugfix) Required options were not validated when mixing required and non-required options in an ArgGroup. Thanks to W Scott Johnson for raising this.
• [#868] (Enhancement) Add built-in default value provider implementation PropertiesDefaultProvider that loads default values from properties file in home directory or specified location.
• [#809] (Enhancement) Add built-in generate-completion subcommand that generates a completion script for its parent command. Thanks to George Gastaldi for the suggestion.
• [#836] (Enhancement) Add convenience methods Help.fullSynopsis() and CommandLine.getHelp().
• [#833] (Enhancement) Non-validating ArgGroups are now automatically set to be non-exclusive. Thanks to Andreas Deininger for raising this.
• [#830] (Enhancement) Enum constants can now be matched by their toString() as well as their name(). Improved error reporting. Thanks to Henning Makholm for the pull request.
• [#846] (Enhancement) Allow value tty for system property picocli.ansi: force picocli to emit ANSI escape characters if the process is using an interactive console.
• [#772] (Enhancement) Generated completion script should enable bash completion in zsh. Thanks to Bob Tiernay for raising this.
• [#480] (DOC) Added a Handling Errors subsection to the Executing Commands section of the user manual to show how to customize how your application deals with invalid input or business logic exceptions.
• [#813] (DOC) Clarify usage of negatable boolean @Option with default value "true". Thanks to Yann ROBERT for raising this.
• [#814] (DOC) Document how a CLI application can be packaged for distribution.
• [#820] (DOC) Update user manual section on ANSI supported platforms: mention Windows Subsystem for Linux under Windows 10.
• [#819] (DOC) Update user manual section on Variable Interpolation: improve example, link to this section from other parts of the manual.
• [#818] (DOC) Update user manual section on Usage Help API to point to picocli-examples.
• [#816] (DOC) Update user manual for IHelpCommandInitializable2.
• [#817] (DOC) Update user manual section on Subcommands for the execute API.
• [#809] (DOC) Output completion script as a subcommand of the command itself. Thanks to George Gastaldi for the suggestion.
• [#456] (DOC) Integrate completion generation into command itself. Thanks to jvassev for the suggestion.
• [#835] (DOC) Document how to create ANSI colored output in an application.
• [#847] (DOC) Improve documentation for ANSI colors in Windows.
• [#844] (DOC) Clarify when @ArgGroup-annotated fields are initialized in user manual.
• [#860] (DOC) Fix broken link to GraalVM Native Image section. Thanks to Andreas Deininger for the pull request.
• [#861] (DOC) Fix broken link to ShowCommandHierarchy example. Thanks to Andreas Deininger for the pull request.
• [#864] (DOC) Fix code examples in documentation. Thanks to Andreas Deininger for the pull request.
• [#867] (DOC) Update user manual to clarify that the toggling behaviour is no longer the default from picocli 4.0. Thanks to Linus Fernandes for raising this.

Deprecations

No features were deprecated in this release.

Potential breaking changes

• From picocli 4.1, subcommands will not be parsed as option values for options with optional parameters.
• Enum constants can now be matched by their toString() as well as their name().