Skip to content

Picocli 4.7.0
Compare
Choose a tag to compare
@remkop remkop released this 31 Oct 20:13
· 348 commits to main since this release
v4.7.0
d9b1e47

Picocli 4.7.0

The picocli community is pleased to announce picocli 4.7.0.

This release includes bugfixes and enhancements.

A potentially breaking change is that the parser now treats char[] as a single-value type.

From this release, applications can programmatically set the trace level, and use tracing in custom components.

Applications can improve startup time by setting system property picocli.disable.closures to true to disable support for closures in annotations.

Many more fixes and enhancements, see the sections below for more details.

This is the seventy-ninth 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

Tracing API

From picocli 4.7.0, applications can programmatically set the trace level, and use tracing in custom components.

In addition to setting system property picocli.trace, applications can now change the trace level via the Tracer::setLevel method. For example:

CommandLine.tracer().setLevel(CommandLine.TraceLevel.INFO);

The new public method CommandLine.tracer() returns the singleton Tracer object that is used internally by picocli, and can also be used by custom component implementations to do tracing. For example:

class MyIntConverter implements ITypeConverter<Integer> {
    public Integer convert(String value) {
        try {
            return Integer.parseInt(value);
        } catch (NumberFormatException ex) {
            CommandLine.tracer().info(
                    "Could not convert %s to Integer, returning default value -1", value);
            return -1;
        }
    }
}

Enable Consuming Option Names or Subcommands

By default, options that take a parameter do not consume values that match a subcommand name or an option name.

This release introduces two parser configuration options to change this behaviour:

  • CommandLine::setAllowOptionsAsOptionParameters allows options to consume option names
  • CommandLine::setAllowSubcommandsAsOptionParameters allows options to consume subcommand names

When set to true, all options in the command (options that take a parameter) can consume values that match option names or subcommand names.

This means that any option will consume the maximum number of arguments possible for its arity.

USE WITH CAUTION!

If an option is defined as arity = "*", this option will consume all remaining command line arguments following this option (until the End-of-options delimiter) as parameters of this option.

Unsorted Synopsis

By default, the synopsis displays options in alphabetical order.
Picocli 4.7.0 introduces a sortSynopsis = false attribute to let the synopsis display options in the order they are declared in your class, or sorted by their order attribute.

@Command(sortSynopsis = false)

Parser change for char[] options

Prior to 4.7, the picocli parser treated options and positional parameters with type char[] as array (multi-value) options, except for interactive options. However, it is more intuitive to treat all char[] options as single-value options, similar to String options.

For end users, this means that existing applications that use non-interactive char[] options will no longer allow multiple characters to be specified separately on the command line. That is, input like -c A -c B -c C will be rejected and the user needs to specify -c ABC instead.

Applications that want to preserve the previous behaviour will need to change their code to use java.lang.Character[] instead of char[].

