Picocli 3.9.0

Picocli 3.9.0

The picocli community is pleased to announce picocli 3.9.0.

This release contains bugfixes and enhancements in the main picocli module, and adds a new module: picocli-shell-jline3.

The new module Picocli Shell JLine3 (picocli-shell-jline3) contains components and documentation for building
interactive shell command line applications with JLine 3 and picocli.

This release contains API enhancements to allow customization of the usage help message:

• help section renderers can be added, replaced or removed
• help section keys to reorder sections in the usage help message
• help factory to create custom Help instances
• option order attribute to reorder options in the usage help message option list

This release also has improved heuristics to decide whether ANSI escape codes should be emitted or not.

The simplified @-file (argument file) format is now fully compatible with JCommander: empty lines are ignored and comments may start with leading whitespace.

The picocli.Autocompletion application now accepts a parameter specifying a custom factory, and returns a non-zero exit code on error, to facilitate incorporating it into the build.

Bug fixes in this release:

• @Command method options and positional parameter values are now cleared correctly when reusing a CommandLine instance
• the default exception handler now correctly respects the exit code for all exceptions

Finally, this release improves internal quality and robustness by increasing the test code coverage. About 300 tests were added to bring the total to 1300+ tests. This improved line coverage to 98% (was 88%) and complexity coverage to 98% (was 82%).

This is the forty-fifth public release.
Picocli follows semantic versioning.

Table of Contents

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

New and Noteworthy

Help Section Renderer API

This release introduces new API to facilitate customizing the usage help message: IHelpFactory allows applications to plug in Help subclasses, and IHelpSectionRenderer allows applications to add custom sections to the usage help message, or redefine existing sections.

The usage help message is no longer hard-coded, but is now constructed from the section renderers defined in CommandLine::getHelpSectionMap (or UsageMessageSpec::sectionMap for a single CommandSpec).

By default this map contains the predefined section renderers:

// The default section renderers delegate to methods in Help for their implementation
// (using Java 8 lambda notation for brevity):
Map<String, IHelpSectionRenderer> map = new HashMap<>();
map.put(SECTION_KEY_HEADER_HEADING,         help -> help.headerHeading());
map.put(SECTION_KEY_HEADER,                 help -> help.header());

//e.g. Usage:
map.put(SECTION_KEY_SYNOPSIS_HEADING,       help -> help.synopsisHeading());

//e.g. <cmd> [OPTIONS] <subcmd> [COMMAND-OPTIONS] [ARGUMENTS]
map.put(SECTION_KEY_SYNOPSIS,               help -> help.synopsis(help.synopsisHeadingLength()));

//e.g. %nDescription:%n%n
map.put(SECTION_KEY_DESCRIPTION_HEADING,    help -> help.descriptionHeading());

//e.g. {"Converts foos to bars.", "Use options to control conversion mode."}
map.put(SECTION_KEY_DESCRIPTION,            help -> help.description());

//e.g. %nPositional parameters:%n%n
map.put(SECTION_KEY_PARAMETER_LIST_HEADING, help -> help.parameterListHeading());

//e.g. [FILE...] the files to convert
map.put(SECTION_KEY_PARAMETER_LIST,         help -> help.parameterList());

//e.g. %nOptions:%n%n
map.put(SECTION_KEY_OPTION_LIST_HEADING,    help -> help.optionListHeading());

//e.g. -h, --help   displays this help and exits
map.put(SECTION_KEY_OPTION_LIST,            help -> help.optionList());

//e.g. %nCommands:%n%n
map.put(SECTION_KEY_COMMAND_LIST_HEADING,   help -> help.commandListHeading());

//e.g.    add       adds the frup to the frooble
map.put(SECTION_KEY_COMMAND_LIST,           help -> help.commandList());
map.put(SECTION_KEY_FOOTER_HEADING,         help -> help.footerHeading());
map.put(SECTION_KEY_FOOTER,                 help -> help.footer());

Applications can add, remove or replace sections in this map. The CommandLine::getHelpSectionKeys method (or UsageMessageSpec::sectionKeys for a single CommandSpec) returns the section keys in the order that the usage help message should render the sections. The default keys are (in order):

