From a6a1844e456ef383ed20daea4f179a1b9f54b7a9 Mon Sep 17 00:00:00 2001 From: Remko Popma Date: Thu, 2 Dec 2021 07:44:19 +0900 Subject: [PATCH] [#1384][#1493][#1366][#1370][#1492][#1491][#1484][#1482][#1485][#1481][#1483][#1495][#1496][#1494][#1497][#1498][#1490][#1489][#1488][#1487][#1486][#1500] Update release notes --- RELEASE-NOTES.md | 423 +++++++++++++++++++++++++---------------------- 1 file changed, 222 insertions(+), 201 deletions(-) diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index 5c2311001..f08f833fb 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -19,6 +19,15 @@ Picocli follows [semantic versioning](http://semver.org/). ## Fixed issues +* [#1384][#1493] Bugfix: parser now correctly handles ArgGroups with optional positional parameters. Thanks to [Matthew Lewis](https://github.com/mattjlewis) for raising this and to [Kurt Kaiser](https://github.com/kurtkaiser) for the pull request. +* [#1366][#1370] Enhancement: show in usage help that the built-in `help` command only works on the first argument. Thanks to [Patrice Duroux](https://github.com/peutch) for the pull request. +* [#1492] Enhancement: Use EditorConfig to define file formats and coding style; Thanks to [Goooler](https://github.com/Goooler) for the pull request. +* [#1491] Build: Add build job in CI; Thanks to [Goooler](https://github.com/Goooler) for the pull request. +* [#1482] Build: Optimize gradle; Thanks to [Goooler](https://github.com/Goooler) for the pull request. +* [#1484] Enhancement: Fixed `org.junit.Assert.assertThat` deprecation warning; Thanks to [Ross Goldberg](https://github.com/rgoldberg) for the pull request. +* [#1485] Enhancement: Fix build warnings; build doc enhancements; Thanks to [Ross Goldberg](https://github.com/rgoldberg) for the pull request. +* [#1483] Enhancement: Improved `AbstractCommandSpecProcessor#isSubcommand`; Thanks to [Ross Goldberg](https://github.com/rgoldberg) for the pull request. +* [#1481] DOC: Removed repeated "whether" typo in JavaDoc; Thanks to [Ross Goldberg](https://github.com/rgoldberg) for the pull request. * [#1474] Bugfix: Avoid `UnsupportedCharsetException: cp65001` on Microsoft Windows console when code page is set to UTF-8. Thanks to [epuni](https://github.com/epuni) for raising this. * [#1466][#1467] Bugfix/Enhancement: Autocomplete now shows subcommand aliases in the completion candidates. Thanks to [Ruud Senden](https://github.com/rsenden) for the pull request. * [#1458][#1473] Enhancement: autocompletion now supports file names containing spaces. Thanks to [zpater345](https://github.com/zpater345) for raising this and thanks to [NewbieOrange](https://github.com/NewbieOrange) for the pull request. @@ -30,6 +39,18 @@ Picocli follows [semantic versioning](http://semver.org/). * [#1457] DOC: add caution about arguments in @files with quoted option parameters. Thanks to [Andreas Deininger](https://github.com/deining) for the pull request. * [#1461] BUILD: Allow publishing without signing for non-release versions. Thanks to [Andreas Deininger](https://github.com/deining) for raising this. * [#1459] BUILD: The nexus-staging Gradle plugin must be applied to the root project, not to subprojects. Thanks to [Andreas Deininger](https://github.com/deining) for raising this. +* [#1495] DEP: Bump validation-api from 2.0.0.Final to 2.0.1.Final +* [#1496] DEP: Bump biz.aQute.bnd.gradle from 5.1.2 to 6.1.0 +* [#1494] DEP: Bump kotlin-gradle-plugin from 1.5.31 to 1.6.0 +* [#1497] DEP: Bump badass-jar from 1.1.3 to 1.2.0 +* [#1498] DEP: Bump hibernate-validator from 6.1.2.Final to 7.0.1.Final +* [#1490] DEP: Bump hibernate-validator-annotation-processor from 6.1.2.Final to 7.0.1.Final +* [#1489] DEP: Bump log4j-core from 2.13.0 to 2.14.1 +* [#1488] DEP: Bump log4j-api from 2.13.0 to 2.14.1 +* [#1487] DEP: Bump kotlin-script-runtime from 1.5.31 to 1.6.0 +* [#1486] DEP: Bump gradle-nexus-staging-plugin from 0.21.0 to 0.30.0 +* [#1500] DEP: Bump gradle from 7.3 to 7.3.1. Thanks to [Ross Goldberg](https://github.com/rgoldberg) for the pull request. + ## Deprecations No features were deprecated in this release. @@ -476,7 +497,7 @@ class Edit { " edit --open FILE opens the specified file in the default editor" }) Editor editor = Editor.defaultEditor; - + static class MyPreprocessor implements IParameterPreprocessor { public boolean preprocess(Stack args, CommandSpec commandSpec, @@ -543,7 +564,7 @@ class Dynamic { * [#1254] API: Added `ArgSpec::root`: this method returns the original `ArgSpec` for inherited `ArgSpec` objects, and `null` for other `ArgSpec` objects. Thanks to [Daniel Gray](https://github.com/danielthegray) for the pull request. * [#1256] API: Added `CommandSpec::removeSubcommand` method. Thanks to [Marko Mackic](https://github.com/MarkoMackic) for raising this. * [#1258] API: Groovy programs can now use closures in the picocli annotations instead of specifying a class. Thanks to [Adrian A.](https://github.com/aadrian) for raising this. -* [#1267] API: Add `CommandLine::getFactory` accessor for the factory. Thanks to [Sualeh Fatehi](https://github.com/sualeh) for the suggestion. +* [#1267] API: Add `CommandLine::getFactory` accessor for the factory. Thanks to [Sualeh Fatehi](https://github.com/sualeh) for the suggestion. * [#1108] Enhancement: Support `Optional` type for options and positional parameters. Thanks to [Max Rydahl Andersen](https://github.com/maxandersen) for raising this. * [#1214] Enhancement: Support Map options with key-only (support `-Dkey` as well as `-Dkey=value`). Thanks to [Max Rydahl Andersen](https://github.com/maxandersen) and [David Walluck](https://github.com/dwalluck) for raising this and subsequent discussion. * [#1260] Enhancement: Support `@Spec`-annotated members in `ArgGroup` classes. Thanks to [Jannick Hemelhof](https://github.com/clone1612) for raising this. @@ -1137,14 +1158,14 @@ class App implements Runnable { @Option(names = "-x", scope = ScopeType.LOCAL) // option is not shared: this is the default int x; - + @Option(names = "-v", scope = ScopeType.INHERIT) // option is shared with subcommands, sub-subcommands, etc public void setVerbose(boolean verbose) { // Configure log4j. // This is a simplistic example: you probably only want to modify the ConsoleAppender level. Configurator.setRootLevel(verbose ? Level.DEBUG : Level.INFO); } - + public void run() { logger.debug("-x={}", x); } @@ -1156,7 +1177,7 @@ class Sub implements Runnable { @Option(names = "-y") int y; - + public void run() { logger.debug("-y={}", y); } @@ -1286,7 +1307,7 @@ Zaphod: 3.4 ``` ### `@Spec(MIXEE)` Annotation -From this release, mixins are more powerful. Mixin classes can declare a `@Spec(MIXEE)`-annotated field, and picocli will inject the `CommandSpec` of the command _receiving_ this mixin (the "mixee") into this field. This is useful for mixins containing shared logic, in addition to shared options and parameters. +From this release, mixins are more powerful. Mixin classes can declare a `@Spec(MIXEE)`-annotated field, and picocli will inject the `CommandSpec` of the command _receiving_ this mixin (the "mixee") into this field. This is useful for mixins containing shared logic, in addition to shared options and parameters. Since picocli 4.3, the `@Spec` annotation has a `value` element. The value is `Spec.Target.SELF` by default, meaning that the `CommandSpec` of the enclosing class is injected into the `@Spec`-annotated field. @@ -1694,7 +1715,7 @@ Example command. ``` By default, the `@` entry is shown before the positional parameters in the synopsis as well as in the parameters list. -This can be changed with the Help API for [reordering sections](https://picocli.info/#_reordering_sections). +This can be changed with the Help API for [reordering sections](https://picocli.info/#_reordering_sections). Both the label and the description of the `@` entry have been defined with [custom variables](https://picocli.info/#_custom_variables), to allow applications to change the text. The variables are: @@ -1760,7 +1781,7 @@ Usage: myapp [-hV] [-o=] * [#468][#505][#852] Auto-completion: added support for positional parameter completion. Thanks to [Serhii Avsheniuk](https://github.com/avshenuk) for the pull request. * [#644][#671] Auto-completion: fix [shellcheck](https://github.com/koalaman/shellcheck) warnings in generated autocompletion scripts. Thanks to [Dylan Cali](https://github.com/calid) for raising this, and thanks to [AlcaYezz](https://github.com/AlcaYezz) for the pull request. * [#396] Auto-completion: completion scripts no longer use associative arrays, and should now work on OSX. -* [#934] Enhancement: Make long options column width configurable. Thanks to [tomerz90](https://github.com/tomerz90) for raising this. +* [#934] Enhancement: Make long options column width configurable. Thanks to [tomerz90](https://github.com/tomerz90) for raising this. * [#930] Enhancement: Add `--factory` option to `ReflectionConfigGenerator`, `ResourceConfigGenerator` and `DynamicProxyConfigGenerator`. Thanks to [Santiago Acosta](https://github.com/hanzo2001) for raising this. * [#690] Enhancement: Postpone instantiating subcommands until they are matched on the command line. Thanks to [Daniel Breitlauch](https://github.com/danielBreitlauch) for raising this. * [#942] Enhancement: Show at files in usage help for picocli built-in commands. @@ -1809,12 +1830,12 @@ Previously all subcommands were instantiated when the top-level command's `Comma # Picocli 4.1.4 The picocli community is pleased to announce picocli 4.1.4. -This release contains a bugfix for GraalVM users, and minor documentation enhancements. +This release contains a bugfix for GraalVM users, and minor documentation enhancements. This release fixes a bug in the `picocli-codegen` annotation processor that generates an incorrect `reflect-config.json` file with invalid entries for inner classes of commands in the unnamed package, that are unnecessarily prefixed with a dot. This makes the GraalVM `native-image` generator fail with an error like "Class .Outer$Inner not found". - + This is the sixty-sixth public release. Picocli follows [semantic versioning](http://semver.org/). @@ -1848,7 +1869,7 @@ 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](http://semver.org/). @@ -1875,7 +1896,7 @@ This release has no breaking changes. # Picocli 4.1.2 The picocli community is pleased to announce picocli 4.1.2. -This release contains bugfixes, improvements, and documentation enhancements. +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. @@ -1887,7 +1908,7 @@ From picocli 4.1.2, all options in an exclusive group are automatically consider - + This is the sixty-fourth public release. Picocli follows [semantic versioning](http://semver.org/). @@ -1900,7 +1921,7 @@ Picocli follows [semantic versioning](http://semver.org/). ## New and Noteworthy ### JLine3 -JLine has had some interesting improvements in its 3.12 release. +JLine has had some interesting improvements in its 3.12 release. 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. @@ -1932,10 +1953,10 @@ This release has no breaking changes. # Picocli 4.1.1 The picocli community is pleased to announce picocli 4.1.1. -This release contains bugfixes, and documentation enhancements. +This release contains bugfixes, and documentation enhancements. + - This is the sixty-third public release. Picocli follows [semantic versioning](http://semver.org/). @@ -1954,7 +1975,7 @@ Picocli follows [semantic versioning](http://semver.org/). * [#875] (DOC) Fix broken internal links in RELEASE-NOTES for 4.1. Thanks to [Andreas Deininger](https://github.com/deining) for raising this. * [#881] (DOC) Update of Quick Guide to the latest `execute` API. Thanks to [Andreas Deininger](https://github.com/deining) for the pull request. * [#874] (DOC) Fix Javadoc issues. Thanks to [Andreas Deininger](https://github.com/deining) for the pull request. - + ## Deprecations No features were deprecated in this release. @@ -1967,7 +1988,7 @@ This release has no breaking changes. # Picocli 4.1.0 The picocli community is pleased to announce picocli 4.1.0. -This release contains bugfixes, and enhancements. +This release contains bugfixes, and enhancements. The library now provides functionality that previously required custom code: @@ -1978,7 +1999,7 @@ The library now provides functionality that previously required custom code: [Help API improvements](#4.1.0-helpapi) make it even easier to add custom sections to the usage help message. This release also includes various bug fixes for [ArgGroups](#4.1.0-arggroups), which were first introduced in picocli 4.0, and are still maturing. - + This is the sixty-second public release. Picocli follows [semantic versioning](http://semver.org/). @@ -2071,7 +2092,7 @@ 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. @@ -2250,10 +2271,10 @@ Picocli follows [semantic versioning](http://semver.org/). ## 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ý](https://github.com/triceo) for raising this issue. -- [#779] Bugfix: `DuplicateOptionAnnotationsException` when a nested group is defined inside a mixin. Thanks to [Matteo Melli](https://github.com/teoincontatto) for the bug report. +- [#779] Bugfix: `DuplicateOptionAnnotationsException` when a nested group is defined inside a mixin. Thanks to [Matteo Melli](https://github.com/teoincontatto) for the bug report. - [#777] Bugfix: Codegen failed when command contains field with argGroup annotation. Thanks to [eomeara](https://github.com/eomeara) for the bug report. - [#776] Bugfix: Argument groups in mixins were ignored. Thanks to [Matteo Melli](https://github.com/teoincontatto) for the bug report. -- [#780] (DOC) Fixed the provided flag usage in the `picocli-codegen` readme. Thanks to [Lasantha Kularatne](https://github.com/lasanthak) for the pull request. +- [#780] (DOC) Fixed the provided flag usage in the `picocli-codegen` readme. Thanks to [Lasantha Kularatne](https://github.com/lasanthak) for the pull request. - [#778] (DOC) Improve documentation for argument group sections in the help. Thanks to [Matteo Melli](https://github.com/teoincontatto) 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](https://github.com/rome-legacy) for the suggestion. @@ -2345,7 +2366,7 @@ Picocli follows [semantic versioning](http://semver.org/). * [`run`, `call`, `invoke`, and `parseWithHandlers` methods](#4.0.0-deprecated-run-call) replaced by `execute` * [`CommandLine.setSplitQuotedStrings`](#4.0.0-deprecated-setSplitQuotedStrings) deprecated * [`parse`](#4.0.0-deprecated-parse) deprecated in favor of `parseArgs` - * [Range public fields](#4.0.0-deprecated-range-public-fields) + * [Range public fields](#4.0.0-deprecated-range-public-fields) * [Potential breaking changes](#4.0.0-breaking-changes) * `picocli.groovy` classes [moved to separate artifact](4.0.0-breaking-groovy) @@ -2363,7 +2384,7 @@ Picocli follows [semantic versioning](http://semver.org/). GraalVM -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. +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. @@ -2441,10 +2462,10 @@ See the [`picocli-codegen` README](https://github.com/remkop/picocli/tree/master executable commands -Picocli 4.0 introduces new API to execute commands. Let’s take a quick look at what changed. +Picocli 4.0 introduces new API to execute commands. Let’s take a quick look at what changed. #### Exit Code -Many command line applications return an [exit code](https://en.wikipedia.org/wiki/Exit_status) to signify success or failure. Zero often means success, a non-zero exit code is often used for errors, but other than that, meanings differ per application. +Many command line applications return an [exit code](https://en.wikipedia.org/wiki/Exit_status) to signify success or failure. Zero often means success, a non-zero exit code is often used for errors, but other than that, meanings differ per application. The new `CommandLine.execute` method introduced in picocli 4.0 returns an `int`, and applications can use this return value to call `System.exit` if desired. For example: @@ -2501,7 +2522,7 @@ assert 3 == new CommandLine(new Gesture()).execute(); By default, the `execute` method returns `CommandLine.ExitCode.USAGE` (`64`) for invalid input, and `CommandLine.ExitCode.SOFTWARE` (`70`) when an exception occurred in the Runnable, Callable or command method. (For reference, these values are `EX_USAGE` and `EX_SOFTWARE`, respectively, from Unix and Linux [sysexits.h](https://www.freebsd.org/cgi/man.cgi?query=sysexits&sektion=3)). This can be customized with the `@Command` annotation. For example: -```java +```java @Command(exitCodeOnInvalidInput = 123, exitCodeOnExecutionException = 456) ``` @@ -2860,7 +2881,7 @@ From this release, picocli supports variable interpolation (variable expansion) class Status { @Option(names = {"${dirOptionName1:--d}", "${dirOptionName2:---directories}"}, // -d or --directories description = {"Specify one or more directories, separated by '${sys:path.separator}'.", - "The default is the user home directory (${DEFAULT-VALUE})."}, + "The default is the user home directory (${DEFAULT-VALUE})."}, arity = "${sys:dirOptionArity:-1..*}", defaultValue = "${sys:user.home}", split = "${sys:path.separator}") @@ -3017,7 +3038,7 @@ This can be switched off with `CommandLine.setAdjustLineBreaksForWideCJKCharacte ### 4.0.0-beta-2 - [#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](https://github.com/pditommaso) and [marinier](https://github.com/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](https://github.com/sebthom) and [AlcaYezz](https://github.com/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](https://github.com/rednoah) for the suggestion. +- [#718] API: Add `IParameterConsumer` and `@Option(parameterConsumer = Xxx.class)` for passing arguments through to another command, like `find -exec`. Thanks to [Reinhard Pointner](https://github.com/rednoah) 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`. @@ -3059,7 +3080,7 @@ This can be switched off with `CommandLine.setAdjustLineBreaksForWideCJKCharacte - [#680] API: Add annotation API for exitCodeList and exitCodeListHeading. - [#611] API: Add `CommandLine.addSubcommand` overloaded method without name or alias. Thanks to [andrewbleonard](https://github.com/andrewbleonard) for the request. - [#684] API: Make `CommandLine.defaultFactory` method public. - - [#675] API: Make `Help.ColorScheme` immutable. This is a breaking API change. + - [#675] API: Make `Help.ColorScheme` immutable. This is a breaking API change. - [#673] API: Deprecate `CommandLine.Range` public fields, add accessor methods to use instead. - [#663] How to remove stacktraces on error. Thanks to [Nicolas Mingo](https://github.com/nicolasmingo) and [jrevault](https://github.com/jrevault) for raising this and subsequent discussion. - [#672] Need way to send errors back from subcommand. Thanks to [Garret Wilson](https://github.com/garretwilson) for raising this. @@ -3078,21 +3099,21 @@ This can be switched off with `CommandLine.setAdjustLineBreaksForWideCJKCharacte - [#681] Documentation: Add exit code section to Internationalization example in user manual. ### 4.0.0-alpha-2 - - [#495] Publish picocli as a JPMS module in a new artifact `picocli-core-module`. Thanks to [Warkdev](https://github.com/Warkdev) for the pull request. + - [#495] Publish picocli as a JPMS module in a new artifact `picocli-core-module`. Thanks to [Warkdev](https://github.com/Warkdev) for the pull request. - [#21] Count double-width Asian characters as two characters for line-breaking purposes. - [#526] Add support for variable interpolation in message strings. Thanks to [Bob Tiernay](https://github.com/bobtiernay-okta) for the suggestion. - [#660] Added `@java.lang.annotation.Inherited` to the `@picocli.CommandLine.Command` annotation. Thanks to [Devin Smith](https://github.com/devinrsmith) for the suggestion. - [#661] Bugfix for stack overflow when option in an argument group had a default value. Thanks to [Andreas Deininger](https://github.com/deining) for reporting this. - [#656] Bugfix for issue where synopsis for composite argument groups did not expand for n..* (n > 1). Thanks to Arno Tuomainen for finding this issue. - [#654] Bugfix: argument group heading text was not retrieved from ResourceBundle. Thanks to [Andreas Deininger](https://github.com/deining) for raising this. - - [#635] Bugfix in argument group validation: did not show an error if some but not all parts of a co-occurring group were specified. Thanks to [Philipp Hanslovsky](https://github.com/hanslovsky) for the pull request. + - [#635] Bugfix in argument group validation: did not show an error if some but not all parts of a co-occurring group were specified. Thanks to [Philipp Hanslovsky](https://github.com/hanslovsky) for the pull request. - [#653] Bugfix: argument group validation should be skipped if help was requested. Thanks to [Andreas Deininger](https://github.com/deining) for raising this. - [#655] Bugfix: argument group validation silently accepts missing subgroup with multiplicity=1. - [#652] Documentation: fixes in user manual. Thanks to [Andreas Deininger](https://github.com/deining) for the pull request. - [#651] Documentation: fixes in user manual. Thanks to [Andreas Deininger](https://github.com/deining) for the pull request. ### 4.0.0-alpha-1 - - [#643] Change `%` to `%%` when using `${DEFAULT-VALUE}` in option description. Thanks to [Steffen Rehberg](https://github.com/StefRe) for the pull request. + - [#643] Change `%` to `%%` when using `${DEFAULT-VALUE}` in option description. Thanks to [Steffen Rehberg](https://github.com/StefRe) for the pull request. - [#638] Document fallback descriptionKey for options and parameters in user manual. Thanks to [Mikusch](https://github.com/Mikusch) for the suggestion. - [#199] mutually exclusive options - [#295] options that must co-occur (dependent options) @@ -3152,7 +3173,7 @@ Note that when toggling is enabled, specifying a flag option twice on the comman ### ParseResult `matchedOptions` now returns full list `ParseResult.matchedOptions()` and `ParseResult.matchedPositionals()` now return the full list of matched options and positional parameters, including duplicates if the option or positional parameter was matched multiple times. -Prior to this release, these methods would return a list that did not contain duplicates. +Prior to this release, these methods would return a list that did not contain duplicates. Applications interested in the old behavior should use the new `matchedOptionSet()` and `matchedPositionalSet()` methods that return a `Set`. ### Error message for unmatched arguments changed @@ -3168,13 +3189,13 @@ New : Unmatched arguments from index 1: 'B', 'C' This may break tests that rely on the exact error message. -### Option order changed +### Option order changed Previously, options that only have a long name (and do not have a short name) were always shown before options with a short name. From this release, they are inserted in the option list by their first non-prefix letter. This may break tests that expect a specific help message. -### Factory +### Factory From version 4.0, picocli delegates all object creation to the [factory](https://picocli.info/#_custom_factory), including creating `Collection` instances to capture [multi-value](https://picocli.info/#_arrays_and_collections) `@Option` values. Previously, `Collection` objects were instantiated separately without involving the factory. @@ -3199,7 +3220,7 @@ 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: +This release introduces two new attributes on the `Option` annotation: * `fallbackValue` * `parameterConsumer` @@ -3284,7 +3305,7 @@ End users may enable this by setting system property `picocli.usage.width` to `A 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. @@ -3320,7 +3341,7 @@ class ExecParameterConsumer implements IParameterConsumer { ## 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](https://github.com/pditommaso) and [marinier](https://github.com/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](https://github.com/sebthom) and [AlcaYezz](https://github.com/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](https://github.com/rednoah) for the suggestion. +- [#718] API: Add `IParameterConsumer` and `@Option(parameterConsumer = Xxx.class)` for passing arguments through to another command, like `find -exec`. Thanks to [Reinhard Pointner](https://github.com/rednoah) 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`. @@ -3334,7 +3355,7 @@ class ExecParameterConsumer implements IParameterConsumer { - [#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`. @@ -3359,21 +3380,21 @@ This may break tests that rely on the exact error message. # Picocli 4.0.0-beta-1b The picocli community is pleased to announce picocli 4.0.0-beta-1b. -This release includes the first cut of an annotation processor that can build a model from the picocli annotations at compile time rather than at runtime. +This release includes the first cut of an annotation processor that 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 [Graal configuration](https://github.com/oracle/graal/blob/master/substratevm/BuildConfiguration.md) files under `META-INF/native-image/picocli-generated/$project` during compilation, to be included in the application jar. By embedding these configuration files, your jar is instantly Graal-enabled. -In most cases no further configuration is needed when generating a native image. +In most cases no further configuration is needed when generating a native image. Also, from this release the main `picocli-4.x` artifact no longer contains the `picocli.groovy` classes: these have been split off into a separate `picocli-groovy-4.x` artifact. The main `picocli-4.x.jar` is now an explicit JPMS module, with a `module-info.class` located in `META-INF/versions/9`. The `picocli-jpms-module` subproject has been removed. From picocli 4.0, options can be `negatable`. -When an option is negatable, picocli will recognize negative aliases of the option on the command line. See the New and Noteworthy section below for more details. +When an option is negatable, picocli will recognize negative aliases of the option on the command line. See the New and Noteworthy section below for more details. _Please try this and provide feedback. We can still make changes._ @@ -3396,7 +3417,7 @@ Picocli follows [semantic versioning](http://semver.org/). ### Annotation Processor -This release includes the first cut of an annotation processor that can build a model from the picocli annotations at compile time rather than at runtime. +This release includes the first cut of an annotation processor that 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. @@ -3405,11 +3426,11 @@ Use this if you’re interested in: This includes configuration files for [reflection](https://github.com/oracle/graal/blob/master/substratevm/Reflection.md), [resources](https://github.com/oracle/graal/blob/master/substratevm/Resources.md) and [dynamic proxies](https://github.com/oracle/graal/blob/master/substratevm/DynamicProxy.md). By embedding these configuration files, your jar is instantly Graal-enabled. The `$project` location is configurable, see [processor options](#picocli-processor-options) below. -In most cases no further configuration is needed when generating a native image. +In most cases no further configuration is needed when generating a native image. #### 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. +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](https://immutables.github.io/apt.html) shows the steps to configure Eclipse and IntelliJ IDEA to enable annotation processing. @@ -3436,7 +3457,7 @@ This requires `maven-compiler-plugin` plugin version 3.5 or higher. ``` -An alternative that works with older versions of the `maven-compiler-plugin` is to specify the `picocli-codegen` module on the classpath as a `provided` dependency. This also prevents the `picocli-codegen` module from being included in the artifact the module produces as a transitive dependency. +An alternative that works with older versions of the `maven-compiler-plugin` is to specify the `picocli-codegen` module on the classpath as a `provided` dependency. This also prevents the `picocli-codegen` module from being included in the artifact the module produces as a transitive dependency. ``` @@ -3454,7 +3475,7 @@ An alternative that works with older versions of the `maven-compiler-plugin` is ``` -See Processor Options below. +See Processor Options below. ##### Gradle @@ -3481,7 +3502,7 @@ The picocli annotation processor supports the options below. ##### Recommended Options * `project` - output subdirectory -The generated files are written to `META-INF/native-image/picocli-generated/${project}`. +The generated files are written to `META-INF/native-image/picocli-generated/${project}`. The `project` option can be omitted, but it is a good idea to specify the `project` option with a unique value for your project (e.g. `${groupId}/${artifactId}`) if your jar may be [shaded](https://stackoverflow.com/a/49811665) with other jars into an uberjar. @@ -3505,7 +3526,7 @@ The `-A` option lets you pass options to annotation processors. See the [javac d ##### Maven -To set an annotation processor option in Maven, you need to use the `maven-compiler-plugin` and configure the `compilerArgs` section. +To set an annotation processor option in Maven, you need to use the `maven-compiler-plugin` and configure the `compilerArgs` section. ``` @@ -3525,10 +3546,10 @@ To set an annotation processor option in Maven, you need to use the `maven-compi ``` -See https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html for details. +See https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html for details. #### Gradle Example -To set an annotation processor option in Gradle, add these options to the `options.compilerArgs` list in the `compileJava` block. +To set an annotation processor option in Gradle, add these options to the `options.compilerArgs` list in the `compileJava` block. ``` compileJava { @@ -3592,7 +3613,7 @@ From this release the main `picocli-4.x` artifact no longer contains the `picocl Scripts upgrading to picocli 4.0 must change more than just the version number! Scripts should use `@Grab('info.picocli:picocli-groovy:4.x')` from version 4.0, `@Grab('info.picocli:picocli:4.x')` will not work. -### Option Order Changed +### Option Order Changed Previously, options that only have a long name (and do not have a short name) were always shown before options with a short name. From this release, they are inserted in the option list by their first non-prefix letter. This may break tests that expect a specific help message. @@ -3607,7 +3628,7 @@ Applications can call `CommandLine.setToggleBooleanFlags(true)` to enable toggli Note that when toggling is enabled, specifying a flag option twice on the command line will have no effect because they cancel each other out. ### Revert `@Inherited` annotation on `@Command` -The `@Inherited` annotated that was added to `@Command` in picocli 4.0.0-alpha-2 turned out to cause +The `@Inherited` annotated that was added to `@Command` in picocli 4.0.0-alpha-2 turned out to cause issues in scenarios with multiple levels of inheritance and is reverted in this release. @@ -3641,10 +3662,10 @@ Picocli follows [semantic versioning](http://semver.org/). ### Executing Commands -Picocli 4.0 introduces new API to execute commands. Let’s take a quick look at what changed. +Picocli 4.0 introduces new API to execute commands. Let’s take a quick look at what changed. #### Exit Code -Many command line applications return an [exit code](https://en.wikipedia.org/wiki/Exit_status) to signify success or failure. Zero often means success, a non-zero exit code is often used for errors, but other than that, meanings differ per application. +Many command line applications return an [exit code](https://en.wikipedia.org/wiki/Exit_status) to signify success or failure. Zero often means success, a non-zero exit code is often used for errors, but other than that, meanings differ per application. The new `CommandLine.execute` method introduced in picocli 4.0 returns an `int`, and applications can use this return value to call `System.exit` if desired. For example: @@ -3701,7 +3722,7 @@ assert 3 == new CommandLine(new Gesture()).execute(); By default, the `execute` method returns `CommandLine.ExitCode.USAGE` (`64`) for invalid input, and `CommandLine.ExitCode.SOFTWARE` (`70`) when an exception occurred in the Runnable, Callable or command method. (For reference, these values are `EX_USAGE` and `EX_SOFTWARE`, respectively, from Unix and Linux [sysexits.h](https://www.freebsd.org/cgi/man.cgi?query=sysexits&sektion=3)). This can be customized with the `@Command` annotation. For example: -```java +```java @Command(exitCodeOnInvalidInput = 123, exitCodeOnExecutionException = 456) ``` @@ -3758,12 +3779,12 @@ Previous versions of picocli offered the `run`, `call` and `invoke` methods to e * *Static* - These are static methods, with the drawback that they don't allow configuration, as mentioned above. * *Type Safety* - It is a compile-time error when an application tries to pass anything else than a `Runnable` to the `run` method, and a `Callable` to the `call` method. The `execute` method does not have this type safety, since the `CommandLine` constructor allows any `Object` as a parameter. -* *Return Value* - The `call` and `invoke` static methods allow commands to return _any_ value, while the `execute` method only returns an `int` exit code. From 4.0 the result object will be available from the `CommandLine.getExecutionResult` method. +* *Return Value* - The `call` and `invoke` static methods allow commands to return _any_ value, while the `execute` method only returns an `int` exit code. From 4.0 the result object will be available from the `CommandLine.getExecutionResult` method. #### Feedback Requested -With the new execute API the `ColorScheme` class will start to play a more central role. I decided to make the `ColorScheme` class immutable from this release. This is a breaking API change. -Should it be deprecated first, or not changed at all, or is the 4.0 release a good time to make breaking changes? Your feedback is very welcome on https://github.com/remkop/picocli/issues/675. +With the new execute API the `ColorScheme` class will start to play a more central role. I decided to make the `ColorScheme` class immutable from this release. This is a breaking API change. +Should it be deprecated first, or not changed at all, or is the 4.0 release a good time to make breaking changes? Your feedback is very welcome on https://github.com/remkop/picocli/issues/675. ### Tools for Configuring GraalVM Native Image Builds @@ -3780,13 +3801,13 @@ The GraalVM native-image builder by default will not integrate any of the that should be included in the Substrate VM native image. The output of `ResourceConfigGenerator` is intended to be passed to the `-H:ResourceConfigurationFiles=/path/to/reflect-config.json` option of the `native-image` GraalVM utility, -or placed in a `META-INF/native-image/` subdirectory of the JAR. +or placed in a `META-INF/native-image/` subdirectory of the JAR. This allows picocli-based native image applications to access these resources. #### DynamicProxyConfigGenerator -Substrate VM doesn't provide machinery for generating and interpreting bytecodes at run time. Therefore all dynamic proxy classes +Substrate VM doesn't provide machinery for generating and interpreting bytecodes at run time. Therefore all dynamic proxy classes [need to be generated](https://github.com/oracle/graal/blob/master/substratevm/DynamicProxy.md) at native image build time. `DynamicProxyConfigGenerator` generates a JSON String with the fully qualified interface names for which @@ -3808,7 +3829,7 @@ This allows picocli-based native image applications that use `@Command`-annotate - [#680] API: Add annotation API for exitCodeList and exitCodeListHeading. - [#611] API: Add `CommandLine.addSubcommand` overloaded method without name or alias. Thanks to [andrewbleonard](https://github.com/andrewbleonard) for the request. - [#684] API: Make `CommandLine.defaultFactory` method public. -- [#675] API: Make `Help.ColorScheme` immutable. This is a breaking API change. +- [#675] API: Make `Help.ColorScheme` immutable. This is a breaking API change. - [#673] API: Deprecate `CommandLine.Range` public fields, add accessor methods to use instead. - [#663] How to remove stacktraces on error. Thanks to [Nicolas Mingo](https://github.com/nicolasmingo) and [jrevault](https://github.com/jrevault) for raising this and subsequent discussion. - [#672] Need way to send errors back from subcommand. Thanks to [Garret Wilson](https://github.com/garretwilson) for raising this. @@ -3888,7 +3909,7 @@ From this release, picocli supports variable interpolation (variable expansion) class Status { @Option(names = {"${dirOptionName1:--d}", "${dirOptionName2:---directories}"}, // -d or --directories description = {"Specify one or more directories, separated by '${sys:path.separator}'.", - "The default is the user home directory (${DEFAULT-VALUE})."}, + "The default is the user home directory (${DEFAULT-VALUE})."}, arity = "${sys:dirOptionArity:-1..*}", defaultValue = "${sys:user.home}", split = "${sys:path.separator}") @@ -3972,14 +3993,14 @@ From this release, picocli will use 2 columns for these wide characters when cal This can be switched off with `CommandLine.setAdjustLineBreaksForWideCJKCharacters(false)`. ## Fixed issues -- [#495] Publish picocli as a JPMS module in a new artifact `picocli-core-module`. Thanks to [Warkdev](https://github.com/Warkdev) for the pull request. +- [#495] Publish picocli as a JPMS module in a new artifact `picocli-core-module`. Thanks to [Warkdev](https://github.com/Warkdev) for the pull request. - [#21] Count double-width Asian characters as two characters for line-breaking purposes. - [#526] Add support for variable interpolation in message strings. Thanks to [Bob Tiernay](https://github.com/bobtiernay-okta) for the suggestion. - [#660] Added `@java.lang.annotation.Inherited` to the `@picocli.CommandLine.Command` annotation. Thanks to [Devin Smith](https://github.com/devinrsmith) for the suggestion. - [#661] Bugfix for stack overflow when option in an argument group had a default value. Thanks to [Andreas Deininger](https://github.com/deining) for reporting this. - [#656] Bugfix for issue where synopsis for composite argument groups did not expand for n..* (n > 1). Thanks to Arno Tuomainen for finding this issue. - [#654] Bugfix: argument group heading text was not retrieved from ResourceBundle. Thanks to [Andreas Deininger](https://github.com/deining) for raising this. -- [#635] Bugfix in argument group validation: did not show an error if some but not all parts of a co-occurring group were specified. Thanks to [Philipp Hanslovsky](https://github.com/hanslovsky) for the pull request. +- [#635] Bugfix in argument group validation: did not show an error if some but not all parts of a co-occurring group were specified. Thanks to [Philipp Hanslovsky](https://github.com/hanslovsky) for the pull request. - [#653] Bugfix: argument group validation should be skipped if help was requested. Thanks to [Andreas Deininger](https://github.com/deining) for raising this. - [#655] Bugfix: argument group validation silently accepts missing subgroup with multiplicity=1. - [#652] Documentation: fixes in user manual. Thanks to [Andreas Deininger](https://github.com/deining) for the pull request. @@ -3997,7 +4018,7 @@ Classes: * `picocli.CommandLine.ParseResult.MatchedGroupMultiple` -> `picocli.CommandLine.ParseResult.GroupMatch` Methods: - + * `ParseResult::getMatchedGroupMultiples` has been renamed to `ParseResult::getGroupMatches` * `ParseResult::findMatchedGroup(ArgGroupSpec)` has been renamed to `ParseResult::findMatches(ArgGroupSpec)` @@ -4322,7 +4343,7 @@ When a `@Parameters` positional parameter is part of a group, its `index` is the ## Fixed issues -- [#643] Change `%` to `%%` when using `${DEFAULT-VALUE}` in option description. Thanks to [Steffen Rehberg](https://github.com/StefRe) for the pull request. +- [#643] Change `%` to `%%` when using `${DEFAULT-VALUE}` in option description. Thanks to [Steffen Rehberg](https://github.com/StefRe) for the pull request. - [#638] Document fallback descriptionKey for options and parameters in user manual. Thanks to [Mikusch](https://github.com/Mikusch) for the suggestion. - [#199] mutually exclusive options - [#295] options that must co-occur (dependent options) @@ -4376,11 +4397,11 @@ The picocli community is pleased to announce picocli 3.9.4. This release contains bugfixes and enhancements. -From this release, `enum`-typed options and positional parameters that are multi-value can be stored in `EnumSet` collections (in addition to other Collections, arrays and Maps). +From this release, `enum`-typed options and positional parameters that are multi-value can be stored in `EnumSet` collections (in addition to other Collections, arrays and Maps). Also, a better error message is now shown when unknown options are encountered while processing clustered short options. The new error message includes both the failing part and the original command line argument. -Bugfixes: +Bugfixes: * `ReflectionConfigGenerator` incorrectly listed superclass fields as fields of the concrete subclass, causing "GraalVM error: Error parsing reflection configuration in json" when creating a native image. * Method subcommands in commands that subclass another command caused `InitializationException`. @@ -4402,7 +4423,7 @@ Picocli follows [semantic versioning](http://semver.org/). - [#619] Bugfix: Method subcommands in commands that subclass another command caused `InitializationException`: "Another subcommand named 'method' already exists...". Thanks to [PorygonZRocks](https://github.com/PorygonZRocks) for the bug report. - [#622] Bugfix: `ReflectionConfigGenerator` incorrectly listed superclass fields as fields of the concrete subclass, causing "GraalVM error: Error parsing reflection configuration in json". Thanks to [Sebastian Thomschke](https://github.com/sebthom) for the bug report. - [#623] `ReflectionConfigGenerator` now generates json in alphabetic order. -- [#627] Improve error message for unknown options when processing clustered short options. +- [#627] Improve error message for unknown options when processing clustered short options. ## Deprecations No features were deprecated in this release. @@ -4537,7 +4558,7 @@ When `CommandLine::setTrimQuotes()` was set to `true`, given input like the belo ``` -p AppOptions="-Da=b -Dx=y" ``` -The above used to result in a map with key `AppOptions` and value `"-Da=b -Dx=y"` (including the quotes), but the same program and input now results in a map with key `AppOptions` and value `-Da=b -Dx=y` (without quotes). +The above used to result in a map with key `AppOptions` and value `"-Da=b -Dx=y"` (including the quotes), but the same program and input now results in a map with key `AppOptions` and value `-Da=b -Dx=y` (without quotes). Also, when `CommandLine::setTrimQuotes()` is `false` (the default), input like the below will now cause a `ParameterException` ("value should be in KEY=VALUE format"): @@ -4545,7 +4566,7 @@ Also, when `CommandLine::setTrimQuotes()` is `false` (the default), input like t -p "AppOptions=-Da=b -Dx=y" ``` Prior to this release, the above was silently ignored (no errors but also no key-value pairs in the resulting map). - + # Picocli 3.9.0 The picocli community is pleased to announce picocli 3.9.0. @@ -4568,7 +4589,7 @@ The simplified @-file (argument file) format is now fully compatible with JComma 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: +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 @@ -4665,7 +4686,7 @@ The `@Option(order = )` attribute can be used to explicitly control the pos ### 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. +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. @@ -4705,7 +4726,7 @@ Support was added for the following environment variables to control enabling AN - [#571] Improve test code coverage. Added ~300 tests to bring the total to 1300+ tests. Improved line coverage to 98% (was 88%) and complexity coverage to 98% (was 82%). - [#590] Fail the build if test coverage falls below minimum threshold. - [#589] Fix index.adoc to eliminate warnings; suppress javadoc warnings. -- [#566] Add example showing how to customize the usage help message to show the full command tree including nested subcommands. Thanks to [lgawron](https://github.com/lgawron) for the request. +- [#566] Add example showing how to customize the usage help message to show the full command tree including nested subcommands. Thanks to [lgawron](https://github.com/lgawron) for the request. ## Deprecations No features were deprecated in this release. @@ -4737,7 +4758,7 @@ Picocli follows [semantic versioning](http://semver.org/). ## Fixed issues - [#557] Bugfix: No colors are shown when compiling to a native image with Graal on MacOS. Thanks to [Oliver Weiler](https://github.com/helpermethod) for the bug report. - + ## Deprecations No features were deprecated in this release. @@ -4754,7 +4775,7 @@ Command methods explicitly throwing a `ParametersException` is now correctly han 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! +Many thanks to the many members of the picocli community who contributed! This is the forty-third public release. Picocli follows [semantic versioning](http://semver.org/). @@ -4770,7 +4791,7 @@ Picocli follows [semantic versioning](http://semver.org/). ### 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. @@ -4809,7 +4830,7 @@ This release contains bugfixes and minor enhancements. 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! +Many thanks to the many members of the picocli community who contributed! This is the forty-second public release. Picocli follows [semantic versioning](http://semver.org/). (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.) @@ -4841,7 +4862,7 @@ class App { ``` 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](https://github.com/knutwalker) for the pull request. - [#532] Enhancement: `OverwrittenOptionException` now has an accessor for the `ArgSpec` that was overwritten. Thanks to [Steven Fontaine](https://github.com/acid1103) for the pull request. @@ -4891,16 +4912,16 @@ This behaviour is now consistent for all annotation-based and programmatic ways # 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: +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 +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! +Many thanks to the many members of the picocli community who contributed! This is the forty-first public release. Picocli follows [semantic versioning](http://semver.org/). @@ -4940,7 +4961,7 @@ f ``` ### New Module `picocli-codegen` -Picocli Code Generation contains tools for generating source code, documentation and configuration files +Picocli Code Generation contains tools for generating source code, documentation and configuration files for picocli-based applications. This release contains the `ReflectionConfigGenerator` class. @@ -4996,7 +5017,7 @@ 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! +Many thanks to the many members of the picocli community who contributed! This is the fortieth public release. Picocli follows [semantic versioning](http://semver.org/). @@ -5040,7 +5061,7 @@ 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! +Many thanks to the many members of the picocli community who raised issues and contributed solutions! This is the thirty-ninth public release. Picocli follows [semantic versioning](http://semver.org/). @@ -5174,9 +5195,9 @@ 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. +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. +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: @@ -5269,7 +5290,7 @@ Picocli follows [semantic versioning](http://semver.org/). ## Promoted Features -Promoted features are features that were incubating in previous versions of picocli but are now supported and subject to backwards compatibility. +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. @@ -5304,7 +5325,7 @@ Picocli follows [semantic versioning](http://semver.org/). ## Promoted Features -Promoted features are features that were incubating in previous versions of picocli but are now supported and subject to backwards compatibility. +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. @@ -5324,9 +5345,9 @@ 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. +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. +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. @@ -5345,7 +5366,7 @@ Picocli follows [semantic versioning](http://semver.org/). ### `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. +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: @@ -5363,7 +5384,7 @@ class Login implements Callable { System.out.printf("Hi %s, your passphrase is hashed to %s.%n", user, base64(md.digest())); return null; } - + private String base64(byte[] arr) { /* ... */ } } ``` @@ -5377,7 +5398,7 @@ CommandLine.call(new Login(), "-u", "user123", "-p"); Then the user will be prompted to enter a value: ``` -Enter value for --password (Passphrase): +Enter value for --password (Passphrase): ``` When running on Java 6 or higher, the user input is not echoed to the console. @@ -5393,9 +5414,9 @@ Methods annotated with `@Option` and `@Parameters` can do simple input validatio ```java class ValidationExample { private Map properties = new LinkedHashMap<>(); - + @Spec private CommandSpec spec; // injected by picocli - + @Option(names = {"-D", "--property"}, paramLabel = "KEY=VALUE") public void setProperty(Map map) { for (String key : map.keySet()) { @@ -5422,7 +5443,7 @@ By following the recipe above and throwing a `ParameterException` on invalid inp ## Promoted Features -Promoted features are features that were incubating in previous versions of picocli but are now supported and subject to backwards compatibility. +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. @@ -5459,7 +5480,7 @@ Picocli follows [semantic versioning](http://semver.org/). ## 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. +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. @@ -5472,7 +5493,7 @@ No features have been promoted in this picocli release. - [#419] Bugfix: Default value for arrays was not rendered correctly with `@{DEFAULT-VALUE}`. - [#418] Doc: Improve installation instructions for autocompletion scripts. - [#420] Doc: Added a Quick Guide - + ## Deprecations No features were deprecated in this release. @@ -5505,20 +5526,20 @@ For example: class App { @Option(names = "--file") File[] files; @Option(names = "--find") String pattern; - + public static void main(String[] args) { App app = new App(); try { new CommandLine(app).parse(args); // ... - + } catch (ParameterException ex) { System.err.println(ex.getMessage()); if (!UnmatchedArgumentException.printSuggestions(ex, System.err)) { // new API ex.getCommandLine().usage(System.err, ansi); } } - } + } } ``` @@ -5535,11 +5556,11 @@ Unknown option: -fi Possible solutions: --file, --find ``` -This is the behaviour for the `CommandLine` convenience methods `run`, `call` and `parseWithHandlers`. +This is the behaviour for the `CommandLine` convenience methods `run`, `call` and `parseWithHandlers`. Note that if possible fixes are found, the usage help message is not displayed. ## Promoted Features -Promoted features are features that were incubating in previous versions of picocli but are now supported and subject to backwards compatibility. +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. @@ -5662,7 +5683,7 @@ The `@Option` and `@Parameters` annotations can be used on methods of a class th ```java class Counter { int count; - + @Option(names = "--count") void setCount(int count) { this.count = count; @@ -5792,12 +5813,12 @@ Usage:
-l= -o=