Picocli 4.6.2

The picocli community is pleased to announce picocli 4.6.2.

This release includes bugfixes and enhancements. Many improvements in the documentation.

Thanks to the many people in the picocli community for raising issues and contributing pull requests to fix issues!

From this release, picocli uses system properties sun.stdout.encoding and sun.stderr.encoding when creating the PrintWriters returned by CommandLine::getOut and CommandLine::getErr. When these system properties do not exist, picocli falls back to the default charset (determined by file.encoding). This addresses an issue on Windows, where the default charset is not the same as the encoding for its console (often the older cp437 codepage on English-language versions of Windows).

Note that these system properties seem to have been introduced in Java 8 (although I cannot find it in the JDK 8 release notes) and may not exist on earlier JVMs or on JVMs other than the Oracle and OpenJDK implementations.

This is the seventy-seventh public release.
Picocli follows semantic versioning.
Artifacts in this release are signed by Remko Popma (6601 E5C0 8DCC BB96).

Table of Contents

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

New and Noteworthy

Fixed issues

• [#1422] API: Un-deprecate the @Option help attribute; it is useful for custom help options. Thanks to kaushalkumar for raising this.
• [#1337][#1338] Enhancement: prevent spurious WARNING: tag not found in include file messages when generating man pages. Thanks to Philip Crotwell for the pull request.
• [#1340] Enhancement: add xref to generated man page document to link to subcommands from the parent command page. Thanks to Philip Crotwell for the pull request.
• [#1351][#1362] Enhancement: avoid calling option completionCandidates when displaying usage help if ${COMPLETION-CANDIDATES} is not specified in description. Thanks to Wenhao ZHANG, sustc11810424 and Yining Tang for the pull request.
• [#1303] Bugfix: Prevent IllegalArgumentException: argument type mismatch error in method subcommands with inherited mixed-in standard help options. Thanks to Andreas Deininger for raising this.
• [#1300] Bugfix: Avoid spurious warning "Could not set initial value for field boolean" when reusing CommandLine with ArgGroup. Thanks to Yashodhan Ghadge for raising this.
• [#1316] Bugfix: Avoid DuplicateOptionAnnotationsException thrown on mixinStandardHelpOptions for subcommands when parent has scope = INHERIT by picocli-codegen annotation processor. Thanks to Philippe Charles for raising this.
• [#1319] Bugfix: Avoid DuplicateOptionAnnotationsException when parent has inherited mixed-in help options and the built-in HelpCommand subcommand. Thanks to Andreas Deininger for raising this.
• [#1331] Bugfix: Avoid IllegalArgumentException when parent has no standard help options and scope = INHERIT, while subcommand does have mixed-in standard help options. Thanks to Andreas Deininger for raising this.
• [#1381][#1382] Bugfix: Default value of option in repeated subcommand was not applied correctly. Thanks to sfeuerhahn for the pull request.
• [#1434][#1435] CommandSpec.remove(arg) should also remove the arg from the args collection in the CommandSpec. Thanks to kaushalkumar for the pull request.
• [#1404] Bugfix/Enhancement: Print paramLabel only when it could exist. Thanks to João Guerra for the pull reqeust.
• [#1320][#1321] Bugfix/Enhancement: Use system properties sun.stdout.encoding and sun.stderr.encoding when creating the PrintWriters returned by CommandLine::getOut and CommandLine::getErr. Thanks to Philippe Charles for the investigation and the pull request.
• [#1431] Bugfix/enhancement: .gitattributes should include HTML files to convert CRLF to LF. Thanks to wenhoujx for pointing this out.
• [#1388][#1430] Bugfix: Fix subcommand aliases autocomplete regression. Thanks to NewbieOrange for the pull request.
• [#1415] Bugfix/DOC: fix NullPointerException in README Example. Thanks to shannonbay for raising this.
• [#1421] Bugfix/DOC: execute method in RunAll, RunFirst and RunLast should not be deprecated. Thanks to Gamal DeWeever for raising this.
• [#1326][#1339] DOC: Added documentation and examples for controlling the locale. Thanks to Andreas Deininger for the pull request.
• [#1296] DOC: add Kotlin code samples to user manual; other user manual improvements. Thanks to Andreas Deininger for the pull request.
• [#1299] DOC: Link to IParameterPreprocessor from IParameterConsumer javadoc. Thanks to Andreas Deininger for the pull request.
• [#1304] DOC: Manual, chapter '17.9 Inherited Command Attributes': added Kotlin version of code sample. Thanks to Andreas Deininger for the pull request.
• [#1305] DOC: Document use of IParameterConsumer as n-ary type converter. Thanks to Martin for raising this.
• [#1307] DOC: Added CAUTION admonitions, Kotlin code sample. Thanks to Andreas Deininger for the pull request.
• [#1308] DOC: Add example for Option converter, improve text for default values. Thanks to Abhijit Sarkar for raising this.
• [#1314] DOC: Fix use of deprecated Maven properties in README. Thanks to Philippe Charles for the pull request.
• [#1323] DOC: Update Testing section of the user manual for Stefan Birkner's library System-Lambda.
• [#1325] DOC: Add section on Short and Long Option Columns to user manual. Thanks to Andrei Ciobanu for raising this.
• [#1336] DOC: Kotlin sample code, documentation improvements. Thanks to Andreas Deininger for the pull request.
• [#1342] DOC: Improve user manual chapter 28.3 'Testing the Exit Code'. Thanks to Andreas Deininger for the pull request.
• [#1344] DOC: Documentation, chapter 'Testing environment variables:': add Kotlin test sample. Thanks to Andreas Deininger for the pull request.
• [#1443] DOC: Fix incorrect method name setLongOptionsMaxWidth to setUsageHelpLongOptionsMaxWidth in user manual section 'Long Option Column Width'. Thanks to kunlk for raising this.
• [#1360][#1359] DOC: add JReleaser as packaging option. Thanks to Andres Almiray for the pull request.
• [#1363][#1364] DOC: Add caution on Variable interpolation in Kotlin. Thanks to MagnusMG for the pull request.
• [#1397][#1399] DOC: Update Jline2 README.md to add some recommended workaround about ANSI incompatible terminals. Thanks to Simon for the pull request.
• [#1398][#1400] DOC: Arity of boolean options is now documented correctly. Thanks to João Guerra for the pull request.
• [#1428][#1433] DOC: Add section about subcommands with the same name as option default value. Thanks to cbcmg for the pull request.
• [#1390][#1432] DOC: Update examples to not throw Exception from main method. Thanks to wenhoujx for the pull request.
• [#1423] DOC: Fixed broken link in README.md to annotation processor documentation. Thanks to Sevy007 for raising this.
• [#1449] DOC: Fix typo in picocli-shell-jline2/README.md. Thanks to Ahmed Ashour for the pull request.
• [#1426] Fix README adoption logos. Thanks to NewbieOrange for the pull request.
• [#1313] DEP: Bump jline3Version in order to avoid stackoverflow error. Thanks to Rupert Madden-Abbott for the pull request.
• [#1455] DEP: Bump spring-boot version to 2.5.6.
• [#1369][#1371] Upgrade jline3 to version 3.19.0 to avoid "ReadConsoleInputW failed: Incorrect function" error. Thanks to auricgoldfinger for the pull request.
• [#1336] BUILD: Bump Spring Boot, Gradle and Kotlin to latest version. Thanks to Andreas Deininger for the pull request.
• [#1327] BUILD: fix incorrect version in MANIFEST.MF. Thanks to Fiouz for the pull request.
• [#1328] BUILD: Upgrade Gradle to 6.8.2 and enable official Gradle Wrapper Validation GitHub Action. Thanks to Fiouz for the pull request.
• [#1329] BUILD: OSGi manifest entry in picocli-4.6.0.jar should not require groovy. Thanks to Fiouz for raising this.
• [#1330] BUILD: use type-safe DSL instead of direct XML manipulation to generate pom.xml. Thanks to Fiouz for the pull request.
• [#1332] BUILD: Bumping asciidoctor + asciidoctor gradle plugin to latest versions. Thanks to Andreas Deininger for the pull request.
• [#1413] BUILD: Improve Travis CI build Performance. Thanks to YunLemon for the pull request.
• [#1322] BUILD: switch from Bintray jcenter to Maven Central.

Deprecations

No features were deprecated in this release.

The @Option help attribute is no longer deprecated from this release; it is useful for custom help options.

Potential breaking changes

This release has no breaking changes.