@remkop remkop released this Sep 12, 2018 · 3 commits to master since this release

Assets 4

Picocli 3.6.0

The picocli community is pleased to announce picocli 3.6.0.

This release contains new features, bugfixes and enhancements.

New interface: IDefaultProvider allows you to get default values from a configuration file or some other central place.

@Command Methods: From this release, methods can be annotated with @Command. The method parameters provide the command options and parameters.

Internationalization: from this release, usage help message sections and the description for options and positional parameters can be specified in a resource bundle. A resource bundle can be set via annotations and programmatically.

The error message on invalid user input has been improved.

This release also contains various improvements the the bash/zsh completion script generation to be more consistent with standard completion on these shells.

Many thanks to the many members of the picocli community who raised issues and contributed solutions!

This is the thirty-nineth public release.
Picocli follows semantic versioning.

Table of Contents

New and Noteworthy

Default Provider

This release allows you to specify a default provider in the @Command annotation:

@Command(defaultValueProvider = MyDefaultProvider.class)
class MyCommand // ...

The default provider allows you to get default values from a configuration file or some other central place.
Default providers need to implement the picocli.CommandLine.IDefaultValueProvider interface:

public interface IDefaultValueProvider {

    /**
     * Returns the default value for an option or positional parameter or {@code null}.
     * The returned value is converted to the type of the option/positional parameter
     * via the same type converter used when populating this option/positional
     * parameter from a command line argument.
     *
     * @param argSpec the option or positional parameter, never {@code null}
     * @return the default value for the option or positional parameter, or {@code null} if
     *       this provider has no default value for the specified option or positional parameter
     * @throws Exception when there was a problem obtaining the default value
     */
    String defaultValue(ArgSpec argSpec) throws Exception;
}

@Command Methods

From picocli 3.6, methods can be annotated with @Command. The method parameters provide the command options and parameters. For example:

class Cat {
    public static void main(String[] args) {
        CommandLine.invoke("cat", Cat.class, args);
    }

    @Command(description = "Concatenate FILE(s) to standard output.",
             mixinStandardHelpOptions = true, version = "3.6.0")
    void cat(@Option(names = {"-E", "--show-ends"}) boolean showEnds,
             @Option(names = {"-n", "--number"}) boolean number,
             @Option(names = {"-T", "--show-tabs"}) boolean showTabs,
             @Option(names = {"-v", "--show-nonprinting"}) boolean showNonPrinting,
             @Parameters(paramLabel = "FILE") File[] files) {
        // process files
    }
}

The usage help of the above command looks like this:

Usage: cat [-EhnTvV] [FILE...]
Concatenate FILE(s) to standard output.
      [FILE...]
  -E, --show-ends
  -h, --help               Show this help message and exit.
  -n, --number
  -T, --show-tabs
  -v, --show-nonprinting
  -V, --version            Print version information and exit.

See below for an example that uses a resource bundle to define usage help descriptions outside the code.

For positional parameters, the @Parameters annotation may be omitted on method parameters.

TIP: If compiled with the -parameters flag on Java 8 or higher, the paramLabel of positional parameters is obtained from the method parameter name using reflection instead of the generic arg0, arg1, etc.

Subcommand Methods

If the enclosing class is annotated with @Command, method commands are added as subcommands to the class command, unless the class command has attribute @Command(addMethodSubcommands = false).
For example:

@Command(name = "git", mixinStandardHelpOptions = true, version = "picocli-3.6.0")
class Git {
    @Option(names = "--git-dir", descriptionKey = "GITDIR")
    Path path;

    @Command
    void commit(@Option(names = {"-m", "--message"}) String commitMessage,
                @Option(names = "--squash", paramLabel = "<commit>") String squash,
                @Parameters(paramLabel = "<file>") File[] files) {
        // ... implement business logic
    }
}

Use @Command(addMethodSubcommands = false) on the class @Command annotation if the @Command-annotated methods in this class should not be added as subcommands.

The usage help of the git commit command looks like this:

