All Versions
409
Latest Version
Avg Release Cycle
-
Latest Release
-

Changelog History
Page 33

  • v3.0.0-mixinStandardHelpOptions Changes

    🚀 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.

  • v3.0.0-HelpCommand Changes

    🚀 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 help for the parent command or sibling subcommands. For example:

    @Command(subcommands = HelpCommand.class)
class AutoHelpDemo implements Runnable {

    @Option(names = "--option", description = "Some option.")
    String option;

    @Override public void run() { }
}

  • v3.0.0-fixes Changes

    • 🛠 [#371] Fixed bug where autocompletion did not work correctly for subcommands with embedded hyphens. Thanks to Paulius Fadelis for the bug report.
    • [#372] Simplify Kotlin example in user manual. Thanks to Dustin Spicuzza.

  • v3.0.0-exit Changes

    0️⃣ From picocli v3.0, the built-in parse result handlers (RunFirst, RunLast and RunAll) and exception handler (DefaultExceptionHandler) can specify an exit code. If an exit code was specified, the handler terminates the JVM with the specified status code when finished.

    @Command class ExitCodeDemo implements Runnable {
    public void run() { throw new ParameterException(new CommandLine(this), "exit code demo"); }

    public static void main(String... args) {
        CommandLine cmd = new CommandLine(new ExitCodeDemo());
        cmd.parseWithHandlers(
                new RunLast().andExit(123),
                new DefaultExceptionHandler().andExit(456),
                args);
    }
}

    🖨 Running this command prints the following to stderr and exits the JVM with status code 456.

    exit code demo
Usage: <main class>

    Custom handlers can extend AbstractHandler to inherit this behaviour.

  • v3.0.0-deprecated

  • v3.0.0-breaking

  • v3.0.0-beta 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 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

  • v3.0.0-alpha Changes

    🚀 This release offers a programmatic API for creating command line applications, in addition to annotations. 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.

    Note that the programmatic API is incubating and the API may change in subsequent releases. If you have suggestions for improving the programmatic API, please raise a ticket on GitHub!

    Example

    CommandSpec spec = CommandSpec.create();
spec.mixinStandardHelpOptions(true); // usageHelp and versionHelp 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);

commandLine.parseWithSimpleHandlers(new AbstractSimpleParseResultHandler() {
    public void handle(ParseResult pr) {
        int count = pr.optionValue('c', 1);
        List<File> files = pr.positionalValue(0, Collections.<File>emptyList());
        for (int i = 0; i < count; i++) {
            for (File f : files) {
                System.out.printf("%d: %s%n", i, f);
            }
        }
    }
}, args);

    CommandSpec (INCUBATING)

    🔧 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 (INCUBATING)

    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.

  • v2.3.0-toc Changes

  • v2.3.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.