Fixed issues

  • [#1599] API: The picocli-codegen artifact is now an explicitly declared named JPMS module with a module-info.class.
  • [#1611] API: The picocli-groovy artifact is now an explicitly declared named JPMS module with a module-info.class.
  • [#1610] API: The picocli-shell-jline2 is now an explicitly declared named JPMS module with a module-info.class.
  • [#1609] API: The picocli-shell-jline3 is now an explicitly declared named JPMS module with a module-info.class.
  • [#1608] API: The picocli-spring-boot-starter is now an explicitly declared named JPMS module with a module-info.class. NOTE: its module name changed to info.picocli.spring.boot from info.picocli.spring.
  • [#1614] API: Change picocli-spring-boot-starter JPMS module name to info.picocli.spring.boot from info.picocli.spring.
  • [#1600] API: Add requires static java.sql to picocli module-info.
  • [#1471] API: Provide a programmatic way to configure Picocli's TraceLevel. Thanks to ekinano for raising this.
  • [#1125] API: Add parser configuration to allow options to consume values that match subcommand names or option names.
  • [#1396][#1401] API: Support generic types in containers (e.g. List, Map). Thanks to Michał Górniewski for the pull request.
  • [#1380][#1505] API, bugfix: requiredOptionMarker should not be displayed on ArgGroup options. Thanks to Ahmed El Khalifa for the pull request.
  • [#1563] API: Add constructor to PicocliSpringFactory to allow custom fallback IFactory. Thanks to Andrew Holland for raising this.
  • [#1767][#1802] API: avoid NPE on OptionSpec.getValue() and add IScoped internal API. Thanks to Ruud Senden for the discussion and the pull request.
  • [#1574] API: Add annotation API to control whether synopsis should be sorted alphabetically or by explicit order.
  • [#1708][#1712][#1723] API: The setUsageHelpLongOptionsMaxWidth method no longer throws an exception when an invalid value is specified; instead, the value is ignored and an INFO-level trace message is logged. Thanks to Fabio for the pull request.
  • [#648][#1846] Enhancement: Treat char[] as single-value types (Potentially breaking change). Thanks to Lukáš Petrovický for the pull request with the test to verify the solution.
  • [#1571] Enhancement: Variables in values from the default value provider should be interpolated. Thanks to Bas Passon for raising this.
  • [#1773] Enhancement: Applications can improve startup time by setting system property picocli.disable.closures to true to disable support for closures in annotations. Thanks to patric-r for raising this.
  • [#1408] Enhancement: Synopsis should respect order if specified. Thanks to Simon for raising this.
  • [#964][#1080] Enhancement: ArgGroup synopsis should respect order (if specified). Thanks to Enderaoe for the pull request with unit tests.
  • [#1706][#1710] Enhancement: Subcommands should get missing messages from parent command resource bundle. Thanks to Ruud Senden and Mike Snowden for the pull request.
  • [#899][#1578][#1579] Enhancement: improve built-in Help command description. Thanks to Michael L Heuer for the pull request. Thanks to Garret Wilson for raising this.
  • [#1713][#1714] Enhancement: Support optional booleans in annotation processor. Thanks to Jan Waś for the pull request.
  • [#1387][#1711] Enhancement: Annotation processor should validate final primitive and String fields with Option and Parameters annotations. Thanks to xehpuk for raising this, and thanks to Adam McElwee for the pull request.
  • [#1572] Enhancement: Remove redundant braces in ArgGroup synopsis.
  • [#1602] Enhancement: Fix incorrect debug output for add/removeAlias.
  • [#1603] Enhancement: Improve debug tracing information for help requests and command execution.
  • [#1629] Enhancement: Omit empty braces in standard prompt for interactive options without description. Thanks to Andreas Deininger for raising this.
  • [#1778] Enhancement: Add support for new Spring Boot auto configuration introduced in Spring Boot 2.7. Thanks to Andreas Asplund for the pull request.
  • [#1836][#1841] Enhancement: Command aliases on Mixin were not being applied. Thanks to Mike Snowden for the pull request and to Ruud Senden for raising this.
  • [#1754][#1759] Enhancement: Autocompletion now correctly handles completion candidates with spaces. Thanks to Juan Martín Sotuyo Dodero for the pull request.
  • [#1834][#1838] Bugfix: Incorrect synopsis for char[] options. Thanks to Ruud Senden and Mike Snowden for the pull request.
  • [#1680] Bugfix: ArgGroups with multiplicity="0" are now disallowed at construction time and no longer throw a StackOverflowError while parsing. Thanks to ARNOLD Somogyi for raising this.
  • [#1615][#1616] Bugfix: getCJKAdjustedLength() no longer miscalculates for supplementary code points. Thanks to gwalbran for the pull request.
  • [#1575] Bugfix: Synopsis should not cluster boolean options if posixClusteredShortOptionsAllowed is set to false.
  • [#1642] Bugfix: Negatable options should negate explicit values. Thanks to Nat Burns for raising this.
  • [#1696][#1697] Bugfix: ManPageGenerator asciidoc output now correctly shows options in nested ArgGroups. Thanks to Ruud Senden for the pull request.
  • [#1741] Bugfix: @Command-annotated method parameters are assigned incorrect indices when contained in a @Command class that is added as a subcommand to another @Command class which has scope = CommandLine.ScopeType.INHERIT. Thanks to Onedy for raising this.
  • [#1779] Bugfix: Custom factory should be used when creating CommandSpec. Thanks to Philippe Charles for raising this.
  • [#1644][#1863] Bugfix: autocompletion of directory names stopped working from picocli 4.6.3. Thanks to NewbieOrange for the pull request, and thanks to philgdn for raising this and verifying the solution.
  • [#1807] BUILD: Optimize incremental builds and local build cache usage. Thanks to Jean André Gauthier for the pull request and Nelson Osacky for the review.
  • [#1298] DOC: Publish all-in-one javadoc for all picocli modules.
  • [#812] DOC: Document how to test a picocli spring-boot application.
  • [#1596] DOC: fix javadoc typos and incorrect links.
  • [#1597] DOC: Add examples to Execution Configuration section in user manual.
  • [#1140] DOC: Add subsection Forcing Interactive Input to user manual Interactive Options section. Thanks to smalirizvi for raising this.
  • [#967] DOC: User manual now shows how to configure null as defaultValue and fallbackValue.
  • [#1625] DOC: Fix broken links after renaming default branch to main from master. Thanks to Andreas Deininger for the pull request.
  • [#1628][#1630] DOC: Fix broken link in picocli-codegen README. Thanks to Andreas Deininger for the pull request.
  • [#1627] DOC: User guide, chapter 3.2.3. Forcing Interactive Input: code sample: add Kotlin version. Thanks to Andreas Deininger for the pull request.
  • [#1650] DOC: User guide, Spring Boot section: add warning about dynamic proxies. Thanks to Ernst Plüss for raising this.
  • [#1677] DOC: Many improvements and corrections to the user manual. Thanks to Björn Kautler for the pull request.
  • [#1678] DOC: Change links from http to https, fix broken links. Thanks to Andreas Deininger for the pull request.
  • [#1750] DOC: Clarify that GPL licensing NOTICE is for docs only.
  • [#1788] DOC: add link to picocli-examples in the user manual. Thanks to Markus Elfring for raising this.
  • [#1796] DOC: Fixing broken links and typos. Thanks to Andreas Deininger for the pull request.
  • [#1798] DOC: update examples for jakarta.validation-api. Thanks to Roy for raising this.
  • [#1803] DOC: show @Command-annotated method with int return value in user manual. Thanks to SinaMobasheri for raising this.
  • [#1581] BUILD: Fix dependabot config.
  • [#1613] DEP: The picocli-groovy module now declares groovy-all as dependency.
  • [#1604] DEP: Remove dependency on slf4j from picocli-spring-boot-starter.
  • [#1783] DEP: Update actions/checkout requirement to 2541b1294d2704b0964813337f33b291d3f8596b
  • [#1837] DEP: Bump actions/checkout from 3.0.2 to 3.1.0
  • [#1607] DEP: Bump actions/setup-java from 2.5.0 to 3
  • [#1646] DEP: Bump actions/setup-java from 3.0.0 to 3.1.0
  • [#1655] DEP: Bump actions/setup-java from 3.1.0 to 3.1.1
  • [#1667] DEP: Bump actions/setup-java from 3.1.1 to 3.2.0
  • [#1674] DEP: Bump actions/setup-java from 3.2.0 to 3.3.0
  • [#1717] DEP: Bump actions/setup-java from 3.3.0 to 3.4.0
  • [#1736] DEP: Bump actions/setup-java from 3.4.0 to 3.4.1
  • [#1806] DEP: Bump actions/setup-java from 3.4.1 to 3.5.0
  • [#1826] DEP: Bump actions/setup-java from 3.5.0 to 3.5.1
  • [#1624] DEP: Bump actions/upload-artifact from 2.3.1 to 3
  • [#1687] DEP: Bump actions/upload-artifact from 3.0.0 to 3.1.0
  • [#1859] DEP: Bump actions/upload-artifact from 3.1.0 to 3.1.1
  • [#1585] DEP: Bump github/codeql-action from 1.0.30 to 1.1.0
  • [#1593] DEP: Bump github/codeql-action from 1.1.0 to 1.1.2
  • [#1601] DEP: Bump github/codeql-action from 1.1.2 to 1.1.3
  • [#1631] DEP: Bump github/codeql-action from 1.1.3 to 1.1.4
  • [#1636] DEP: Bump github/codeql-action from 1.1.4 to 1.1.5
  • [#1643] DEP: Bump github/codeql-action from 1.1.5 to 2.1.6
  • [#1652] DEP: Bump github/codeql-action from 2.1.6 to 2.1.7
  • [#1654] DEP: Bump github/codeql-action from 2.1.7 to 2.1.8
  • [#1669] DEP: Bump github/codeql-action from 2.1.8 to 2.1.9
  • [#1676] DEP: Bump github/codeql-action from 2.1.9 to 2.1.10
  • [#1682] DEP: Bump github/codeql-action from 2.1.10 to 2.1.11
  • [#1700] DEP: Bump github/codeql-action from 2.1.11 to 2.1.12
  • [#1720] DEP: Bump github/codeql-action from 2.1.12 to 2.1.14
  • [#1728] DEP: Bump github/codeql-action from 2.1.14 to 2.1.15
  • [#1739] DEP: Bump github/codeql-action from 2.1.15 to 2.1.16
  • [#1781] DEP: Bump github/codeql-action from 2.1.18 to 2.1.1
  • [#1786] DEP: Bump github/codeql-action from 2.1.18 to 2.1.20
  • [#1792] DEP: Bump github/codeql-action from 2.1.20 to 2.1.21
  • [#1797] DEP: Bump github/codeql-action from 2.1.21 to 2.1.22
  • [#1817] DEP: Bump github/codeql-action from 2.1.22 to 2.1.23
  • [#1820] DEP: Bump github/codeql-action from 2.1.22 to 2.1.24
  • [#1823] DEP: Bump github/codeql-action from 2.1.24 to 2.1.25
  • [#1831] DEP: Bump github/codeql-action from 2.1.25 to 2.1.26
  • [#1842] DEP: Bump github/codeql-action from 2.1.26 to 2.1.27
  • [#1862] DEP: Bump github/codeql-action from 2.1.28 to 2.1.29
  • [#1782] DEP: Bump gradle/gradle-build-action from c6619898ec857b418d6436d3efe8a0becf74eb9e to 2.2.4
  • [#1787] DEP: Bump gradle/gradle-build-action from c6619898ec857b418d6436d3efe8a0becf74eb9e to 2.2.5
  • [#1825] DEP: Bump gradle/gradle-build-action from 2.3.0 to 2.3.1
  • [#1832] DEP: Bump gradle/gradle-build-action from 2.3.1 to 2.3.2
  • [#1860] DEP: Bump gradle/gradle-build-action from 2.3.2 to 2.3.3
  • [#1861] DEP: Bump gradle/wrapper-validation-action from 1.0.4 to 1.0.5
  • [#1586] DEP: Bump ossf/scorecard-action from 1.0.2 to 1.0.3
  • [#1594] DEP: Bump ossf/scorecard-action from 1.0.3 to 1.0.4
  • [#1691] DEP: Bump ossf/scorecard-action from 1.0.4 to 1.1.0
  • [#1699] DEP: Bump ossf/scorecard-action from 1.1.0 to 1.1.1
  • [#1805] DEP: Bump ossf/scorecard-action from 1.1.2 to 2.0.0
  • [#1813] DEP: Bump ossf/scorecard-action from 2.0.0 to 2.0.2
  • [#1816] DEP: Bump ossf/scorecard-action from 2.0.0 to 2.0.3
  • [#1828] DEP: Bump ossf/scorecard-action from 2.0.3 to 2.0.4
  • [#1583] DEP: Bump step-security/harden-runner from 1.3.0 to 1.4.0
  • [#1639] DEP: Bump step-security/harden-runner from 1.4.0 to 1.4.1
  • [#1666] DEP: Bump step-security/harden-runner from 1.4.1 to 1.4.2
  • [#1730] DEP: Bump step-security/harden-runner from 1.4.3 to 1.4.4
  • [#1833] DEP: Bump step-security/harden-runner from 1.4.5 to 1.5.0
  • [#1580] DEP: Bump asciidoctor to 2.5.3 from 2.5.2. Thanks to Andreas Deininger for the pull request.
  • [#1688] DEP: Bump asciidoctorj-pdf from 1.6.2 to 2.0.0
  • [#1690] DEP: Bump asciidoctorj-pdf from 2.0.0 to 2.0.2
  • [#1692] DEP: Bump asciidoctorj-pdf from 2.0.2 to 2.0.3
  • [#1694] DEP: Bump asciidoctorj-pdf from 2.0.3 to 2.0.4
  • [#1695] DEP: Bump asciidoctorj-pdf from 2.0.4 to 2.0.6
  • [#1715] DEP: Bump asciidoctorj-pdf from 2.0.6 to 2.0.8
  • [#1722] DEP: Bump asciidoctorj-pdf from 2.0.8 to 2.1.2
  • [#1785] DEP: Bump asciidoctorj-pdf from 2.1.6 to 2.3.0
  • [#1854] DEP: Bump asciidoctorj-pdf from 2.3.0 to 2.3.3
  • [#1618] DEP: Bump biz.aQute.bnd.gradle from 6.1.0 to 6.2.0
  • [#1698] DEP: Bump biz.aQute.bnd.gradle from 6.2.0 to 6.3.0
  • [#1703] DEP: Bump biz.aQute.bnd.gradle from 6.3.0 to 6.3.1
  • [#1582] DEP: Bump groovy-all from 2.4.10 to 2.5.15 // latest version of Groovy that supports Java 5
  • [#1589] DEP: Bump hamcrest-core from 1.3 to 2.2
  • [#1621] DEP: Bump hibernate-validator from 7.0.2.Final to 7.0.3.Final
  • [#1633][#1635] DEP: Bump hibernate-validator from 7.0.3.Final to 7.0.4.Final
  • [#1821] DEP: Bump hibernate-validator from 7.0.5.Final to 8.0.0.Final
  • [#1812] DEP: Bump hibernate-validator from 7.0.5.Final to 8.0.0.Final
  • [#1622] DEP: Bump hibernate-validator-annotation-processor from 7.0.2.Final to 7.0.3.Final
  • [#1634] DEP: Bump hibernate-validator-annotation-processor from 7.0.3.Final to 7.0.4.Final
  • [#1587] DEP: Bump ivy from 2.4.0 to 2.5.0
  • [#1584] DEP: Bump jansi from 2.1.0 to 2.4.0
  • [#1573] DEP: Bump JLine3 version to 3.21.0 from 3.19.0.
  • [#1590] DEP: Bump junit-dep from 4.11 to 4.11.20120805.1225
  • [#1591] DEP: Bump junit from 4.12 to 4.13.2
  • [#1649] DEP: Bump kotlin-gradle-plugin from 1.6.10 to 1.6.20
  • [#1829] DEP: Bump kotlin-gradle-plugin from 1.7.10 to 1.7.20
  • [#1648] DEP: Bump kotlin-script-runtime from 1.6.10 to 1.6.20
  • [#1830] DEP: Bump kotlin-script-runtime from 1.7.10 to 1.7.20
  • [#1617] DEP: Bump log4j2Version from 2.17.1 to 2.17.2
  • [#1729] DEP: Bump log4j2Version from 2.17.2 to 2.18.0
  • [#1819] DEP: Bump log4j2Version from 2.18.0 to 2.19.0
  • [#1822] DEP: Bump scala-library from 2.13.8 to 2.13.9
  • [#1843] DEP: Bump scala-library from 2.13.9 to 2.13.10
  • [#1576] DEP: Bump Spring Boot version from 2.5.6 to 2.6.3
  • [#1606] DEP: Bump Spring Boot version from 2.6.3 to 2.6.4
  • [#1641] DEP: Bump Spring Boot version from 2.6.4 to 2.6.5
  • [#1645] DEP: Bump Spring Boot version from 2.6.5 to 2.6.6
  • [#1684] DEP: Bump Spring Boot version from 2.6.7 to 2.6.8
  • [#1686] DEP: Bump Spring Boot version from 2.6.8 to 2.7.0
  • [#1719] DEP: Bump Spring Boot version from 2.7.0 to 2.7.1
  • [#1747] DEP: Bump Spring Boot version from 2.7.1 to 2.7.2
  • [#1780] DEP: Bump spring Boot Version from 2.7.2 to 2.7.3
  • [#1824] DEP: Bump springBootVersion from 2.7.3 to 2.7.4
  • [#1853] DEP: Bump springBootVersion from 2.7.4 to 2.7.5
  • [#1588] DEP: Bump system-rules from 1.17.1 to 1.19.0

Deprecations

No features were deprecated in this release.

Potential breaking changes

  • The JPMS module name of picocli-spring-boot-starter has been changed to info.picocli.spring.boot from info.picocli.spring.
  • The picocli-groovy module now declares groovy-all as dependency.
  • The parser now treats char[] as a single-value type.
  • Redundant braces are now omitted in ArgGroup synopsis in usage help messages.
Assets 17