1. SECTION_KEY_HEADER_HEADING
2. SECTION_KEY_HEADER
3. SECTION_KEY_SYNOPSIS_HEADING
4. SECTION_KEY_SYNOPSIS
5. SECTION_KEY_DESCRIPTION_HEADING
6. SECTION_KEY_DESCRIPTION
7. SECTION_KEY_PARAMETER_LIST_HEADING
8. SECTION_KEY_PARAMETER_LIST
9. SECTION_KEY_OPTION_LIST_HEADING
10. SECTION_KEY_OPTION_LIST
11. SECTION_KEY_COMMAND_LIST_HEADING
12. SECTION_KEY_COMMAND_LIST
13. SECTION_KEY_FOOTER_HEADING
14. SECTION_KEY_FOOTER

This ordering may be modified with the CommandLine::setHelpSectionKeys setter method (or UsageMessageSpec::sectionKeys(List) for a single CommandSpec).

Option order Attribute

Options are sorted alphabetically by default, but this can be switched off by specifying @Command(sortOptions = false) on the command declaration. This displays options in the order they are declared.

However, when mixing @Option methods and @Option fields, options do not reliably appear in declaration order.

The @Option(order = <int>) attribute can be used to explicitly control the position in the usage help message at which the option should be shown. Options with a lower number are shown before options with a higher number.

New Module picocli-shell-jline3

Picocli Shell JLine3 contains components and documentation for building interactive shell command line applications with JLine 3 and picocli.

This release contains the picocli.shell.jline3.PicocliJLineCompleter class.
PicocliJLineCompleter is a small component that generates completion candidates to allow users to get command line TAB auto-completion for a picocli-based application running in a JLine 3 shell.
It is similar to the class with the same name in the picocli.shell.jline2 package in the picocli-shell-jline2 module.

See the module's README for more details.

Improved ANSI Heuristics

This release has improved heuristics to decide whether ANSI escape codes should be emitted or not.

Support was added for the following environment variables to control enabling ANSI:

• NO_COLOR
• CLICOLOR_FORCE
• CLICOLOR
• ConEmuANSI
• ANSICON

Fixed issues

