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)

picocli 0.9.5

Bugfix release for public review. API may change.

Issues Closed

• #122 API change: remove field CommandLine.ansi (enhancement)
• #123 API change: make public Arity fields final (enhancement)
• #124 API change: make Help fields optionFields and positionalParameterFields final and unmodifiable (enhancement)
• #118 BumpVersion gradle task scrambles chars in manual (bug)
• #119 Add gradle task to publish to local folder (enhancement)