picocli 2.1.0

Picocli 2.1.0

This release contains bugfixes and new features.

Users sometimes run into system limitations on the length of a command line when creating a command line with lots of options or with long arguments for options. Starting from this release, picocli supports "argument files" or "@-files". Argument files are files that themselves contain arguments to the command. When picocli encounters an argument beginning with the character `@', it expands the contents of that file into the argument list.

Secondly, this release adds support for multi-value boolean flags. A common use case where this is useful is to let users control the level of output verbosity by specifying more -v flags on the command line. For example, -v could give high-level output, -vv could show more detailed output, and -vvv could show debug-level information.

Finally, thanks to aadrian and RobertZenz, an examples subproject containing running examples has been added. (Your contributions are welcome!)

This is the sixteenth public release.
Picocli follows semantic versioning.

Table of Contents

• New and noteworthy
• Promoted features
• Fixed issues
• Deprecations
• Potential breaking changes

New and noteworthy

Argument Files (@-files)

An argument file can include options and positional parameters in any combination. The arguments within a file can be space-separated or newline-separated. If an argument contains embedded whitespace, put the whole argument in double or single quotes ("-f=My Files\Stuff.java").

Lines starting with # are comments and are ignored. The file may itself contain additional @-file arguments; any such arguments will be processed recursively.

Multiple @-files may be specified on the command line.

For example, suppose a file with arguments exists at /home/foo/args, with these contents:

# This line is a comment and is ignored.
ABC -option=123
'X Y Z'

A command may be invoked with the @file argument, like this:

java MyCommand @/home/foo/args

The above will be expanded to the contents of the file:

java MyCommand ABC -option=123 "X Y Z"

This feature is similar to the 'Command Line Argument File' processing supported by gcc, javadoc and javac. The documentation for these tools shows further examples.

Repeated Boolean Flags

Multi-valued boolean options are now supported. For example:

@Option(names = "-v", description = { "Specify multiple -v options to increase verbosity.",
                                      "For example, `-v -v -v` or `-vvv`"})
boolean[] verbosity;

Users may specify multiple boolean flag options without parameters. For example:

<command> -v -v -v -vvv

The above example results in six true values being added to the verbosity array.

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

• [#126] New feature: Support expanding argument files, also called @-files.
• [#241] New feature (enhancing [#126]): Recursively process nested @-files; allow multiple arguments per line, allow quoted arguments with embedded whitespace.
• [#217] New feature: Support repeated boolean flag options captured in multi-valued fields.
• [#223] New feature: Added examples subproject containing running examples. Thanks to aadrian and RobertZenz.
• [#68] Enhancement: Reject private final primitive fields annotated with @option or @parameters: because compile-time constants are inlined, updates by picocli to such fields would not be visible to the application.
• [#239] Enhancement: Improve error message when Exception thrown from Runnable/Callable.
• [#240] Bugfix: RunAll handler should return empty list, not null, when help is requested.
• [#244] Bugfix: the parser only considered help options instead of any of help, usageHelp and versionHelp to determine if missing required options can be ignored when encountering a subcommand. Thanks to mkavanagh.

Deprecations

The Range::defaultArity(Class) method is now deprecated in favour of the Range::defaultArity(Field) method introduced in v2.0.

Potential breaking changes

Private final fields that are either String or primitive types can no longer be annotated with @Option or @Parameters.
Picocli will throw an InitializationException when it detects such fields,
because compile-time constants are inlined, and updates by picocli to such fields would not be visible to the application.

picocli 2.0.3

Picocli 2.0.3

The picocli community is pleased to announce picocli 2.0.3.

This is a bugfix release that fixes a parser bug where the first argument following a clustered options was treated as a positional parameter.

Picocli 2.0 accidentally introduced a transitive required dependency on groovy-lang. This is not desirable: Java applications using picocli don’t need this dependency.

Groovy scripts using the @PicocliScript annotation also don’t need this dependency because the Groovy runtime provides it. The picocli 2.0.3 release makes groovy-lang a compile-only dependency so it doesn’t appear in the POM.

This release also includes a minor enhancement to support embedded newlines in usage help sections like header or descriptions. This allows Groovy applications to use triple-quoted and dollar slashy multi-line strings in usage help sections.

This is the fifteenth public release.
Picocli follows semantic versioning.

Table of Contents

• New and noteworthy
• Promoted features
• Fixed issues
• Deprecations
• Potential breaking changes

New and noteworthy

This is a bugfix release and does not include any new features.

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

• [#230] Enhancement: Support embedded newlines in usage help sections like header or descriptions. Thanks to ddimtirov.
• [#233] Bugfix: Parser bug: first argument following clustered options is treated as a positional parameter. Thanks to mgrossmann.
• [#232] Bugfix: Remove required runtime dependency on groovy-lang. Thanks to aadrian.

Deprecations

This release does not deprecate any features.

Potential breaking changes

This release does not include any breaking features.

picocli 2.0.2

Picocli 2.0.2

The picocli community is pleased to announce picocli 2.0.2.

This is a bugfix release that prevents an EmptyStackException from being thrown when the command line ends in a cluster of boolean options, and furthermore fixes two scripting-related minor issues.

This is the fourteenth public release.
Picocli follows semantic versioning.

Table of Contents

• New and noteworthy
• Promoted features
• Fixed issues
• Deprecations
• Potential breaking changes

New and noteworthy

This is a bugfix release and does not include any new features.

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

• [#226] Bugfix: EmptyStackException when command line ends in a cluster of boolean options. Thanks to RobertZenz.
• [#222] Bugfix: Register default converter for Object fields for better scripting support.
• [#219] Bugfix: Command line system property -Dpicocli.trace (without value) throws exception when used with Groovy.
• [#220] Enhancement: Improve tracing for positional parameters (provide detail on current position).
• [#221] Enhancement: Add documentation for Grapes bug workaround on Groovy versions before 2.4.7.

Deprecations

This release does not deprecate any features.

Potential breaking changes

This release does not include any breaking features.

picocli 2.0.1

Picocli 2.0.1

The picocli community is pleased to announce picocli 2.0.1.

This is a bugfix release that removes a dependency on Java 1.7 which was accidentally included.

This is the thirteenth public release.
Picocli follows semantic versioning.

Table of Contents

• New and noteworthy
• Promoted features
• Fixed issues
• Deprecations
• Potential breaking changes

New and noteworthy

This is a bugfix release and does not include any new features.

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

• [#214] Removed a dependency on Java 1.7 that was accidentally included. Thanks to sjsajj.

Deprecations

This release does not deprecate any features.

Potential breaking changes

This release does not include any breaking features.

picocli 2.0

Picocli 2.0

The picocli community is pleased to announce picocli 2.0.

First, picocli now provides tight integration for Groovy scripts. The new @picocli.groovy.PicocliScript annotation allows Groovy scripts to use the @Command annotation, and turns a Groovy script into a picocli-based command line application. When the script is run, @Field variables annotated with @Option or @Parameters are initialized from the command line arguments before the script body is executed.

Applications with subcommands will also benefit from upgrading to picocli 2.0. The CommandLine.run and CommandLine.call methods now work for subcommands, and if more flexibility is needed, take a look at the new parseWithHandler methods. Error handling for subcommands has been improved in this release with the new ParseException.getCommandLine method.

Improved ease of use: Usage help is now printed automatically from the CommandLine.run and CommandLine.call methods and from the built-in handlers used with the parseWithHandler method.

The parser has been improved and users can now mix positional arguments with options on the command line. Previously, positional parameter had to follow the options. Important notice: To make this feature possible, the default parsing behaviour of multi-value options and parameters changed to be non-greedy by default.

Finally, this release includes many bug fixes.

This is the twelfth public release.
Picocli follows semantic versioning.

Table of Contents

• New and noteworthy
  • Groovy Script Support
  • Better Subcommand Support
  • Easier To Use
  • Parser Improvements
  • Usage Help Format Improvements
• Promoted features
• Fixed issues
• Deprecations
• Potential breaking changes

New and noteworthy

Groovy Script Support

Picocli 2.0 introduces special support for Groovy scripts.

Scripts annotated with @picocli.groovy.PicocliScript are automatically transformed to use picocli.groovy.PicocliBaseScript as their base class and can also use the @Command annotation to customize parts of the usage message like command name, description, headers, footers etc.

Before the script body is executed, the PicocliBaseScript base class parses the command line and initializes @Field variables annotated with @Option or @Parameters. The script body is executed if the user input was valid and did not request usage help or version information.

// exampleScript.groovy
@Grab('info.picocli:picocli:2.0.0')
@Command(name = "myCommand", description = "does something special")
@PicocliScript
import picocli.groovy.PicocliScript
import picocli.CommandLine.Command
import picocli.CommandLine.Option
import groovy.transform.Field

@Option(names = "-x", description = "number of repetitions")
@Field int count;

@Option(names = ["-h", "--help"], usageHelp = true, description = "print this help message and exit")
@Field boolean helpRequested;

//if (helpRequested) { // not necessary: PicocliBaseScript takes care of this
//    CommandLine.usage(this, System.err); return 0;
//}
count.times {
   println "hi"
}
// the CommandLine that parsed the args is available as a property
assert this.commandLine.commandName == "myCommand"

Better Subcommand Support

New methods CommandLine::parseWithHandler were added. These methods intend to offer the same ease of use as the run and call methods, but with more flexibility and better support for nested subcommands.

The CommandLine::call and CommandLine::run now support subcommands and will execute the last subcommand specified by the user. (Previously subcommands were ignored and only the top-level command was executed.)

From this release, picocli exceptions provide a getCommandLine method that returns the command or subcommand where parsing or execution failed. Previously, if the user provided invalid input for applications with subcommands, it was difficult to pinpoint exactly which subcommand failed to parse the input.

Easier To Use

The convenience methods will automatically print usage help and version information when the user specifies options annotated with the versionHelp or usageHelp attributes.

Methods that automatically print help:

• CommandLine::call
• CommandLine::run
• CommandLine::parseWithHandler (with the built-in Run…​ handlers)
• CommandLine::parseWithHandlers (with the built-in Run…​ handlers)

Methods that do not automatically print help:

• CommandLine::parse
• CommandLine::populateCommand

Also notable: Collection and Map fields no longer require the type annotation attribute: picocli now infers the conversion target type from the generic type parameters where possible.

Parser Improvements

Positional parameters can now be mixed with options on the command line. Previously, positional parameter had to follow the options.

To make this feature possible, the default parsing behaviour of multi-value options and parameters changed to be non-greedy by default.

Usage Help Format Improvements

This release contains various bugfixes related to improving the usage help format for multi-value options and collections. For example, for Maps that don't have a paramLabel, picocli now shows key type and value type instead of the internal Java field name.

Promoted features

Promoted features are features that were incubating in previous versions of picocli but are now supported and subject to backwards compatibility.

The following are the features that have been promoted in this picocli release.

• Autocomplete - as of picocli 2.0, autocompletion is no longer beta.

Fixed issues

• [#207] API Change: Provide ability to find which subcommand threw a ParameterException API enhancement. Thanks to velit and AshwinJay.
• [#179] API Change to remove full JRE dependency and require only Compact Profile. Replace use of java.awt.Point with picocli.CommandLine.Help.TextTable.Cell. Thanks to webfolderio.
• [#205] API Change: CommandLine::getCommand now returns a generic type instead of Object so client code can avoid type casting.
• [#196] API Change: Option::type() and Parameters::type() now return empty array by default (was {String.class}).
• [#210] API Change: Deprecated the option help attribute in favour of the usageHelp and versionHelp attributes.
• [#115] New feature: Added new CommandLine::parseWithHandler convenience methods for commands with subcommands.
• [#130] New feature: Options and positional parameters can now be mixed on the command line.
• [#196] New feature: Infer type from collections and maps when type annotation not specified. Thanks to ddimtirov for the suggestion.
• [#197] New feature: Use type attribute to determine conversion target type instead of field type. This allows fields to be declared as interfaces or abstract types (or arrays/collections/maps of these) and via the type attribute picocli will be able to convert String arguments to concrete implementation objects.
• [#187] New feature: Added methods to programmatically get and set the command name.
• [#192] Bugfix: Default arity should be 1, not *, for array and collection options. Thanks to RobertZenz.
• [#193] Bugfix: Splitting an argument should not cause max arity to be exceeded.
• [#191] Bugfix: Arity should not limit the total number of values put in an array or collection. Thanks to RobertZenz.
• [#186] Bugfix: Confusing usage message for collection options. Thanks to AlexFalappa.
• [#181] Bugfix: Incorrect help message was displayed for short options with paramLabel when arity > 1.
• [#184] Bugfix/Enhancement: Programmatically setting the separator is now reflected in the usage help message. Thanks to defnull.
• [#200] Bugfix: Prevent NPE when command name is set to empty string or spaces. Thanks to jansohn.
• [#203] Bugfix: Empty string parameter parsed incorrectly. Thanks to AshwinJay.
• [#194] Enhancement: Usage help should show split regex for option/parameters.
• [#198] Enhancement: Usage help parameter list details should indicate arity for positional parameters.
• [#195] Enhancement: Usage help should show Map types if paramLabel not specified.
• [#183] Enhancement: Add examples to user manual for using picocli in other JVM languages. Thanks to binkley for pointing out that Kotlin may support array literals in annotations from 1.2.
• [#185] Enhancement: Exception message text for missing options should not use field names but be more descriptive and consistent with usage help. Thanks to AlexFalappa.
• [#201] Enhancement: Usage help should not show null default values. Thanks to jansohn.
• [#202] Enhancement: Java 9: add Automatic-Module-Name: info.picocli to MANIFEST.MF to make picocli play nice in the Java 9 module system.
• [#204] Enhancement: instantiate LinkedHashSet instead of HashSet for Set fields to preserve input ordering.
• [#208] Enhancement: Remove pom.xml, which was not ...

picocli 1.0.1

Summary: zsh autocompletion bugfix

This is the eleventh public release.
Picocli follows semantic versioning.

• #178 Fixed autocompletion bug for subcommands in zsh. Autocomplete on zsh would show only the global command options even when a subcommand was specified. Autocompletion now works for nested subcommands.

picocli 1.0.0

Summary: command line autocompletion, -Dkey=value-like Map options, parser tracing, stricter parsing, bugfixes

This is the tenth public release. Picocli follows semantic versioning.

• #121 New feature: command line autocompletion. Picocli can generate bash and zsh completion scripts that allow the shell to generate potential completion matches based on the @Option and @Command annotations in your application. After this script is installed, the shell will show the options and subcommands available in your java command line application, and in some cases show possible option values.
• #67 New feature: Map options like -Dkey1=val1 -Dkey2=val2. Both key and value can be strongly typed (not just Strings).
• #158 New feature: parser TRACING for easy troubleshooting. The trace level can be controlled with a system property.
• #170 New feature: added call convenience method similar to run. Applications whose main business logic may throw an exception or returns a result can now implement Callable and reduce some boilerplate code.
• #149 Parser now throws UnmatchedArgumentException for args that resemble options but are not, instead of treating like them positional parameters. Thanks to giaco777.
• #172 Parser now throws MaxValuesforFieldExceededException when multi-valued option or parameters max arity exceeded
• #173 Parser now throws UnmatchedArgumentException when not all positional parameters are assigned to a field
• #171 WARN when option overwritten with different value (when isOverwrittenOptionsAllowed=true); WARN for unmatched args (when isUnmatchedArgumentsAllowed=true). Thanks to ddimtirov.
• #164 API change: Support format patterns in version string and printVersionHelp
• #167 API change: Change type attribute from Class to Class[]. This was needed for Map options support.
• #168 API change: CommandLine::setSeparator method now returns this CommandLine (was void), allowing for chained method calls.
• #156 Added example to user manual to clarify main command common usage. Thanks to nagkumar.
• #166 Fixed bug where adjacent markup sections resulted in incorrect ANSI escape sequences
• #174 Fixed bug where under some circumstances, unmatched parameters were added to UnmatchedParameters list twice

picocli 0.9.8

Improved version and usage help, improved subcommand support, bugfixes and enhancements.
API may change.

Issues Closed

• #162 Added new Version Help section to user manual; added version attribute on @Command; added CommandLine::printVersionHelp convenience method to print version information from this annotation to the console
• #145 Added usageHelp and versionHelp attributes on @Option; added CommandLine::isUsageHelpRequested and CommandLine::isVersionHelpRequested to allow external components to detect whether usage help or version information was requested (without inspecting the annotated domain object). Thanks to kakawait.
• #160 Added @since version in javadoc for recent API changes.
• #157 API change: added CommandLine::getParent method to get the parent command of a subcommand. Thanks to nagkumar.
• #152 Added support for registering subcommands declaratively with the @Command(subcommands={...}) annotation. Thanks to nagkumar.
• #146 Show underlying error when type conversion fails
• #147 Toggle boolean flags instead of setting to true
• #148 Long string in default value no longer causes infinite loop when printing usage. Thanks to smartboyathome.
• #142 First line of long synopsis no longer overshoots 80-character usage help width. Thanks to waacc-gh.

picocli 0.9.7

0.9.7 - Bugfix and enhancements release for public review. API may change.

Issues Closed

• #127 Added support for nested sub-subcommands
• #135 API change: renamed static convenience method CommandLine::parse to populateCommand
• #134 API change: CommandLine::parse now returns List<CommandLine> (was List<Object>)
• #133 API change: CommandLine::getCommands now returns Map<String, CommandLine> (was Map<String, Object>)
• #133 API change: Added method CommandLine::getCommand
• #136 API change: renamed method CommandLine::addCommand to addSubcommand;
• #136 API change: renamed method CommandLine::getCommands to getSubcommands
• #131 API change: Renamed class Arity to Range
• #137 Improve validation: disallow index gap in @parameters annotations
• #132 Improve validation: parsing should fail when unmatched arguments remain
• #138 Improve validation: disallow option overwriting by default
• #129 Make "allow option overwriting" configurable
• #140 Make "allow unmatched arguments" configurable
• #139 Improve validation: CommandLine must be constructed with a command that has at least one of @command, @option or @parameters annotation
• #141 Bugfix: prevent NullPointerException when sorting required options/parameters

picocli 0.9.6

Bugfix release for public review. API may change.

Issues Closed

• #128 Fix unexpected MissingParameterException when a help-option is supplied (bug)