picocli/CHANGELOG and picocli Releases

All Versions

409

Latest Version

4.7.0-toc

Avg Release Cycle

Latest Release

Changelog History

Page 32

v3.0.0 Changes
- New and noteworthy
- Promoted features
- 🛠 Fixed issues
- 🗄 Deprecations
- Potential breaking changes

v3.0.0-UsageHelpLayout Changes

🛠 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 gave strange-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 (up to 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

v3.0.0-Unmatched Changes

🚀 Unmatched arguments are the command line arguments that could not be assigned to any of the defined options or positional parameters. From this release, fields annotated with @Unmatched will be populated with the unmatched arguments. The field must be of type String[] or List<String>.

💻 If picocli finds a field annotated with @Unmatched, it automatically sets unmatchedArgumentsAllowed to true so no UnmatchedArgumentException is thrown when a command line argument cannot be assigned to an option or positional parameter.
v3.0.0-StricterArity Changes
🚀 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.

v3.0.0-std Changes

🖨 From picocli v3.0, the run and call convenience methods follow unix conventions: print to stdout when the user requested help, and print to stderr when the input was invalid or an unexpected error occurred.

💅 Custom handlers can extend AbstractHandler to facilitate following this convention. AbstractHandler also provides useOut and useErr methods to allow customizing the target output streams, and useAnsi to customize the Ansi style to use:

@Command class CustomizeTargetStreamsDemo implements Runnable {
    public void run() { ... }

    public static void main(String... args) {
        CommandLine cmd = new CommandLine(new CustomizeTargetStreamsDemo());

        PrintStream myOut = getOutputPrintStream(); // custom stream to send command output to
        PrintStream myErr = getErrorPrintStream();  // custom stream for error messages

        cmd.parseWithHandlers(
                new RunLast().useOut(myOut).useAnsi(Help.Ansi.ON),
                new DefaultExceptionHandler().useErr(myErr).useAnsi(Help.Ansi.OFF),
                args);
    }
}

v3.0.0-ShowDefault Changes
🚀 This release adds a showDefaultValue attribute to the @Option and @Parameters annotation. This allows you to specify for each individual option and positional parameter whether its default value should be shown in the usage help.

This attribute accepts three values:
- 0️⃣ ALWAYS - always display the default value of this option or positional parameter, even null values, regardless what value of showDefaultValues was specified on the command
- 0️⃣ NEVER - don't show the default value for this option or positional parameter, regardless what value of showDefaultValues was specified on the command
- 0️⃣ ON_DEMAND - (this is the default) only show the default value for this option or positional parameter if showDefaultValues was specified on the command
🔒 The NEVER value is useful for security sensitive command line arguments like passwords. The ALWAYS value is useful when you only want to show the default value for a few arguments but not for all (in combination with @Command(showDefaultValues = false)).
v3.0.0-promoted Changes

👍 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.
v3.0.0-Programmatic Changes
🚀 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.

0️⃣ 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.
v3.0.0-ParseResult Changes

📜 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.
v3.0.0-new

picocli changelog

Changelog History Page 32

Example

CommandSpec

OptionSpec and PositionalParamSpec

v3.0.0-new

Changelog History

Page 32