• [#574] Add picocli-shell-jline3 module. Thanks to mattirn for the pull request.
• [#587] Enhance picocli-shell-jline3 example by using JLine's DefaultParser to split lines into arguments. Thanks to mattirn for the pull request.
• [#567] Usage message customization API initial implementation. Thanks to Christian Helmer for the pull request.
• [#530] Added API for easily customizing the usage help message. Thanks to stechio for raising the request and productive discussions.
• [#569] Facilitate customization of the synopsis: split Help.detailedSynopsis() into protected methods.
• [#508] Annotation API: added @Option(order = <int>) attribute to allow explicit control of option ordering in the usage help message; useful when mixing methods and fields with @Option annotation.
• [#588] Added method CommandSpec.names returning both name and aliases.
• [#578] Add API for simplified @files argument files.
• [#573] Make simplified @files JCommander-compatible: ignore empty lines and comments starting with whitespace. Thanks to Lukáš Petrovický for the pull request with test to reproduce the issue.
• [#572] CommandSpec.addMethodSubcommands now throws picocli.CommandLine.InitializationException instead of java.lang.UnsupportedOperationException when the user object of the parent command is a java.lang.reflect.Method.
• [#581] Added support for ConEmu, ANSICON and other environment variables to improve the ANSI heuristics. Documented the heuristics in the user manual.
• [#579] Improved AutoComplete error message when not overwriting existing files.
• [#585] picocli.AutoComplete now accepts a parameter specifying a custom IFactory implementation. Thanks to Bob Tiernay for the suggestion.
• [#582] picocli.AutoComplete now returns a non-zero return code on error. Thanks to Bob Tiernay for the suggestion.
• [#570] Bugfix: Command method options and positional parameter Object values are now cleared correctly when reusing CommandLine. Thanks to Christian Helmer for the pull request.
• [#576] Bugfix: fixed StringIndexOutOfBoundsException in shell-jline2 completion when cursor was before = when option parameter was attached to option name.
• [#583] Bugfix: Default exception handler now exits on exception if exitCode was set, regardless of exception type.
• [#584] Add documentation for generating autocompletion script during a Maven b...

Picocli 3.8.2

Picocli 3.8.2

The picocli community is pleased to announce picocli 3.8.2.

This release contains bugfixes only.

When running a native image with Graal, ANSI colors are now shown correctly.

This is the forty-forth public release.
Picocli follows semantic versioning.

Table of Contents

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

New and Noteworthy

Fixed issues

• [#557] Bugfix: No colors are shown when compiling to a native image with Graal on MacOS. Thanks to Oliver Weiler for the bug report.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This is a patch release and has no breaking changes.

Picocli 3.8.1

Picocli 3.8.1

The picocli community is pleased to announce picocli 3.8.1.

This release contains bugfixes and minor enhancements.

Command methods explicitly throwing a ParametersException is now correctly handled by picocli, showing the error message and the usage help message.

This release adds support for JCommander-style argument files (one argument per line, no quoting) and better tracing.

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

This is the forty-third public release.
Picocli follows semantic versioning.

Table of Contents

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

New and Noteworthy

Simplified Argument Files

In this argument file format every line (except comment lines) is interpreted as a single argument. Arguments containing whitespace do not need to be quoted, but it is not possible to have arguments with embedded newlines.

Set system property picocli.useSimplifiedAtFiles without a value or with value "true" (case-insensitive) to enable this simpler argument file format.

This format is similar to the way JCommander processes argument files, which makes it easier for command line applications to migrate from JCommander to picocli.

Improved Tracing

The following information has been added to the tracing output in this release:

• Version information (picocli version, java version, os version), logged at INFO level
• ANSI enabled status, logged at DEBUG level
• Log at DEBUG level when a Map or Collection binding for an option or positional parameter is initialized with a new instance
• Log at DEBUG level when parameters are being split (into how many parts, show resulting parts)

Fixed issues

• [#551] Enhancement: Add support for JCommander-style argument files (one argument per line, no quoting). Thanks to Lukáš Petrovický for the bug report and unit tests.
• [#562] Enhancement: Allow for enabling quote trimming via system property picocli.trimQuotes. Thanks to Lukáš Petrovický for the pull request.
• [#560] Enhancement: Better tracing.
• [#554] Bugfix: Convenience method error handling was broken for command methods that explicitly throw an ParameterException: InvocationTargetException hides the ParameterException. Thanks to SysLord for the bug report.
• [#553] Doc: Fix broken link to CommandLine.java source code. Thanks to Simon Legner for the pull request.
• [#563] Doc: Improve documentation for explicitly showing usage help from subcommands. Thanks to Steve Johnson for raising this issue.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This is a patch release and has no breaking changes.

Picocli 3.8.0

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.

Picocli 3.7.0

Picocli 3.7.0

The picocli community is pleased to announce picocli 3.7.0.

This release contains bugfixes and enhancements in the main picocli module, and adds two new modules:
picocli-codegen and picocli-shell-jline2.

Picocli Code Generation (picocli-codegen) contains tools for generating source code, documentation and configuration files
for picocli-based applications.

Picocli Shell JLine2 (picocli-shell-jline2) contains components and documentation for building
interactive shell command line applications with JLine 2 and picocli.

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

This is the forty-first public release.
Picocli follows semantic versioning.

Table of Contents

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

New and Noteworthy

Improved Parsing of Quoted Values

This release improves parser behaviour of quoted arguments:

• Quotes around command line parameters are now preserved by default (previously they were removed). This can be configured with CommandLine::setTrimQuotes.
• When splitting parameters, quoted strings are no longer split. This can be configured with CommandLine::setSplitQuotedStrings.

Example:

@Option(names = "-x", split = ",")
String[] parts;

Given input like below:

<command> -x a,b,"c,d,e",f,"xxx,yyy"

This results in the parts array having the following values:

a
b
"c,d,e"
f
"xxx,yyy"

New Module picocli-codegen

Picocli Code Generation contains tools for generating source code, documentation and configuration files
for picocli-based applications.

This release contains the ReflectionConfigGenerator class.
ReflectionConfigGenerator generates a JSON String with the program elements that will be accessed reflectively in a picocli-based application, in order to compile this application ahead-of-time into a native executable with GraalVM.

The output of ReflectionConfigGenerator is intended to be passed to the -H:ReflectionConfigurationFiles=/path/to/reflectconfig option of the native-image GraalVM utility. This allows picocli-based applications to be compiled to a native image.

See Picocli on GraalVM: Blazingly Fast Command Line Apps for details.

The module's README explains how to configure your build to generate the configuration file automatically as part of your build.

New Module picocli-shell-jline2

Picocli Shell JLine2 contains components and documentation for building
interactive shell command line applications with JLine 2 and picocli.

This release contains the PicocliJLineCompleter class.
PicocliJLineCompleter is a small component that generates completion candidates to allow users to
get command line TAB auto-completion for a picocli-based application running in a JLine 2 shell.

See the module's README for more details.

Fixed issues

• [#503] Build: Upgrade to gradle 4.10.2.
• [#497] add module picocli-shell-jline2 for components and documentation for building interactive shell command line applications with JLine 2 and picocli.
• [#499] add module picocli-codegen for tools to generate documentation, configuration, source code and other files from a picocli model
• [#410] add ReflectionConfigGenerator class for GraalVM native-image
• [#513] Enhancement: Simplify AutoCompletion script generator code.
• [#481] Enhancement: Add @Command(usageHelpWidth = <int>) annotation attribute.
• [#379] Option with split property should not split quoted strings. Thanks to Markus Kramer for the feature request.
• [#514] Bugfix/Enhancement: picocli no longer removes opening and closing quotes around arguments by default. This is configurable with CommandLine::setTrimQuotes. Thanks to mshatalov for the bug report.
• [#509] Bugfix: Long boolean options with arity 0 should not allow parameters. Thanks to Adam Zegelin for the bug report.
• [#510] Documentation: Fix broken link for moved example files. Thanks to Anthony Keenan for the pull request.
• [#24] Documentation: Added Chinese translations of "Picocli 2.0 Do More With Less" and "Picocli 2.0 Groovy Scripts on Steroids".

Deprecations

No features were deprecated in this release.

Potential breaking changes

From this release, picocli no longer removes opening and closing quotes around arguments by default.
This is configurable with CommandLine::setTrimQuotes.

Picocli 3.6.1

Picocli 3.6.1

The picocli community is pleased to announce picocli 3.6.1.

This release contains bugfixes, minor enhancements and documentation improvements.

ANSI is automatically enabled on Windows if Jansi's AnsiConsole has been installed.

It is now possible to selectively avoid loading type converters with reflection.

Bugfix: Enum values were not rendered in ${COMPLETION-CANDIDATES} for collection type options.

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

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

Table of Contents

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

New and Noteworthy

Fixed issues

• [#487] Enhancement: Auto-completion script should return from generateOptionsSwitch immediately if there is nothing to generate. Thanks to David Walluck for the pull request.
• [#483][#486] Enhancement: Improve Help.Ansi.AUTO: automatically enable ANSI on Windows if Jansi's AnsiConsole has been installed. Thanks to Philippe Charles for the pull request.
• [#491] Enhancement: Improve Help.Ansi.AUTO cygwin/msys detection on Windows.
• [#451] Enhancement: Selectively disable reflective type converter registration. Thanks to Paolo Di Tommaso for the suggestion.
• [#488] Doc: Clarify in user manual that CommandLine.setPosixClusteredShortOptionsAllowed(false) means that option parameters cannot be attached to the option name. Thanks to Maryam Ziyad for raising this.
• [#492][#493] Doc: Add section on @Command(aliases) attribute to user manual. Thanks to marinier for the pull request.
• [#494] Bugfix: Enum values were not rendered in ${COMPLETION-CANDIDATES} for collection type options.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This release has no breaking changes.

Picocli 3.6.0

Picocli 3.6.0

The picocli community is pleased to announce picocli 3.6.0.

This release contains new features, bugfixes and enhancements.

New interface: IDefaultProvider allows you to get default values from a configuration file or some other central place.

@Command Methods: From this release, methods can be annotated with @Command. The method parameters provide the command options and parameters.

Internationalization: from this release, usage help message sections and the description for options and positional parameters can be specified in a resource bundle. A resource bundle can be set via annotations and programmatically.

The error message on invalid user input has been improved.

This release also contains various improvements the the bash/zsh completion script generation to be more consistent with standard completion on these shells.

Many thanks to the many members of the picocli community who raised issues and contributed solutions!

This is the thirty-nineth public release.
Picocli follows semantic versioning.

Table of Contents

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

New and Noteworthy

Default Provider

This release allows you to specify a default provider in the @Command annotation:

@Command(defaultValueProvider = MyDefaultProvider.class)
class MyCommand // ...

The default provider allows you to get default values from a configuration file or some other central place.
Default providers need to implement the picocli.CommandLine.IDefaultValueProvider interface:

public interface IDefaultValueProvider {

    /**
     * Returns the default value for an option or positional parameter or {@code null}.
     * The returned value is converted to the type of the option/positional parameter
     * via the same type converter used when populating this option/positional
     * parameter from a command line argument.
     *
     * @param argSpec the option or positional parameter, never {@code null}
     * @return the default value for the option or positional parameter, or {@code null} if
     *       this provider has no default value for the specified option or positional parameter
     * @throws Exception when there was a problem obtaining the default value
     */
    String defaultValue(ArgSpec argSpec) throws Exception;
}

@Command Methods

From picocli 3.6, methods can be annotated with @Command. The method parameters provide the command options and parameters. For example:

class Cat {
    public static void main(String[] args) {
        CommandLine.invoke("cat", Cat.class, args);
    }

    @Command(description = "Concatenate FILE(s) to standard output.",
             mixinStandardHelpOptions = true, version = "3.6.0")
    void cat(@Option(names = {"-E", "--show-ends"}) boolean showEnds,
             @Option(names = {"-n", "--number"}) boolean number,
             @Option(names = {"-T", "--show-tabs"}) boolean showTabs,
             @Option(names = {"-v", "--show-nonprinting"}) boolean showNonPrinting,
             @Parameters(paramLabel = "FILE") File[] files) {
        // process files
    }
}

The usage help of the above command looks like this:

Usage: cat [-EhnTvV] [FILE...]
Concatenate FILE(s) to standard output.
      [FILE...]
  -E, --show-ends
  -h, --help               Show this help message and exit.
  -n, --number
  -T, --show-tabs
  -v, --show-nonprinting
  -V, --version            Print version information and exit.

See below for an example that uses a resource bundle to define usage help descriptions outside the code.

For positional parameters, the @Parameters annotation may be omitted on method parameters.

TIP: If compiled with the -parameters flag on Java 8 or higher, the paramLabel of positional parameters is obtained from the method parameter name using reflection instead of the generic arg0, arg1, etc.

Subcommand Methods

If the enclosing class is annotated with @Command, method commands are added as subcommands to the class command, unless the class command has attribute @Command(addMethodSubcommands = false).
For example:

@Command(name = "git", mixinStandardHelpOptions = true, version = "picocli-3.6.0")
class Git {
    @Option(names = "--git-dir", descriptionKey = "GITDIR")
    Path path;

    @Command
    void commit(@Option(names = {"-m", "--message"}) String commitMessage,
                @Option(names = "--squash", paramLabel = "<commit>") String squash,
                @Parameters(paramLabel = "<file>") File[] files) {
        // ... implement business logic
    }
}

Use @Command(addMethodSubcommands = false) on the class @Command annotation if the @Command-annotated methods in this class should not be added as subcommands.

The usage help of the git commit command looks like this:

Usage: git commit [--squash=<commit>] [-m=<arg0>] [<file>...]
      [<file>...]
      --squash=<commit>
  -m, --message=<arg0>

Internationalization

From version 3.6, usage help message sections and the description for options and positional parameters can be specified in a resource bundle. A resource bundle can be set via annotations and programmatically.

Annotation example:

@Command(name = "i18n-demo", resourceBundle = "my.org.I18nDemo_Messages")
class I18nDemo {}

Programmatic example:

@Command class I18nDemo2 {}

CommandLine cmd = new CommandLine(new I18nDemo2());
cmd.setResourceBundle(ResourceBundle.getBundle("my.org.I18nDemo2_Messages"));

Resources for multiple commands can be specified in a single ResourceBundle. Keys and their value can be shared by multiple commands (so you don't need to repeat them for every command), but keys can be prefixed with fully qualified command name + "." to specify different values for different commands. The most specific key wins.

This is especially convenient for @Command methods where long description annotations would make the code less easy to read.

You can use a resource bundle to move the descriptions out of the code:

# shared between all commands
help = Show this help message and exit.
version = Print version information and exit.

# command-specific strings
git.usage.description = Version control system
git.GITDIR = Set the path to the repository

git.commit.usage.description = Record changes to the repository
git.commit.message = Use the given <msg> as the commit message.
git.commit.squash = Construct a commit message for use with rebase --autosquash.
git.commit.<file>[0..*] = The files to commit.

With this resource bundle, the usage help for the above git commit command looks like this:

Usage: git commit [--squash=<commit>] [-m=<arg0>] [<file>...]
Record changes to the repository
      [<file>...]         The files to commit.
      --squash=<commit>   Construct a commit message for use with rebase
                            --autosquash.
  -m, --message=<arg0>    Use the given <msg> as the commit message.

Improved Error Messages

The error messages on invalid input have been improved. For example:

Previously, if an argument could not be converted to a primitive type, the error looked like this:

Could not convert 'abc' to int for option '-num': java.lang.NumberFormatException: For input string: \"abc\"

The new error message for primitive types looks like this:

Invalid value for option '-num': 'abc' is not an int

Previously, if an argument could not be converted to an enum, the error looked like this:

Could not convert 'xyz' to TimeUnit for option '-timeUnit': java.lang.IllegalArgumentException: No enum constant java.util.concurrent.TimeUnit.xyz

The new error message for enums looks like this:

Invalid value for option '-timeUnit': expected one of [NANOSECONDS, MILLISECONDS, MICROSECONDS, SECONDS, MINUTES, HOURS, DAYS] but was 'xyz'

Fixed issues

• [#321] API: Add support for IDefaultValueProvider. Thanks to Nicolas MASSART for the pull request.
• [#416] API: Added support for @Command annotation on methods (in addition to classes). Thanks to illes for the pull request.
• [#433] API: Added method printHelpIfRequested that accepts a ColorScheme parameter. Thanks to Benny Bottema for the suggestion.
• [#441] API: Added hideParamSyntax attribute to @Option and @Parameters to allow suppressing usage syntax decorations around the param label. Thanks to Benny Bottema for the pull request.
• [#22], [#415], [#436] API: Added internationalization and localization support via resource bundles.
• [#473] Enhancement: Improved error messages for invalid input.
• [#461] Bugfix: Script auto-completion only suggests options and never default bash completions. Thanks to David Walluck for the pull request.
• [#466] Bugfix: Script auto-completion should not generate suggestions for options with arguments that have no known completions. Thanks to David Walluck for the pull request.
• [#470] Bugfix: Script auto-completion should generate suggestions for short options with arguments. Thanks to David Walluck for the pull request.
• [#444] Bugfix: Usage help shows duplicate aliases if registered with same alias multiple times.
• [#452] Doc: Add UML class diagrams to picocli Javadoc.
• [#475] Doc: Renamed module examples to picocli-examples.
• [#478] Doc: Add convenience API example to ...

Picocli 3.5.2

Picocli 3.5.2

The picocli community is pleased to announce picocli 3.5.2.

This is a bugfix release that fixes an issue where subcommand aliases were not recognized in some cases.

This is the thirty-eighth public release.
Picocli follows semantic versioning.

Table of Contents

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

New and Noteworthy

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

• [#443] Bugfix: Subcommand aliases were not recognized in some cases. Thanks to K. Alex Mills for the bug report.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This release has no breaking changes.

Picocli 3.5.1

Picocli 3.5.1

The picocli community is pleased to announce picocli 3.5.1.

This is a bugfix release that fixes an issue where CommandSpec injected into Mixins had a null CommandLine.

This is the thirty-seventh public release.
Picocli follows semantic versioning.

Table of Contents

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

New and Noteworthy

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

• [#439] Bugfix: CommandSpec injected into Mixins had a null CommandLine. Thanks to Adam Zegelin for the bug report.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This release has no breaking changes.

Picocli 3.5.0

Picocli 3.5.0

The picocli community is pleased to announce picocli 3.5.0.

This release contains new features, bugfixes and enhancements.

Password support: for options and positional parameters marked as interactive, the user is prompted to enter a value on the console. When running on Java 6 or higher, picocli will use the Console.readPassword API so that user input is not echoed to the console.

Client code can now perform simple validation in annotated setter methods by throwing a ParameterException on invalid input.

Also, from this release, the comment character in @-files (argument files) and the end-of-options delimiter (-- by default) are configurable.

This is the thirty-sixth public release.
Picocli follows semantic versioning.

Table of Contents

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

New and Noteworthy

Interactive Options for Passwords or Passphrases

This release introduces password support: for options and positional parameters marked as interactive, the user is prompted to enter a value on the console. When running on Java 6 or higher, picocli will use the Console.readPassword API so that user input is not echoed to the console.

Example usage:

class Login implements Callable<Object> {
    @Option(names = {"-u", "--user"}, description = "User name")
    String user;

    @Option(names = {"-p", "--password"}, description = "Passphrase", interactive = true)
    String password;

    public Object call() throws Exception {
        MessageDigest md = MessageDigest.getInstance("SHA-256");
        md.update(password.getBytes());
        System.out.printf("Hi %s, your passphrase is hashed to %s.%n", user, base64(md.digest()));
        return null;
    }
    
    private String base64(byte[] arr) { /* ... */ }
}

When this command is invoked like this:

CommandLine.call(new Login(), "-u", "user123", "-p");

Then the user will be prompted to enter a value:

Enter value for --password (Passphrase): 

When running on Java 6 or higher, the user input is not echoed to the console.
After the user enters a value and presses enter, the call() method is invoked, which prints the following:

Hi user123, your passphrase is hashed to 75K3eLr+dx6JJFuJ7LwIpEpOFmwGZZkRiB84PURz6U8=.

Simple Validation in Setter Methods

Methods annotated with @Option and @Parameters can do simple input validation by throwing a ParameterException when invalid values are specified on the command line.

class ValidationExample {
    @Spec private CommandSpec spec; // injected by picocli
    
    private Map<String, String> properties = new LinkedHashMap<>();
    
    @Option(names = {"-D", "--property"}, paramLabel = "KEY=VALUE")
    public void setProperty(Map<String, String> map) {
        for (String key : map.keySet()) {
            String newValue = map.get(key);
            validateUnique(key, newValue);
            properties.put(key, newValue);
        }
    }

    private void validateUnique(String key, String newValue) {
        String existing = properties.get(key);
        if (existing != null && !existing.equals(newValue)) {
            throw new ParameterException(spec.commandLine(),
                    String.format("Duplicate key '%s' for values '%s' and '%s'.",
                    key, existing, newValue));
        }
    }
}

Prior to this release, the exception thrown from the method was wrapped in a java.lang.reflect.InvocationTargetException, which in turn was wrapped in a PicocliException, and finally in another ParameterException.

By following the recipe above and throwing a ParameterException on invalid input, all these intermediate exceptions are skipped.

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

• [#430] Bugfix: formatting was incorrect (did not break on embedded newlines) in the subcommands list descriptions. Thanks to Benny Bottema for the bug report.
• [#431] Better support for validation in setter methods: cleaner stack trace.
• [#432] Make comment character in @-files (argument files) configurable.
• [#359] Make end-of-options delimiter configurable.
• [#82] Support reading passwords from the console with echoing disabled.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This release has no breaking changes.