Usage: git commit [--squash=<commit>] [-m=<arg0>] [<file>...]
      [<file>...]
      --squash=<commit>
  -m, --message=<arg0>

Internationalization

From version 3.6, usage help message sections and the description for options and positional parameters can be specified in a resource bundle. A resource bundle can be set via annotations and programmatically.

Annotation example:

@Command(name = "i18n-demo", resourceBundle = "my.org.I18nDemo_Messages")
class I18nDemo {}

Programmatic example:

@Command class I18nDemo2 {}

CommandLine cmd = new CommandLine(new I18nDemo2());
cmd.setResourceBundle(ResourceBundle.getBundle("my.org.I18nDemo2_Messages"));

Resources for multiple commands can be specified in a single ResourceBundle. Keys and their value can be shared by multiple commands (so you don't need to repeat them for every command), but keys can be prefixed with fully qualified command name + "." to specify different values for different commands. The most specific key wins.

This is especially convenient for @Command methods where long description annotations would make the code less easy to read.

You can use a resource bundle to move the descriptions out of the code:

# shared between all commands
help = Show this help message and exit.
version = Print version information and exit.

# command-specific strings
git.usage.description = Version control system
git.GITDIR = Set the path to the repository

git.commit.usage.description = Record changes to the repository
git.commit.message = Use the given <msg> as the commit message.
git.commit.squash = Construct a commit message for use with rebase --autosquash.
git.commit.<file>[0..*] = The files to commit.

With this resource bundle, the usage help for the above git commit command looks like this:

Usage: git commit [--squash=<commit>] [-m=<arg0>] [<file>...]
Record changes to the repository
      [<file>...]         The files to commit.
      --squash=<commit>   Construct a commit message for use with rebase
                            --autosquash.
  -m, --message=<arg0>    Use the given <msg> as the commit message.

Improved Error Messages

The error messages on invalid input have been improved. For example:

Previously, if an argument could not be converted to a primitive type, the error looked like this:

Could not convert 'abc' to int for option '-num': java.lang.NumberFormatException: For input string: \"abc\"

The new error message for primitive types looks like this:

Invalid value for option '-num': 'abc' is not an int

Previously, if an argument could not be converted to an enum, the error looked like this:

Could not convert 'xyz' to TimeUnit for option '-timeUnit': java.lang.IllegalArgumentException: No enum constant java.util.concurrent.TimeUnit.xyz

The new error message for enums looks like this:

Invalid value for option '-timeUnit': expected one of [NANOSECONDS, MILLISECONDS, MICROSECONDS, SECONDS, MINUTES, HOURS, DAYS] but was 'xyz'

Fixed issues

  • [#321] API: Add support for IDefaultValueProvider. Thanks to Nicolas MASSART for the pull request.
  • [#416] API: Added support for @Command annotation on methods (in addition to classes). Thanks to illes for the pull request.
  • [#433] API: Added method printHelpIfRequested that accepts a ColorScheme parameter. Thanks to Benny Bottema for the suggestion.
  • [#441] API: Added hideParamSyntax attribute to @Option and @Parameters to allow suppressing usage syntax decorations around the param label. Thanks to Benny Bottema for the pull request.
  • [#22], [#415], [#436] API: Added internationalization and localization support via resource bundles.
  • [#473] Enhancement: Improved error messages for invalid input.
  • [#461] Bugfix: Script auto-completion only suggests options and never default bash completions. Thanks to David Walluck for the pull request.
  • [#466] Bugfix: Script auto-completion should not generate suggestions for options with arguments that have no known completions. Thanks to David Walluck for the pull request.
  • [#470] Bugfix: Script auto-completion should generate suggestions for short options with arguments. Thanks to David Walluck for the pull request.
  • [#444] Bugfix: Usage help shows duplicate aliases if registered with same alias multiple times.
  • [#452] Doc: Add UML class diagrams to picocli Javadoc.
  • [#475] Doc: Renamed module examples to picocli-examples.
  • [#478] Doc: Add convenience API example to CommandLine class Javadoc.

Deprecations

No features were deprecated in this release.

Potential breaking changes

The error message displayed on invalid input is different from previous releases. This may break unit tests that expect an exact error message.

@remkop remkop released this Aug 14, 2018 · 109 commits to master since this release

Assets 4

Picocli 3.5.2

The picocli community is pleased to announce picocli 3.5.2.

This is a bugfix release that fixes an issue where subcommand aliases were not recognized in some cases.

This is the thirty-eighth 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

  • [#443] Bugfix: Subcommand aliases were not recognized in some cases. Thanks to K. Alex Mills for the bug report.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This release has no breaking changes.

@remkop remkop released this Aug 11, 2018 · 114 commits to master since this release

Assets 4

Picocli 3.5.1

The picocli community is pleased to announce picocli 3.5.1.

This is a bugfix release that fixes an issue where CommandSpec injected into Mixins had a null CommandLine.

This is the thirty-seventh 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

  • [#439] Bugfix: CommandSpec injected into Mixins had a null CommandLine. Thanks to Adam Zegelin for the bug report.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This release has no breaking changes.

@remkop remkop released this Aug 7, 2018 · 122 commits to master since this release

Assets 4

Picocli 3.5.0

The picocli community is pleased to announce picocli 3.5.0.

This release contains new features, bugfixes and enhancements.

Password support: for options and positional parameters marked as interactive, the user is prompted to enter a value on the console. When running on Java 6 or higher, picocli will use the Console.readPassword API so that user input is not echoed to the console.

Client code can now perform simple validation in annotated setter methods by throwing a ParameterException on invalid input.

Also, from this release, the comment character in @-files (argument files) and the end-of-options delimiter (-- by default) are configurable.

This is the thirty-sixth public release.
Picocli follows semantic versioning.

Table of Contents

New and Noteworthy

Interactive Options for Passwords or Passphrases

This release introduces password support: for options and positional parameters marked as interactive, the user is prompted to enter a value on the console. When running on Java 6 or higher, picocli will use the Console.readPassword API so that user input is not echoed to the console.

Example usage:

class Login implements Callable<Object> {
    @Option(names = {"-u", "--user"}, description = "User name")
    String user;

    @Option(names = {"-p", "--password"}, description = "Passphrase", interactive = true)
    String password;

    public Object call() throws Exception {
        MessageDigest md = MessageDigest.getInstance("SHA-256");
        md.update(password.getBytes());
        System.out.printf("Hi %s, your passphrase is hashed to %s.%n", user, base64(md.digest()));
        return null;
    }
    
    private String base64(byte[] arr) { /* ... */ }
}

When this command is invoked like this:

CommandLine.call(new Login(), "-u", "user123", "-p");

Then the user will be prompted to enter a value:

Enter value for --password (Passphrase): 

When running on Java 6 or higher, the user input is not echoed to the console.
After the user enters a value and presses enter, the call() method is invoked, which prints the following:

Hi user123, your passphrase is hashed to 75K3eLr+dx6JJFuJ7LwIpEpOFmwGZZkRiB84PURz6U8=.

Simple Validation in Setter Methods

Methods annotated with @Option and @Parameters can do simple input validation by throwing a ParameterException when invalid values are specified on the command line.

class ValidationExample {
    @Spec private CommandSpec spec; // injected by picocli
    
    private Map<String, String> properties = new LinkedHashMap<>();
    
    @Option(names = {"-D", "--property"}, paramLabel = "KEY=VALUE")
    public void setProperty(Map<String, String> map) {
        for (String key : map.keySet()) {
            String newValue = map.get(key);
            validateUnique(key, newValue);
            properties.put(key, newValue);
        }
    }

    private void validateUnique(String key, String newValue) {
        String existing = properties.get(key);
        if (existing != null && !existing.equals(newValue)) {
            throw new ParameterException(spec.commandLine(),
                    String.format("Duplicate key '%s' for values '%s' and '%s'.",
                    key, existing, newValue));
        }
    }
}

Prior to this release, the exception thrown from the method was wrapped in a java.lang.reflect.InvocationTargetException, which in turn was wrapped in a PicocliException, and finally in another ParameterException.

By following the recipe above and throwing a ParameterException on invalid input, all these intermediate exceptions are skipped.

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

  • [#430] Bugfix: formatting was incorrect (did not break on embedded newlines) in the subcommands list descriptions. Thanks to Benny Bottema for the bug report.
  • [#431] Better support for validation in setter methods: cleaner stack trace.
  • [#432] Make comment character in @-files (argument files) configurable.
  • [#359] Make end-of-options delimiter configurable.
  • [#82] Support reading passwords from the console with echoing disabled.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This release has no breaking changes.

@remkop remkop released this Aug 1, 2018 · 132 commits to master since this release

Assets 4

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) and Help.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.

@remkop remkop released this Jul 13, 2018 · 163 commits to master since this release

Assets 4

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.

@remkop remkop released this Jul 6, 2018 · 172 commits to master since this release

Assets 4

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 @Option and @Parameters
  • Support for JLine-based interactive command line interfaces (completionCandidates attribute on @Option and @Parameters, and the AutoComplete.complete method)
  • New @Spec annotation for injecting a command with its CommandSpec

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:

  • CommandLine constructor now accepts a Class instance as the user object, and will delegate to the IFactory to get an instance.
  • New CommandLine.run(Class<Runnable>, IFactory, ...) and CommandLine.call(Class<Callable>, IFactory, ...) methods. These work the same as the existing run and call methods except that the Runnable or Callable instance 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 value

Annotating 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 value

JLine 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 injected spec
   }
}
  

Lenient Parse Mode

This release adds the ability to continue parsing invalid input to the end.
When collectErrors is set to true, and a problem occurs during parsing, an Exception is added to the ParseResult.errors() list and parsing continues. The default behaviour (when collectErrors is false) is to abort parsing by throwing the Exception.

This is useful when generating completion candidates on partial input, and is also useful when using picocli in
languages like Clojure where idiomatic error handling does not involve throwing and catching exceptions.

When using this feature, applications are responsible for actively verifying that no errors occurred before executing the business logic. Use with care!

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

  • [#182] New Feature: Add support for annotating methods with @Option and @Parameters.
  • [#393] New feature: Add support for JLine completers.
  • [#389] New feature: Support 'lenient' parsing mode: don't throw Exceptions but add them to the ParseResult.errors() list and continue parsing.
  • [#392] New feature: Ability to map command line arguments to picocli spec elements. Internally used for generating completion candidates.
  • [#391] New feature: Add API to get completion candidates for option and positional parameter values of any type.
  • [#395] New feature: Allow embedding default values anywhere in description for @Option or @Parameters.
  • [#259] New Feature: Added @Spec annotation to inject CommandSpec into application field.
  • [#400] Enhancement: Add run/call static methods that accept an IFactory. This allows Dependency Injection containers to provide the Runnable/Callable implementation.
  • [#404] Enhancement: Ask IFactory for implementation before creating Proxy for interface. Needed for Dependency Injection.
  • [#398] Enhancement: Allow @PicocliScript annotation on Groovy script @Field variables instead of just on imports.
  • [#322] Enhancement: Add defaultValue attribute to @option and @parameters annotation.
  • [#375] Enhancement: Improve ParameterIndexGapException error message. Thanks to gpettey.
  • [#405] Enhancement: Add method CommandLine.getUsageMessage().
  • [#406] Enhancement: Added fields to ParameterException. Thanks to David Hait.
  • [#401] Doc: The user manual no longer includes the full CommandLine.java source code.

Deprecations

No features were deprecated in this release.

Potential breaking changes

This release has no breaking changes.

@remkop remkop released this Jun 11, 2018 · 220 commits to master since this release

Assets 4

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.

@remkop remkop released this May 23, 2018 · 258 commits to master since this release

Assets 4

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.

@remkop remkop released this May 14, 2018 · 263 commits to master since this release

Assets 4

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 mixinStandardHelpOptions is set and sortOptions is 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).