21 Dec 22:35

remkop

1337071

Picocli 4.1.3

The picocli community is pleased to announce picocli 4.1.3.

This release contains a bugfix for GraalVM users.

This release fixes a bug in the picocli-codegen annotation processor that generates an incorrect reflect-config.json file with duplicate entries for inner classes of a command, one with the standard class name and one with the canonical class name. This makes the GraalVM native-image generator fail with an error like "Class Outer.Inner not found".

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

New and noteworthy
Fixed issues
Deprecations
Potential breaking changes

New and Noteworthy

Fixed issues

[#901] Bugfix: picocli-codegen generated invalid reflect-config.json for inner classes.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This release has no breaking changes.

Assets 9

08 Dec 08:08

remkop

v4.1.2

8a92085

Picocli 4.1.2

The picocli community is pleased to announce picocli 4.1.2.

This release contains bugfixes, improvements, and documentation enhancements.

This version of picocli requires JLine 3.13.2 or higher and adds a PicocliCommands class that provides command descriptions that can be displayed in the terminal status bar via the new JLine TailTipWidgets functionality.

The built-in picocli.AutoComplete.GenerateCompletion (generate-completion) subcommand now omits validation of mandatory options in the parent command.

"Hidden" subcommands and options are no longer shown as suggestions in unmatched argument usage help or autocompletion scripts.

From picocli 4.1.2, all options in an exclusive group are automatically considered required, even if they are not marked as required = true in the annotations. Applications using older versions of picocli should mark all options in exclusive groups as required.

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

Thanks to the Community

Special thanks to mattirn and to Andreas Deininger for the pull requests and feedback!

New and noteworthy
Fixed issues
Deprecations
Potential breaking changes

New and Noteworthy

JLine3

JLine has had some interesting improvements in its 3.12 release.

See the picocli-shell-jline3 README for details.

Completion

The built-in picocli.AutoComplete.GenerateCompletion (generate-completion) subcommand now omits validation of mandatory options in the parent command.

Also, "hidden" subcommands and options are no longer shown as suggestions in unmatched argument usage help or autocompletion scripts.

Fixed issues

[#888] (API) Added new PicocliCommands class to picocli-shell-jline3 module; bumped JLine to 3.13.2. Thanks to mattirn for the pull request.
[#884] (Bugfix) Built-in picocli.AutoComplete.GenerateCompletion (generate-completion) subcommand now omits validation of mandatory options in the parent command. Thanks to Andreas Deininger for raising this.
[#887] (Bugfix) "Hidden" subcommands and options are no longer shown as suggestions in unmatched argument usage help or autocompletion scripts. Thanks to Andreas Deininger for raising this.
[#871] (Bugfix) All options in an exclusive group are now automatically considered required, to prevent unexpected results when mixing required and non-required options in exclusive ArgGroups. Thanks to W Scott Johnson for raising this.
[#883] (DOC) Update of Quick Guide. Thanks to Andreas Deininger for the pull request.
[#889][#885] (DOC) Update of Picocli Programmatic API documentation. Thanks to Andreas Deininger for the pull request.
[#891] (DOC) Fixed broken links in README. Thanks to Andreas Deininger for the pull request.
[#892] (DOC) Minor improvements to example app in picocli-shell-jline3.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This release has no breaking changes.

Assets 9

26 Nov 15:39

remkop

v4.1.1

f914fdb

Picocli 4.1.1

The picocli community is pleased to announce picocli 4.1.1.

This release contains bugfixes, and documentation enhancements.

The new picocli.AutoComplete.GenerateCompletion reusable subcommand did not flush the generated script to the System.out stream, making it unusable. This has been fixed.

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

Thanks to the Community

Special thanks to Andreas Deininger for the many pull requests and feedback!

New and noteworthy
Fixed issues
Deprecations
Potential breaking changes

New and Noteworthy

Fixed issues

[#880] (Bugfix) Built-in picocli.AutoComplete.GenerateCompletion (generate-completion) subcommand does not flush, resulting in no output. Thanks to Andreas Deininger for raising this.
[#875] (DOC) Fix broken internal links in RELEASE-NOTES for 4.1. Thanks to Andreas Deininger for raising this.
[#881] (DOC) Update of Quick Guide to the latest execute API. Thanks to Andreas Deininger for the pull request.
[#874] (DOC) Fix Javadoc issues. Thanks to Andreas Deininger for the pull request.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This release has no breaking changes.

Assets 9

22 Nov 10:33

remkop

v4.1.0

6389c43

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.

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 esc...

Assets 9

08 Sep 23:06

remkop

v4.0.4

aaa1eeb

Picocli 4.0.4

The picocli community is pleased to announce picocli 4.0.4.

This release contains a bugfixes and enhancements.

GraalVM native image-configuration generation for options or positional parameters with custom type converters or custom parameter consumers now work correctly.

Also fixed a bug where validation was performed on ArgGroups even when they were marked as validate = false.

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

New and noteworthy
Fixed issues
Deprecations
Potential breaking changes

New and Noteworthy

Fixed issues

[#803] (Bugfix) Custom IParameterConsumer caused native-image to fail. Thanks to Patrick Plenefisch for raising this.
[#804][#806] (Bugfix) Visit Parameter Consumers when doing GraalVM reflection generation; added test. Thanks to Patrick Plenefisch for the pull requests.
[#808] (Bugfix) Option-specific ITypeConverter class is now correctly included in generated reflect-config.json.
[#807] (Bugfix) ArgGroup should not validate when marked as validate = false. Thanks to cranphin for the bug report.
[#799] (DOC) Update adoption section in README.
[#805] (DOC) Add example for alphabetically sorting subcommands by subclassing Help. Thanks to frontfact for raising this issue.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This release has no breaking changes.

Assets 9

26 Aug 15:34

remkop

v4.0.3

a979f98

Picocli 4.0.3

The picocli community is pleased to announce picocli 4.0.3.

This release contains a bugfixes and enhancements.

GraalVM native image-configuration generation for picocli commands with argument groups now work correctly.

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

New and noteworthy
Fixed issues
Deprecations
Potential breaking changes

New and Noteworthy

Fixed issues

[#794] (Bugfix) Perform topological sort on ArgGroups in annotation processor before wiring up the model to prevent FATAL ERROR in annotation processor: picocli.CommandLine$InitializationException: ArgGroup has no options or positional parameters, and no subgroups.
[#793] (Bugfix) Argument groups disappear in GraalVM native-image (the generated reflect-config.json was missing the @ArgGroup-annotated fields). Thanks to Mike Hearn for the bug report.
[#787] (Enhancement) Throw InitializationException instead of StackOverflowError when subcommand is subclass of itself. Thanks to Peter Murray-Rust for raising this.
[#784] (DOC) Update documentation to show custom IFactory implementations should fall back to the default factory to enable the creation of collections for @Option-annotated methods and fields.
[#788] (DOC) Add link to GitHub examples in user manual Mixins section. Thanks to Peter Murray-Rust for the suggestion.
[#789] (DOC) Add example usage help to the user manual Negatable Options section.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This release has no breaking changes.

Assets 9

12 Aug 02:42

remkop

v4.0.2

7a9bb55

Picocli 4.0.2

The picocli community is pleased to announce picocli 4.0.2.

This release contains a bugfixes and enhancements.

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

New and noteworthy
Fixed issues
Deprecations
Potential breaking changes

New and Noteworthy

Fixed issues

[#781] Bugfix: Standard help mixin options not added in source order when running on Java 12+.
[#773] Bugfix: Add public NativeImageConfigGeneratorProcessor constructor to fix build error in IntelliJ IDEA 2019.2. Thanks to Lukáš Petrovický for raising this issue.
[#779] Bugfix: DuplicateOptionAnnotationsException when a nested group is defined inside a mixin. Thanks to Matteo Melli for the bug report.
[#777] Bugfix: Codegen failed when command contains field with argGroup annotation. Thanks to eomeara for the bug report.
[#776] Bugfix: Argument groups in mixins were ignored. Thanks to Matteo Melli for the bug report.
[#780] (DOC) Fixed the provided flag usage in the picocli-codegen readme. Thanks to Lasantha Kularatne for the pull request.
[#778] (DOC) Improve documentation for argument group sections in the help. Thanks to Matteo Melli for raising this.
[#774] (DOC) Add example demonstrating how to left-align long options in the usage help.
[#766] (DOC) Update user manual: mention the dependency required for using PicocliSpringFactory. Thanks to rome-legacy for the suggestion.
[#775] (DOC) Document jline2 incompatibility with picocli's interactive options for passwords, and update the example to show a workaround. Thanks to querqueq for the pull request.
[#770][#771] (DOC) Improve example code in picocli-spring-boot-starter README. Thanks to Stéphane Nicoll for the pull requests.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This release has no breaking changes.

Assets 9

19 Jul 13:17

remkop

v4.0.1

350bbfb

Picocli 4.0.1

The picocli community is pleased to announce picocli 4.0.1.

This release contains a fix for a bug in the annotation processor that caused a compilation error when a subcommand contains a @Mixin-annotated field or method.

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

New and noteworthy
Fixed issues
Deprecations
Potential breaking changes

New and Noteworthy

Fixed issues

[#769] Annotation processor fails on subcommands with mixins. Thanks to MortronMeymo for the bug report.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This release has no breaking changes.

Assets 9

17 Jul 04:20

remkop

v4.0.0

9ffd9c4

Picocli 4.0.0

Picocli 4.0.0 GA

The picocli community is pleased to announce picocli 4.0. This is a big release.

First, the picocli-codegen module now includes an annotation processor that instantly enables your JAR for GraalVM native images. It also gives compile-time errors for invalid annotations and attributes. We recommend that all projects using picocli enable this annotation processor.

The execute API is an easy way to execute your command with almost no code. It allows for more flexible configuration than previous APIs, and introduces much improved exit code support. This replaces the static methods call and run, as well as the parseWithHandlers methods, which are now deprecated.

Improved Spring support: the new picocli-spring-boot-starter module includes a PicocliSpringFactory and auto-configuration to use Spring dependency injection in your picocli command line application. This is especially useful if your application contains subcommands.

The parser has been enhanced to handle argument groups: mutually exclusive options, mutually dependent options, and option sections in the usage help. What makes the picocli design unique and extremely powerful is that argument groups can be nested, so applications can define repeating composite groups of mutually exclusive or co-dependent options.

Annotation attributes can now contain variables that can be resolved as system properties, environment variables and resource bundle keys.

The picocli JAR is now an explicit JPMS module, as well as an OSGi bundle. As part of this change, the Groovy support classes and annotations have been moved to a separate picocli-groovy artifact.

Boolean options can now easily be made negatable, which adds a "no-" version of the option. This is a common feature in command line parser libraries for Perl, PHP, Ruby, Lisp, Dart and Go, but we are not aware of any other Java libraries that support this.

All in all, this release contains 96 bugfixes and improvements over picocli 3.9.6.

Many thanks to the following community contributors to this release of picocli:

AkosCz, AlcaYezz, Andreas Deininger, andrewbleonard, Arturo Alonso, Bob Tiernay, Devin Smith, feinstein, Garret Wilson, Gerard Bosch, gitfineon, jrevault, Judd Gaddie, Liam Esteban Prince, marinier, Michael D. Adams, Mikaël Barbero, Mikusch, Nicolas Mingo, Paolo Di Tommaso, Philipp Hanslovsky, Radu Cotescu, Reinhard Pointner, Sebastian Thomschke, Shane Rowatt, shanetreacy, Steffen Rehberg, Sualeh Fatehi, Takuya Ishibashi, Thibaud Lepretre and Warkdev.

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

New and noteworthy
- Annotation processor
- Execution API
- Spring Boot support
- Argument groups
- Variable interpolation in annotation attributes
- Explicit JPMS module and OSGi bundle
- New Groovy module
- Negatable options
- Fallback value for options
- Custom parameter processing
- Improved parsing of quoted parameters
- Auto-detect terminal width for usage help
- Improved support for Chinese, Japanese and Korean usage help
Fixed issues
Deprecations
- run, call, invoke, and parseWithHandlers methods replaced by execute
- CommandLine.setSplitQuotedStrings deprecated
- parse deprecated in favor of parseArgs
- Range public fields
Potential breaking changes
- picocli.groovy classes moved to separate artifact
- Split regex on single-value options is now disallowed
- ColorScheme is now immutable
- Boolean options no longer toggle by default
- ParseResult matchedOptions now returns full list
- Error message for unmatched arguments changed
- Option order changed
- Factory

New and Noteworthy

Annotation processor

The picocli-codegen module now includes an annotation processor that instantly enables your JAR for GraalVM native images. The annotation processor can build a model from the picocli annotations at compile time rather than at runtime.

Use this if you’re interested in:

Compile time error checking. The annotation processor shows errors for invalid annotations and attributes immediately when you compile, instead of during testing at runtime, resulting in shorter feedback cycles.
Graal native images. The annotation processor generates and updates Graal configuration files under
META-INF/native-image/picocli-generated/$project during compilation, to be included in the application jar.
This includes configuration files for reflection, resources and dynamic proxies.
By embedding these configuration files, your jar is instantly Graal-enabled.
The $project location is configurable, see processor options below.
In most cases no further configuration is needed when generating a native image.

Processor option: `project`

The picocli annotation processor supports a number of options, most important of which is the project option to control the output subdirectory: the generated files are written to META-INF/native-image/picocli-generated/${project}. A good convention is to use the Maven ${groupId}/${artifactId} as the value; a unique subdirectory ensures your jar can be shaded with other jars that may also contain generated configuration files.

To configure this option, pass the -Aproject=<some value> to the javac compiler. The examples below show how to do this for Maven and Gradle.

Enabling the Annotation Processor

Since Java 6, annotation processing is part of the standard javac compiler, but many IDEs and build tools require something extra to enable annotation processing.

IDE

This page shows the steps to configure Eclipse and IntelliJ IDEA to enable annotation processing.

Maven

In Maven, use annotationProcessorPaths in the configuration of the maven-compiler-plugin. This requires maven-compiler-plugin plugin version 3.5 or higher.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <!-- annotationProcessorPaths requires maven-compiler-plugin version 3.5 or higher -->
  <version>${maven-compiler-plugin-version}</version>
  <configuration>
    <annotationProcessorPaths>
      <path>
        <groupId>info.picocli</groupId>
        <artifactId>picocli-codegen</artifactId>
        <version>4.0.0</version>
      </path>
    </annotationProcessorPaths>
    <compilerArgs>
      <arg>-Aproject=${groupId}/${artifactId}</arg>
    </compilerArgs>
  </configuration>
</plugin>

See the picocli-codegen README for more details.

Gradle

Use the annotationProcessor path in Gradle 4.6 and higher:

dependencies {
    compile 'info.picocli:picocli:4.0.0'
    annotationProcessor 'info.picocli:picocli-codegen:4.0.0'
}

To set an annotation processor option in Gradle, add these options to the options.compilerArgs list in the compileJava block.

compileJava {
    options.compilerArgs += ["-Aproject=${project.group}/${project.name}"]
}

See the [picocli-codegen README](https://github.com/remkop/picocli/tree/master/picoc...

Assets 9

19 Jun 16:18

remkop

v4.0.0-beta-2

9f29386

Picocli 4.0.0-beta-2

The picocli community is pleased to announce picocli 4.0.0-beta-2.

Bugfixes and improvements.

This release introduces two new attributes on the Option annotation:

fallbackValue
parameterConsumer

fallbackValue is for options with optional parameter: assign this value when the option was specified on the command line without parameter. parameterConsumer and the associated IParameterConsumer interface allows for options to bypass picocli's parsing logic and replace it with custom logic. One use case is collecting arguments to pass them through to another command.

This release introduces a new synopsisSubcommandLabel attribute on the @Command annotation to allow customization of the subcommands part of the synopsis. This is useful for applications that have required subcommands.

Also, this release adds the ability to dynamically detect the terminal width.

From this release, the picocli JAR is an OSGi bundle with Bundle-Name: picocli and other appropriate metadata in the manifest.

Please try this and provide feedback. We can still make changes.

What do you think of the @ArgGroup annotations API? What about the programmatic API? Does it work as expected? Are the input validation error messages correct and clear? Is the documentation clear and complete? Anything you want to change or improve? Any other feedback?

Many thanks to the picocli community for the contributions!

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

New and noteworthy
Fixed issues
Deprecations
Potential breaking changes

New and Noteworthy

Fallback Value API

This release introduces a new attribute on the Option annotation: fallbackValue for options with optional parameter: assign this value when the option was specified on the command line without parameter.

This is different from the defaultValue, which is assigned if the option is not specified at all on the command line.

Using a fallbackValue allows applications to distinguish between cases where

the option was not specified on the command line (default value assigned)
the option was specified without parameter on the command line (fallback value assigned)
the option was specified with parameter on the command line (command line argument value assigned)

This is useful to define options that can function as a boolean "switch" and optionally allow users to provide a (strongly typed) extra parameter value.

The option description may contain the ${FALLBACK-VALUE} variable which will be replaced with the actual fallback value when the usage help is shown.

Synopsis Subcommand Label

For commands with subcommands, the string [COMMAND] is appended to the end of the synopsis (whether the synopsis is abbreviated or not). This looks something like this:

<cmd> [OPTIONS] FILES [COMMAND]

From picocli 4.0, this can be customized with the synopsisSubcommandLabel attribute.

For example, to clarify that a subcommand is mandatory, an application may specify COMMAND, without the [ and ] brackets:

@Command(name = "git", synopsisSubcommandLabel = "COMMAND")
class Git implements Runnable {
    @Spec CommandSpec spec;
    public void run() {
        throw new ParameterException(spec.commandLine(), "Missing required subcommand");
    }
}

An application with a limited number of subcommands may want to show them all in the synopsis, for example:

@Command(name = "fs", synopsisSubcommandLabel = "(list | add | delete)",
         subcommands = {List.class, Add.class, Delete.class})
class Fs { ... }

Dynamically Detect Terminal Size

From this release, commands defined with @Command(usageHelpAutoWidth = true) will try to adjust the usage message help layout to the terminal width.
There is also programmatic API to control this via the CommandLine::setUsageHelpAutoWidth and UsageMessageSpec::autoWidth methods.

End users may enable this by setting system property picocli.usage.width to AUTO, and may disable this by setting this system property to a numeric value.

This feature requires Java 7.

Custom Parameter Processing

Options or positional parameters can be assigned a IParameterConsumer that implements custom logic to process the parameters for this option or this position. When an option or positional parameter with a custom IParameterConsumer is matched on the command line, picocli's internal parser is temporarily suspended, and the custom parameter consumer becomes responsible for consuming and processing as many command line arguments as needed.

This can be useful when passing options through to another command.

For example, the unix find command has a -exec option to execute some action for each file found. Any arguments following the -exec option until a ; or + argument are not options for the find command itself, but are interpreted as a separate command and its options.

The example below demonstrates how to implement find -exec using this API:

@Command(name = "find")
class Find {
    @Option(names = "-exec", parameterConsumer = ExecParameterConsumer.class)
    List<String> list = new ArrayList<String>();
}

class ExecParameterConsumer implements IParameterConsumer {
    public void consumeParameters(Stack<String> args, ArgSpec argSpec, CommandSpec commandSpec) {
        List<String> list = argSpec.getValue();
        while (!args.isEmpty()) {
            String arg = args.pop();
            list.add(arg);

            // `find -exec` semantics: stop processing after a ';' or '+' argument
            if (";".equals(arg) || "+".equals(arg)) {
                break;
            }
        }
    }
}

Fixed issues

[#280] API: @Option(fallbackValue = "...") for options with optional parameter: assign this value when the option was specified on the command line without parameter. Thanks to Paolo Di Tommaso and marinier for the suggestion and in-depth discussion.
[#625] API: @Command(synopsisSubcommandLabel = "...") to allow customization of the subcommands part of the synopsis: by default this is [COMMAND]. Thanks to Sebastian Thomschke and AlcaYezz for the feature request and subsequent discussion.
[#718] API: Add IParameterConsumer and @Option(parameterConsumer = Xxx.class) for passing arguments through to another command, like find -exec. Thanks to Reinhard Pointner for the suggestion.
[#721] API: Add public method Text.getCJKAdjustedLength().
[#634] API: Dynamically detect terminal size. Requires Java 7. Thanks to my colleague Takuya Ishibashi for the suggestion.
[#737] Deprecate the parse method in favor of parseArgs.
[#717] Negatable options change: avoid unmappable character ± for synopsis: it renders as scrambled characters in encoding ASCII and in some terminals.
[#734][#735] Make the picocli jar OSGi friendly. Thanks to Radu Cotescu for the pull request.
[#733] Improve error message for unmatched arguments. Thanks to my colleague Takuya Ishibashi for raising this.
[#719] Bugfix: options with variable arity should stop consuming arguments on custom end-of-options delimiter.
[#720] Bugfix: @Unmatched list should be cleared prior to subsequent invocations.
[#723] Bugfix: variables in defaultValue were not expanded in usage help option description line for showDefaultValues = true. Thanks to Mikaël Barbero for raising this.
[#722] Bugfix: synopsis of deeply nested @ArgGroup shows @Options duplicate on outer level of command. Thanks to Shane Rowatt for raising this.
[#724] Bugfix: Usage message exceeds width.
[#731] Doc: Add Zero Bugs Commitment to README.

Deprecations

From this release, the parse method is deprecated in favor of parseArgs.

Potential breaking changes

The error message for unmatched arguments now shows the index in the command line arguments where the unmatched argument was found,
and shows the unmatched value in single quotes. This is useful when the unmatched value is whitespace or an empty String.

For example:

Previously:  Unmatched arguments: B, C
New       :  Unmatched arguments from index 1: 'B', 'C'

This may break tests that rely on the exact error message.

Assets 8

Releases: remkop/picocli

Picocli 4.1.3

Picocli 4.1.3

Table of Contents

New and Noteworthy

Fixed issues

Deprecations

Potential breaking changes

Picocli 4.1.2

Picocli 4.1.2

Thanks to the Community

Table of Contents

New and Noteworthy

JLine3

Completion

Fixed issues

Deprecations

Potential breaking changes

Picocli 4.1.1

Picocli 4.1.1

Thanks to the Community

Table of Contents

New and Noteworthy

Fixed issues

Deprecations

Potential breaking changes

Picocli 4.1.0

Picocli 4.1.0

Table of Contents

New and Noteworthy

PropertiesDefaultProvider

PropertiesDefaultProvider Format

Subcommands Default Values

AutoComplete.GenerateCompletion

Autocompletion script improvements

Help API improvements

ArgGroup improvements

Fixed issues

Picocli 4.0.4

Picocli 4.0.4

Table of Contents

New and Noteworthy

Fixed issues

Deprecations

Potential breaking changes

Picocli 4.0.3

Picocli 4.0.3

Table of Contents

New and Noteworthy

Fixed issues

Deprecations

Potential breaking changes

Picocli 4.0.2

Picocli 4.0.2

Table of Contents

New and Noteworthy

Fixed issues

Deprecations

Potential breaking changes

Picocli 4.0.1

Picocli 4.0.1

Table of Contents

New and Noteworthy

Fixed issues

Deprecations

Potential breaking changes

Picocli 4.0.0

Picocli 4.0.0 GA

Table of Contents

New and Noteworthy

Annotation processor

Processor option: project

Enabling the Annotation Processor

IDE

Maven

Gradle

Picocli 4.0.0-beta-2

Picocli 4.0.0-beta-2

Table of Contents

New and Noteworthy

Processor option: `project`