Picocli 4.3.0
Picocli 4.3.0
The picocli community is pleased to announce picocli 4.3.0.
This is a fairly big release with 70 tickets closed, and over 50 bugfixes and enhancements. Many thanks to the picocli community who contributed 21 pull requests!
A major theme of this release is sharing options between commands:
- New feature: "inherited" options. Options defined with
scope = ScopeType.INHERIT
are shared with all subcommands (and sub-subcommands, to any level of depth). Applications can define an inherited option on the top-level command, in one place, to allow end users to specify this option anywhere: not only on the top-level command, but also on any of the subcommands and nested sub-subcommands. - More powerful mixins. Mixin classes can declare a
@Spec(MIXEE)
-annotated field, and picocli will inject theCommandSpec
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.
Another major theme is improved support for positional parameters:
- Automatic indexes for positional parameters. Single-value positional parameters without an explicit
index = "..."
attribute are now automatically assigned an index based on the other positional parameters in the command. One use case is mixins with positional parameters. - Repeatable ArgGroups can now define positional parameters.
Other improvements:
- The parser now supports case-insensitive mode for options and subcommands.
- Error handlers now use ANSI colors and styles. The default styles are bold red for the error message, and italic for stack traces. Applications can customize with the new
Help.ColorScheme
methodserrors
andstackTraces
. - The usage help message can now show an entry for
--
in the options list with the@Command(showEndOfOptionsDelimiterInUsageHelp = true)
annotation. - Easily make subcommands mandatory by making the top-level command a class that does not implement
Runnable
orCallable
.
This is the sixty-eighth public release.
Picocli follows semantic versioning.
Table of Contents
New and Noteworthy
Inherited Options
This release adds support for "inherited" options. Options defined with scope = ScopeType.INHERIT
are shared with all subcommands (and sub-subcommands, to any level of depth). Applications can define an inherited option on the top-level command, in one place, to allow end users to specify this option anywhere: not only on the top-level command, but also on any of the subcommands and nested sub-subcommands.
Below is an example where an inherited option is used to configure logging.
@Command(name = "app", subcommands = Sub.class)
class App implements Runnable {
private static Logger logger = LogManager.getLogger(App.class);
@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);
}
}
@Command(name = "sub")
class Sub implements Runnable {
private static Logger logger = LogManager.getLogger(Sub.class);
@Option(names = "-y")
int y;
public void run() {
logger.debug("-y={}", y);
}
}
Users can specify the -v
option on either the top-level command or on the subcommand, and it will have the same effect.
# the -v option can be specified on the top-level command
java App -x=3 -v sub -y=4
Specifying the -v
option on the subcommand will have the same effect. For example:
# specifying the -v option on the subcommand also changes the log level
java App -x=3 sub -y=4 -v
NOTE: Subcommands don't need to do anything to receive inherited options, but a potential drawback is that subcommands do not get a reference to inherited options.
Subcommands that need to inspect the value of an inherited option can use the @ParentCommand
annotation to get a reference to their parent command, and access the inherited option via the parent reference.
Alternatively, for such subcommands, sharing options via mixins may be a more suitable mechanism.
Case-insensitive mode
By default, all options and subcommands are case sensitive. Case sensitivity can be switched off globally, as well as on a per-command basis.
To toggle case sensitivity for all commands, use the CommandLine::setSubcommandsCaseInsensitive
and CommandLine::setOptionsCaseInsensitive
methods. Use the CommandSpec::subcommandsCaseInsensitive
and CommandSpec::optionsCaseInsensitive
methods to give some commands a different case sensitivity than others.
Automatic Indexes for Positional Parameters
From this release, when the index = "..."
attribute is omitted, the default index is index = "0+"
, which tells picocli to assign an index automatically, starting from zero, based on the other positional parameters defined in the same command.
A simple example can look like this:
class AutomaticIndex {
@Parameters(hidden = true) // "hidden": don't show this parameter in usage help message
List<String> allParameters; // no "index" attribute: captures _all_ arguments
@Parameters String group; // assigned index = "0"
@Parameters String artifact; // assigned index = "1"
@Parameters String version; // assigned index = "2"
}
Picocli initializes fields with the values at the specified index in the arguments array.
String[] args = { "info.picocli", "picocli", "4.3.0" };
AutomaticIndex auto = CommandLine.populateCommand(new AutomaticIndex(), args);
assert auto.group.equals("info.picocli");
assert auto.artifact.equals("picocli");
assert auto.version.equals("4.3.0");
assert auto.allParameters.equals(Arrays.asList(args));
The default automatic index (index = "0+"
) for single-value positional parameters is "anchored at zero": it starts at zero, and is increased with each additional positional parameter.
Sometimes you want to have indexes assigned automatically from a different starting point than zero. This can be useful when defining Mixins with positional parameters.
To accomplish this, specify an index with the anchor point and a +
character to indicate that picocli should start to automatically assign indexes from that anchor point. For example:
class Anchored {
@Parameters(index = "1+") String p1; // assigned index = "1" or higher
@Parameters(index = "1+") String p2; // assigned index = "2" or higher
}
Finally, sometimes you want to have indexes assigned automatically to come at the end. Again, this can be useful when defining Mixins with positional parameters.
To accomplish this, specify an index with a +
character to indicate that picocli should automatically assign indexes that come at the end. For example:
class Unanchored {
@Parameters(index = "+") String penultimate; // assigned the penultimate index in the command
@Parameters(index = "+") String last; // assigned the last index in the command
}
Repeatable ArgGroups with Positional Parameters
From this release, positional parameters can be used in repeating Argument Groups.
When a @Parameters
positional parameter is part of a group, its index
is the index within the group, not within the command.
Below is an example of an application that uses a repeating group of positional parameters:
@Command(name = "grades", mixinStandardHelpOptions = true, version = "grades 1.0")
public class Grades implements Runnable {
static class StudentGrade {
@Parameters(index = "0") String name;
@Parameters(index = "1") BigDecimal grade;
}
@ArgGroup(exclusive = false, multiplicity = "1..*")
List<StudentGrade> gradeList;
@Override
public void run() {
gradeList.forEach(e -> System.out.println(e.name + ": " + e.grade));
}
public static void main(String[] args) {
System.exit(new CommandLine(new Grades()).execute(args));
}
}
Running the above program with this input:
Alice 3.1 Betty 4.0 "X Æ A-12" 3.5 Zaphod 3.4
Produces the following output:
Alice: 3.1
Betty: 4.0
X Æ A-12: 3.5
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.
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.
For classes that are used as a mixins, there is another value that may be useful.
When @Spec(Spec.Target.MIXEE)
is specified in a mixin class, the CommandSpec
of the command receiving this mixin (the "mixee") is injected into the @Spec
-annotated field.
This can be useful when a mixin contains logic that is common to many commands. For example:
import picocli.CommandLine.Option;
import picocli.CommandLine.Spec;
class AdvancedMixin {
@Spec(Spec.Target.MIXEE) CommandSpec mixee;
/**
* When the -x option is specified on any subcommand,
* multiply its value with another integer supplied by this subcommand
* and set the result on the top-level command.
* @param x the value of the -x option
*/
@Option(names = "-x")
void setValue(int x) {
// Get another value from the command we are mixed into.
// This mixin requires the command(s) it is mixed into to implement `IntSupplier`.
int y = ((java.util.function.IntSupplier) mixee.userObject()).getAsInt();
int product = x * y;
// Set the result on the top-level (root) command.
// This mixin requires the root command to implement `IntConsumer`.
((java.util.function.IntConsumer) mixee.root().userObject()).accept(product);
}
}
Showing --
End of Options in usage help
From picocli 4.3, an entry for the --
End of Options delimiter can be shown in the options list of the usage help message of a command with the @Command(showEndOfOptionsDelimiterInUsageHelp = true)
annotation.
Example command:
@Command(name = "myapp", showEndOfOptionsDelimiterInUsageHelp = true,
mixinStandardHelpOptions = true, description = "Example command.")
class MyApp {
@Parameters(description = "A file.") File file;
}
The usage help message for this command looks like this:
Usage: myapp [-hV] [--] <file>
Example command.
<file> A file.
-h, --help Show this help message and exit.
-V, --version Print version information and exit.
-- This option can be used to separate command-line options from
the list of positional parameters.
Fixed issues
- [#649][#948] Provide convenience API for inherited/global options (was: Feature request: inheriting mixins in subcommands). Thanks to Garret Wilson for the request and subsequent discussion (and patience!).
- [#1001] Support required inherited options.
- [#996] Default values should not be applied to inherited options.
- [#985] API: Show end-of-options
--
in usage help options list. - [#958] API: Add
@Spec(Spec.Target.MIXEE)
annotation element to allow mixins to get a reference to the command they are mixed into. - [#960] API: Add method
CommandSpec::root
to return theCommandSpec
of the top-level command. - [#484][#845][#1008] API: Error handlers now use ANSI colors and styles. Added methods
errors
andstackTraces
toHelp.ColorScheme
. Thanks to Neko Null for the pull request. - [#765][#1017] API: Added
splitSynopsisLabel
attribute on@Option
and@Parameters
for controlling howsplit
regular expressions are displayed in the synopsis. Thanks to Murphy Han for the pull request and thanks to deining for raising this. - [#9][#1021][#1020][#1023][#154] API: Added support for case-insensitive subcommands and options. Thanks to NewbieOrange for the pull request, thanks to ifsheldon for exploring alternative solutions and helping clarify the requirements, and thanks to Neko Null for the pull request with documentation and executable examples.
- [#564] Add support for relative indices for positional parameters. Useful in mixins and inherited positional parameters. Thanks to krisleonard-mcafee for raising this topic.
- [#956] Enhancement: Default ParameterExceptionHandler should show stack trace when tracing is set to DEBUG level.
- [#952] Enhancement: Make annotation processor quiet by default; add
-Averbose
annotation processor option to enable printing NOTE-level diagnostic messages to the console. - [#959] Enhancement: Print "Missing required subcommand" instead of throwing exception if command with subcommands does not implement
Runnable
orCallable
. Thanks to Max Rydahl Andersen for the suggestion. - [#693][#1009][#1011] Enhancement: Add autocompletion for the built-in
HelpCommand
. Thanks to NewbieOrange for the pull request. - [#1022][#1029] Enhancement/Bugfix: Duplicate negated options were incorrectly accepted. Thanks to NewbieOrange for the pull request.
- [#1030][#1029] Enhancement/Bugfix:
setOptionsCaseInsensitive
should make negatable options case insensitive. Thanks to NewbieOrange for the pull request. - [#1027][#1036] Enhancement: Support repeatable ArgGroups with positional parameters. Thanks to NewbieOrange for the pull request.
- [#974] Enhancement/Bugfix: Add support for
@ArgGroup
argument groups in@Command
-annotated methods. Thanks to Usman Saleem for raising this. - [#962][#961] Enhancement/Bugfix: Default value should only be applied if value is missing. Thanks to 粟嘉逸 and chirlo for raising this.
- [#995][#1024][#1035] Enhancement/Bugfix: Reset multi-value options/positional params to initial value when reusing
CommandLine
instances. Thanks to Linyer-qwq, WU Jiangning, and Wycers for the pull request. - [#991][#993] Enhancement/Bugfix: Detecting terminal width fails on non-English Windows versions. Thanks to Stefan Gärtner for the pull request.
- [#1040] Enhancement: internal code cleanup and minor fixes. Thanks to NewbieOrange for the pull request.
- [#987] Bugfix: Bump JLine to 3.14.1 and fix [#969] autocompletion in Picocli Shell JLine3. Thanks to mattirn for the pull request.
- [#969] Bugfix: Fixed broken autocompletion for nested subcommands in Picocli Shell JLine3. Thanks to niklas97 for raising this.
- [#968] Bugfix: Avoid creating user object in Help constructor. Thanks to Immueggpain for raising this.
- [#990] Bugfix: Options in subcommands were not reset to their initial value between invocations when the
CommandLine
object is reused. Thanks to marinier for pointing this out. - [#984][#997] Bugfix: Parameters heading is now shown in the usage help message when
@filename
is the only parameter. Thanks to Wycer for the pull request. - [#1004] Bugfix: Prevent
NullPointerException
inIParameterConsumer
with@Option
in@ArgGroup
. Thanks to masupilami for raising this. - [#988][#1002] Bugfix: Option group sections in the usage help message now include subgroup options. Thanks to Wycer for the pull request.
- [#957] Bugfix: Debug tracing now shows variable value instead of variable name.
- [#955] Bugfix: TargetInvocationMessage handling in
MethodBinding.set
methods should usegetTargetException
notgetCause
; better error reporting. - [#1007] Bugfix: Custom Type Converters are missing for repeated subcommands. Thanks to Bastian Diehl for raising this.
- [#1026] Bugfix: Hidden options should not impact usage help.
- [#1034] Bugfix: Writer should
flush()
inUnmatchedArgumentException.printSuggestions
. Thanks to darkmoonka for raising this. - [#963] DOC: Fixed broken link in README. Thanks to vladimirf7 for the pull request.
- [#895] DOC: Added Initialization Before Execution section on initialization with subcommands to the user manual. Thanks to Walter Scott Johnson for raising this.
- [#951] DOC: Fixed typo in
picocli-codegen
annotation processor documentation:disable.resource.config
is correct (the option name was incorrectly spelled asdisable.resources.config
). Thanks to Max Rydahl Andersen for raising this. - [#966] DOC: Add section about Testing to the user manual.
- [#973] DOC: Update documentation for using the
picocli-codegen
annotation processor during the build with Kotlin. - [#972] DOC: Add section "Handling Invalid Input" for custom type converters to user manual, demonstrating
TypeConversionException
. Add exampleInetSocketAddressConverter
topicocli-examples
. Thanks to Simon for raising this. - [#975] DOC: Update user manual Annotation Processor section to use
${project.groupId}
instead of deprecated${groupId}
. Thanks to Dmitry Timofeev for the pull request. - [#976] DOC: Update user manual Testing section; add subsection on Testing Environment Variables. Thanks to David M. Carr for raising this and providing a sample project.
- [#979][#981] DOC: Update user manual: add section Options with an Optional Parameter. Thanks to razvanh, Jake and mohdpasha for raising this.
- [#989] DOC: Update examples for
picocli-shell-jline3
prior to and after the [#987][#969] bugfix. Thanks to Ralf D. Müller for raising this. - [#998] DOC: Update manual: quote option parameter containing pipe characters in
split
regex for FIX message example. Thanks to Galder Zamarreño and Max Rydahl Andersen for raising this and subsequent discussion. - [#1012] DOC: Update user manual: add to ArgGroup limitations. Thanks to masupilami and patric-r for raising this and subsequent discussion.
- [#1015] DOC: Update user manual: added section Variable Arity Options and Unknown Options. Thanks to Chris Smowton for raising this.
- [#1019] DOC: Fix PrintExceptionMessageHandler example. Thanks to Adam Hosman for the pull request.
- [#1006] DOC: Add Mixin example: MyLogger to the user manual.
- [#1028][#1031] DOC: Update user manual: added Java 15 text blocks example. Thanks to Enderaoe for the pull request.
- [#1037] DOC: Update user manual for programmatic API: fix typo. Thanks to Yoshida for the pull request.
- [#1041] DOC: Fix broken links in javaDoc. Thanks to Andreas Deininger for the pull request.
- [#1033] TEST: Added tests for [#984][#997]. Thanks to WU Jiangning for the pull request.
- [#965] Dependency Upgrade: in
picocli-examples
, bumphibernate-validator
from 6.0.2 to 6.1.2 to deal with CVE-2019-10219. Thanks to https://github.com/Security3rd for raising this.
Deprecations
No features were deprecated in this release.
Potential breaking changes
Behaviour has changed for some cases involving positional parameters.
One example is applications that define multiple positional parameters without an explicit index
(see next section).
I hope these are edge cases.
Other than that, some error messages and details of the usage help message have changed.
See details below.
Default index for single-value positional parameters
Prior to picocli 4.3.0, if your application defines any single-value positional parameters without explicit index
, these parameters would all point to index zero.
From picocli 4.3.0, picocli automatically assigns an index, so the first such parameter gets index 0
(zero), the next parameter gets index 1
(one), the next parameter gets index 2
(two), etc.
This may break applications that have multiple single-value positional parameters without explicit index
, that expect to capture the first argument in all of these parameters.
Different error when user specifies too many parameters
The error message has changed when a user specifies more positional parameters than the program can accept. For example:
class SingleValue {
@Parameters String str;
}
This program only accepts one parameter. What happens when this program is invoked incorrectly with two parameters, like this:
java SingleValue val1 val2
Before this release, picocli would throw an OverwrittenOptionException
with message "positional parameter at index 0..* (<str>) should be specified only once"
.
From picocli 4.3, picocli throws an UnmatchedArgumentException
with message "Unmatched argument at index 1: 'val2'"
.
This may break applications that have error handling that depends on an OverwrittenOptionException
being thrown.
Different mechanism for dealing with too many parameters
Continuing with the previous example, before this release, applications could deal with this by allowing single-value options to be overwritten:
// before
CommandLine cmd = new CommandLine(new SingleValue());
cmd.setOverwrittenOptionsAllowed(true);
// ...
From picocli 4.3, applications need to allow unmatched arguments instead:
// after
CommandLine cmd = new CommandLine(new SingleValue());
cmd.setUnmatchedArgumentsAllowed(true);
// ...
// get the invalid values
cmd.getUnmatchedArguments();
Usage help message for single-value positional parameters
Before picocli 4.3.0, single-value positional parameters would incorrectly show an ellipsis (...
) after their parameter label. This ellipsis is incorrect because it indicates that multiple values can be specified. The ellipsis is no longer shown for single-value positional parameters from picocli 4.3.0.
Before:
Usage: <main class> PARAM...
PARAM... Param description.
After:
Usage: <main class> PARAM
PARAM Param description.
This may break application tests that expect a specific usage help message format.
Different error for missing required options or parameters
Missing options list now starts with colon, no more square brackets
Before:
Missing required option '--required=<required>'
Missing required options [-a=<first>, -b=<second>, -c=<third>]
After:
Missing required option: '--required=<required>'
Missing required options: '-a=<first>', '-b=<second>', '-c=<third>'
Better message when both options and positional parameters are missing
Before:
Missing required options [-x=<x>, params[0]=<p0>, params[1]=<p1>]
After:
Missing required options and parameters: '-x=<x>', '<p0>', '<p1>'
Missing positional parameters are now quoted
Before:
Missing required parameter: <mandatory>
Missing required parameters: <mandatory>, <anotherMandatory>
After:
Missing required parameter: '<mandatory>'
Missing required parameters: '<mandatory>', '<anotherMandatory>'