Releases: remkop/picocli
Picocli 3.4.0
Picocli 3.4.0
The picocli community is pleased to announce picocli 3.4.0.
This release contains new features, bugfixes and enhancements.
The parser can now ignore case when parsing arguments for an Enum option or positional parameter.
New methods Help.Ansi.text(String) and Help.Ansi.string(String) assist client code in easily creating ANSI messages outside usage help and version help.
This is the thirty-fifth public release.
Picocli follows semantic versioning.
Table of Contents
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.
No features have been promoted in this picocli release.
Fixed issues
- [#14] New API: Support enum values to be parsed in an case-insensitive way.
- [#376] New API:
Help.Ansi.text(String)andHelp.Ansi.string(String)help client code easily create ANSI messages outside usage help and version help. - [#412] Enhancement: Enum constant names are now returned from
ArgSpec::completionCandidates(). Thanks to Radovan Panák. - [#417] Enhancement: Ensure bash scripts have correct line separators. Thanks to Holger Stenger.
- [#425] Enhancement: Fix autocomplete script errors in zsh. Thanks to Anthony Keenan.
- [#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.
Potential breaking changes
This release has no breaking changes.
Picocli 3.3.0
Picocli 3.3.0
The picocli community is pleased to announce picocli 3.3.0.
This release contains a bugfix for the JLine TAB completion support and improves the error messages for missing required parameters and unmatched arguments.
This is the thirty-fourth public release.
Picocli follows semantic versioning.
Table of Contents
New and Noteworthy
UnmatchedArgumentException Improvements
The UnmatchedArgumentException class now has several methods that allow an application to offer suggestions for fixes to the end user.
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);
}
}
}
}If you run this class with an invalid option that is similar to an actual option, the UnmatchedArgumentException.printSuggestions method will show the actual options. For example:
<cmd> -fi
Prints this output:
Unknown option: -fi
Possible solutions: --file, --find
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.
No features have been promoted in this picocli release.
Fixed issues
- [#411] Bugfix: Completion candidates were only generated for the first option, not for subsequent options.
- [#409] Enhancement: Improve error message for missing required positional parameters. Thanks to Mārtiņš Kalvāns and Olle Lundberg.
- [#298] Enhancement: Add help for mistyped commands and options. Added new API to
UnmatchedArgumentException. Thanks to Philippe Charles.
Deprecations
No features were deprecated in this release.
Potential breaking changes
The error message format has changed. This may impact client tests that expect a specific error message.
picocli 3.2.0
Picocli 3.2.0
The picocli community is pleased to announce picocli 3.2.0.
This release contains new features and enhancements:
- Improved support for Dependency Injection
- Methods can now be annotated with
@Optionand@Parameters - Support for JLine-based interactive command line interfaces (
completionCandidatesattribute on@Optionand@Parameters, and theAutoComplete.completemethod) - New
@Specannotation for injecting a command with itsCommandSpec
This is the thirty-third public release.
Picocli follows semantic versioning.
Table of Contents
New and Noteworthy
Dependency Injection
This release makes integration with Dependency Injection containers extremely easy:
CommandLineconstructor now accepts aClassinstance as the user object, and will delegate to theIFactoryto get an instance.- New
CommandLine.run(Class<Runnable>, IFactory, ...)andCommandLine.call(Class<Callable>, IFactory, ...)methods. These work the same as the existingrunandcallmethods except that theRunnableorCallableinstance is created by the factory.
The below example shows how to create an IFactory implementation with a Guice Injector:
import com.google.inject.*;
import picocli.CommandLine.IFactory;
public class GuiceFactory implements IFactory {
private final Injector injector = Guice.createInjector(new DemoModule());
@Override
public <K> K create(Class<K> aClass) throws Exception {
return injector.getInstance(aClass);
}
static class DemoModule extends AbstractModule {
@Override
protected void configure() {
bind(java.util.List.class).to(java.util.LinkedList.class);
bind(Runnable.class).to(InjectionDemo.class);
}
}
}Use the custom factory when creating a CommandLine instance, or when invoking the run or call convenience methods:
import javax.inject.Inject;
@Command(name = "di-demo")
public class InjectionDemo implements Runnable {
@Inject java.util.List list;
// @Option(names = "-x") int x; // add options etc as needed...
public static void main(String[] args) {
CommandLine.run(Runnable.class, new GuiceFactory(), args);
}
@Override
public void run() {
assert list instanceof java.util.LinkedList;
}
}Annotated Methods
From this release, @Option and @Parameter annotations can be added to methods as well as fields of a class.
For concrete classes, annotate "setter" methods (methods that accept a parameter) and when the option is specified on the command line, picocli will invoke the method with the value specified on the command line, converted to the type of the method parameter.
Alternatively, you may annotate "getter-like" methods (methods that return a value) on an interface, and picocli will create an instance of the interface that returns the values specified on the command line, converted to the method return type. This feature is inspired by Jewel CLI.
Annotating Methods of an Interface
The @Option and @Parameters annotations can be used on methods of an interface that return a value. For example:
interface Counter {
@Option(names = "--count")
int getCount();
}You use it by specifying the class of the interface:
CommandLine cmd = new CommandLine(Counter.class); // specify a class
String[] args = new String[] {"--count", "3"};
cmd.parse(args);
Counter counter = cmd.getCommand(); // picocli created an instance
assert counter.getCount() == 3; // method returns command line valueAnnotating Methods of a Concrete Class
The @Option and @Parameters annotations can be used on methods of a class that accept a parameter. For example:
class Counter {
int count;
@Option(names = "--count")
void setCount(int count) {
this.count = count;
}
}You use it by passing an instance of the class:
Counter counter = new Counter(); // the instance to populate
CommandLine cmd = new CommandLine(counter);
String[] args = new String[] {"--count", "3"};
cmd.parse(args);
assert counter.count == 3; // method was invoked with command line valueJLine Tab-Completion Support
This release adds support for JLine Tab-Completion.
Jline 2.x and 3.x is a Java library for handling console input, often used to create interactive shell applications.
Command line applications based on picocli can generate completion candidates for the command line in the JLine shell. The generated completion candidates are context sensitive, so once a subcommand is specified, only the options for that subcommand are shown, and once an option is specified, only parameters for that option are shown.
Below is an example picocli Completer implementation for JLine 2.x:
import jline.console.completer.ArgumentCompleter;
import jline.console.completer.Completer;
import picocli.AutoComplete;
import picocli.CommandLine;
import picocli.CommandLine.Model.CommandSpec;
import java.util.List;
public class PicocliJLineCompleter implements Completer {
private final CommandSpec spec;
public PicocliJLineCompleter(CommandSpec spec) {
this.spec = spec;
}
@Override
public int complete(String buffer, int cursor, List<CharSequence> candidates) {
// use the jline internal parser to split the line into tokens
ArgumentCompleter.ArgumentList list =
new ArgumentCompleter.WhitespaceArgumentDelimiter().delimit(buffer, cursor);
// let picocli generate completion candidates for the token where the cursor is at
return AutoComplete.complete(spec,
list.getArguments(),
list.getCursorArgumentIndex(),
list.getArgumentPosition(),
cursor,
candidates);
}
}Completion Candidates
From this release, @Options and @Parameters have a new completionCandidates attribute that can be used to generate a list of completions for this option or positional parameter. For example:
static class MyAbcCandidates extends ArrayList<String> {
MyAbcCandidates() { super(Arrays.asList("A", "B", "C")); }
}
class ValidValuesDemo {
@Option(names = "-o", completionCandidates = MyAbcCandidates.class)
String option;
}This will generate completion option values A, B and C in the generated bash auto-completion script and in JLine.
${DEFAULT-VALUE} Variable
From picocli 3.2, it is possible to embed the default values in the description for an option or positional parameter by
specifying the variable ${DEFAULT-VALUE} in the description text.
Picocli uses reflection to get the default values from the annotated fields.
The variable is replaced with the default value regardless of the @Command(showDefaultValues) attribute
and regardless of the @Option(showDefaultValues) or @Parameters(showDefaultValues) attribute.
class DefaultValues {
@Option(names = {"-f", "--file"},
description = "the file to use (default: ${DEFAULT-VALUE})")
File file = new File("config.xml");
}
CommandLine.usage(new DefaultValues(), System.out);This produces the following usage help:
Usage: <main class> -f=<file>
-f, --file=<file> the file to use (default: config.xml)
${COMPLETION-CANDIDATES} Variable
Similarly, it is possible to embed the completion candidates in the description for an option or positional parameter by
specifying the variable ${COMPLETION-CANDIDATES} in the description text.
This works for java enum classes and for options or positional parameters of non-enum types for which completion candidates are specified.
enum Lang { java, groovy, kotlin, javascript, frege, clojure }
static class MyAbcCandidates extends ArrayList<String> {
MyAbcCandidates() { super(Arrays.asList("A", "B", "C")); }
}
class ValidValuesDemo {
@Option(names = "-l", description = "Enum. Values: ${COMPLETION-CANDIDATES}")
Lang lang = null;
@Option(names = "-o", completionCandidates = MyAbcCandidates.class,
description = "Candidates: ${COMPLETION-CANDIDATES}")
String option;
}
CommandLine.usage(new ValidValuesDemo(), System.out);This produces the following usage help:
Usage: <main class> -l=<lang> -o=<option>
-l=<lang> Enum. Values: java, groovy, kotlin, javascript, frege, clojure
-o=<option> Candidates: A, B, C
@Spec Annotation
A new @Spec annotation is now available that injects the CommandSpec model of the command into a command field.
This is useful when a command needs to use the picocli API, for example to walk the command hierarchy and iterate over its sibling commands.
This complements the @ParentCommand annotation; the @ParentCommand annotation injects a user-defined command object, whereas this annotation injects a picocli class.
class InjectSpecExample implements Runnable {
@Spec CommandSpec commandSpec;
//...
public void run() {
// do something with the i...picocli 3.1.0
Picocli 3.1.0
The picocli community is pleased to announce picocli 3.1.0.
This release contains bugfixes and support for command aliases.
Picocli has a new logo! Many thanks to Reallinfo for the design!
This is the thirty-second public release.
Picocli follows semantic versioning.
Table of Contents
New and Noteworthy
Command Aliases
This release adds support for command aliases.
@Command(name = "top", subcommands = {SubCommand.class},
description = "top level command")
static class TopLevelCommand { }
@Command(name = "sub", aliases = {"s", "sb"},
description = "I'm a subcommand")
static class SubCommand {}
new CommandLine(new TopLevelCommand()).usage(System.out);The above would print the following usage help message:
Usage: top [COMMAND]
top level command
Commands:
sub, s, sb I'm a subcommand
Promoted Features
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.
Fixed issues
- [#288] New feature: add support for command aliases.
- [#383] Enhancement: Reallinfo designed the new picocli logo. Amazing work, many thanks!
- [#388] Bugfix: Prevent AnnotationFormatError "Duplicate annotation for class" with @PicocliScript when the script contains classes. Thanks to Bradford Powell for the bug report.
Deprecations
No features were deprecated in this release.
Potential breaking changes
This release has no breaking changes.
picocli 3.0.2
Picocli 3.0.2
The picocli community is pleased to announce picocli 3.0.2.
This release contains bugfixes and enhancements for programmatic configuration.
This is the thirty-first public release.
Picocli follows semantic versioning.
Table of Contents
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.
No features have been promoted in this picocli release.
Fixed issues
- [#381] Bugfix: Prevent NPE when adding programmatically created subcommands to CommandLine. Thanks to Mikusch for the bug report.
- [#382] Enhancement: Subcommand name should be initialized when added to parent.
Deprecations
No features were deprecated in this release.
Potential breaking changes
This release has no breaking changes.
picocli 3.0.1
Picocli 3.0.1
The picocli community is pleased to announce picocli 3.0.1.
This release fixes a bug for map options and has several improvements for the usage help message, especially for subcommands.
This is the thirtieth public release.
Picocli follows semantic versioning.
Table of Contents
New and Noteworthy
From this release, the usage help synopsis of the subcommand shows not only the subcommand name but also the parent command name. For example, take the following hierarchy of subcommands.
@Command(name = "main", subcommands = {Sub.class}) class App { }
@Command(name = "sub", subcommands = {SubSub.class}) class Sub { }
@Command(name = "subsub", mixinStandardHelpOptions = true) class SubSub { }
CommandLine parser = new CommandLine(new App());
ParseResult result = parser.parseArgs("sub", "subsub", "--help");
CommandLine.printHelpIfRequested(result);The above code prints the usage help for the subsub nested subcommand. Notice that this shows not only the subcommand name but the full command hierarchy:
Usage: main sub subsub [-hV]
-h, --help Show this help message and exit.
-V, --version Print version information and exit.
Promoted Features
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.
Fixed issues
- [#287] Enhancement: Subcommand help now also shows parent command name in synopsis.
- [#378] Bugfix: Map option problem when value contains '=' separator. Thanks to Markus Kramer for the bug report.
- [#377] Bugfix: Standard help options should be added last: when
mixinStandardHelpOptionsis set andsortOptionsis false, the help options should appear after the command options in the usage help message.
Deprecations
No features were deprecated in this release.
Potential breaking changes
The usage help synopsis of the subcommand shows not only the subcommand name but also the parent command name (and parent's parent command name, up to the top-level command).
picocli 3.0.0
Picocli 3.0.0
The picocli community is pleased to announce picocli 3.0.0.
This release offers a programmatic API for creating command line applications, in addition to the annotations API. The programmatic API allows applications to dynamically create command line options on the fly, and also makes it possible to create idiomatic domain-specific languages for processing command line arguments, using picocli, in other JVM languages. The picocli community is proud to announce that Apache Groovy's CliBuilder DSL for command line applications has been rewritten to use the picocli programmatic API, starting from Groovy 2.5.
Another new feature in this release are Mixins. Mixins allow reusing common options, parameters and command attributes in multiple applications without copy-and-paste duplication.
This release aims to reduce boilerplate code in user applications even further with the new mixinStandardHelpOptions command attribute. Picocli adds standard usageHelp and versionHelp options to commands with this attribute. Additionally picocli now offers a HelpCommand that can be installed as a subcommand on any application command to provide usage help for the parent command or sibling subcommands.
From this release, picocli is better at following unix conventions: by default it now prints to stdout when the user requested help, and prints to stderr when the input was invalid or an unexpected error occurred. This release also gives better control over the process exit code.
A new @Unmatched annotation allows applications to easily capture unmatched arguments (arguments that could not be matched with any of the registered options or positional parameters).
Usage help message improvements: the usage help message width is now configurable, and the message layout is improved to reduce horizontal padding. Furthermore, you can now specify for individual options or positional parameters whether their default value should be shown in the description or hidden.
Finally, this release adds several options to configure parser behaviour. Picocli can now be configured to function like Apache Commons CLI, to facilitate migration from Apache Commons CLI to picocli.
This is the twenty-ninth public release.
Picocli follows semantic versioning.
Table of Contents
New and Noteworthy
Programmatic API
This release offers a programmatic API for creating command line applications, in addition to the annotations API. The programmatic API allows applications to dynamically create command line options on the fly, and also makes it possible to create idiomatic domain-specific languages for processing command line arguments, using picocli, in other JVM languages. (Example: Groovy CliBuilder.)
If you have suggestions for improving the programmatic API, please raise a ticket on GitHub!
Example
CommandSpec spec = CommandSpec.create();
spec.mixinStandardHelpOptions(true); // --help and --version options
spec.addOption(OptionSpec.builder("-c", "--count")
.paramLabel("COUNT")
.type(int.class)
.description("number of times to execute").build());
spec.addPositional(PositionalParamSpec.builder()
.paramLabel("FILES")
.type(List.class).auxiliaryTypes(File.class) // List<File>
.description("The files to process").build());
CommandLine commandLine = new CommandLine(spec);
try {
// see also the CommandLine.parseWithHandler(s) convenience methods
ParseResult pr = commandLine.parseArgs(args);
if (CommandLine.printHelpIfRequested(pr)) {
return;
}
int count = pr.matchedOptionValue('c', 1);
List<File> files = pr.matchedPositionalValue(0, Collections.<File>emptyList());
for (File f : files) {
for (int i = 0; i < count; i++) {
System.out.printf("%d: %s%n", i, f);
}
}
} catch (ParseException invalidInput) {
System.err.println(invalidInput.getMessage());
invalidInput.getCommandLine().usage(System.err);
}CommandSpec
CommandSpec models a command. It is the programmatic variant of the @Command annotation. It has a name and a version, both of which may be empty. It also has a UsageMessageSpec to configure aspects of the usage help message and a ParserSpec that can be used to control the behaviour of the parser.
OptionSpec and PositionalParamSpec
OptionSpec models a named option, and PositionalParamSpec models one or more positional parameters. They are the programmatic variant of the @Option and @Parameters annotations, respectively.
An OptionSpec must have at least one name, which is used during parsing to match command line arguments. Other attributes can be left empty and picocli will give them a reasonable default value. This defaulting is why OptionSpec objects are created with a builder: this allows you to specify only some attributes and let picocli initialise the other attributes. For example, if only the option’s name is specified, picocli assumes the option takes no parameters (arity = 0), and is of type boolean. Another example, if arity is larger than 1, picocli sets the type to List and the auxiliary type to String.
PositionalParamSpec objects don’t have names, but have an index range instead. A single PositionalParamSpec object can capture multiple positional parameters. The default index range is set to 0..* (all indices). A command may have multiple PositionalParamSpec objects to capture positional parameters at different index ranges. This can be useful if positional parameters at different index ranges have different data types.
Similar to OptionSpec objects, Once a PositionalParamSpec is constructed, its configuration becomes immutable, but its value can still be modified. Usually the value is set during command line parsing when a non-option command line argument is encountered at a position in its index range.
ParseResult
A ParseResult class is now available that allows applications to inspect the result of parsing a sequence of command line arguments.
This class provides methods to query whether the command line arguments included certain options or position parameters, and what the value or values of these options and positional parameters was. Both the original command line argument String value as well as a strongly typed value can be obtained.
Mixins for Reuse
Mixins are a convenient alternative to subclassing: picocli annotations from any class can be added to ("mixed in" with) another command. This includes options, positional parameters, subcommands and command attributes. Picocli autoHelp internally uses a mixin.
A mixin is a separate class with options, positional parameters, subcommands and command attributes that can be reused in other commands. Mixins can be installed by calling the CommandLine.addMixin method with an object of this class, or annotating a field in your command with @Mixin. Here is an example mixin class:
public class ReusableOptions {
@Option(names = { "-v", "--verbose" }, description = {
"Specify multiple -v options to increase verbosity.", "For example, `-v -v -v` or `-vvv`" })
protected boolean[] verbosity = new boolean[0];
}Adding Mixins Programmatically
The below example shows how a mixin can be added programmatically with the CommandLine.addMixin method.
CommandLine commandLine = new CommandLine(new MyCommand());
commandline.addMixin("myMixin", new ReusableOptions());@Mixin Annotation
A command can also include mixins by annotating fields with @Mixin. All picocli annotations found in the mixin class are added to the command that has a field annotated with @Mixin. For example:
@Command(name = "zip", description = "Example reuse with @Mixin annotation.")
public class MyCommand {
// adds the options defined in ReusableOptions to this command
@Mixin
private ReusableOptions myMixin;
}Standard Help Options
This release introduces the mixinStandardHelpOptions command attribute. When this attribute is set to true, picocli adds a mixin to the command that adds usageHelp and versionHelp options to the command. For example:
@Command(mixinStandardHelpOptions = true, version = "auto help demo - picocli 3.0")
class AutoHelpDemo implements Runnable {
@Option(names = "--option", description = "Some option.")
String option;
@Override public void run() { }
}Commands with mixinStandardHelpOptions do not need to explicitly declare fields annotated with @Option(usageHelp = true) and @Option(versionHelp = true) any more. The usage help message for the above example looks like this:
Usage: <main class> [-hV] [--option=<option>]
--option=<option> Some option.
-h, --help Show this help message and exit.
-V, --version Print version information and exit.
Help Command
From this release, picocli provides a help subcommand (picocli.CommandLine.HelpCommand) that can be installed as a subcommand on any application command to provide usage ...
picocli 3.0.0-beta-2
Picocli 3.0.0-beta-2
The picocli community is pleased to announce picocli 3.0.0-beta-2.
This release contains enhancements and bug fixes.
This is the twenty-eighth public release.
Picocli follows semantic versioning.
Table of Contents
New and Noteworthy
Stricter Arity Validation
Until this release, options with mandatory parameters would consume as many arguments as required, even if those arguments matched other option flags. For example:
Given a command like this:
class App {
@Option(names = "-a", arity = "2")
String[] a;
@Option(names = "-v")
boolean v;
}Prior to this change, the following input would be accepted:
<command> -a 1 -v
In previous versions, picocli accepted this and assigned "1" and "-v" as the two values for the -a option.
From this release, the parser notices that one of the arguments is an option and throws a MissingParameterException because not enough parameters were specified for the first option.
Promoted Features
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.
Fixed issues
- [#366] API Change: Add
ArgSpec.getTypedValues()method. - [#365] Enhancement: Stricter arity validation: options with mandatory parameters no longer consume other option flags.
- [#357] Enhancement: Improve synopsis format. Be more succinct when
limitSplitis true. Support repeating groups.
Deprecations
This release has no deprecations.
Potential breaking changes
- Stricter arity validation may break existing applications that intentionally consume arguments regardless of whether arguments are other options.
picocli 3.0.0-beta-1
Picocli 3.0.0-beta-1
The picocli community is pleased to announce picocli 3.0.0-beta-1.
This release contains enhancements and bug fixes.
This is the twenty-seventh public release.
Picocli follows semantic versioning.
Table of Contents
New and Noteworthy
Previously, the usage message layout had a fixed width long option name column: this column is always 24 characters, even if none of the options have a long option name.
This gives weird-looking usage help messages in some cases. For example:
@Command(name="ls")
class App {
@Option(names = "-a", description = "display all files") boolean a;
@Option(names = "-l", description = "use a long listing format") boolean l;
@Option(names = "-t", description = "sort by modification time") boolean t;
}The usage message for this example was:
Usage: ls [-alt]
-a display all files
-l use a long listing format
-t sort by modification time
From this release, picocli adjusts the width of the long option name column to the longest name (max 24).
The new usage message for this example looks like this:
Usage: ls [-alt]
-a display all files
-l use a long listing format
-t sort by modification time
Promoted Features
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.
Fixed issues
- [#364] API Change: Remove parser option
arityRestrictsCumulativeSize. - [#355] API Change: Add method
ArgSpec.hasInitialValue. - [#361] API Change: Add parser option
aritySatisfiedByAttachedOptionParamfor commons-cli compatibility. - [#363] API Change: Add parser option to limit the number of parts when splitting to max arity, for compatibility with commons-cli.
- [#360] Enhancement: Dynamically adjust width of long option name column (up to max 24).
Deprecations
Potential breaking changes
- The usage message format changed: it now dynamically adjusts the width of the long option name column. This may break tests.
- API Change: Removed parser option
arityRestrictsCumulativeSizeintroduced in 3.0.0-alpha-3.