diff --git a/docs/man/3.x/announcing-picocli-1.0.html b/docs/man/3.x/announcing-picocli-1.0.html new file mode 100644 index 000000000..6f2f32df1 --- /dev/null +++ b/docs/man/3.x/announcing-picocli-1.0.html @@ -0,0 +1,645 @@ + + + + + + + + +Announcing picocli 1.0 - a mighty tiny command line interface + + + + + + + +
+
+
+
+
+Fork me on GitHub +
+
+
+

Picocli (http://picocli.info/) is a one-file framework for creating Java command line applications with almost zero code. A number of similar libraries already exist, so why create another one? There are three common concerns that have been mostly ignored by other command line parser libraries.

+
+
+
    +
  • +

    No extra dependencies for end users. How can we avoid adding a JAR?

    +
    • +
  • +

    Usage help should look beautiful, be customizable and use colors.

    +
    • +
  • +

    Command line TAB autocompletion. Because why not!

    +
    • +
+
+
+

Let’s look at how picocli tries to address these issues.

+
+
+
+
+

One Single Source File - Include as Source

+
+
+

How often have you chosen to write custom code to parse command line arguments instead of using a library because you didn’t want to burden your users with the extra dependency?

+
+
+

Picocli offers a way to let users run picocli-based applications without requiring the picocli library as an external dependency: all the source code lives in a single file, to encourage application authors to include it in source form. This is convenient for utility-like single-jar applications.

+
+
+

There are other ways to accomplish this, like JAR shading, but this is an alternative. It is easy to understand, easy to do, and it doesn’t require any special tooling. Application authors can upgrade to newer versions of picocli by replacing a single source file.

+
+
+

Binaries Available

+
+

Including as source is optional. If you prefer to use picocli as a library, that is fine. Picocli is distributed in binary form as well as source and its JAR file is available on Maven, Bintray JCenter and GitHub.

+
+
+
+
+
+

Customizable Usage Help - with ANSI Styles and Colors

+
+
+

Usage help is the face of a command line application. The generated help message should look great out of the box, but should also be easy to tweak.

+
+
+

Do you want your application’s usage help to look compact, or do you prefer a more spacious look? A good command line library should let you customize the usage help message to accomodate a variety of styles.

+
+
+

This is easily accomplished in picocli with annotations. Separate annotations exist for sections like description, header and footer. Text can be multi-line and each section has a customizable heading. If the annotations are not sufficient, picocli has a Help API that offers some building blocks for further customizing the help message. This may range from the basic (reordering sections and passing parameters for format specifiers in the headings or section text) to the more advanced (custom layouts for options).

+
+
+

ANSI styles and colors are applied automatically to the generated sections of the help message on supported platforms. Picocli uses a default color scheme for options, parameters and subcommands. This color scheme can be customized.

+
+
+

In addition, you can use ANSI colors and styles in your descriptions and headings by embedding markup like @|red text|@ in the annotations text. For example, generating usage for an annotated class like this:

+
+
+
+
@Command(description = "Custom @|bold,underline styles|@ and @|fg(red) colors|@.")
+class AnsiDescription { }
+CommandLine.usage(new AnsiDescription(), System.out);
+
+
+
+
+Custom description with ANSI styles and colors +
+
+
+

Below is an example of what kind of usage help messages can be created with just annotations.

+
+
+
+Picocli demo help message +
+
+
+
+
+

Command Line Completion

+
+
+

Picocli-based applications can have command line autocompletion on supported platforms.

+
+
+

Not all shells support programmable completion. Currently picocli autocompletion works only in the Bash and Zsh shells. Hopefully this is still useful: the Bash Unix shell has been distributed widely as the default login shell for most Linux distributions and Apple’s macOS. Windows 10 now offers native support for Bash, on older versions of Windows you may want to look at Cygwin or Babun.

+
+
+

How does this work? Picocli inspects the @Command and @Option annotations of your command class and generates a completion function. When this completion function is installed, pressing the TAB key shows the available options, option parameters and subcommands, for any level of nested subcommands. For options that accept files or directories, hosts, or Java enums, the shell will show the possible option values that match what the user typed so far.

+
+
+
+
+

Feedback Welcome

+
+
+

There is much more to picocli but hopefully the above has whetted your appetite.

+
+
+

Please give it a try and use the issue tracker to let me know your thoughts. Bug reports, documentation improvements, ideas, any feedback is welcome!

+
+
+

If you like the project, please star it on GitHub and tell your friends!

+
+
+
+
+ + + \ No newline at end of file diff --git a/docs/man/3.x/apidocs/allclasses-frame.html b/docs/man/3.x/apidocs/allclasses-frame.html new file mode 100644 index 000000000..581bac154 --- /dev/null +++ b/docs/man/3.x/apidocs/allclasses-frame.html @@ -0,0 +1,90 @@ + + + + + +All Classes (picocli 3.9.5 API) + + + + + +

All Classes

+
+ +
+ + diff --git a/docs/man/3.x/apidocs/allclasses-noframe.html b/docs/man/3.x/apidocs/allclasses-noframe.html new file mode 100644 index 000000000..2be05c415 --- /dev/null +++ b/docs/man/3.x/apidocs/allclasses-noframe.html @@ -0,0 +1,90 @@ + + + + + +All Classes (picocli 3.9.5 API) + + + + + +

All Classes

+
+ +
+ + diff --git a/docs/man/3.x/apidocs/constant-values.html b/docs/man/3.x/apidocs/constant-values.html new file mode 100644 index 000000000..714bb498b --- /dev/null +++ b/docs/man/3.x/apidocs/constant-values.html @@ -0,0 +1,385 @@ + + + + + +Constant Field Values (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ +
+

Constant Field Values

+

Contents

+ +
+
+ + +

picocli.*

+ + + + +

picocli.groovy.*

+ +
+ +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/deprecated-list.html b/docs/man/3.x/apidocs/deprecated-list.html new file mode 100644 index 000000000..c10cbc3df --- /dev/null +++ b/docs/man/3.x/apidocs/deprecated-list.html @@ -0,0 +1,272 @@ + + + + + +Deprecated List (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ +
+

Deprecated API

+

Contents

+ +
+
+ + + + + + + + + + + + + + + +
+ +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/help-doc.html b/docs/man/3.x/apidocs/help-doc.html new file mode 100644 index 000000000..9ce0b9128 --- /dev/null +++ b/docs/man/3.x/apidocs/help-doc.html @@ -0,0 +1,223 @@ + + + + + +API Help (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ +
+

How This API Document Is Organized

+
This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.
+
+
+ +This help file applies to API documentation generated using the standard doclet.
+ +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/index-all.html b/docs/man/3.x/apidocs/index-all.html new file mode 100644 index 000000000..5c29b8e3e --- /dev/null +++ b/docs/man/3.x/apidocs/index-all.html @@ -0,0 +1,3188 @@ + + + + + +Index (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ +
A B C D E F G H I J L M N O P Q R S T U V W  + + +

A

+
+
abbreviatedSynopsis() - Method in class picocli.CommandLine.Help
+
+
Generates a generic synopsis like <command name> [OPTIONS] [PARAM1 [PARAM2]...], omitting parts + that don't apply to the command (e.g., does not show [OPTIONS] if the command has no options).
+
+
abbreviateSynopsis() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns whether the synopsis line(s) should show an abbreviated synopsis without detailed option names.
+
+
abbreviateSynopsis(boolean) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets whether the synopsis line(s) should show an abbreviated synopsis without detailed option names.
+
+
AbstractHandler() - Constructor for class picocli.CommandLine.AbstractHandler
+
 
+
AbstractParseResultHandler() - Constructor for class picocli.CommandLine.AbstractParseResultHandler
+
 
+
add(CommandLine.Model.ArgSpec) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Adds the specified option spec or positional parameter spec to the list of configured arguments to expect.
+
+
add(CommandLine.Model.ArgSpec, int) - Method in class picocli.CommandLine.ParseResult.Builder
+
+
Adds the specified OptionSpec or PositionalParamSpec to the list of options and parameters + that were matched on the command line.
+
+
addAllSubcommands(Map<String, CommandLine>) - Method in class picocli.CommandLine.Help
+
+
Registers all specified subcommands with this Help.
+
+
addEmptyRow() - Method in class picocli.CommandLine.Help.TextTable
+
+
Adds the required char[] slots for a new row to the CommandLine.Help.TextTable.columnValues field.
+
+
addError(CommandLine.PicocliException) - Method in class picocli.CommandLine.ParseResult.Builder
+
 
+
addMethodSubcommands() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Reflects on the class of the user object and registers any command methods + (class methods annotated with @Command) as subcommands.
+
+
addMethodSubcommands(CommandLine.IFactory) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Reflects on the class of the user object and registers any command methods + (class methods annotated with @Command) as subcommands.
+
+
addMixin(String, Object) - Method in class picocli.CommandLine
+
+
Adds the options and positional parameters in the specified mixin to this command.
+
+
addMixin(String, CommandLine.Model.CommandSpec) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Adds the specified mixin CommandSpec object to the map of mixins for this command.
+
+
addOption(CommandLine.Model.OptionSpec, CommandLine.Help.IParamLabelRenderer) - Method in class picocli.CommandLine.Help.Layout
+
+
Delegates to the option renderer of this layout to obtain + text values for the specified CommandLine.Model.OptionSpec, and then calls the CommandLine.Help.Layout.layout(CommandLine.Model.ArgSpec, CommandLine.Help.Ansi.Text[][]) + method to write these text values into the correct cells in the TextTable.
+
+
addOption(CommandLine.Model.OptionSpec) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Adds the specified option spec to the list of configured arguments to expect.
+
+
addOption(CommandLine.Model.OptionSpec) - Method in class picocli.CommandLine.ParseResult.Builder
+
+
Adds the specified OptionSpec to the list of options that were matched on the command line.
+
+
addOptions(List<CommandLine.Model.OptionSpec>, CommandLine.Help.IParamLabelRenderer) - Method in class picocli.CommandLine.Help.Layout
+
+
Calls CommandLine.Help.Layout.addOption(CommandLine.Model.OptionSpec, CommandLine.Help.IParamLabelRenderer) for all non-hidden Options in the list.
+
+
addPositional(CommandLine.Model.PositionalParamSpec) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Adds the specified positional parameter spec to the list of configured arguments to expect.
+
+
addPositionalParam(CommandLine.Model.PositionalParamSpec, int) - Method in class picocli.CommandLine.ParseResult.Builder
+
+
Adds the specified PositionalParamSpec to the list of parameters that were matched on the command line.
+
+
addPositionalParameter(CommandLine.Model.PositionalParamSpec, CommandLine.Help.IParamLabelRenderer) - Method in class picocli.CommandLine.Help.Layout
+
+
Delegates to the parameter renderer of this layout + to obtain text values for the specified positional parameter, and then calls + CommandLine.Help.Layout.layout(CommandLine.Model.ArgSpec, CommandLine.Help.Ansi.Text[][]) to write these text values into the correct cells in the TextTable.
+
+
addPositionalParameters(List<CommandLine.Model.PositionalParamSpec>, CommandLine.Help.IParamLabelRenderer) - Method in class picocli.CommandLine.Help.Layout
+
+
Calls CommandLine.Help.Layout.addPositionalParameter(CommandLine.Model.PositionalParamSpec, CommandLine.Help.IParamLabelRenderer) for all non-hidden Parameters in the list.
+
+
addRowValues(String...) - Method in class picocli.CommandLine.Help.TextTable
+
+
Delegates to CommandLine.Help.TextTable.addRowValues(CommandLine.Help.Ansi.Text...).
+
+
addRowValues(CommandLine.Help.Ansi.Text...) - Method in class picocli.CommandLine.Help.TextTable
+
+
Adds a new empty row, then calls putValue for each of the specified values, adding more empty rows + if the return value indicates that the value spanned multiple columns or was wrapped to multiple rows.
+
+
addSubcommand(String, Object) - Method in class picocli.CommandLine
+
+
Registers a subcommand with the specified name.
+
+
addSubcommand(String, Object, String...) - Method in class picocli.CommandLine
+
+
Registers a subcommand with the specified name and all specified aliases.
+
+
addSubcommand(String, Object) - Method in class picocli.CommandLine.Help
+
+
Deprecated. 
+
+
addSubcommand(String, CommandLine.Model.CommandSpec) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Adds the specified subcommand with the specified name.
+
+
addSubcommand(String, CommandLine) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Adds the specified subcommand with the specified name.
+
+
addUnmatched(String) - Method in class picocli.CommandLine.ParseResult.Builder
+
+
Adds the specified command line argument to the list of unmatched command line arguments.
+
+
addUnmatched(Stack<String>) - Method in class picocli.CommandLine.ParseResult.Builder
+
+
Adds all elements of the specified command line arguments stack to the list of unmatched command line arguments.
+
+
addUnmatchedArgsBinding(CommandLine.Model.UnmatchedArgsBinding) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Adds the specified UnmatchedArgsBinding to the list of model objects to capture unmatched arguments for this command.
+
+
aliases() - Method in class picocli.CommandLine.Help
+
+
Returns the list of aliases for the command in this Help.
+
+
aliases() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the alias command names of this subcommand.
+
+
aliases(String...) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Sets the alternative names by which this subcommand is recognized on the command line.
+
+
andExit(int) - Method in class picocli.CommandLine.AbstractHandler
+
+
Indicates that the handler should call System.exit(int) after processing completes and sets the exit code to use as the termination status.
+
+
ansi() - Method in class picocli.CommandLine.AbstractHandler
+
+
Returns the ANSI style to use.
+
+
ansi() - Method in class picocli.CommandLine.Help
+
+
Returns whether ANSI escape codes are enabled or not.
+
+
ansi() - Method in class picocli.CommandLine.Help.ColorScheme
+
 
+
append(String) - Method in class picocli.CommandLine.Help.Ansi.Text
+
+
Deprecated. +
use CommandLine.Help.Ansi.Text.concat(String) instead
+
+
+
append(CommandLine.Help.Ansi.Text) - Method in class picocli.CommandLine.Help.Ansi.Text
+
+
Deprecated. +
use #concat(Text) instead
+
+
+
apply(String, List<CommandLine.Help.Ansi.IStyle>) - Method in enum picocli.CommandLine.Help.Ansi
+
+
Returns a new Text object where all the specified styles are applied to the full length of the + specified plain text.
+
+
applySystemProperties() - Method in class picocli.CommandLine.Help.ColorScheme
+
+
Replaces colors and styles in this scheme with ones specified in system properties, and returns this scheme.
+
+
args() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the list of all options and positional parameters configured for this command.
+
+
arity() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns how many arguments this option or positional parameter requires.
+
+
aritySatisfiedByAttachedOptionParam() - Method in class picocli.CommandLine.Model.ParserSpec
+
+
Returns true if options with attached arguments should not consume subsequent arguments and should not validate arity.
+
+
aritySatisfiedByAttachedOptionParam(boolean) - Method in class picocli.CommandLine.Model.ParserSpec
+
+
Returns true if options with attached arguments should not consume subsequent arguments and should not validate arity.
+
+
asCommandLineList() - Method in class picocli.CommandLine.ParseResult
+
+
Returns this ParseResult as a list of CommandLine objects, one for each matched command/subcommand.
+
+
atFileCommentChar() - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
atFileCommentChar(Character) - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
AutoComplete - Class in picocli
+
+
Stand-alone tool that generates bash auto-complete scripts for picocli-based command line applications.
+
+
auxiliaryTypes() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns auxiliary type information used when the CommandLine.Model.ArgSpec.type() is a generic Collection, Map or an abstract class.
+
+
+ + + +

B

+
+
bash(String, File, File, CommandLine) - Static method in class picocli.AutoComplete
+
+
Generates source code for an autocompletion bash script for the specified picocli-based application, + and writes this script to the specified out file, and optionally writes an invocation script + to the specified command file.
+
+
bash(String, CommandLine) - Static method in class picocli.AutoComplete
+
+
Generates and returns the source code for an autocompletion bash script for the specified picocli-based application.
+
+
bg(String) - Static method in enum picocli.CommandLine.Help.Ansi.Style
+
+
Parses the specified style markup and returns the associated style.
+
+
build() - Method in class picocli.CommandLine.Model.OptionSpec.Builder
+
+
Returns a valid OptionSpec instance.
+
+
build() - Method in class picocli.CommandLine.Model.PositionalParamSpec.Builder
+
+
Returns a valid PositionalParamSpec instance.
+
+
build() - Method in class picocli.CommandLine.ParseResult.Builder
+
+
Creates and returns a new ParseResult instance for this builder's configuration.
+
+
builder(String, String...) - Static method in class picocli.CommandLine.Model.OptionSpec
+
 
+
builder(String[]) - Static method in class picocli.CommandLine.Model.OptionSpec
+
 
+
builder() - Static method in class picocli.CommandLine.Model.PositionalParamSpec
+
 
+
builder(CommandLine.Model.CommandSpec) - Static method in class picocli.CommandLine.ParseResult
+
+
Creates and returns a new ParseResult.Builder for the specified command spec.
+
+
+ + + +

C

+
+
call(C, String...) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.call(Callable, PrintStream, PrintStream, Help.Ansi, String...) with System.out for + requested usage help messages, System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO.
+
+
call(C, PrintStream, String...) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.call(Callable, PrintStream, PrintStream, Help.Ansi, String...) with System.err for + diagnostic error messages and CommandLine.Help.Ansi.AUTO.
+
+
call(C, PrintStream, CommandLine.Help.Ansi, String...) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.call(Callable, PrintStream, PrintStream, Help.Ansi, String...) with System.err for diagnostic error messages.
+
+
call(C, PrintStream, PrintStream, CommandLine.Help.Ansi, String...) - Static method in class picocli.CommandLine
+
+
Convenience method to allow command line application authors to avoid some boilerplate code in their application.
+
+
call(Class<C>, CommandLine.IFactory, String...) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.call(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...) with System.out for + requested usage help messages, System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO.
+
+
call(Class<C>, CommandLine.IFactory, PrintStream, String...) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.call(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...) with + System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO.
+
+
call(Class<C>, CommandLine.IFactory, PrintStream, CommandLine.Help.Ansi, String...) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.call(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...) with + System.err for diagnostic error messages.
+
+
call(Class<C>, CommandLine.IFactory, PrintStream, PrintStream, CommandLine.Help.Ansi, String...) - Static method in class picocli.CommandLine
+
+
Convenience method to allow command line application authors to avoid some boilerplate code in their application.
+
+
caseInsensitiveEnumValuesAllowed() - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
caseInsensitiveEnumValuesAllowed(boolean) - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
Cell(int, int) - Constructor for class picocli.CommandLine.Help.TextTable.Cell
+
+
Constructs a new Cell with the specified coordinates in the table.
+
+
cellAt(int, int) - Method in class picocli.CommandLine.Help.TextTable
+
+
Deprecated. +
use CommandLine.Help.TextTable.textAt(int, int) instead
+
+
+
clone() - Method in class picocli.CommandLine.Help.Ansi.Text
+
 
+
collectErrors() - Method in class picocli.CommandLine.Model.ParserSpec
+
+
Returns true if exceptions during parsing should be collected instead of thrown.
+
+
collectErrors(boolean) - Method in class picocli.CommandLine.Model.ParserSpec
+
+
Sets whether exceptions during parsing should be collected instead of thrown.
+
+
colorScheme() - Method in class picocli.CommandLine.Help
+
+
Returns the ColorScheme model that this Help was constructed with.
+
+
ColorScheme() - Constructor for class picocli.CommandLine.Help.ColorScheme
+
+
Constructs a new empty ColorScheme with CommandLine.Help.Ansi.AUTO.
+
+
ColorScheme(CommandLine.Help.Ansi) - Constructor for class picocli.CommandLine.Help.ColorScheme
+
+
Constructs a new empty ColorScheme with the specified Ansi enabled mode.
+
+
colorScheme - Variable in class picocli.CommandLine.Help.Layout
+
 
+
Column(int, int, CommandLine.Help.Column.Overflow) - Constructor for class picocli.CommandLine.Help.Column
+
 
+
column - Variable in class picocli.CommandLine.Help.TextTable.Cell
+
+
Table column index (zero based).
+
+
columns() - Method in class picocli.CommandLine.Help.TextTable
+
+
The column definitions of this table.
+
+
columnValues - Variable in class picocli.CommandLine.Help.TextTable
+
+
The char[] slots of the TextTable to copy text values into.
+
+
COMMAND_LINE - Static variable in class picocli.groovy.PicocliBaseScript
+
+
Name of the property that holds the CommandLine instance for this script ("commandLine").
+
+
CommandLine - Class in picocli
+
+
+ CommandLine interpreter that uses reflection to initialize an annotated domain object with values obtained from the + command line arguments.
+
+
CommandLine(Object) - Constructor for class picocli.CommandLine
+
+
Constructs a new CommandLine interpreter with the specified object (which may be an annotated user object or a CommandSpec) and a default subcommand factory.
+
+
CommandLine(Object, CommandLine.IFactory) - Constructor for class picocli.CommandLine
+
+
Constructs a new CommandLine interpreter with the specified object (which may be an annotated user object or a CommandSpec) and object factory.
+
+
commandLine() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the CommandLine constructed with this CommandSpec model.
+
+
commandLine(CommandLine) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Sets the CommandLine constructed with this CommandSpec model.
+
+
CommandLine.AbstractHandler<R,T extends CommandLine.AbstractHandler<R,T>> - Class in picocli
+
+
Abstract superclass for CommandLine.IParseResultHandler2 and CommandLine.IExceptionHandler2 implementations.
+
+
CommandLine.AbstractParseResultHandler<R> - Class in picocli
+
+
Command line parse result handler that returns a value.
+
+
CommandLine.Command - Annotation Type in picocli
+
+
Annotate your class with @Command when you want more control over the format of the generated help + message.
+
+
CommandLine.DefaultExceptionHandler<R> - Class in picocli
+
+
Default exception handler that handles invalid user input by printing the exception message, followed by the usage + message for the command or subcommand whose input was invalid.
+
+
CommandLine.DuplicateOptionAnnotationsException - Exception in picocli
+
+
Exception indicating that multiple fields have been annotated with the same Option name.
+
+
CommandLine.ExecutionException - Exception in picocli
+
+
Exception indicating a problem while invoking a command or subcommand.
+
+
CommandLine.Help - Class in picocli
+
+
A collection of methods and inner classes that provide fine-grained control over the contents and layout of + the usage help message to display to end users when help is requested or invalid input values were specified.
+
+
CommandLine.Help.Ansi - Enum in picocli
+
+
Provides methods and inner classes to support using ANSI escape codes in usage help messages.
+
+
CommandLine.Help.Ansi.IStyle - Interface in picocli
+
+
Defines the interface for an ANSI escape sequence.
+
+
CommandLine.Help.Ansi.Style - Enum in picocli
+
+
A set of pre-defined ANSI escape code styles and colors, and a set of convenience methods for parsing + text with embedded markup style names, as well as convenience methods for converting + styles to strings with embedded escape codes.
+
+
CommandLine.Help.Ansi.Text - Class in picocli
+
+
Encapsulates rich text with styles and colors.
+
+
CommandLine.Help.ColorScheme - Class in picocli
+
+
All usage help message are generated with a color scheme that assigns certain styles and colors to common + parts of a usage message: the command name, options, positional parameters and option parameters.
+
+
CommandLine.Help.Column - Class in picocli
+
+
Columns define the width, indent (leading number of spaces in a column before the value) and + Overflow policy of a column in a TextTable.
+
+
CommandLine.Help.Column.Overflow - Enum in picocli
+
+
Policy for handling text that is longer than the column width: + span multiple columns, wrap to the next row, or simply truncate the portion that doesn't fit.
+
+
CommandLine.Help.IOptionRenderer - Interface in picocli
+
+
When customizing online help for Option details, a custom IOptionRenderer can be + used to create textual representation of an Option in a tabular format: one or more rows, each containing + one or more columns.
+
+
CommandLine.Help.IParameterRenderer - Interface in picocli
+
+
When customizing online help for positional parameters details, a custom IParameterRenderer + can be used to create textual representation of a Parameters field in a tabular format: one or more rows, + each containing one or more columns.
+
+
CommandLine.Help.IParamLabelRenderer - Interface in picocli
+
+
When customizing online usage help for an option parameter or a positional parameter, a custom + IParamLabelRenderer can be used to render the parameter name or label to a String.
+
+
CommandLine.Help.Layout - Class in picocli
+
+
Use a Layout to format usage help text for options and parameters in tabular format.
+
+
CommandLine.Help.TextTable - Class in picocli
+
+
Responsible for spacing out CommandLine.Help.Ansi.Text values according to the CommandLine.Help.Column definitions the table was + created with.
+
+
CommandLine.Help.TextTable.Cell - Class in picocli
+
+
Helper class to index positions in a Help.TextTable.
+
+
CommandLine.Help.Visibility - Enum in picocli
+
+
Controls the visibility of certain aspects of the usage help message.
+
+
CommandLine.HelpCommand - Class in picocli
+
+
Help command that can be installed as a subcommand on all application commands.
+
+
CommandLine.IDefaultValueProvider - Interface in picocli
+
+
Provides default value for a command.
+
+
CommandLine.IExceptionHandler - Interface in picocli
+
+
Deprecated. +
Use CommandLine.IExceptionHandler2 instead.
+
+
+
CommandLine.IExceptionHandler2<R> - Interface in picocli
+
+
Classes implementing this interface know how to handle ParameterExceptions (usually from invalid user input) + and ExecutionExceptions that occurred while executing the Runnable or Callable command.
+
+
CommandLine.IFactory - Interface in picocli
+
+
Factory for instantiating classes that are registered declaratively with annotation attributes, like + CommandLine.Command.subcommands(), CommandLine.Option.converter(), CommandLine.Parameters.converter() and CommandLine.Command.versionProvider().
+
+
CommandLine.IHelpCommandInitializable - Interface in picocli
+
+
Help commands that provide usage help for other commands can implement this interface to be initialized with the information they need.
+
+
CommandLine.IHelpFactory - Interface in picocli
+
+
Creates the CommandLine.Help instance used to render the usage help message.
+
+
CommandLine.IHelpSectionRenderer - Interface in picocli
+
+
Renders a section of the usage help message.
+
+
CommandLine.InitializationException - Exception in picocli
+
+
Exception indicating a problem during CommandLine initialization.
+
+
CommandLine.IParseResultHandler - Interface in picocli
+
+
Deprecated. +
Use CommandLine.IParseResultHandler2 instead.
+
+
+
CommandLine.IParseResultHandler2<R> - Interface in picocli
+
+
Represents a function that can process the ParseResult object resulting from successfully + parsing the command line arguments.
+
+
CommandLine.ITypeConverter<K> - Interface in picocli
+
+
+ When parsing command line arguments and initializing + fields annotated with @Option or @Parameters, + String values can be converted to any type for which a ITypeConverter is registered.
+
+
CommandLine.IVersionProvider - Interface in picocli
+
+
Provides version information for a command.
+
+
CommandLine.MaxValuesExceededException - Exception in picocli
+
+
Exception indicating that more values were specified for an option or parameter than its arity allows.
+
+
CommandLine.MissingParameterException - Exception in picocli
+
+
Exception indicating that a required parameter was not specified.
+
+
CommandLine.MissingTypeConverterException - Exception in picocli
+
+
Exception indicating that an annotated field had a type for which no CommandLine.ITypeConverter was + registered.
+
+
CommandLine.Mixin - Annotation Type in picocli
+
+
+ Fields annotated with @Mixin are "expanded" into the current command: @Option and + @Parameters in the mixin class are added to the options and positional parameters of this command.
+
+
CommandLine.Model - Class in picocli
+
+
This class provides a namespace for classes and interfaces that model concepts and attributes of command line interfaces in picocli.
+
+
CommandLine.Model.ArgSpec - Class in picocli
+
+
Models the shared attributes of CommandLine.Model.OptionSpec and CommandLine.Model.PositionalParamSpec.
+
+
CommandLine.Model.CommandSpec - Class in picocli
+
+
The CommandSpec class models a command specification, including the options, positional parameters and subcommands + supported by the command, as well as attributes for the version help message and the usage help message of the command.
+
+
CommandLine.Model.IGetter - Interface in picocli
+
+
Customizable getter for obtaining the current value of an option or positional parameter.
+
+
CommandLine.Model.ISetter - Interface in picocli
+
+
Customizable setter for modifying the value of an option or positional parameter.
+
+
CommandLine.Model.Messages - Class in picocli
+
+
Utility class for getting resource bundle strings.
+
+
CommandLine.Model.OptionSpec - Class in picocli
+
+
The OptionSpec class models aspects of a named option of a command, including whether + it is required or optional, the option parameters supported (or required) by the option, + and attributes for the usage help message describing the option.
+
+
CommandLine.Model.OptionSpec.Builder - Class in picocli
+
+
Builder responsible for creating valid OptionSpec objects.
+
+
CommandLine.Model.ParserSpec - Class in picocli
+
+
Models parser configuration specification.
+
+
CommandLine.Model.PositionalParamSpec - Class in picocli
+
+
The PositionalParamSpec class models aspects of a positional parameter of a command, including whether + it is required or optional, and attributes for the usage help message describing the positional parameter.
+
+
CommandLine.Model.PositionalParamSpec.Builder - Class in picocli
+
+
Builder responsible for creating valid PositionalParamSpec objects.
+
+
CommandLine.Model.UnmatchedArgsBinding - Class in picocli
+
+
This class allows applications to specify a custom binding that will be invoked for unmatched arguments.
+
+
CommandLine.Model.UsageMessageSpec - Class in picocli
+
+
Models the usage help message specification and can be used to customize the usage help message.
+
+
CommandLine.Option - Annotation Type in picocli
+
+
+ Annotate fields in your class with @Option and picocli will initialize these fields when matching + arguments are specified on the command line.
+
+
CommandLine.OverwrittenOptionException - Exception in picocli
+
+
Exception indicating that an option for a single-value option field has been specified multiple times on the command line.
+
+
CommandLine.ParameterException - Exception in picocli
+
+
Exception indicating something went wrong while parsing command line options.
+
+
CommandLine.ParameterIndexGapException - Exception in picocli
+
+
Exception indicating that there was a gap in the indices of the fields annotated with CommandLine.Parameters.
+
+
CommandLine.Parameters - Annotation Type in picocli
+
+
+ Fields annotated with @Parameters will be initialized with positional parameters.
+
+
CommandLine.ParentCommand - Annotation Type in picocli
+
+
+ Fields annotated with @ParentCommand will be initialized with the parent command of the current subcommand.
+
+
CommandLine.ParseResult - Class in picocli
+
+
Encapsulates the result of parsing an array of command line arguments.
+
+
CommandLine.ParseResult.Builder - Class in picocli
+
+
Builds immutable ParseResult instances.
+
+
CommandLine.PicocliException - Exception in picocli
+
+
Base class of all exceptions thrown by picocli.CommandLine.
+
+
CommandLine.Range - Class in picocli
+
+
Describes the number of parameters required and accepted by an option or a positional parameter.
+
+
CommandLine.RunAll - Class in picocli
+
+
Command line parse result handler that prints help if requested, and otherwise executes the top-level command and + all subcommands as Runnable or Callable.
+
+
CommandLine.RunFirst - Class in picocli
+
+
Command line parse result handler that prints help if requested, and otherwise executes the top-level + Runnable or Callable command.
+
+
CommandLine.RunLast - Class in picocli
+
+
Command line parse result handler that prints help if requested, and otherwise executes the most specific + Runnable or Callable subcommand.
+
+
CommandLine.Spec - Annotation Type in picocli
+
+
Fields annotated with @Spec will be initialized with the CommandSpec for the command the field is part of.
+
+
CommandLine.TypeConversionException - Exception in picocli
+
+
Exception thrown by CommandLine.ITypeConverter implementations to indicate a String could not be converted.
+
+
CommandLine.Unmatched - Annotation Type in picocli
+
+
Fields annotated with @Unmatched will be initialized with the list of unmatched command line arguments, if any.
+
+
CommandLine.UnmatchedArgumentException - Exception in picocli
+
+
Exception indicating that a command line argument could not be mapped to any of the fields annotated with + CommandLine.Option or CommandLine.Parameters.
+
+
commandList() - Method in class picocli.CommandLine.Help
+
+
Returns a 2-column list with command names and the first line of their header or (if absent) description.
+
+
commandListHeading(Object...) - Method in class picocli.CommandLine.Help
+
+
Returns the text displayed before the command list; an empty string if there are no commands, + otherwise the result of String.format(commandListHeading, params).
+
+
commandListHeading() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the optional heading preceding the subcommand list.
+
+
commandListHeading(String) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the optional heading preceding the subcommand list.
+
+
commandNamesText(String) - Method in class picocli.CommandLine.Help
+
+
Returns a Text object containing the command name and all aliases, separated with the specified separator.
+
+
commands(CommandLine.Help.Ansi.IStyle...) - Method in class picocli.CommandLine.Help.ColorScheme
+
+
Adds the specified styles to the registered styles for commands in this color scheme and returns this color scheme.
+
+
commandSpec() - Method in class picocli.CommandLine.Help
+
+
Returns the CommandSpec model that this Help was constructed with.
+
+
commandSpec() - Method in class picocli.CommandLine.Model.Messages
+
+
Returns the CommandSpec of this object, never null.
+
+
commandSpec() - Method in class picocli.CommandLine.ParseResult
+
+
Returns the CommandSpec for the matched command.
+
+
commandStyles - Variable in class picocli.CommandLine.Help.ColorScheme
+
 
+
commandText(String) - Method in class picocli.CommandLine.Help.ColorScheme
+
+
Returns a Text with all command styles applied to the specified command string.
+
+
compareTo(CommandLine.Range) - Method in class picocli.CommandLine.Range
+
 
+
complete(CommandLine.Model.CommandSpec, String[], int, int, int, List<CharSequence>) - Static method in class picocli.AutoComplete
+
 
+
completionCandidates() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the explicitly set completion candidates for this option or positional parameter, valid enum + constant names, or null if this option or positional parameter does not have any completion + candidates and its type is not an enum.
+
+
concat(String) - Method in class picocli.CommandLine.Help.Ansi.Text
+
+
Returns a copy of this Text instance with the specified text concatenated to the end.
+
+
concat(CommandLine.Help.Ansi.Text) - Method in class picocli.CommandLine.Help.Ansi.Text
+
+
Returns a copy of this Text instance with the specified text concatenated to the end.
+
+
contains(int) - Method in class picocli.CommandLine.Range
+
+
Returns true if this Range includes the specified value, false otherwise.
+
+
convert(String) - Method in interface picocli.CommandLine.ITypeConverter
+
+
Converts the specified command line argument value to some domain object.
+
+
converters() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns one or more type converters to use to convert the command line + argument into a strongly typed value (or key-value pair for map fields).
+
+
copy(CommandLine.Model.CommandSpec, CommandLine.Model.Messages) - Static method in class picocli.CommandLine.Model.Messages
+
+
Returns a copy of the specified Messages object with the CommandSpec replaced by the specified one.
+
+
create(Class<K>) - Method in interface picocli.CommandLine.IFactory
+
+
Returns an instance of the specified class.
+
+
create(CommandLine.Model.CommandSpec, CommandLine.Help.ColorScheme) - Method in interface picocli.CommandLine.IHelpFactory
+
+
Returns a Help instance to assist in rendering the usage help message
+
+
create() - Static method in class picocli.CommandLine.Model.CommandSpec
+
+
Creates and returns a new CommandSpec without any associated user object.
+
+
createCommandLine() - Method in class picocli.groovy.PicocliBaseScript
+
+
Create and returns a new CommandLine instance.
+
+
createDefaultLayout() - Method in class picocli.CommandLine.Help
+
+
Returns a Layout instance configured with the user preferences captured in this Help instance.
+
+
createDefaultOptionRenderer() - Method in class picocli.CommandLine.Help
+
+
Returns a new default OptionRenderer which converts Options to five columns of text to match + the default TextTable column layout.
+
+
createDefaultParameterRenderer() - Method in class picocli.CommandLine.Help
+
+
Returns a new default ParameterRenderer which converts positional parameters to four columns of + text to match the default TextTable column layout.
+
+
createDefaultParamLabelRenderer() - Method in class picocli.CommandLine.Help
+
+
Returns a new default param label renderer that separates option parameters from their option name + with the specified separator string, and, unless CommandLine.Model.ArgSpec.hideParamSyntax() is true, + surrounds optional parameters with '[' and ']' + characters and uses ellipses ("...") to indicate that any number of a parameter are allowed.
+
+
createDetailedSynopsisCommandText() - Method in class picocli.CommandLine.Help
+
+
Returns a Text object containing a partial detailed synopsis showing only the subcommands, starting with a " " space.
+
+
createDetailedSynopsisOptionsText(Comparator<CommandLine.Model.OptionSpec>, boolean) - Method in class picocli.CommandLine.Help
+
+
Returns a Text object containing a partial detailed synopsis showing only the options, starting with a " " space.
+
+
createDetailedSynopsisPositionalsText() - Method in class picocli.CommandLine.Help
+
+
Returns a Text object containing a partial detailed synopsis showing only the positional parameters, starting with a " " space.
+
+
createMinimalOptionRenderer() - Static method in class picocli.CommandLine.Help
+
+
Returns a new minimal OptionRenderer which converts Options to a single row with two columns + of text: an option name and a description.
+
+
createMinimalParameterRenderer() - Static method in class picocli.CommandLine.Help
+
+
Returns a new minimal ParameterRenderer which converts positional parameters + to a single row with two columns of text: an option name and a description.
+
+
createMinimalParamLabelRenderer() - Static method in class picocli.CommandLine.Help
+
+
Returns a value renderer that returns the paramLabel if defined or the field name otherwise.
+
+
createShortOptionArityAndNameComparator() - Static method in class picocli.CommandLine.Help
+
+
Sorts OptionSpecs by their option max arity first, by + min arity next, and by option name last.
+
+
createShortOptionNameComparator() - Static method in class picocli.CommandLine.Help
+
+
Sorts OptionSpecs by their option name in case-insensitive alphabetic order.
+
+
CSI - Static variable in interface picocli.CommandLine.Help.Ansi.IStyle
+
+
The Control Sequence Introducer (CSI) escape sequence "\u001b[".
+
+
customSynopsis(Object...) - Method in class picocli.CommandLine.Help
+
+
Returns command custom synopsis as a string.
+
+
customSynopsis() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the optional custom synopsis lines to use instead of the auto-generated synopsis.
+
+
customSynopsis(String...) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the optional custom synopsis lines to use instead of the auto-generated synopsis.
+
+
+ + + +

D

+
+
DEFAULT_COMMAND_NAME - Static variable in class picocli.CommandLine.Help
+
+
Constant String holding the default program name, value defined in CommandLine.Model.CommandSpec.DEFAULT_COMMAND_NAME.
+
+
DEFAULT_SEPARATOR - Static variable in class picocli.CommandLine.Help
+
+
Constant String holding the default string that separates options from option parameters, value defined in CommandLine.Model.ParserSpec.DEFAULT_SEPARATOR.
+
+
DEFAULT_USAGE_WIDTH - Static variable in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Constant holding the default usage message width: 80.
+
+
defaultArity(Field) - Static method in class picocli.CommandLine.Range
+
+
Returns the default arity Range: for options this is 0 for booleans and 1 for + other types, for parameters booleans have arity 0, arrays or Collections have + arity "0..*", and other types have arity 1.
+
+
defaultArity(Class<?>) - Static method in class picocli.CommandLine.Range
+
+
Deprecated. +
use CommandLine.Range.defaultArity(Field) instead
+
+
+
defaultColorScheme(CommandLine.Help.Ansi) - Static method in class picocli.CommandLine.Help
+
+
Creates and returns a new CommandLine.Help.ColorScheme initialized with picocli default values: commands are bold, + options and parameters use a yellow foreground, and option parameters use italic.
+
+
defaultExceptionHandler() - Static method in class picocli.CommandLine
+
+
Convenience method that returns new DefaultExceptionHandler<List<Object>>().
+
+
DefaultExceptionHandler() - Constructor for class picocli.CommandLine.DefaultExceptionHandler
+
 
+
defaultValue(CommandLine.Model.ArgSpec) - Method in interface picocli.CommandLine.IDefaultValueProvider
+
+
Returns the default value for an option or positional parameter or null.
+
+
defaultValue() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the default value of this option or positional parameter, before splitting and type conversion.
+
+
defaultValueProvider() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the default value provider for this command.
+
+
defaultValueProvider(CommandLine.IDefaultValueProvider) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Sets default value provider for this command.
+
+
defaultValueString() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the default value String displayed in the description.
+
+
description(Object...) - Method in class picocli.CommandLine.Help
+
+
Returns command description text as a string.
+
+
description() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the description template of this option, before variables are rendered.
+
+
description() - Method in class picocli.CommandLine.Model.OptionSpec
+
+
Returns the description template of this option, before variables are rendered.
+
+
description() - Method in class picocli.CommandLine.Model.PositionalParamSpec
+
+
Returns the description template of this positional parameter, before variables are rendered.
+
+
description() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the optional text lines to use as the description of the help message, displayed between the synopsis and the + options list.
+
+
description(String...) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the optional text lines to use as the description of the help message, displayed between the synopsis and the + options list.
+
+
descriptionHeading(Object...) - Method in class picocli.CommandLine.Help
+
+
Returns the text displayed before the description text; an empty string if there is no description, + otherwise the result of String.format(descriptionHeading, params).
+
+
descriptionHeading() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the optional heading preceding the description section.
+
+
descriptionHeading(String) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the heading preceding the description section.
+
+
descriptionKey() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the description key of this arg spec, used to get the description from a resource bundle.
+
+
detailedSynopsis(Comparator<CommandLine.Model.OptionSpec>, boolean) - Method in class picocli.CommandLine.Help
+
+
Deprecated. +
use CommandLine.Help.detailedSynopsis(int, Comparator, boolean) instead.
+
+
+
detailedSynopsis(int, Comparator<CommandLine.Model.OptionSpec>, boolean) - Method in class picocli.CommandLine.Help
+
+
Generates a detailed synopsis message showing all options and parameters.
+
+
DuplicateOptionAnnotationsException(String) - Constructor for exception picocli.CommandLine.DuplicateOptionAnnotationsException
+
 
+
+ + + +

E

+
+
empty(CommandLine.Model.Messages) - Static method in class picocli.CommandLine.Model.Messages
+
+
Returns true if the specified Messages is null or has a null ResourceBundle.
+
+
enabled() - Method in enum picocli.CommandLine.Help.Ansi
+
+
Returns true if ANSI escape codes should be emitted, false otherwise.
+
+
endOfOptionsDelimiter() - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
endOfOptionsDelimiter(String) - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
equals(Object) - Method in class picocli.CommandLine.Help.Ansi.Text
+
 
+
equals(Object) - Method in class picocli.CommandLine.Model.OptionSpec
+
 
+
equals(Object) - Method in class picocli.CommandLine.Model.PositionalParamSpec
+
 
+
equals(Object) - Method in class picocli.CommandLine.Range
+
 
+
equalsImpl(CommandLine.Model.ArgSpec) - Method in class picocli.CommandLine.Model.ArgSpec
+
 
+
err() - Method in class picocli.CommandLine.AbstractHandler
+
+
Returns the stream to print diagnostic messages to.
+
+
errors() - Method in class picocli.CommandLine.ParseResult
+
+
If CommandLine.Model.ParserSpec.collectErrors is true, returns the list of exceptions that were encountered during parsing, otherwise, returns an empty list.
+
+
ExecutionException(CommandLine, String) - Constructor for exception picocli.CommandLine.ExecutionException
+
 
+
ExecutionException(CommandLine, String, Throwable) - Constructor for exception picocli.CommandLine.ExecutionException
+
 
+
exit(int) - Method in class picocli.CommandLine.AbstractHandler
+
+
Calls System.exit(int) with the specified exit code.
+
+
EXIT_CODE_COMMAND_SCRIPT_EXISTS - Static variable in class picocli.AutoComplete
+
+
Exit code of this application when the specified command script exists (2).
+
+
EXIT_CODE_COMPLETION_SCRIPT_EXISTS - Static variable in class picocli.AutoComplete
+
+
Exit code of this application when the specified completion script exists (3).
+
+
EXIT_CODE_EXECUTION_ERROR - Static variable in class picocli.AutoComplete
+
+
Exit code of this application when an exception was encountered during operation (4).
+
+
EXIT_CODE_INVALID_INPUT - Static variable in class picocli.AutoComplete
+
+
Exit code of this application when the specified command line arguments are invalid (1).
+
+
EXIT_CODE_SUCCESS - Static variable in class picocli.AutoComplete
+
+
Normal exit code of this application (0).
+
+
exitCode() - Method in class picocli.CommandLine.AbstractHandler
+
+
Returns the exit code to use as the termination status, or null (the default) if the handler should + not call System.exit(int) after processing completes.
+
+
expandAtFiles() - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
expandAtFiles(boolean) - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
+ + + +

F

+
+
fg(String) - Static method in enum picocli.CommandLine.Help.Ansi.Style
+
+
Parses the specified style markup and returns the associated style.
+
+
findOption(char) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the option with the specified short name, or null if no option with that name is defined for this command.
+
+
findOption(String) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the option with the specified name, or null if no option with that name is defined for this command.
+
+
footer(Object...) - Method in class picocli.CommandLine.Help
+
+
Returns command footer text as a string.
+
+
footer() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the optional footer text lines displayed at the bottom of the help message.
+
+
footer(String...) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the optional footer text lines displayed at the bottom of the help message.
+
+
footerHeading(Object...) - Method in class picocli.CommandLine.Help
+
+
Returns the text displayed before the footer text; the result of String.format(footerHeading, params).
+
+
footerHeading() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the optional heading preceding the footer section.
+
+
footerHeading(String) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the optional heading preceding the footer section.
+
+
forAnnotatedObject(Object) - Static method in class picocli.CommandLine.Model.CommandSpec
+
+
Creates and returns a new CommandSpec initialized from the specified associated user object.
+
+
forAnnotatedObject(Object, CommandLine.IFactory) - Static method in class picocli.CommandLine.Model.CommandSpec
+
+
Creates and returns a new CommandSpec initialized from the specified associated user object.
+
+
forAnnotatedObjectLenient(Object) - Static method in class picocli.CommandLine.Model.CommandSpec
+
+
Creates and returns a new CommandSpec initialized from the specified associated user object.
+
+
forAnnotatedObjectLenient(Object, CommandLine.IFactory) - Static method in class picocli.CommandLine.Model.CommandSpec
+
+
Creates and returns a new CommandSpec initialized from the specified associated user object.
+
+
forColumns(CommandLine.Help.Ansi, CommandLine.Help.Column...) - Static method in class picocli.CommandLine.Help.TextTable
+
+
Constructs a TextTable with the specified columns.
+
+
forColumnWidths(CommandLine.Help.Ansi, int...) - Static method in class picocli.CommandLine.Help.TextTable
+
+
Constructs a new TextTable with columns with the specified width, all SPANning multiple columns on + overflow except the last column which WRAPS to the next row.
+
+
forDefaultColumns(CommandLine.Help.Ansi, int) - Static method in class picocli.CommandLine.Help.TextTable
+
+
Constructs a TextTable with five columns as follows: + + required option/parameter marker (width: 2, indent: 0, TRUNCATE on overflow) + short option name (width: 2, indent: 0, TRUNCATE on overflow) + comma separator (width: 1, indent: 0, TRUNCATE on overflow) + long option name(s) (width: 24, indent: 1, SPAN multiple columns on overflow) + description line(s) (width: 51, indent: 1, WRAP to next row on overflow) +
+
+
forDefaultColumns(CommandLine.Help.Ansi, int, int) - Static method in class picocli.CommandLine.Help.TextTable
+
+
Constructs a TextTable with five columns as follows: + + required option/parameter marker (width: 2, indent: 0, TRUNCATE on overflow) + short option name (width: 2, indent: 0, TRUNCATE on overflow) + comma separator (width: 1, indent: 0, TRUNCATE on overflow) + long option name(s) (width: 24, indent: 1, SPAN multiple columns on overflow) + description line(s) (width: 51, indent: 1, WRAP to next row on overflow) +
+
+
forStringArrayConsumer(CommandLine.Model.ISetter) - Static method in class picocli.CommandLine.Model.UnmatchedArgsBinding
+
+
Creates a UnmatchedArgsBinding for a setter that consumes String[] objects.
+
+
forStringCollectionSupplier(CommandLine.Model.IGetter) - Static method in class picocli.CommandLine.Model.UnmatchedArgsBinding
+
+
Creates a UnmatchedArgsBinding for a getter that produces a Collection<String> that the unmatched arguments can be added to.
+
+
+ + + +

G

+
+
get() - Method in interface picocli.CommandLine.Model.IGetter
+
+
Returns the current value of the binding.
+
+
getArgSpec() - Method in exception picocli.CommandLine.ParameterException
+
+
Returns the ArgSpec object for the (sub)command whose input could not be parsed.
+
+
getAtFileCommentChar() - Method in class picocli.CommandLine
+
+
Returns the character that starts a single-line comment or null if all content of argument files should + be interpreted as arguments (without comments).
+
+
getCommand() - Method in class picocli.CommandLine
+
+
Returns the annotated user object that this CommandLine instance was constructed with.
+
+
getCommandLine() - Method in exception picocli.CommandLine.ExecutionException
+
+
Returns the CommandLine object for the (sub)command that could not be invoked.
+
+
getCommandLine() - Method in exception picocli.CommandLine.ParameterException
+
+
Returns the CommandLine object for the (sub)command whose input could not be parsed.
+
+
getCommandMethods(Class<?>, String) - Static method in class picocli.CommandLine
+
+
Helper to get methods of a class annotated with @Command via reflection, optionally filtered by method name (not @Command.name).
+
+
getCommandName() - Method in class picocli.CommandLine
+
+
Returns the command name (also called program name) displayed in the usage help synopsis.
+
+
getCommandSpec() - Method in class picocli.CommandLine
+
+
Returns the CommandSpec model that this CommandLine was constructed with.
+
+
getDefaultValueProvider() - Method in class picocli.CommandLine
+
+
Returns the default value provider for the command, or null if none has been set.
+
+
getEndOfOptionsDelimiter() - Method in class picocli.CommandLine
+
+
Returns the end-of-options delimiter that signals that the remaining command line arguments should be treated as positional parameters.
+
+
getHelpFactory() - Method in class picocli.CommandLine
+
+
Returns the IHelpFactory that is used to construct the usage help message.
+
+
getHelpSectionKeys() - Method in class picocli.CommandLine
+
+
Returns the section keys in the order that the usage help message should render the sections.
+
+
getHelpSectionMap() - Method in class picocli.CommandLine
+
+
Returns the map of section keys and renderers used to construct the usage help message.
+
+
getMissing() - Method in exception picocli.CommandLine.MissingParameterException
+
 
+
getMixins() - Method in class picocli.CommandLine
+
+
Returns a map of user objects whose options and positional parameters were added to ("mixed in" with) this command.
+
+
getOrCreateCommandLine() - Method in class picocli.groovy.PicocliBaseScript
+
+
Return the CommandLine for this script.
+
+
getOverwritten() - Method in exception picocli.CommandLine.OverwrittenOptionException
+
+
Returns the CommandLine.Model.ArgSpec for the option which was being overwritten.
+
+
getParent() - Method in class picocli.CommandLine
+
+
Returns the command that this is a subcommand of, or null if this is a top-level command.
+
+
getParseResult() - Method in class picocli.CommandLine
+
 
+
getResourceBundle() - Method in class picocli.CommandLine
+
+
Returns the ResourceBundle of this command or null if no resource bundle is set.
+
+
getScriptArguments() - Method in class picocli.groovy.PicocliBaseScript
+
+
Return the script arguments as an array of strings.
+
+
getSeparator() - Method in class picocli.CommandLine
+
+
Returns the String that separates option names from option values when parsing command line options.
+
+
getString(String, String) - Method in class picocli.CommandLine.Model.Messages
+
+
Returns the String value found in the resource bundle for the specified key, or the specified default value if not found.
+
+
getStringArray(String, String[]) - Method in class picocli.CommandLine.Model.Messages
+
+
Returns the String array value found in the resource bundle for the specified key, or the specified default value if not found.
+
+
getStyledChars(int, int, CommandLine.Help.Ansi.Text, int) - Method in class picocli.CommandLine.Help.Ansi.Text
+
+
Copies the specified substring of this Text into the specified destination, preserving the markup.
+
+
getSubcommands() - Method in class picocli.CommandLine
+
+
Returns a map with the subcommands registered on this instance.
+
+
getSuggestions() - Method in exception picocli.CommandLine.UnmatchedArgumentException
+
+
Returns suggested solutions if such solutions exist, otherwise returns an empty list.
+
+
getter() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the CommandLine.Model.IGetter that is responsible for supplying the value of this argument.
+
+
getter() - Method in class picocli.CommandLine.Model.UnmatchedArgsBinding
+
+
Returns the getter responsible for producing a Collection that the unmatched arguments can be added to.
+
+
getUnmatched() - Method in exception picocli.CommandLine.UnmatchedArgumentException
+
+
Returns the unmatched command line arguments.
+
+
getUnmatchedArguments() - Method in class picocli.CommandLine
+
+
Returns the list of unmatched command line arguments, if any.
+
+
getUsageHelpWidth() - Method in class picocli.CommandLine
+
+
Returns the maximum width of the usage help message.
+
+
getUsageMessage() - Method in class picocli.CommandLine
+
+
Similar to CommandLine.usage(PrintStream), but returns the usage help message as a String instead of printing it to the PrintStream.
+
+
getUsageMessage(CommandLine.Help.Ansi) - Method in class picocli.CommandLine
+
+
Similar to CommandLine.usage(PrintStream, Help.Ansi), but returns the usage help message as a String instead of printing it to the PrintStream.
+
+
getUsageMessage(CommandLine.Help.ColorScheme) - Method in class picocli.CommandLine
+
+
Similar to CommandLine.usage(PrintStream, Help.ColorScheme), but returns the usage help message as a String instead of printing it to the PrintStream.
+
+
getValue() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the current value of this argument.
+
+
getValue() - Method in exception picocli.CommandLine.ParameterException
+
+
Returns the String value for the (sub)command whose input could not be parsed.
+
+
getVersion() - Method in interface picocli.CommandLine.IVersionProvider
+
+
Returns version information for a command.
+
+
+ + + +

H

+
+
handle(CommandLine.ParseResult) - Method in class picocli.CommandLine.AbstractParseResultHandler
+
+
Processes the specified ParseResult and returns the result as a list of objects.
+
+
handle(CommandLine.ParseResult) - Method in class picocli.CommandLine.RunAll
+
+
Executes the top-level command and all subcommands as Runnable or Callable.
+
+
handle(CommandLine.ParseResult) - Method in class picocli.CommandLine.RunFirst
+
+
Executes the top-level Runnable or Callable subcommand.
+
+
handle(CommandLine.ParseResult) - Method in class picocli.CommandLine.RunLast
+
+
Executes the most specific Runnable or Callable subcommand.
+
+
handleException(CommandLine.ParameterException, PrintStream, CommandLine.Help.Ansi, String...) - Method in class picocli.CommandLine.DefaultExceptionHandler
+
 
+
handleException(CommandLine.ParameterException, PrintStream, CommandLine.Help.Ansi, String...) - Method in interface picocli.CommandLine.IExceptionHandler
+
+
Deprecated.
+
Handles a ParameterException that occurred while parsing the command + line arguments and optionally returns a list of results.
+
+
handleExecutionException(CommandLine.ExecutionException, CommandLine.ParseResult) - Method in class picocli.CommandLine.DefaultExceptionHandler
+
+
This implementation always simply rethrows the specified exception.
+
+
handleExecutionException(CommandLine.ExecutionException, CommandLine.ParseResult) - Method in interface picocli.CommandLine.IExceptionHandler2
+
+
Handles a ExecutionException that occurred while executing the Runnable or + Callable command and optionally returns a list of results.
+
+
handleExecutionException(CommandLine, String[], Exception) - Method in class picocli.groovy.PicocliBaseScript
+
+
If an Exception occurs during PicocliBaseScript.runRunnableSubcommand(List), or PicocliBaseScript.runScriptBody() + then this gets called to report the problem.
+
+
handleParameterException(CommandLine.ParameterException, String[]) - Method in class picocli.groovy.PicocliBaseScript
+
+
If a ParameterException occurs during PicocliBaseScript.parseScriptArguments(CommandLine, String[]) + then this method gets called to report the problem.
+
+
handleParseException(CommandLine.ParameterException, String[]) - Method in class picocli.CommandLine.DefaultExceptionHandler
+
+
Prints the message of the specified exception, followed by the usage message for the command or subcommand + whose input was invalid, to the stream returned by CommandLine.AbstractHandler.err().
+
+
handleParseException(CommandLine.ParameterException, String[]) - Method in interface picocli.CommandLine.IExceptionHandler2
+
+
Handles a ParameterException that occurred while parsing the command + line arguments and optionally returns a list of results.
+
+
handleParseResult(CommandLine.ParseResult) - Method in class picocli.CommandLine.AbstractParseResultHandler
+
+
Prints help if requested, and otherwise calls CommandLine.AbstractParseResultHandler.handle(CommandLine.ParseResult).
+
+
handleParseResult(List<CommandLine>, PrintStream, CommandLine.Help.Ansi) - Method in interface picocli.CommandLine.IParseResultHandler
+
+
Deprecated.
+
Processes a List of CommandLine objects resulting from successfully + parsing the command line arguments and optionally returns a list of results.
+
+
handleParseResult(CommandLine.ParseResult) - Method in interface picocli.CommandLine.IParseResultHandler2
+
+
Processes the ParseResult object resulting from successfully + parsing the command line arguments and returns a return value.
+
+
handleParseResult(List<CommandLine>, PrintStream, CommandLine.Help.Ansi) - Method in class picocli.CommandLine.RunAll
+
+
Prints help if requested, and otherwise executes the top-level command and all subcommands as Runnable + or Callable.
+
+
handleParseResult(List<CommandLine>, PrintStream, CommandLine.Help.Ansi) - Method in class picocli.CommandLine.RunFirst
+
+
Prints help if requested, and otherwise executes the top-level Runnable or Callable command.
+
+
handleParseResult(List<CommandLine>, PrintStream, CommandLine.Help.Ansi) - Method in class picocli.CommandLine.RunLast
+
+
Prints help if requested, and otherwise executes the most specific Runnable or Callable subcommand.
+
+
hasExitCode() - Method in class picocli.CommandLine.AbstractHandler
+
+
Returns true if an exit code was set with CommandLine.AbstractHandler.andExit(int), or false (the default) if + the handler should not call System.exit(int) after processing completes.
+
+
hashCode() - Method in class picocli.CommandLine.Help.Ansi.Text
+
 
+
hashCode() - Method in class picocli.CommandLine.Model.OptionSpec
+
 
+
hashCode() - Method in class picocli.CommandLine.Model.PositionalParamSpec
+
 
+
hashCode() - Method in class picocli.CommandLine.Range
+
 
+
hashCodeImpl() - Method in class picocli.CommandLine.Model.ArgSpec
+
 
+
hasInitialValue() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Determines whether the option or positional parameter will be reset to the CommandLine.Model.ArgSpec.initialValue() + before parsing new input.
+
+
hasMatchedOption(char) - Method in class picocli.CommandLine.ParseResult
+
+
Returns whether an option whose aliases include the specified short name was matched on the command line.
+
+
hasMatchedOption(String) - Method in class picocli.CommandLine.ParseResult
+
+
Returns whether an option whose aliases include the specified name was matched on the command line.
+
+
hasMatchedOption(CommandLine.Model.OptionSpec) - Method in class picocli.CommandLine.ParseResult
+
+
Returns whether the specified option was matched on the command line.
+
+
hasMatchedPositional(int) - Method in class picocli.CommandLine.ParseResult
+
+
Returns whether a positional parameter was matched at the specified position.
+
+
hasMatchedPositional(CommandLine.Model.PositionalParamSpec) - Method in class picocli.CommandLine.ParseResult
+
+
Returns whether the specified positional parameter was matched on the command line.
+
+
hasSubcommand() - Method in class picocli.CommandLine.ParseResult
+
+
Returns true if a subcommand was matched on the command line, false otherwise.
+
+
header(Object...) - Method in class picocli.CommandLine.Help
+
+
Returns the command header text as a string.
+
+
header() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the optional header lines displayed at the top of the help message.
+
+
header(String...) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the optional header lines displayed at the top of the help message.
+
+
headerHeading(Object...) - Method in class picocli.CommandLine.Help
+
+
Returns the text displayed before the header text; the result of String.format(headerHeading, params).
+
+
headerHeading() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the optional heading preceding the header section.
+
+
headerHeading(String) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the heading preceding the header section.
+
+
Help(Object) - Constructor for class picocli.CommandLine.Help
+
+
Constructs a new Help instance with a default color scheme, initialized from annotatations + on the specified class and superclasses.
+
+
Help(Object, CommandLine.Help.Ansi) - Constructor for class picocli.CommandLine.Help
+
+
Constructs a new Help instance with a default color scheme, initialized from annotatations + on the specified class and superclasses.
+
+
Help(Object, CommandLine.Help.ColorScheme) - Constructor for class picocli.CommandLine.Help
+
+
Deprecated. +
use picocli.CommandLine.Help#Help(picocli.CommandLine.Model.CommandSpec, picocli.CommandLine.Help.ColorScheme)
+
+
+
Help(CommandLine.Model.CommandSpec, CommandLine.Help.ColorScheme) - Constructor for class picocli.CommandLine.Help
+
+
Constructs a new Help instance with the specified color scheme, initialized from annotatations + on the specified class and superclasses.
+
+
help() - Method in class picocli.CommandLine.Model.OptionSpec.Builder
+
+
Deprecated. +
Use CommandLine.Model.OptionSpec.Builder.usageHelp() and CommandLine.Model.OptionSpec.Builder.versionHelp() instead.
+
+
+
help(boolean) - Method in class picocli.CommandLine.Model.OptionSpec.Builder
+
+
Sets whether this option disables validation of the other arguments, and returns this builder.
+
+
help() - Method in class picocli.CommandLine.Model.OptionSpec
+
+
Deprecated. +
Use CommandLine.Model.OptionSpec.usageHelp() and CommandLine.Model.OptionSpec.versionHelp() instead.
+
+
+
HelpCommand() - Constructor for class picocli.CommandLine.HelpCommand
+
 
+
helpCommand() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns whether this subcommand is a help command, and required options and positional + parameters of the parent command should not be validated.
+
+
helpCommand(boolean) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Sets whether this is a help command and required parameter checking should be suspended.
+
+
helpFactory() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the IHelpFactory that is used to construct the usage help message.
+
+
helpFactory(CommandLine.IHelpFactory) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets a new IHelpFactory to customize the usage help message.
+
+
hidden() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns whether this option should be excluded from the usage message.
+
+
hidden() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns whether this command should be hidden from the usage help message of the parent command.
+
+
hidden(boolean) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Set the hidden flag on this command to control whether to show or hide it in the help usage text of the parent command.
+
+
hideParamSyntax() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns whether usage syntax decorations around the paramLabel should be suppressed.
+
+
+ + + +

I

+
+
indent - Variable in class picocli.CommandLine.Help.Column
+
+
Indent (number of empty spaces at the start of the column preceding the text value)
+
+
indentWrappedLines - Variable in class picocli.CommandLine.Help.TextTable
+
+
By default, indent wrapped lines by 2 spaces.
+
+
index() - Method in class picocli.CommandLine.Model.PositionalParamSpec.Builder
+
+
Returns an index or range specifying which of the command line arguments should be assigned to this positional parameter.
+
+
index(String) - Method in class picocli.CommandLine.Model.PositionalParamSpec.Builder
+
+
Sets the index or range specifying which of the command line arguments should be assigned to this positional parameter, and returns this builder.
+
+
index(CommandLine.Range) - Method in class picocli.CommandLine.Model.PositionalParamSpec.Builder
+
+
Sets the index or range specifying which of the command line arguments should be assigned to this positional parameter, and returns this builder.
+
+
index() - Method in class picocli.CommandLine.Model.PositionalParamSpec
+
+
Returns an index or range specifying which of the command line arguments should be assigned to this positional parameter.
+
+
init(CommandLine, CommandLine.Help.Ansi, PrintStream, PrintStream) - Method in class picocli.CommandLine.HelpCommand
+
+
Initializes this object with the information needed to implement a help command that provides usage help for other commands.
+
+
init(CommandLine, CommandLine.Help.Ansi, PrintStream, PrintStream) - Method in interface picocli.CommandLine.IHelpCommandInitializable
+
+
Initializes this object with the information needed to implement a help command that provides usage help for other commands.
+
+
InitializationException(String) - Constructor for exception picocli.CommandLine.InitializationException
+
 
+
InitializationException(String, Exception) - Constructor for exception picocli.CommandLine.InitializationException
+
 
+
initialValue() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the initial value this option or positional parameter.
+
+
insertSynopsisCommandName(int, CommandLine.Help.Ansi.Text) - Method in class picocli.CommandLine.Help
+
+
Returns the detailed synopsis text by inserting the command name before the specified text with options and positional parameters details.
+
+
interactive() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns whether this option will prompt the user to enter a value on the command line.
+
+
internalShowDefaultValue(boolean) - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns whether the default for this option or positional parameter should be shown, potentially overriding the specified global setting.
+
+
internalShowDefaultValue(boolean) - Method in class picocli.CommandLine.Model.OptionSpec
+
 
+
invoke(String, Class<?>, String...) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.invoke(String, Class, PrintStream, PrintStream, Help.Ansi, String...) with System.out for + requested usage help messages, System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO.
+
+
invoke(String, Class<?>, PrintStream, String...) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.invoke(String, Class, PrintStream, PrintStream, Help.Ansi, String...) with the specified stream for + requested usage help messages, System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO.
+
+
invoke(String, Class<?>, PrintStream, CommandLine.Help.Ansi, String...) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.invoke(String, Class, PrintStream, PrintStream, Help.Ansi, String...) with the specified stream for + requested usage help messages, System.err for diagnostic error messages, and the specified Ansi mode.
+
+
invoke(String, Class<?>, PrintStream, PrintStream, CommandLine.Help.Ansi, String...) - Static method in class picocli.CommandLine
+
+
Convenience method to allow command line application authors to avoid some boilerplate code in their application.
+
+
isCaseInsensitiveEnumValuesAllowed() - Method in class picocli.CommandLine
+
+
Returns whether the parser should ignore case when converting arguments to enum values.
+
+
isExpandAtFiles() - Method in class picocli.CommandLine
+
+
Returns whether arguments starting with '@' should be treated as the path to an argument file and its + contents should be expanded into separate arguments for each line in the specified file.
+
+
isMultiValue() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns true if this argument's CommandLine.Model.ArgSpec.type() is an array, a Collection or a Map, false otherwise.
+
+
isOption() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns true if this argument is a named option, false otherwise.
+
+
isOption() - Method in class picocli.CommandLine.Model.OptionSpec
+
 
+
isOption() - Method in class picocli.CommandLine.Model.PositionalParamSpec
+
 
+
isOverwrittenOptionsAllowed() - Method in class picocli.CommandLine
+
+
Returns whether options for single-value fields can be specified multiple times on the command line.
+
+
isPositional() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns true if this argument is a positional parameter, false otherwise.
+
+
isPositional() - Method in class picocli.CommandLine.Model.OptionSpec
+
 
+
isPositional() - Method in class picocli.CommandLine.Model.PositionalParamSpec
+
 
+
isPosixClusteredShortOptionsAllowed() - Method in class picocli.CommandLine
+
+
Returns whether the parser accepts clustered short options.
+
+
isSplitQuotedStrings() - Method in class picocli.CommandLine
+
+
Returns whether the parser is allowed to split quoted Strings or not.
+
+
isStopAtPositional() - Method in class picocli.CommandLine
+
+
Returns whether the parser interprets the first positional parameter as "end of options" so the remaining + arguments are all treated as positional parameters.
+
+
isStopAtUnmatched() - Method in class picocli.CommandLine
+
+
Returns whether the parser should stop interpreting options and positional parameters as soon as it encounters an + unmatched option.
+
+
isToggleBooleanFlags() - Method in class picocli.CommandLine
+
+
Returns whether the value of boolean flag options should be "toggled" when the option is matched.
+
+
isTrimQuotes() - Method in class picocli.CommandLine
+
+
Returns whether the parser should trim quotes from command line arguments before processing them.
+
+
isUnknownOption() - Method in exception picocli.CommandLine.UnmatchedArgumentException
+
+
Returns true if the first unmatched command line arguments resembles an option, false otherwise.
+
+
isUnmatchedArgumentsAllowed() - Method in class picocli.CommandLine
+
+
Returns whether the end user may specify arguments on the command line that are not matched to any option or parameter fields.
+
+
isUnmatchedOptionsArePositionalParams() - Method in class picocli.CommandLine
+
+
Returns whether arguments on the command line that resemble an option should be treated as positional parameters.
+
+
isUsageHelpRequested() - Method in class picocli.CommandLine
+
+
Returns true if an option annotated with CommandLine.Option.usageHelp() was specified on the command line.
+
+
isUsageHelpRequested() - Method in class picocli.CommandLine.ParseResult
+
+
Returns true if one of the options that was matched on the command line is a usageHelp option.
+
+
isUseSimplifiedAtFiles() - Method in class picocli.CommandLine
+
+
Returns whether to use a simplified argument file format that is compatible with JCommander.
+
+
isVariable - Variable in class picocli.CommandLine.Range
+
 
+
isVersionHelpRequested() - Method in class picocli.CommandLine
+
+
Returns true if an option annotated with CommandLine.Option.versionHelp() was specified on the command line.
+
+
isVersionHelpRequested() - Method in class picocli.CommandLine.ParseResult
+
+
Returns true if one of the options that was matched on the command line is a versionHelp option.
+
+
+ + + +

J

+
+
join(CommandLine.Help.Ansi, int, String[], StringBuilder, Object...) - Static method in class picocli.CommandLine.Help
+
+
Formats each of the specified values and appends it to the specified StringBuilder.
+
+
+ + + +

L

+
+
Layout(CommandLine.Help.ColorScheme, int) - Constructor for class picocli.CommandLine.Help.Layout
+
+
Constructs a Layout with the specified color scheme, a new default TextTable, the + default option renderer, and the + default parameter renderer.
+
+
Layout(CommandLine.Help.ColorScheme, CommandLine.Help.TextTable) - Constructor for class picocli.CommandLine.Help.Layout
+
+
Constructs a Layout with the specified color scheme, the specified TextTable, the + default option renderer, and the + default parameter renderer.
+
+
Layout(CommandLine.Help.ColorScheme, CommandLine.Help.TextTable, CommandLine.Help.IOptionRenderer, CommandLine.Help.IParameterRenderer) - Constructor for class picocli.CommandLine.Help.Layout
+
+
Constructs a Layout with the specified color scheme, the specified TextTable, the + specified option renderer and the specified parameter renderer.
+
+
layout(CommandLine.Model.ArgSpec, CommandLine.Help.Ansi.Text[][]) - Method in class picocli.CommandLine.Help.Layout
+
+
Copies the specified text values into the correct cells in the CommandLine.Help.TextTable.
+
+
limitSplit() - Method in class picocli.CommandLine.Model.ParserSpec
+
+
Returns true if arguments should be split first before any further processing and the number of + parts resulting from the split is limited to the max arity of the argument.
+
+
limitSplit(boolean) - Method in class picocli.CommandLine.Model.ParserSpec
+
+
Sets whether arguments should be split first before any further processing.
+
+
longestName() - Method in class picocli.CommandLine.Model.OptionSpec
+
+
Returns the longest option name.
+
+
+ + + +

M

+
+
main(String...) - Static method in class picocli.AutoComplete
+
+
Generates a bash completion script for the specified command class.
+
+
matchedOption(char) - Method in class picocli.CommandLine.ParseResult
+
+
Returns the option with the specified short name, or null if no option with that name was matched + on the command line.
+
+
matchedOption(String) - Method in class picocli.CommandLine.ParseResult
+
+
Returns the option with the specified name, or null if no option with that name was matched on the command line.
+
+
matchedOptions() - Method in class picocli.CommandLine.ParseResult
+
+
Returns a list of matched options, in the order they were found on the command line.
+
+
matchedOptionValue(char, T) - Method in class picocli.CommandLine.ParseResult
+
+
Returns the command line argument value of the option with the specified name, converted to the type of the option, or the specified default value if no option with the specified name was matched.
+
+
matchedOptionValue(String, T) - Method in class picocli.CommandLine.ParseResult
+
+
Returns the command line argument value of the option with the specified name, converted to the type of the option, or the specified default value if no option with the specified name was matched.
+
+
matchedPositional(int) - Method in class picocli.CommandLine.ParseResult
+
+
Returns the first PositionalParamSpec that matched an argument at the specified position, or null if no positional parameters were matched at that position.
+
+
matchedPositionals(int) - Method in class picocli.CommandLine.ParseResult
+
+
Returns all PositionalParamSpec objects that matched an argument at the specified position, or an empty list if no positional parameters were matched at that position.
+
+
matchedPositionals() - Method in class picocli.CommandLine.ParseResult
+
+
Returns a list of matched positional parameters.
+
+
matchedPositionalValue(int, T) - Method in class picocli.CommandLine.ParseResult
+
+
Returns the command line argument value of the positional parameter at the specified position, converted to the type of the positional parameter, or the specified default value if no positional parameter was matched at that position.
+
+
max - Variable in class picocli.CommandLine.Range
+
+
Maximum accepted number of parameters for an option or positional parameter.
+
+
max(int) - Method in class picocli.CommandLine.Range
+
+
Returns a new Range object with the max value replaced by the specified value.
+
+
MaxValuesExceededException(CommandLine, String) - Constructor for exception picocli.CommandLine.MaxValuesExceededException
+
 
+
messages() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the Messages for this arg specification, or null.
+
+
messages(CommandLine.Model.Messages) - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Sets the Messages for this ArgSpec, and returns this ArgSpec.
+
+
Messages(CommandLine.Model.CommandSpec, ResourceBundle) - Constructor for class picocli.CommandLine.Model.Messages
+
 
+
messages() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the Messages for this usage help message specification, or null.
+
+
messages(CommandLine.Model.Messages) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the Messages for this usageMessage specification, and returns this UsageMessageSpec.
+
+
min - Variable in class picocli.CommandLine.Range
+
+
Required number of parameters for an option or positional parameter.
+
+
min(int) - Method in class picocli.CommandLine.Range
+
+
Returns a new Range object with the min value replaced by the specified value.
+
+
MissingParameterException(CommandLine, CommandLine.Model.ArgSpec, String) - Constructor for exception picocli.CommandLine.MissingParameterException
+
 
+
MissingParameterException(CommandLine, Collection<CommandLine.Model.ArgSpec>, String) - Constructor for exception picocli.CommandLine.MissingParameterException
+
 
+
MissingTypeConverterException(CommandLine, String) - Constructor for exception picocli.CommandLine.MissingTypeConverterException
+
 
+
mixins() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns a map of the mixin names to mixin CommandSpec objects configured for this command.
+
+
mixinStandardHelpOptions() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns true if the standard help options have been mixed in with this command, false otherwise.
+
+
mixinStandardHelpOptions(boolean) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Sets whether the standard help options should be mixed in with this command.
+
+
+ + + +

N

+
+
name() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns name of this command.
+
+
name(String) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Sets the String to use as the program name in the synopsis line of the help message.
+
+
names() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns all names of this command, including CommandLine.Model.CommandSpec.name() and CommandLine.Model.CommandSpec.aliases().
+
+
names() - Method in class picocli.CommandLine.Model.OptionSpec.Builder
+
+
Returns one or more option names.
+
+
names(String...) - Method in class picocli.CommandLine.Model.OptionSpec.Builder
+
+
Replaces the option names with the specified values.
+
+
names() - Method in class picocli.CommandLine.Model.OptionSpec
+
+
Returns one or more option names.
+
+
+ + + +

O

+
+
off() - Method in interface picocli.CommandLine.Help.Ansi.IStyle
+
+
Returns the ANSI escape code for turning this style off.
+
+
off() - Method in enum picocli.CommandLine.Help.Ansi.Style
+
 
+
off(CommandLine.Help.Ansi.IStyle...) - Static method in enum picocli.CommandLine.Help.Ansi.Style
+
+
Returns the concatenated ANSI escape codes for turning all specified styles off.
+
+
on() - Method in interface picocli.CommandLine.Help.Ansi.IStyle
+
+
Returns the ANSI escape code for turning this style on.
+
+
on() - Method in enum picocli.CommandLine.Help.Ansi.Style
+
 
+
on(CommandLine.Help.Ansi.IStyle...) - Static method in enum picocli.CommandLine.Help.Ansi.Style
+
+
Returns the concatenated ANSI escape codes for turning all specified styles on.
+
+
optionArity(Field) - Static method in class picocli.CommandLine.Range
+
+
Returns a new Range based on the CommandLine.Option.arity() annotation on the specified field, + or the field type's default arity if no arity was specified.
+
+
optionList() - Method in class picocli.CommandLine.Help
+
+
Returns a description of the options supported by the application.
+
+
optionList(CommandLine.Help.Layout, Comparator<CommandLine.Model.OptionSpec>, CommandLine.Help.IParamLabelRenderer) - Method in class picocli.CommandLine.Help
+
+
Sorts all Options with the specified comparator (if the comparator is non-null), + then adds all non-hidden options to the + specified TextTable and returns the result of TextTable.toString().
+
+
optionListHeading(Object...) - Method in class picocli.CommandLine.Help
+
+
Returns the text displayed before the option list; an empty string if there are no options, + otherwise the result of String.format(optionListHeading, params).
+
+
optionListHeading() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the optional heading preceding the options list.
+
+
optionListHeading(String) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the heading preceding the options list.
+
+
optionParams(CommandLine.Help.Ansi.IStyle...) - Method in class picocli.CommandLine.Help.ColorScheme
+
+
Adds the specified styles to the registered styles for option parameters in this color scheme and returns this color scheme.
+
+
optionParamStyles - Variable in class picocli.CommandLine.Help.ColorScheme
+
 
+
optionParamText(String) - Method in class picocli.CommandLine.Help.ColorScheme
+
+
Returns a Text with all optionParam styles applied to the specified optionParam string.
+
+
optionRenderer - Variable in class picocli.CommandLine.Help.Layout
+
 
+
options(CommandLine.Help.Ansi.IStyle...) - Method in class picocli.CommandLine.Help.ColorScheme
+
+
Adds the specified styles to the registered styles for options in this color scheme and returns this color scheme.
+
+
options() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the list of options configured for this command.
+
+
optionsMap() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns a map of the option names to option spec objects configured for this command.
+
+
optionStyles - Variable in class picocli.CommandLine.Help.ColorScheme
+
 
+
optionText(String) - Method in class picocli.CommandLine.Help.ColorScheme
+
+
Returns a Text with all option styles applied to the specified option string.
+
+
order() - Method in class picocli.CommandLine.Model.OptionSpec.Builder
+
+
Returns the position in the options list in the usage help message at which this option should be shown.
+
+
order(int) - Method in class picocli.CommandLine.Model.OptionSpec.Builder
+
+
Sets the position in the options list in the usage help message at which this option should be shown, and returns this builder.
+
+
order() - Method in class picocli.CommandLine.Model.OptionSpec
+
+
Returns the position in the options list in the usage help message at which this option should be shown.
+
+
originalArgs(String[]) - Method in class picocli.CommandLine.ParseResult.Builder
+
+
Sets the specified command line arguments that were parsed.
+
+
originalArgs() - Method in class picocli.CommandLine.ParseResult
+
+
Returns the command line arguments that were parsed.
+
+
originalStringValues() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the original command line arguments matched by this option or positional parameter spec.
+
+
out() - Method in class picocli.CommandLine.AbstractHandler
+
+
Returns the stream to print command output to.
+
+
overflow - Variable in class picocli.CommandLine.Help.Column
+
+
Policy that determines how to handle values larger than the column width.
+
+
OverwrittenOptionException(CommandLine, CommandLine.Model.ArgSpec, String) - Constructor for exception picocli.CommandLine.OverwrittenOptionException
+
 
+
overwrittenOptionsAllowed() - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
overwrittenOptionsAllowed(boolean) - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
+ + + +

P

+
+
parameterArity(Field) - Static method in class picocli.CommandLine.Range
+
+
Returns a new Range based on the CommandLine.Parameters.arity() annotation on the specified field, + or the field type's default arity if no arity was specified.
+
+
ParameterException(CommandLine, String) - Constructor for exception picocli.CommandLine.ParameterException
+
+
Constructs a new ParameterException with the specified CommandLine and error message.
+
+
ParameterException(CommandLine, String, Throwable) - Constructor for exception picocli.CommandLine.ParameterException
+
+
Constructs a new ParameterException with the specified CommandLine and error message.
+
+
ParameterException(CommandLine, String, Throwable, CommandLine.Model.ArgSpec, String) - Constructor for exception picocli.CommandLine.ParameterException
+
+
Constructs a new ParameterException with the specified CommandLine and error message.
+
+
ParameterException(CommandLine, String, CommandLine.Model.ArgSpec, String) - Constructor for exception picocli.CommandLine.ParameterException
+
+
Constructs a new ParameterException with the specified CommandLine and error message.
+
+
parameterIndex(Field) - Static method in class picocli.CommandLine.Range
+
+
Returns a new Range based on the CommandLine.Parameters.index() annotation on the specified field.
+
+
ParameterIndexGapException(String) - Constructor for exception picocli.CommandLine.ParameterIndexGapException
+
 
+
parameterLabelRenderer() - Method in class picocli.CommandLine.Help
+
+
Option and positional parameter value label renderer used for the synopsis line(s) and the option list.
+
+
parameterList() - Method in class picocli.CommandLine.Help
+
+
Returns the section of the usage help message that lists the parameters with their descriptions.
+
+
parameterList(CommandLine.Help.Layout, CommandLine.Help.IParamLabelRenderer) - Method in class picocli.CommandLine.Help
+
+
Returns the section of the usage help message that lists the parameters with their descriptions.
+
+
parameterListHeading(Object...) - Method in class picocli.CommandLine.Help
+
+
Returns the text displayed before the positional parameter list; an empty string if there are no positional + parameters, otherwise the result of String.format(parameterListHeading, params).
+
+
parameterListHeading() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the optional heading preceding the parameter list.
+
+
parameterListHeading(String) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the optional heading preceding the parameter list.
+
+
parameterRenderer - Variable in class picocli.CommandLine.Help.Layout
+
 
+
parameters(CommandLine.Help.Ansi.IStyle...) - Method in class picocli.CommandLine.Help.ColorScheme
+
+
Adds the specified styles to the registered styles for positional parameters in this color scheme and returns this color scheme.
+
+
parameterStyles - Variable in class picocli.CommandLine.Help.ColorScheme
+
 
+
parameterText(String) - Method in class picocli.CommandLine.Help.ColorScheme
+
+
Returns a Text with all parameter styles applied to the specified parameter string.
+
+
paramLabel() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the name of the option or positional parameter used in the usage help message.
+
+
parent() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the parent command of this subcommand, or null if this is a top-level command.
+
+
parent(CommandLine.Model.CommandSpec) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Sets the parent command of this subcommand.
+
+
parse(String) - Static method in enum picocli.CommandLine.Help.Ansi.Style
+
+
Parses the specified comma-separated sequence of style descriptors and returns the associated + styles.
+
+
parse(String...) - Method in class picocli.CommandLine
+
+
Parses the specified command line arguments and returns a list of CommandLine objects representing the + top-level command and any subcommands (if any) that were recognized and initialized during the parsing process.
+
+
parseArgs(String...) - Method in class picocli.CommandLine
+
+
Parses the specified command line arguments and returns a list of ParseResult with the options, positional + parameters, and subcommands (if any) that were recognized and initialized during the parsing process.
+
+
parser() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the parser specification for this command.
+
+
parser(CommandLine.Model.ParserSpec) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Initializes the parser specification for this command from the specified settings and returns this commandSpec.
+
+
ParserSpec() - Constructor for class picocli.CommandLine.Model.ParserSpec
+
 
+
parseScriptArguments(CommandLine, String[]) - Method in class picocli.groovy.PicocliBaseScript
+
+
Returns the result of calling CommandLine.parse(String...) with the given arguments.
+
+
parseWithHandler(CommandLine.IParseResultHandler, PrintStream, String...) - Method in class picocli.CommandLine
+
+
Deprecated. +
use CommandLine.parseWithHandler(IParseResultHandler2, String[]) instead
+
+
+
parseWithHandler(CommandLine.IParseResultHandler2<R>, String[]) - Method in class picocli.CommandLine
+
+
Returns the result of calling CommandLine.parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...) with + a new CommandLine.DefaultExceptionHandler in addition to the specified parse result handler and the specified command line arguments.
+
+
parseWithHandlers(CommandLine.IParseResultHandler, PrintStream, CommandLine.Help.Ansi, CommandLine.IExceptionHandler, String...) - Method in class picocli.CommandLine
+
+
Deprecated. +
use CommandLine.parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...) instead
+
+
+
parseWithHandlers(CommandLine.IParseResultHandler2<R>, CommandLine.IExceptionHandler2<R>, String...) - Method in class picocli.CommandLine
+
+
Tries to parse the specified command line arguments, and if successful, delegates + the processing of the resulting ParseResult object to the specified handler.
+
+
picocli - package picocli
+
+
Provides classes and interfaces for the main picocli command line parsing and + autocompletion functionality.
+
+
picocli.groovy - package picocli.groovy
+
+
Provides classes and annotations to give Groovy scripts convenient access to picocli functionality.
+
+
PicocliBaseScript - Class in picocli.groovy
+
+
+ Base script class that provides picocli declarative (annotation-based) command line argument processing for Groovy scripts.
+
+
PicocliBaseScript() - Constructor for class picocli.groovy.PicocliBaseScript
+
 
+
PicocliException(String) - Constructor for exception picocli.CommandLine.PicocliException
+
 
+
PicocliException(String, Throwable) - Constructor for exception picocli.CommandLine.PicocliException
+
 
+
PicocliScript - Annotation Type in picocli.groovy
+
+
+ Annotation to give Groovy scripts convenient access to picocli functionality.
+
+
PicocliScriptASTTransformation - Class in picocli.groovy
+
+
Ensures that Groovy scripts annotated with PicocliScript are transformed into a class that + extends PicocliBaseScript.
+
+
PicocliScriptASTTransformation() - Constructor for class picocli.groovy.PicocliScriptASTTransformation
+
 
+
plainString() - Method in class picocli.CommandLine.Help.Ansi.Text
+
+
Returns the plain text without any formatting.
+
+
populateCommand(T, String...) - Static method in class picocli.CommandLine
+
+
+ Convenience method that initializes the specified annotated object from the specified command line arguments.
+
+
populateSpec(Class<T>, String...) - Static method in class picocli.CommandLine
+
+
+ Convenience method that derives the command specification from the specified interface class, and returns an + instance of the specified interface.
+
+
positionalParameters() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the list of positional parameters configured for this command.
+
+
posixClusteredShortOptionsAllowed() - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
posixClusteredShortOptionsAllowed(boolean) - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
posixOptionsMap() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns a map of the short (single character) option names to option spec objects configured for this command.
+
+
printErrorMessage(String) - Method in class picocli.groovy.PicocliBaseScript
+
+
Error messages that arise from command line processing call this.
+
+
printHelpIfRequested(List<CommandLine>, PrintStream, CommandLine.Help.Ansi) - Static method in class picocli.CommandLine
+
+
Deprecated. +
use CommandLine.printHelpIfRequested(List, PrintStream, PrintStream, Help.Ansi) instead
+
+
+
printHelpIfRequested(CommandLine.ParseResult) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.printHelpIfRequested(List, PrintStream, PrintStream, Help.Ansi) with + parseResult.asCommandLineList(), System.out, System.err, Help.Ansi.AUTO.
+
+
printHelpIfRequested(List<CommandLine>, PrintStream, PrintStream, CommandLine.Help.Ansi) - Static method in class picocli.CommandLine
+
+
Helper method that may be useful when processing the list of CommandLine objects that result from successfully + parsing command line arguments.
+
+
printHelpIfRequested(List<CommandLine>, PrintStream, PrintStream, CommandLine.Help.ColorScheme) - Static method in class picocli.CommandLine
+
+
Helper method that may be useful when processing the list of CommandLine objects that result from successfully + parsing command line arguments.
+
+
printHelpMessage(CommandLine) - Method in class picocli.groovy.PicocliBaseScript
+
+
If an @Option whose usageHelp attribute is annotated as true appears in the arguments.
+
+
printHelpMessage(CommandLine, PrintStream) - Method in class picocli.groovy.PicocliBaseScript
+
+
If an @Option whose usageHelp attribute is annotated as true appears in the arguments.
+
+
printSuggestions(CommandLine.ParameterException, PrintStream) - Static method in exception picocli.CommandLine.UnmatchedArgumentException
+
+
Returns true and prints suggested solutions to the specified stream if such solutions exist, otherwise returns false.
+
+
printSuggestions(PrintStream) - Method in exception picocli.CommandLine.UnmatchedArgumentException
+
+
Returns true and prints suggested solutions to the specified stream if such solutions exist, otherwise returns false.
+
+
printVersionHelp(PrintStream) - Method in class picocli.CommandLine
+
+
Delegates to CommandLine.printVersionHelp(PrintStream, Help.Ansi) with the platform default.
+
+
printVersionHelp(PrintStream, CommandLine.Help.Ansi) - Method in class picocli.CommandLine
+
+
Prints version information from the CommandLine.Command.version() annotation to the specified PrintStream.
+
+
printVersionHelp(PrintStream, CommandLine.Help.Ansi, Object...) - Method in class picocli.CommandLine
+
+
Prints version information from the CommandLine.Command.version() annotation to the specified PrintStream.
+
+
printVersionHelpMessage(CommandLine) - Method in class picocli.groovy.PicocliBaseScript
+
+
If an @Option whose versionHelp attribute is annotated as true appears in the arguments.
+
+
putValue(int, int, CommandLine.Help.Ansi.Text) - Method in class picocli.CommandLine.Help.TextTable
+
+
Writes the specified value into the cell at the specified row and column and returns the last row and + column written to.
+
+
+ + + +

Q

+
+
qualifiedName() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the String to use as the program name in the synopsis line of the help message: + this command's name, preceded by the qualified name of the parent command, if any, separated by a space.
+
+
qualifiedName(String) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns this command's fully qualified name, which is its name, preceded by the qualified name of the parent command, if this command has a parent command.
+
+
+ + + +

R

+
+
Range(int, int, boolean, boolean, String) - Constructor for class picocli.CommandLine.Range
+
+
Constructs a new Range object with the specified parameters.
+
+
registerConverter(Class<K>, CommandLine.ITypeConverter<K>) - Method in class picocli.CommandLine
+
+
Registers the specified type converter for the specified class.
+
+
render(CommandLine.Model.OptionSpec, CommandLine.Help.IParamLabelRenderer, CommandLine.Help.ColorScheme) - Method in interface picocli.CommandLine.Help.IOptionRenderer
+
+
Returns a text representation of the specified option and its parameter(s) if any.
+
+
render(CommandLine.Model.PositionalParamSpec, CommandLine.Help.IParamLabelRenderer, CommandLine.Help.ColorScheme) - Method in interface picocli.CommandLine.Help.IParameterRenderer
+
+
Returns a text representation of the specified positional parameter.
+
+
render(CommandLine.Help) - Method in interface picocli.CommandLine.IHelpSectionRenderer
+
+
Renders a section of the usage help, like header heading, header, synopsis heading, + synopsis, description heading, description, etc.
+
+
renderedDescription() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the description of this option, after variables are rendered.
+
+
renderParameterLabel(CommandLine.Model.ArgSpec, CommandLine.Help.Ansi, List<CommandLine.Help.Ansi.IStyle>) - Method in interface picocli.CommandLine.Help.IParamLabelRenderer
+
+
Returns a text rendering of the option parameter or positional parameter; returns an empty string + "" if the option is a boolean and does not take a parameter.
+
+
required() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns whether this is a required option or positional parameter.
+
+
requiredArgs() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the list of required options and positional parameters configured for this command.
+
+
requiredOptionMarker() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the character used to prefix required options in the options list.
+
+
requiredOptionMarker(char) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the character used to prefix required options in the options list.
+
+
resetOriginalStringValues() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Sets the originalStringValues to a new list instance.
+
+
resetStringValues() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Sets the stringValues to a new list instance.
+
+
resourceBundle() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the resource bundle for this command.
+
+
resourceBundle(ResourceBundle) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Initializes the resource bundle for this command: sets the UsageMessageSpec.messages to + a Messages object created from this command spec and the specified bundle, and then sets the + ArgSpec.messages of all options and positional parameters in this command + to the same Messages instance.
+
+
resourceBundle(CommandLine.Model.Messages) - Static method in class picocli.CommandLine.Model.Messages
+
+
Returns the ResourceBundle of the specified Messages object or null if the specified Messages object is null.
+
+
resourceBundle() - Method in class picocli.CommandLine.Model.Messages
+
+
Returns the ResourceBundle of this object or null.
+
+
returnResultOrExit(R) - Method in class picocli.CommandLine.AbstractHandler
+
+
Convenience method for subclasses that returns the specified result object if no exit code was set, + or otherwise, if an exit code was set, calls System.exit with the configured + exit code to terminate the currently running Java virtual machine.
+
+
row - Variable in class picocli.CommandLine.Help.TextTable.Cell
+
+
Table row index (zero based).
+
+
rowCount() - Method in class picocli.CommandLine.Help.TextTable
+
+
Returns the current number of rows of this TextTable.
+
+
run() - Method in class picocli.CommandLine.HelpCommand
+
+
Invokes usage for the specified command, or for the parent command.
+
+
run(R, String...) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.run(Runnable, PrintStream, PrintStream, Help.Ansi, String...) with System.out for + requested usage help messages, System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO.
+
+
run(R, PrintStream, String...) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.run(Runnable, PrintStream, PrintStream, Help.Ansi, String...) with System.err for diagnostic error messages and CommandLine.Help.Ansi.AUTO.
+
+
run(R, PrintStream, CommandLine.Help.Ansi, String...) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.run(Runnable, PrintStream, PrintStream, Help.Ansi, String...) with System.err for diagnostic error messages.
+
+
run(R, PrintStream, PrintStream, CommandLine.Help.Ansi, String...) - Static method in class picocli.CommandLine
+
+
Convenience method to allow command line application authors to avoid some boilerplate code in their application.
+
+
run(Class<R>, CommandLine.IFactory, String...) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.run(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...) with System.out for + requested usage help messages, System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO.
+
+
run(Class<R>, CommandLine.IFactory, PrintStream, String...) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.run(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...) with + System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO.
+
+
run(Class<R>, CommandLine.IFactory, PrintStream, CommandLine.Help.Ansi, String...) - Static method in class picocli.CommandLine
+
+
Delegates to CommandLine.run(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...) with + System.err for diagnostic error messages.
+
+
run(Class<R>, CommandLine.IFactory, PrintStream, PrintStream, CommandLine.Help.Ansi, String...) - Static method in class picocli.CommandLine
+
+
Convenience method to allow command line application authors to avoid some boilerplate code in their application.
+
+
run() - Method in class picocli.groovy.PicocliBaseScript
+
+
+ Parses the command line and initializes @Field variables + annotated with @Option or @Parameters before executing the script body.
+
+
RunAll() - Constructor for class picocli.CommandLine.RunAll
+
 
+
RunFirst() - Constructor for class picocli.CommandLine.RunFirst
+
 
+
RunLast() - Constructor for class picocli.CommandLine.RunLast
+
 
+
runRunnableSubcommand(List<CommandLine>) - Method in class picocli.groovy.PicocliBaseScript
+
+
If the most specific subcommand (the last CommandLine object in the list) implements Runnable or Callable, + then run it.
+
+
runScriptBody() - Method in class picocli.groovy.PicocliBaseScript
+
+
The script body.
+
+
+ + + +

S

+
+
SECTION_KEY_COMMAND_LIST - Static variable in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Section key to control the section renderer for the Subcommand List section.
+
+
SECTION_KEY_COMMAND_LIST_HEADING - Static variable in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Section key to control the section renderer for the Subcommand List Heading section.
+
+
SECTION_KEY_DESCRIPTION - Static variable in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Section key to control the section renderer for the Description section.
+
+
SECTION_KEY_DESCRIPTION_HEADING - Static variable in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Section key to control the section renderer for the Description Heading section.
+
+
SECTION_KEY_FOOTER - Static variable in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Section key to control the section renderer for the Footer section.
+
+
SECTION_KEY_FOOTER_HEADING - Static variable in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Section key to control the section renderer for the Footer Heading section.
+
+
SECTION_KEY_HEADER - Static variable in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Section key to control the section renderer for the Header section.
+
+
SECTION_KEY_HEADER_HEADING - Static variable in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Section key to control the section renderer for the Header Heading section.
+
+
SECTION_KEY_OPTION_LIST - Static variable in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Section key to control the section renderer for the Option List section.
+
+
SECTION_KEY_OPTION_LIST_HEADING - Static variable in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Section key to control the section renderer for the Option List Heading section.
+
+
SECTION_KEY_PARAMETER_LIST - Static variable in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Section key to control the section renderer for the Parameter List section.
+
+
SECTION_KEY_PARAMETER_LIST_HEADING - Static variable in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Section key to control the section renderer for the Parameter List Heading section.
+
+
SECTION_KEY_SYNOPSIS - Static variable in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Section key to control the section renderer for the Synopsis section.
+
+
SECTION_KEY_SYNOPSIS_HEADING - Static variable in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Section key to control the section renderer for the Synopsis Heading section.
+
+
sectionKeys() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the section keys in the order that the usage help message should render the sections.
+
+
sectionKeys(List<String>) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the section keys in the order that the usage help message should render the sections.
+
+
sectionMap() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the map of section keys and renderers used to construct the usage help message.
+
+
sectionMap(Map<String, CommandLine.IHelpSectionRenderer>) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the map of section keys and renderers used to construct the usage help message to a copy of the specified map.
+
+
self() - Method in class picocli.CommandLine.AbstractHandler
+
+
Returns this to allow method chaining when calling the setters for a fluent API.
+
+
self() - Method in class picocli.CommandLine.DefaultExceptionHandler
+
 
+
self() - Method in class picocli.CommandLine.Model.OptionSpec.Builder
+
+
Returns this builder.
+
+
self() - Method in class picocli.CommandLine.Model.PositionalParamSpec.Builder
+
+
Returns this builder.
+
+
self() - Method in class picocli.CommandLine.RunAll
+
 
+
self() - Method in class picocli.CommandLine.RunFirst
+
 
+
self() - Method in class picocli.CommandLine.RunLast
+
 
+
separator() - Method in interface picocli.CommandLine.Help.IParamLabelRenderer
+
+
Returns the separator between option name and param label.
+
+
separator() - Method in class picocli.CommandLine.Model.ParserSpec
+
+
Returns the String to use as the separator between options and option parameters.
+
+
separator(String) - Method in class picocli.CommandLine.Model.ParserSpec
+
+
Sets the String to use as the separator between options and option parameters.
+
+
set(T) - Method in interface picocli.CommandLine.Model.ISetter
+
+
Sets the new value of the option or positional parameter.
+
+
setAtFileCommentChar(Character) - Method in class picocli.CommandLine
+
+
Sets the character that starts a single-line comment or null if all content of argument files should + be interpreted as arguments (without comments).
+
+
setCaseInsensitiveEnumValuesAllowed(boolean) - Method in class picocli.CommandLine
+
+
Sets whether the parser should ignore case when converting arguments to enum values.
+
+
setCommandName(String) - Method in class picocli.CommandLine
+
+
Sets the command name (also called program name) displayed in the usage help synopsis to the specified value.
+
+
setDefaultValueProvider(CommandLine.IDefaultValueProvider) - Method in class picocli.CommandLine
+
+
Sets a default value provider for the command and sub-commands
+
+
setEndOfOptionsDelimiter(String) - Method in class picocli.CommandLine
+
+
Sets the end-of-options delimiter that signals that the remaining command line arguments should be treated as positional parameters.
+
+
setExpandAtFiles(boolean) - Method in class picocli.CommandLine
+
+
Sets whether arguments starting with '@' should be treated as the path to an argument file and its + contents should be expanded into separate arguments for each line in the specified file.
+
+
setHelpFactory(CommandLine.IHelpFactory) - Method in class picocli.CommandLine
+
+
Sets a new IHelpFactory to customize the usage help message.
+
+
setHelpSectionKeys(List<String>) - Method in class picocli.CommandLine
+
+
Sets the section keys in the order that the usage help message should render the sections.
+
+
setHelpSectionMap(Map<String, CommandLine.IHelpSectionRenderer>) - Method in class picocli.CommandLine
+
+
Sets the map of section keys and renderers used to construct the usage help message.
+
+
setOverwrittenOptionsAllowed(boolean) - Method in class picocli.CommandLine
+
+
Sets whether options for single-value fields can be specified multiple times on the command line without a CommandLine.OverwrittenOptionException being thrown.
+
+
setPosixClusteredShortOptionsAllowed(boolean) - Method in class picocli.CommandLine
+
+
Sets whether short options like -x -v -f SomeFile can be clustered together like -xvfSomeFile.
+
+
setResourceBundle(ResourceBundle) - Method in class picocli.CommandLine
+
+
Sets the ResourceBundle containing usage help message strings.
+
+
setSeparator(String) - Method in class picocli.CommandLine
+
+
Sets the String the parser uses to separate option names from option values to the specified value.
+
+
setSplitQuotedStrings(boolean) - Method in class picocli.CommandLine
+
+
Sets whether the parser is allowed to split quoted Strings.
+
+
setStopAtPositional(boolean) - Method in class picocli.CommandLine
+
+
Sets whether the parser interprets the first positional parameter as "end of options" so the remaining + arguments are all treated as positional parameters.
+
+
setStopAtUnmatched(boolean) - Method in class picocli.CommandLine
+
+
Sets whether the parser should stop interpreting options and positional parameters as soon as it encounters an + unmatched option.
+
+
setter() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the CommandLine.Model.ISetter that is responsible for modifying the value of this argument.
+
+
setter() - Method in class picocli.CommandLine.Model.UnmatchedArgsBinding
+
+
Returns the setter responsible for consuming the unmatched arguments.
+
+
setToggleBooleanFlags(boolean) - Method in class picocli.CommandLine
+
+
Sets whether the value of boolean flag options should be "toggled" when the option is matched.
+
+
setTrimQuotes(boolean) - Method in class picocli.CommandLine
+
+
Sets whether the parser should trim quotes from command line arguments before processing them.
+
+
setUnmatchedArgumentsAllowed(boolean) - Method in class picocli.CommandLine
+
+
Sets whether the end user may specify unmatched arguments on the command line without a CommandLine.UnmatchedArgumentException being thrown.
+
+
setUnmatchedOptionsArePositionalParams(boolean) - Method in class picocli.CommandLine
+
+
Sets whether arguments on the command line that resemble an option should be treated as positional parameters.
+
+
setUsageHelpWidth(int) - Method in class picocli.CommandLine
+
+
Sets the maximum width of the usage help message.
+
+
setUseSimplifiedAtFiles(boolean) - Method in class picocli.CommandLine
+
+
Sets whether to use a simplified argument file format that is compatible with JCommander.
+
+
setValue(T) - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Sets the value of this argument to the specified value and returns the previous value.
+
+
setValue(T, CommandLine) - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Deprecated. +
use CommandLine.Model.ArgSpec.setValue(Object) instead. This was a design mistake.
+
+
+
shortestFirst() - Static method in class picocli.CommandLine.Help
+
+
Sorts short strings before longer strings.
+
+
showDefaultValue() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns whether this option or positional parameter's default value should be shown in the usage help.
+
+
showDefaultValues() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns whether the options list in the usage help message should show default values for all non-boolean options.
+
+
showDefaultValues(boolean) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets whether the options list in the usage help message should show default values for all non-boolean options.
+
+
sortOptions() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns whether the options list in the usage help message should be sorted alphabetically.
+
+
sortOptions(boolean) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets whether the options list in the usage help message should be sorted alphabetically.
+
+
splitLines() - Method in class picocli.CommandLine.Help.Ansi.Text
+
 
+
splitQuotedStrings() - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
splitQuotedStrings(boolean) - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
splitRegex() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns a regular expression to split option parameter values or "" if the value should not be split.
+
+
stopAtPositional() - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
stopAtPositional(boolean) - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
stopAtUnmatched() - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
stopAtUnmatched(boolean) - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
string(String) - Method in enum picocli.CommandLine.Help.Ansi
+
+
Returns a String where any markup like + @|bg(red),white,underline some text|@ is converted to ANSI escape codes + if this Ansi is ON, or suppressed if this Ansi is OFF.
+
+
stringValues() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the untyped command line arguments matched by this option or positional parameter spec.
+
+
subcommand(CommandLine.ParseResult) - Method in class picocli.CommandLine.ParseResult.Builder
+
+
Sets the specified ParseResult for a subcommand that was matched on the command line.
+
+
subcommand() - Method in class picocli.CommandLine.ParseResult
+
+
Returns the ParseResult for the subcommand of this command that was matched on the command line, or null if no subcommand was matched.
+
+
subcommands() - Method in class picocli.CommandLine.Help
+
+
Returns the map of subcommand Help instances for this command Help.
+
+
subcommands() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns a read-only view of the subcommand map.
+
+
substring(int) - Method in class picocli.CommandLine.Help.Ansi.Text
+
+
Returns a new Text instance that is a substring of this Text.
+
+
substring(int, int) - Method in class picocli.CommandLine.Help.Ansi.Text
+
+
Returns a new Text instance that is a substring of this Text.
+
+
synopsis() - Method in class picocli.CommandLine.Help
+
+
Deprecated. +
use CommandLine.Help.synopsis(int) instead
+
+
+
synopsis(int) - Method in class picocli.CommandLine.Help
+
+
Returns a synopsis for the command, reserving the specified space for the synopsis heading.
+
+
synopsisHeading(Object...) - Method in class picocli.CommandLine.Help
+
+
Returns the text displayed before the synopsis text; the result of String.format(synopsisHeading, params).
+
+
synopsisHeading() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the optional heading preceding the synopsis.
+
+
synopsisHeading(String) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the optional heading preceding the synopsis.
+
+
synopsisHeadingLength() - Method in class picocli.CommandLine.Help
+
+
Returns the number of characters the synopsis heading will take on the same line as the synopsis.
+
+
+ + + +

T

+
+
table - Variable in class picocli.CommandLine.Help.Layout
+
 
+
text(String) - Method in enum picocli.CommandLine.Help.Ansi
+
+
Returns a new Text object for this Ansi mode, encapsulating the specified string + which may contain markup like @|bg(red),white,underline some text|@.
+
+
Text(int) - Constructor for class picocli.CommandLine.Help.Ansi.Text
+
+
Constructs a Text with the specified max length (for use in a TextTable Column).
+
+
Text(CommandLine.Help.Ansi.Text) - Constructor for class picocli.CommandLine.Help.Ansi.Text
+
+
Copy constructor.
+
+
Text(String) - Constructor for class picocli.CommandLine.Help.Ansi.Text
+
+
Constructs a Text with the specified String, which may contain markup like + @|bg(red),white,underline some text|@.
+
+
textAt(int, int) - Method in class picocli.CommandLine.Help.TextTable
+
+
Returns the Text slot at the specified row and column to write a text value into.
+
+
TextTable(CommandLine.Help.Ansi, CommandLine.Help.Column[]) - Constructor for class picocli.CommandLine.Help.TextTable
+
 
+
throwOrExit(CommandLine.ExecutionException) - Method in class picocli.CommandLine.AbstractHandler
+
+
Convenience method for subclasses that throws the specified ExecutionException if no exit code was set, + or otherwise, if an exit code was set, prints the stacktrace of the specified exception + to the diagnostic error stream and calls System.exit with the configured + exit code to terminate the currently running Java virtual machine.
+
+
toBuilder() - Method in class picocli.CommandLine.Model.OptionSpec
+
+
Returns a new Builder initialized with the attributes from this OptionSpec.
+
+
toBuilder() - Method in class picocli.CommandLine.Model.PositionalParamSpec
+
+
Returns a new Builder initialized with the attributes from this PositionalParamSpec.
+
+
toggleBooleanFlags() - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
toggleBooleanFlags(boolean) - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
toString() - Method in class picocli.CommandLine.Help.Ansi.Text
+
+
Returns a String representation of the text with ANSI escape codes embedded, unless ANSI is + CommandLine.Help.Ansi.enabled() not enabled}, in which case the plain text is returned.
+
+
toString() - Method in class picocli.CommandLine.Help.Layout
+
+
Returns the section of the usage help message accumulated in the TextTable owned by this layout.
+
+
toString(StringBuilder) - Method in class picocli.CommandLine.Help.TextTable
+
+
Copies the text representation that we built up from the options into the specified StringBuilder.
+
+
toString() - Method in class picocli.CommandLine.Help.TextTable
+
 
+
toString - Variable in class picocli.CommandLine.Model.ArgSpec
+
 
+
toString() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns a string respresentation of this option or positional parameter.
+
+
toString() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns a string representation of this command, used in error messages and trace messages.
+
+
toString() - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
toString() - Method in class picocli.CommandLine.Range
+
 
+
trimQuotes() - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
trimQuotes(boolean) - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
type() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the type to convert the option or positional parameter to before setting the value.
+
+
TypeConversionException(String) - Constructor for exception picocli.CommandLine.TypeConversionException
+
 
+
typedValues() - Method in class picocli.CommandLine.Model.ArgSpec
+
+
Returns the typed command line arguments matched by this option or positional parameter spec.
+
+
+ + + +

U

+
+
unmatched() - Method in class picocli.CommandLine.ParseResult
+
+
Returns a list of command line arguments that did not match any options or positional parameters.
+
+
unmatchedArgsBindings() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the list of UnmatchedArgumentsBindings configured for this command; + each UnmatchedArgsBinding captures the arguments that could not be matched to any options or positional parameters.
+
+
UnmatchedArgumentException(CommandLine, String) - Constructor for exception picocli.CommandLine.UnmatchedArgumentException
+
 
+
UnmatchedArgumentException(CommandLine, Stack<String>) - Constructor for exception picocli.CommandLine.UnmatchedArgumentException
+
 
+
UnmatchedArgumentException(CommandLine, List<String>) - Constructor for exception picocli.CommandLine.UnmatchedArgumentException
+
 
+
unmatchedArgumentsAllowed() - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
unmatchedArgumentsAllowed(boolean) - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
unmatchedOptionsArePositionalParams() - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
unmatchedOptionsArePositionalParams(boolean) - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
unspecified(boolean) - Method in class picocli.CommandLine.Range
+
+
Returns a new Range object with the isUnspecified value replaced by the specified value.
+
+
usage(Object, PrintStream) - Static method in class picocli.CommandLine
+
+
Equivalent to new CommandLine(command).usage(out).
+
+
usage(Object, PrintStream, CommandLine.Help.Ansi) - Static method in class picocli.CommandLine
+
+
Equivalent to new CommandLine(command).usage(out, ansi).
+
+
usage(Object, PrintStream, CommandLine.Help.ColorScheme) - Static method in class picocli.CommandLine
+
+
Equivalent to new CommandLine(command).usage(out, colorScheme).
+
+
usage(PrintStream) - Method in class picocli.CommandLine
+
+
Delegates to CommandLine.usage(PrintStream, Help.Ansi) with the platform default.
+
+
usage(PrintWriter) - Method in class picocli.CommandLine
+
+
Delegates to CommandLine.usage(PrintWriter, Help.Ansi) with the platform default.
+
+
usage(PrintStream, CommandLine.Help.Ansi) - Method in class picocli.CommandLine
+
+
Delegates to CommandLine.usage(PrintStream, Help.ColorScheme) with the default color scheme.
+
+
usage(PrintWriter, CommandLine.Help.Ansi) - Method in class picocli.CommandLine
+
+
Similar to CommandLine.usage(PrintStream, Help.Ansi) but with the specified PrintWriter instead of a PrintStream.
+
+
usage(PrintStream, CommandLine.Help.ColorScheme) - Method in class picocli.CommandLine
+
+
Prints a usage help message for the annotated command class to the specified PrintStream.
+
+
usage(PrintWriter, CommandLine.Help.ColorScheme) - Method in class picocli.CommandLine
+
+
Similar to CommandLine.usage(PrintStream, Help.ColorScheme), but with the specified PrintWriter instead of a PrintStream.
+
+
usageHelp() - Method in class picocli.CommandLine.Model.OptionSpec.Builder
+
+
Returns whether this option allows the user to request usage help.
+
+
usageHelp(boolean) - Method in class picocli.CommandLine.Model.OptionSpec.Builder
+
+
Sets whether this option allows the user to request usage help, and returns this builder.
+
+
usageHelp() - Method in class picocli.CommandLine.Model.OptionSpec
+
+
Returns whether this option allows the user to request usage help.
+
+
usageMessage() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the usage help message specification for this command.
+
+
usageMessage(CommandLine.Model.UsageMessageSpec) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Initializes the usageMessage specification for this command from the specified settings and returns this commandSpec.
+
+
UsageMessageSpec() - Constructor for class picocli.CommandLine.Model.UsageMessageSpec
+
 
+
useAnsi(CommandLine.Help.Ansi) - Method in class picocli.CommandLine.AbstractHandler
+
+
Sets the ANSI style to use.
+
+
useErr(PrintStream) - Method in class picocli.CommandLine.AbstractHandler
+
+
Sets the stream to print diagnostic messages to.
+
+
useOut(PrintStream) - Method in class picocli.CommandLine.AbstractHandler
+
+
Sets the stream to print command output to.
+
+
userObject() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the user object associated with this command.
+
+
useSimplifiedAtFiles() - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
useSimplifiedAtFiles(boolean) - Method in class picocli.CommandLine.Model.ParserSpec
+
 
+
+ + + +

V

+
+
valueOf(String) - Static method in enum picocli.CommandLine.Help.Ansi.Style
+
+
Returns the enum constant of this type with the specified name.
+
+
valueOf(String) - Static method in enum picocli.CommandLine.Help.Ansi
+
+
Returns the enum constant of this type with the specified name.
+
+
valueOf(boolean) - Static method in enum picocli.CommandLine.Help.Ansi
+
+
Returns Ansi.ON if the specified enabled flag is true, Ansi.OFF otherwise.
+
+
valueOf(String) - Static method in enum picocli.CommandLine.Help.Column.Overflow
+
+
Returns the enum constant of this type with the specified name.
+
+
valueOf(String) - Static method in enum picocli.CommandLine.Help.Visibility
+
+
Returns the enum constant of this type with the specified name.
+
+
valueOf(String) - Static method in class picocli.CommandLine.Range
+
+
Leniently parses the specified String as an Range value and return the result.
+
+
values() - Static method in enum picocli.CommandLine.Help.Ansi.Style
+
+
Returns an array containing the constants of this enum type, in +the order they are declared.
+
+
values() - Static method in enum picocli.CommandLine.Help.Ansi
+
+
Returns an array containing the constants of this enum type, in +the order they are declared.
+
+
values() - Static method in enum picocli.CommandLine.Help.Column.Overflow
+
+
Returns an array containing the constants of this enum type, in +the order they are declared.
+
+
values() - Static method in enum picocli.CommandLine.Help.Visibility
+
+
Returns an array containing the constants of this enum type, in +the order they are declared.
+
+
version() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns version information for this command, to print to the console when the user specifies an + option to request version help.
+
+
version(String...) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Sets version information literals for this command, to print to the console when the user specifies an + option to request version help.
+
+
VERSION - Static variable in class picocli.CommandLine
+
+
This is picocli version "3.9.5".
+
+
versionHelp() - Method in class picocli.CommandLine.Model.OptionSpec.Builder
+
+
Returns whether this option allows the user to request version information.
+
+
versionHelp(boolean) - Method in class picocli.CommandLine.Model.OptionSpec.Builder
+
+
Sets whether this option allows the user to request version information, and returns this builder.
+
+
versionHelp() - Method in class picocli.CommandLine.Model.OptionSpec
+
+
Returns whether this option allows the user to request version information.
+
+
versionProvider() - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Returns the version provider for this command, to generate the CommandLine.Model.CommandSpec.version() strings.
+
+
versionProvider(CommandLine.IVersionProvider) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Sets version provider for this command, to generate the CommandLine.Model.CommandSpec.version() strings.
+
+
visit(ASTNode[], SourceUnit) - Method in class picocli.groovy.PicocliScriptASTTransformation
+
 
+
+ + + +

W

+
+
width - Variable in class picocli.CommandLine.Help.Column
+
+
Column width in characters
+
+
width(int) - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Sets the maximum usage help message width to the specified value.
+
+
width() - Method in class picocli.CommandLine.Model.UsageMessageSpec
+
+
Returns the maximum usage help message width.
+
+
withToString(String) - Method in class picocli.CommandLine.Model.CommandSpec
+
+
Sets the string representation of this command, used in error messages and trace messages.
+
+
wrapWithoutInspection(Object) - Static method in class picocli.CommandLine.Model.CommandSpec
+
+
Creates and returns a new CommandSpec with the specified associated user object.
+
+
+A B C D E F G H I J L M N O P Q R S T U V W 
+ +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/index.html b/docs/man/3.x/apidocs/index.html new file mode 100644 index 000000000..42143c108 --- /dev/null +++ b/docs/man/3.x/apidocs/index.html @@ -0,0 +1,75 @@ + + + + + +picocli 3.9.5 API + + + + + + + + + +<noscript> +<div>JavaScript is disabled on your browser.</div> +</noscript> +<h2>Frame Alert</h2> +<p>This document is designed to be viewed using the frames feature. If you see this message, you are using a non-frame-capable web client. Link to <a href="overview-summary.html">Non-frame version</a>.</p> + + + diff --git a/docs/man/3.x/apidocs/overview-frame.html b/docs/man/3.x/apidocs/overview-frame.html new file mode 100644 index 000000000..0ab77e65c --- /dev/null +++ b/docs/man/3.x/apidocs/overview-frame.html @@ -0,0 +1,22 @@ + + + + + +Overview List (picocli 3.9.5 API) + + + + + +
All Classes
+
+

Packages

+ +
+

 

+ + diff --git a/docs/man/3.x/apidocs/overview-summary.html b/docs/man/3.x/apidocs/overview-summary.html new file mode 100644 index 000000000..43ebefa08 --- /dev/null +++ b/docs/man/3.x/apidocs/overview-summary.html @@ -0,0 +1,204 @@ + + + + + +Overview (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ +
+

picocli 3.9.5 API

+
+
+
+
+ Picocli is a one-file framework for creating Java command line applications with almost zero code.
+
+

See: Description

+
+
+ + + + + + + + + + + + + + + + +
Packages 
PackageDescription
picocli +
Provides classes and interfaces for the main picocli command line parsing and + autocompletion functionality.
+
picocli.groovy +
Provides classes and annotations to give Groovy scripts convenient access to picocli functionality.
+
+
+
+ + +

+ Picocli is a one-file framework for creating Java command line applications with almost zero code. + It supports a variety of command line syntax styles including POSIX, GNU, MS-DOS and more. + Generates highly customizable usage help messages with ANSI colors and styles. + Picocli-based applications can have command line TAB completion + showing available options, option parameters and subcommands, for any level of nested subcommands. +

+

+ How it works: annotate your class and picocli initializes it from the command line arguments, + converting the input to strongly typed values in the fields of your class. + Then invoke CommandLine.parse or CommandLine.populateCommand with the command line parameters and an object you want to initialize. +

+

+ Picocli provides a number of convenience methods + that allow you to omit error handling and other boilerplate code for common use cases. + Here is a small example application that uses the CommandLine.call convenience method + to do parsing and error handling in one line of code. +

+

+ The full user manual is hosted at http://picocli.info. +

+
+@Command(name = "checksum", mixinStandardHelpOptions = true, version = "Checksum 2.0",
+    description = "Prints the checksum (MD5 by default) of a file to STDOUT.")
+class CheckSum implements Callable<Void> {
+
+    @Parameters(index = "0", description = "The file whose checksum to calculate.")
+    private File file;
+
+    @Option(names = {"-a", "--algorithm"}, description = "MD5, SHA-1, SHA-256, ...")
+    private String algorithm = "MD5";
+
+    public static void main(String[] args) throws Exception {
+        // CheckSum implements Callable, so parsing, error handling and handling user
+        // requests for usage help or version help can be done with one line of code.
+        CommandLine.call(new CheckSum(), args);
+    }
+
+    @Override
+    public Void call() throws Exception {
+        // your business logic goes here
+        byte[] fileContents = Files.readAllBytes(file.toPath());
+        byte[] digest = MessageDigest.getInstance(algorithm).digest(fileContents);
+        System.out.println(javax.xml.bind.DatatypeConverter.printHexBinary(digest));
+        return null;
+    }
+}
+
+
+ +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/overview-tree.html b/docs/man/3.x/apidocs/overview-tree.html new file mode 100644 index 000000000..9712f6229 --- /dev/null +++ b/docs/man/3.x/apidocs/overview-tree.html @@ -0,0 +1,267 @@ + + + + + +Class Hierarchy (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ +
+

Hierarchy For All Packages

+Package Hierarchies: + +
+
+

Class Hierarchy

+ +

Interface Hierarchy

+ +

Annotation Type Hierarchy

+ +

Enum Hierarchy

+ +
+ +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/package-list b/docs/man/3.x/apidocs/package-list new file mode 100644 index 000000000..895b4631b --- /dev/null +++ b/docs/man/3.x/apidocs/package-list @@ -0,0 +1,2 @@ +picocli +picocli.groovy diff --git a/docs/man/3.x/apidocs/picocli/AutoComplete.html b/docs/man/3.x/apidocs/picocli/AutoComplete.html new file mode 100644 index 000000000..77d5e55f7 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/AutoComplete.html @@ -0,0 +1,452 @@ + + + + + +AutoComplete (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class AutoComplete

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.AbstractHandler.html b/docs/man/3.x/apidocs/picocli/CommandLine.AbstractHandler.html new file mode 100644 index 000000000..4b6d958ff --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.AbstractHandler.html @@ -0,0 +1,530 @@ + + + + + +CommandLine.AbstractHandler (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.AbstractHandler<R,T extends CommandLine.AbstractHandler<R,T>>

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.AbstractParseResultHandler.html b/docs/man/3.x/apidocs/picocli/CommandLine.AbstractParseResultHandler.html new file mode 100644 index 000000000..b09c5b3b5 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.AbstractParseResultHandler.html @@ -0,0 +1,356 @@ + + + + + +CommandLine.AbstractParseResultHandler (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.AbstractParseResultHandler<R>

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.AbstractSimpleParseResultHandler.html b/docs/man/3.x/apidocs/picocli/CommandLine.AbstractSimpleParseResultHandler.html new file mode 100644 index 000000000..d0949b631 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.AbstractSimpleParseResultHandler.html @@ -0,0 +1,370 @@ + + + + + +CommandLine.AbstractSimpleParseResultHandler (picocli 3.0.0-alpha-1 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.AbstractSimpleParseResultHandler

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Arity.html b/docs/man/3.x/apidocs/picocli/CommandLine.Arity.html new file mode 100644 index 000000000..5f7424434 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Arity.html @@ -0,0 +1,538 @@ + + + + + +CommandLine.Arity (picocli 0.9.6 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Arity

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Command.html b/docs/man/3.x/apidocs/picocli/CommandLine.Command.html new file mode 100644 index 000000000..5a7363e60 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Command.html @@ -0,0 +1,1130 @@ + + + + + +CommandLine.Command (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Annotation Type CommandLine.Command

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.DefaultExceptionHandler.html b/docs/man/3.x/apidocs/picocli/CommandLine.DefaultExceptionHandler.html new file mode 100644 index 000000000..2cd03ac80 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.DefaultExceptionHandler.html @@ -0,0 +1,411 @@ + + + + + +CommandLine.DefaultExceptionHandler (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.DefaultExceptionHandler<R>

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.DuplicateOptionAnnotationsException.html b/docs/man/3.x/apidocs/picocli/CommandLine.DuplicateOptionAnnotationsException.html new file mode 100644 index 000000000..8b4ad8346 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.DuplicateOptionAnnotationsException.html @@ -0,0 +1,280 @@ + + + + + +CommandLine.DuplicateOptionAnnotationsException (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.DuplicateOptionAnnotationsException

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.ExecutionException.html b/docs/man/3.x/apidocs/picocli/CommandLine.ExecutionException.html new file mode 100644 index 000000000..b5aeaaef5 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.ExecutionException.html @@ -0,0 +1,336 @@ + + + + + +CommandLine.ExecutionException (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.ExecutionException

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Help.Ansi.IStyle.html b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Ansi.IStyle.html new file mode 100644 index 000000000..bd5e44f91 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Ansi.IStyle.html @@ -0,0 +1,298 @@ + + + + + +CommandLine.Help.Ansi.IStyle (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.Help.Ansi.IStyle

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Help.Ansi.Style.html b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Ansi.Style.html new file mode 100644 index 000000000..12a358ae8 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Ansi.Style.html @@ -0,0 +1,779 @@ + + + + + +CommandLine.Help.Ansi.Style (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Enum CommandLine.Help.Ansi.Style

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Help.Ansi.Text.html b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Ansi.Text.html new file mode 100644 index 000000000..93e632874 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Ansi.Text.html @@ -0,0 +1,588 @@ + + + + + +CommandLine.Help.Ansi.Text (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Help.Ansi.Text

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Help.Ansi.html b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Ansi.html new file mode 100644 index 000000000..2d30d7944 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Ansi.html @@ -0,0 +1,523 @@ + + + + + +CommandLine.Help.Ansi (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Enum CommandLine.Help.Ansi

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Help.ColorScheme.html b/docs/man/3.x/apidocs/picocli/CommandLine.Help.ColorScheme.html new file mode 100644 index 000000000..a58be3b51 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Help.ColorScheme.html @@ -0,0 +1,583 @@ + + + + + +CommandLine.Help.ColorScheme (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Help.ColorScheme

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Help.Column.Overflow.html b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Column.Overflow.html new file mode 100644 index 000000000..0e68b79d5 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Column.Overflow.html @@ -0,0 +1,357 @@ + + + + + +CommandLine.Help.Column.Overflow (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Enum CommandLine.Help.Column.Overflow

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Help.Column.html b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Column.html new file mode 100644 index 000000000..978893a88 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Column.html @@ -0,0 +1,338 @@ + + + + + +CommandLine.Help.Column (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Help.Column

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Help.IOptionRenderer.html b/docs/man/3.x/apidocs/picocli/CommandLine.Help.IOptionRenderer.html new file mode 100644 index 000000000..cbb36e7af --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Help.IOptionRenderer.html @@ -0,0 +1,244 @@ + + + + + +CommandLine.Help.IOptionRenderer (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.Help.IOptionRenderer

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Help.IParamLabelRenderer.html b/docs/man/3.x/apidocs/picocli/CommandLine.Help.IParamLabelRenderer.html new file mode 100644 index 000000000..06a6febf5 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Help.IParamLabelRenderer.html @@ -0,0 +1,264 @@ + + + + + +CommandLine.Help.IParamLabelRenderer (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.Help.IParamLabelRenderer

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Help.IParameterRenderer.html b/docs/man/3.x/apidocs/picocli/CommandLine.Help.IParameterRenderer.html new file mode 100644 index 000000000..1e6652a73 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Help.IParameterRenderer.html @@ -0,0 +1,244 @@ + + + + + +CommandLine.Help.IParameterRenderer (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.Help.IParameterRenderer

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Help.Layout.html b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Layout.html new file mode 100644 index 000000000..8bc182091 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Layout.html @@ -0,0 +1,570 @@ + + + + + +CommandLine.Help.Layout (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Help.Layout

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Help.TextTable.Cell.html b/docs/man/3.x/apidocs/picocli/CommandLine.Help.TextTable.Cell.html new file mode 100644 index 000000000..131356370 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Help.TextTable.Cell.html @@ -0,0 +1,309 @@ + + + + + +CommandLine.Help.TextTable.Cell (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Help.TextTable.Cell

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Help.TextTable.html b/docs/man/3.x/apidocs/picocli/CommandLine.Help.TextTable.html new file mode 100644 index 000000000..21dcc297f --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Help.TextTable.html @@ -0,0 +1,694 @@ + + + + + +CommandLine.Help.TextTable (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Help.TextTable

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Help.Visibility.html b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Visibility.html new file mode 100644 index 000000000..11b0eb701 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Help.Visibility.html @@ -0,0 +1,356 @@ + + + + + +CommandLine.Help.Visibility (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Enum CommandLine.Help.Visibility

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Help.html b/docs/man/3.x/apidocs/picocli/CommandLine.Help.html new file mode 100644 index 000000000..465a28206 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Help.html @@ -0,0 +1,1644 @@ + + + + + +CommandLine.Help (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Help

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.HelpCommand.html b/docs/man/3.x/apidocs/picocli/CommandLine.HelpCommand.html new file mode 100644 index 000000000..9a1fb2e79 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.HelpCommand.html @@ -0,0 +1,335 @@ + + + + + +CommandLine.HelpCommand (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.HelpCommand

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.IDefaultValueProvider.html b/docs/man/3.x/apidocs/picocli/CommandLine.IDefaultValueProvider.html new file mode 100644 index 000000000..3b4b79b06 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.IDefaultValueProvider.html @@ -0,0 +1,245 @@ + + + + + +CommandLine.IDefaultValueProvider (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.IDefaultValueProvider

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.IExceptionHandler.html b/docs/man/3.x/apidocs/picocli/CommandLine.IExceptionHandler.html new file mode 100644 index 000000000..d650092c5 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.IExceptionHandler.html @@ -0,0 +1,268 @@ + + + + + +CommandLine.IExceptionHandler (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.IExceptionHandler

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.IExceptionHandler2.html b/docs/man/3.x/apidocs/picocli/CommandLine.IExceptionHandler2.html new file mode 100644 index 000000000..4d92a0cc7 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.IExceptionHandler2.html @@ -0,0 +1,288 @@ + + + + + +CommandLine.IExceptionHandler2 (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.IExceptionHandler2<R>

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.IFactory.html b/docs/man/3.x/apidocs/picocli/CommandLine.IFactory.html new file mode 100644 index 000000000..315c9a07b --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.IFactory.html @@ -0,0 +1,252 @@ + + + + + +CommandLine.IFactory (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.IFactory

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.IHelpCommandInitializable.html b/docs/man/3.x/apidocs/picocli/CommandLine.IHelpCommandInitializable.html new file mode 100644 index 000000000..671161a99 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.IHelpCommandInitializable.html @@ -0,0 +1,257 @@ + + + + + +CommandLine.IHelpCommandInitializable (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.IHelpCommandInitializable

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.IHelpFactory.html b/docs/man/3.x/apidocs/picocli/CommandLine.IHelpFactory.html new file mode 100644 index 000000000..0b3f5462e --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.IHelpFactory.html @@ -0,0 +1,240 @@ + + + + + +CommandLine.IHelpFactory (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.IHelpFactory

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.IHelpSectionRenderer.html b/docs/man/3.x/apidocs/picocli/CommandLine.IHelpSectionRenderer.html new file mode 100644 index 000000000..fef3dc888 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.IHelpSectionRenderer.html @@ -0,0 +1,250 @@ + + + + + +CommandLine.IHelpSectionRenderer (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.IHelpSectionRenderer

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.IParseResultHandler.html b/docs/man/3.x/apidocs/picocli/CommandLine.IParseResultHandler.html new file mode 100644 index 000000000..6890d86a4 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.IParseResultHandler.html @@ -0,0 +1,272 @@ + + + + + +CommandLine.IParseResultHandler (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.IParseResultHandler

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.IParseResultHandler2.html b/docs/man/3.x/apidocs/picocli/CommandLine.IParseResultHandler2.html new file mode 100644 index 000000000..c860ed01f --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.IParseResultHandler2.html @@ -0,0 +1,266 @@ + + + + + +CommandLine.IParseResultHandler2 (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.IParseResultHandler2<R>

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.ITypeConverter.html b/docs/man/3.x/apidocs/picocli/CommandLine.ITypeConverter.html new file mode 100644 index 000000000..c63717b48 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.ITypeConverter.html @@ -0,0 +1,274 @@ + + + + + +CommandLine.ITypeConverter (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.ITypeConverter<K>

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.IVersionProvider.html b/docs/man/3.x/apidocs/picocli/CommandLine.IVersionProvider.html new file mode 100644 index 000000000..916534886 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.IVersionProvider.html @@ -0,0 +1,239 @@ + + + + + +CommandLine.IVersionProvider (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.IVersionProvider

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.InitializationException.html b/docs/man/3.x/apidocs/picocli/CommandLine.InitializationException.html new file mode 100644 index 000000000..de14444aa --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.InitializationException.html @@ -0,0 +1,295 @@ + + + + + +CommandLine.InitializationException (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.InitializationException

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.MaxValuesExceededException.html b/docs/man/3.x/apidocs/picocli/CommandLine.MaxValuesExceededException.html new file mode 100644 index 000000000..492bdb941 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.MaxValuesExceededException.html @@ -0,0 +1,289 @@ + + + + + +CommandLine.MaxValuesExceededException (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.MaxValuesExceededException

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.MaxValuesforFieldExceededException.html b/docs/man/3.x/apidocs/picocli/CommandLine.MaxValuesforFieldExceededException.html new file mode 100644 index 000000000..3bca29279 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.MaxValuesforFieldExceededException.html @@ -0,0 +1,277 @@ + + + + + +CommandLine.MaxValuesforFieldExceededException (picocli 3.0.0-alpha-2 API) + + + + + + + +
+ + + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.MaxValuesforFieldExceededException

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.MissingParameterException.html b/docs/man/3.x/apidocs/picocli/CommandLine.MissingParameterException.html new file mode 100644 index 000000000..398b10b7f --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.MissingParameterException.html @@ -0,0 +1,341 @@ + + + + + +CommandLine.MissingParameterException (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.MissingParameterException

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.MissingTypeConverterException.html b/docs/man/3.x/apidocs/picocli/CommandLine.MissingTypeConverterException.html new file mode 100644 index 000000000..a71009a15 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.MissingTypeConverterException.html @@ -0,0 +1,290 @@ + + + + + +CommandLine.MissingTypeConverterException (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.MissingTypeConverterException

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Mixin.html b/docs/man/3.x/apidocs/picocli/CommandLine.Mixin.html new file mode 100644 index 000000000..7b9e0947f --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Mixin.html @@ -0,0 +1,257 @@ + + + + + +CommandLine.Mixin (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Annotation Type CommandLine.Mixin

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Model.ArgSpec.html b/docs/man/3.x/apidocs/picocli/CommandLine.Model.ArgSpec.html new file mode 100644 index 000000000..df3dc0393 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Model.ArgSpec.html @@ -0,0 +1,1030 @@ + + + + + +CommandLine.Model.ArgSpec (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Model.ArgSpec

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Model.CommandSpec.html b/docs/man/3.x/apidocs/picocli/CommandLine.Model.CommandSpec.html new file mode 100644 index 000000000..9ba4e3dcf --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Model.CommandSpec.html @@ -0,0 +1,1434 @@ + + + + + +CommandLine.Model.CommandSpec (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Model.CommandSpec

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Model.IBinding.html b/docs/man/3.x/apidocs/picocli/CommandLine.Model.IBinding.html new file mode 100644 index 000000000..e515f794e --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Model.IBinding.html @@ -0,0 +1,247 @@ + + + + + +CommandLine.Model.IBinding (picocli 3.0.0-alpha-3 API) + + + + + + + +
+ + + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.Model.IBinding

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Model.IGetter.html b/docs/man/3.x/apidocs/picocli/CommandLine.Model.IGetter.html new file mode 100644 index 000000000..3fc0adf3f --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Model.IGetter.html @@ -0,0 +1,241 @@ + + + + + +CommandLine.Model.IGetter (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.Model.IGetter

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Model.ISetter.html b/docs/man/3.x/apidocs/picocli/CommandLine.Model.ISetter.html new file mode 100644 index 000000000..0bcfff17f --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Model.ISetter.html @@ -0,0 +1,248 @@ + + + + + +CommandLine.Model.ISetter (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Interface CommandLine.Model.ISetter

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Model.Messages.html b/docs/man/3.x/apidocs/picocli/CommandLine.Model.Messages.html new file mode 100644 index 000000000..a67c3eff2 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Model.Messages.html @@ -0,0 +1,464 @@ + + + + + +CommandLine.Model.Messages (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Model.Messages

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Model.OptionSpec.Builder.html b/docs/man/3.x/apidocs/picocli/CommandLine.Model.OptionSpec.Builder.html new file mode 100644 index 000000000..9c28c4fc7 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Model.OptionSpec.Builder.html @@ -0,0 +1,1213 @@ + + + + + +CommandLine.Model.OptionSpec.Builder (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Model.OptionSpec.Builder

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Model.OptionSpec.html b/docs/man/3.x/apidocs/picocli/CommandLine.Model.OptionSpec.html new file mode 100644 index 000000000..264e63d12 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Model.OptionSpec.html @@ -0,0 +1,616 @@ + + + + + +CommandLine.Model.OptionSpec (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Model.OptionSpec

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Model.ParserSpec.html b/docs/man/3.x/apidocs/picocli/CommandLine.Model.ParserSpec.html new file mode 100644 index 000000000..442d3cbc9 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Model.ParserSpec.html @@ -0,0 +1,928 @@ + + + + + +CommandLine.Model.ParserSpec (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Model.ParserSpec

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Model.PositionalParamSpec.Builder.html b/docs/man/3.x/apidocs/picocli/CommandLine.Model.PositionalParamSpec.Builder.html new file mode 100644 index 000000000..806e08e76 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Model.PositionalParamSpec.Builder.html @@ -0,0 +1,1069 @@ + + + + + +CommandLine.Model.PositionalParamSpec.Builder (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Model.PositionalParamSpec.Builder

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Model.PositionalParamSpec.html b/docs/man/3.x/apidocs/picocli/CommandLine.Model.PositionalParamSpec.html new file mode 100644 index 000000000..f8d069167 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Model.PositionalParamSpec.html @@ -0,0 +1,476 @@ + + + + + +CommandLine.Model.PositionalParamSpec (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Model.PositionalParamSpec

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Model.UnmatchedArgsBinding.html b/docs/man/3.x/apidocs/picocli/CommandLine.Model.UnmatchedArgsBinding.html new file mode 100644 index 000000000..857ac80f1 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Model.UnmatchedArgsBinding.html @@ -0,0 +1,305 @@ + + + + + +CommandLine.Model.UnmatchedArgsBinding (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Model.UnmatchedArgsBinding

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Model.UsageMessageSpec.html b/docs/man/3.x/apidocs/picocli/CommandLine.Model.UsageMessageSpec.html new file mode 100644 index 000000000..dfa3f98e7 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Model.UsageMessageSpec.html @@ -0,0 +1,1524 @@ + + + + + +CommandLine.Model.UsageMessageSpec (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Model.UsageMessageSpec

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Model.html b/docs/man/3.x/apidocs/picocli/CommandLine.Model.html new file mode 100644 index 000000000..9b5b8b07e --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Model.html @@ -0,0 +1,283 @@ + + + + + +CommandLine.Model (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Model

+
+
+ +
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Option.html b/docs/man/3.x/apidocs/picocli/CommandLine.Option.html new file mode 100644 index 000000000..7543e7485 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Option.html @@ -0,0 +1,968 @@ + + + + + +CommandLine.Option (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Annotation Type CommandLine.Option

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.OverwrittenOptionException.html b/docs/man/3.x/apidocs/picocli/CommandLine.OverwrittenOptionException.html new file mode 100644 index 000000000..26ffd30f5 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.OverwrittenOptionException.html @@ -0,0 +1,332 @@ + + + + + +CommandLine.OverwrittenOptionException (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.OverwrittenOptionException

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.ParameterException.html b/docs/man/3.x/apidocs/picocli/CommandLine.ParameterException.html new file mode 100644 index 000000000..301008000 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.ParameterException.html @@ -0,0 +1,468 @@ + + + + + +CommandLine.ParameterException (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.ParameterException

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.ParameterIndexGapException.html b/docs/man/3.x/apidocs/picocli/CommandLine.ParameterIndexGapException.html new file mode 100644 index 000000000..696a14b8d --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.ParameterIndexGapException.html @@ -0,0 +1,280 @@ + + + + + +CommandLine.ParameterIndexGapException (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.ParameterIndexGapException

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Parameters.html b/docs/man/3.x/apidocs/picocli/CommandLine.Parameters.html new file mode 100644 index 000000000..853f10648 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Parameters.html @@ -0,0 +1,684 @@ + + + + + +CommandLine.Parameters (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Annotation Type CommandLine.Parameters

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.ParentCommand.html b/docs/man/3.x/apidocs/picocli/CommandLine.ParentCommand.html new file mode 100644 index 000000000..8f5590e5e --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.ParentCommand.html @@ -0,0 +1,195 @@ + + + + + +CommandLine.ParentCommand (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Annotation Type CommandLine.ParentCommand

+
+
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.ParseResult.Builder.html b/docs/man/3.x/apidocs/picocli/CommandLine.ParseResult.Builder.html new file mode 100644 index 000000000..77616b5ef --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.ParseResult.Builder.html @@ -0,0 +1,388 @@ + + + + + +CommandLine.ParseResult.Builder (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.ParseResult.Builder

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.ParseResult.html b/docs/man/3.x/apidocs/picocli/CommandLine.ParseResult.html new file mode 100644 index 000000000..a603bfc9e --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.ParseResult.html @@ -0,0 +1,691 @@ + + + + + +CommandLine.ParseResult (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.ParseResult

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.PicocliException.html b/docs/man/3.x/apidocs/picocli/CommandLine.PicocliException.html new file mode 100644 index 000000000..215fca0eb --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.PicocliException.html @@ -0,0 +1,294 @@ + + + + + +CommandLine.PicocliException (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.PicocliException

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Range.html b/docs/man/3.x/apidocs/picocli/CommandLine.Range.html new file mode 100644 index 000000000..072e27fd0 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Range.html @@ -0,0 +1,664 @@ + + + + + +CommandLine.Range (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.Range

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.RunAll.html b/docs/man/3.x/apidocs/picocli/CommandLine.RunAll.html new file mode 100644 index 000000000..66bc897e1 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.RunAll.html @@ -0,0 +1,391 @@ + + + + + +CommandLine.RunAll (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.RunAll

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.RunFirst.html b/docs/man/3.x/apidocs/picocli/CommandLine.RunFirst.html new file mode 100644 index 000000000..2586a9688 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.RunFirst.html @@ -0,0 +1,389 @@ + + + + + +CommandLine.RunFirst (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.RunFirst

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.RunLast.html b/docs/man/3.x/apidocs/picocli/CommandLine.RunLast.html new file mode 100644 index 000000000..8720dffc1 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.RunLast.html @@ -0,0 +1,422 @@ + + + + + +CommandLine.RunLast (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.RunLast

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Spec.html b/docs/man/3.x/apidocs/picocli/CommandLine.Spec.html new file mode 100644 index 000000000..2899be6d9 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Spec.html @@ -0,0 +1,177 @@ + + + + + +CommandLine.Spec (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Annotation Type CommandLine.Spec

+
+
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.TypeConversionException.html b/docs/man/3.x/apidocs/picocli/CommandLine.TypeConversionException.html new file mode 100644 index 000000000..624100e3d --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.TypeConversionException.html @@ -0,0 +1,275 @@ + + + + + +CommandLine.TypeConversionException (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.TypeConversionException

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.Unmatched.html b/docs/man/3.x/apidocs/picocli/CommandLine.Unmatched.html new file mode 100644 index 000000000..ba1623893 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.Unmatched.html @@ -0,0 +1,171 @@ + + + + + +CommandLine.Unmatched (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Annotation Type CommandLine.Unmatched

+
+
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.UnmatchedArgumentException.html b/docs/man/3.x/apidocs/picocli/CommandLine.UnmatchedArgumentException.html new file mode 100644 index 000000000..d7ebcd7b0 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.UnmatchedArgumentException.html @@ -0,0 +1,441 @@ + + + + + +CommandLine.UnmatchedArgumentException (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine.UnmatchedArgumentException

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/CommandLine.html b/docs/man/3.x/apidocs/picocli/CommandLine.html new file mode 100644 index 000000000..ca0f71843 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/CommandLine.html @@ -0,0 +1,4150 @@ + + + + + +CommandLine (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli
+

Class CommandLine

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/doc-files/class-diagram-definition.png b/docs/man/3.x/apidocs/picocli/doc-files/class-diagram-definition.png new file mode 100644 index 000000000..d1467d127 Binary files /dev/null and b/docs/man/3.x/apidocs/picocli/doc-files/class-diagram-definition.png differ diff --git a/docs/man/3.x/apidocs/picocli/doc-files/class-diagram-exceptions.png b/docs/man/3.x/apidocs/picocli/doc-files/class-diagram-exceptions.png new file mode 100644 index 000000000..d5f862708 Binary files /dev/null and b/docs/man/3.x/apidocs/picocli/doc-files/class-diagram-exceptions.png differ diff --git a/docs/man/3.x/apidocs/picocli/doc-files/class-diagram-help-api.png b/docs/man/3.x/apidocs/picocli/doc-files/class-diagram-help-api.png new file mode 100644 index 000000000..d46184528 Binary files /dev/null and b/docs/man/3.x/apidocs/picocli/doc-files/class-diagram-help-api.png differ diff --git a/docs/man/3.x/apidocs/picocli/doc-files/class-diagram-parsing.png b/docs/man/3.x/apidocs/picocli/doc-files/class-diagram-parsing.png new file mode 100644 index 000000000..39a83e398 Binary files /dev/null and b/docs/man/3.x/apidocs/picocli/doc-files/class-diagram-parsing.png differ diff --git a/docs/man/3.x/apidocs/picocli/groovy/PicocliBaseScript.html b/docs/man/3.x/apidocs/picocli/groovy/PicocliBaseScript.html new file mode 100644 index 000000000..e93cc1e47 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/groovy/PicocliBaseScript.html @@ -0,0 +1,715 @@ + + + + + +PicocliBaseScript (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli.groovy
+

Class PicocliBaseScript

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/groovy/PicocliScript.html b/docs/man/3.x/apidocs/picocli/groovy/PicocliScript.html new file mode 100644 index 000000000..a009b4e64 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/groovy/PicocliScript.html @@ -0,0 +1,275 @@ + + + + + +PicocliScript (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli.groovy
+

Annotation Type PicocliScript

+
+
+
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/groovy/PicocliScriptASTTransformation.html b/docs/man/3.x/apidocs/picocli/groovy/PicocliScriptASTTransformation.html new file mode 100644 index 000000000..d76635495 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/groovy/PicocliScriptASTTransformation.html @@ -0,0 +1,319 @@ + + + + + +PicocliScriptASTTransformation (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
picocli.groovy
+

Class PicocliScriptASTTransformation

+
+
+ +
+ +
+
+ +
+
+ +
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/groovy/package-frame.html b/docs/man/3.x/apidocs/picocli/groovy/package-frame.html new file mode 100644 index 000000000..2a1a726cd --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/groovy/package-frame.html @@ -0,0 +1,25 @@ + + + + + +picocli.groovy (picocli 3.9.5 API) + + + + + +

picocli.groovy

+
+

Classes

+ +

Annotation Types

+ +
+ + diff --git a/docs/man/3.x/apidocs/picocli/groovy/package-summary.html b/docs/man/3.x/apidocs/picocli/groovy/package-summary.html new file mode 100644 index 000000000..cc31c6ebf --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/groovy/package-summary.html @@ -0,0 +1,177 @@ + + + + + +picocli.groovy (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ +
+

Package picocli.groovy

+
+
Provides classes and annotations to give Groovy scripts convenient access to picocli functionality.
+
+

See: Description

+
+
+ + + + +

Package picocli.groovy Description

+
Provides classes and annotations to give Groovy scripts convenient access to picocli functionality.
+
+ +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/groovy/package-tree.html b/docs/man/3.x/apidocs/picocli/groovy/package-tree.html new file mode 100644 index 000000000..1eb70addf --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/groovy/package-tree.html @@ -0,0 +1,152 @@ + + + + + +picocli.groovy Class Hierarchy (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ +
+

Hierarchy For Package picocli.groovy

+Package Hierarchies: + +
+
+

Class Hierarchy

+ +

Annotation Type Hierarchy

+ +
+ +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/package-frame.html b/docs/man/3.x/apidocs/picocli/package-frame.html new file mode 100644 index 000000000..5b0a51039 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/package-frame.html @@ -0,0 +1,100 @@ + + + + + +picocli (picocli 3.9.5 API) + + + + + +

picocli

+
+

Interfaces

+ +

Classes

+ +

Enums

+ +

Exceptions

+ +

Annotation Types

+ +
+ + diff --git a/docs/man/3.x/apidocs/picocli/package-summary.html b/docs/man/3.x/apidocs/picocli/package-summary.html new file mode 100644 index 000000000..d4291e4d8 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/package-summary.html @@ -0,0 +1,665 @@ + + + + + +picocli (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ +
+

Package picocli

+
+
Provides classes and interfaces for the main picocli command line parsing and + autocompletion functionality.
+
+

See: Description

+
+
+ + + + +

Package picocli Description

+
Provides classes and interfaces for the main picocli command line parsing and + autocompletion functionality. +

+ The CommandLine class is a one-file framework for creating Java command line + applications with almost zero code. + + CommandLine is in a single file, so it can be included in source form. + This lets users run picocli-based applications without requiring picocli as an external dependency. +

+

Classes and Interfaces for Defining a CommandSpec Model

+

+ Classes and Interfaces for Defining a CommandSpec Model +

+

Classes Related to Parsing Command Line Arguments

+

+ Classes Related to Parsing Command Line Arguments +

+

Class Diagram of the Picocli Exceptions

+

+ Class Diagram of the Picocli Exceptions +

+

Class Diagram of the CommandLine.Help API

+

+ Class Diagram of the CommandLine.Help API +

+
+ +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/picocli/package-tree.html b/docs/man/3.x/apidocs/picocli/package-tree.html new file mode 100644 index 000000000..a04bd1b13 --- /dev/null +++ b/docs/man/3.x/apidocs/picocli/package-tree.html @@ -0,0 +1,251 @@ + + + + + +picocli Class Hierarchy (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ +
+

Hierarchy For Package picocli

+Package Hierarchies: + +
+
+

Class Hierarchy

+ +

Interface Hierarchy

+ +

Annotation Type Hierarchy

+ +

Enum Hierarchy

+ +
+ +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/resources/background.gif b/docs/man/3.x/apidocs/resources/background.gif new file mode 100644 index 000000000..f471940fd Binary files /dev/null and b/docs/man/3.x/apidocs/resources/background.gif differ diff --git a/docs/man/3.x/apidocs/resources/tab.gif b/docs/man/3.x/apidocs/resources/tab.gif new file mode 100644 index 000000000..1a73a83be Binary files /dev/null and b/docs/man/3.x/apidocs/resources/tab.gif differ diff --git a/docs/man/3.x/apidocs/resources/titlebar.gif b/docs/man/3.x/apidocs/resources/titlebar.gif new file mode 100644 index 000000000..17443b3e1 Binary files /dev/null and b/docs/man/3.x/apidocs/resources/titlebar.gif differ diff --git a/docs/man/3.x/apidocs/resources/titlebar_end.gif b/docs/man/3.x/apidocs/resources/titlebar_end.gif new file mode 100644 index 000000000..3ad78d461 Binary files /dev/null and b/docs/man/3.x/apidocs/resources/titlebar_end.gif differ diff --git a/docs/man/3.x/apidocs/script.js b/docs/man/3.x/apidocs/script.js new file mode 100644 index 000000000..b34635693 --- /dev/null +++ b/docs/man/3.x/apidocs/script.js @@ -0,0 +1,30 @@ +function show(type) +{ + count = 0; + for (var key in methods) { + var row = document.getElementById(key); + if ((methods[key] & type) != 0) { + row.style.display = ''; + row.className = (count++ % 2) ? rowColor : altColor; + } + else + row.style.display = 'none'; + } + updateTabs(type); +} + +function updateTabs(type) +{ + for (var value in tabs) { + var sNode = document.getElementById(tabs[value][0]); + var spanNode = sNode.firstChild; + if (value == type) { + sNode.className = activeTableTab; + spanNode.innerHTML = tabs[value][1]; + } + else { + sNode.className = tableTab; + spanNode.innerHTML = "" + tabs[value][1] + ""; + } + } +} diff --git a/docs/man/3.x/apidocs/serialized-form.html b/docs/man/3.x/apidocs/serialized-form.html new file mode 100644 index 000000000..9d52bc172 --- /dev/null +++ b/docs/man/3.x/apidocs/serialized-form.html @@ -0,0 +1,301 @@ + + + + + +Serialized Form (picocli 3.9.5 API) + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ +
+

Serialized Form

+
+
+ +
+ +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+ + +
+ + + diff --git a/docs/man/3.x/apidocs/stylesheet.css b/docs/man/3.x/apidocs/stylesheet.css new file mode 100644 index 000000000..98055b22d --- /dev/null +++ b/docs/man/3.x/apidocs/stylesheet.css @@ -0,0 +1,574 @@ +/* Javadoc style sheet */ +/* +Overall document style +*/ + +@import url('resources/fonts/dejavu.css'); + +body { + background-color:#ffffff; + color:#353833; + font-family:'DejaVu Sans', Arial, Helvetica, sans-serif; + font-size:14px; + margin:0; +} +a:link, a:visited { + text-decoration:none; + color:#4A6782; +} +a:hover, a:focus { + text-decoration:none; + color:#bb7a2a; +} +a:active { + text-decoration:none; + color:#4A6782; +} +a[name] { + color:#353833; +} +a[name]:hover { + text-decoration:none; + color:#353833; +} +pre { + font-family:'DejaVu Sans Mono', monospace; + font-size:14px; +} +h1 { + font-size:20px; +} +h2 { + font-size:18px; +} +h3 { + font-size:16px; + font-style:italic; +} +h4 { + font-size:13px; +} +h5 { + font-size:12px; +} +h6 { + font-size:11px; +} +ul { + list-style-type:disc; +} +code, tt { + font-family:'DejaVu Sans Mono', monospace; + font-size:14px; + padding-top:4px; + margin-top:8px; + line-height:1.4em; +} +dt code { + font-family:'DejaVu Sans Mono', monospace; + font-size:14px; + padding-top:4px; +} +table tr td dt code { + font-family:'DejaVu Sans Mono', monospace; + font-size:14px; + vertical-align:top; + padding-top:4px; +} +sup { + font-size:8px; +} +/* +Document title and Copyright styles +*/ +.clear { + clear:both; + height:0px; + overflow:hidden; +} +.aboutLanguage { + float:right; + padding:0px 21px; + font-size:11px; + z-index:200; + margin-top:-9px; +} +.legalCopy { + margin-left:.5em; +} +.bar a, .bar a:link, .bar a:visited, .bar a:active { + color:#FFFFFF; + text-decoration:none; +} +.bar a:hover, .bar a:focus { + color:#bb7a2a; +} +.tab { + background-color:#0066FF; + color:#ffffff; + padding:8px; + width:5em; + font-weight:bold; +} +/* +Navigation bar styles +*/ +.bar { + background-color:#4D7A97; + color:#FFFFFF; + padding:.8em .5em .4em .8em; + height:auto;/*height:1.8em;*/ + font-size:11px; + margin:0; +} +.topNav { + background-color:#4D7A97; + color:#FFFFFF; + float:left; + padding:0; + width:100%; + clear:right; + height:2.8em; + padding-top:10px; + overflow:hidden; + font-size:12px; +} +.bottomNav { + margin-top:10px; + background-color:#4D7A97; + color:#FFFFFF; + float:left; + padding:0; + width:100%; + clear:right; + height:2.8em; + padding-top:10px; + overflow:hidden; + font-size:12px; +} +.subNav { + background-color:#dee3e9; + float:left; + width:100%; + overflow:hidden; + font-size:12px; +} +.subNav div { + clear:left; + float:left; + padding:0 0 5px 6px; + text-transform:uppercase; +} +ul.navList, ul.subNavList { + float:left; + margin:0 25px 0 0; + padding:0; +} +ul.navList li{ + list-style:none; + float:left; + padding: 5px 6px; + text-transform:uppercase; +} +ul.subNavList li{ + list-style:none; + float:left; +} +.topNav a:link, .topNav a:active, .topNav a:visited, .bottomNav a:link, .bottomNav a:active, .bottomNav a:visited { + color:#FFFFFF; + text-decoration:none; + text-transform:uppercase; +} +.topNav a:hover, .bottomNav a:hover { + text-decoration:none; + color:#bb7a2a; + text-transform:uppercase; +} +.navBarCell1Rev { + background-color:#F8981D; + color:#253441; + margin: auto 5px; +} +.skipNav { + position:absolute; + top:auto; + left:-9999px; + overflow:hidden; +} +/* +Page header and footer styles +*/ +.header, .footer { + clear:both; + margin:0 20px; + padding:5px 0 0 0; +} +.indexHeader { + margin:10px; + position:relative; +} +.indexHeader span{ + margin-right:15px; +} +.indexHeader h1 { + font-size:13px; +} +.title { + color:#2c4557; + margin:10px 0; +} +.subTitle { + margin:5px 0 0 0; +} +.header ul { + margin:0 0 15px 0; + padding:0; +} +.footer ul { + margin:20px 0 5px 0; +} +.header ul li, .footer ul li { + list-style:none; + font-size:13px; +} +/* +Heading styles +*/ +div.details ul.blockList ul.blockList ul.blockList li.blockList h4, div.details ul.blockList ul.blockList ul.blockListLast li.blockList h4 { + background-color:#dee3e9; + border:1px solid #d0d9e0; + margin:0 0 6px -8px; + padding:7px 5px; +} +ul.blockList ul.blockList ul.blockList li.blockList h3 { + background-color:#dee3e9; + border:1px solid #d0d9e0; + margin:0 0 6px -8px; + padding:7px 5px; +} +ul.blockList ul.blockList li.blockList h3 { + padding:0; + margin:15px 0; +} +ul.blockList li.blockList h2 { + padding:0px 0 20px 0; +} +/* +Page layout container styles +*/ +.contentContainer, .sourceContainer, .classUseContainer, .serializedFormContainer, .constantValuesContainer { + clear:both; + padding:10px 20px; + position:relative; +} +.indexContainer { + margin:10px; + position:relative; + font-size:12px; +} +.indexContainer h2 { + font-size:13px; + padding:0 0 3px 0; +} +.indexContainer ul { + margin:0; + padding:0; +} +.indexContainer ul li { + list-style:none; + padding-top:2px; +} +.contentContainer .description dl dt, .contentContainer .details dl dt, .serializedFormContainer dl dt { + font-size:12px; + font-weight:bold; + margin:10px 0 0 0; + color:#4E4E4E; +} +.contentContainer .description dl dd, .contentContainer .details dl dd, .serializedFormContainer dl dd { + margin:5px 0 10px 0px; + font-size:14px; + font-family:'DejaVu Sans Mono',monospace; +} +.serializedFormContainer dl.nameValue dt { + margin-left:1px; + font-size:1.1em; + display:inline; + font-weight:bold; +} +.serializedFormContainer dl.nameValue dd { + margin:0 0 0 1px; + font-size:1.1em; + display:inline; +} +/* +List styles +*/ +ul.horizontal li { + display:inline; + font-size:0.9em; +} +ul.inheritance { + margin:0; + padding:0; +} +ul.inheritance li { + display:inline; + list-style:none; +} +ul.inheritance li ul.inheritance { + margin-left:15px; + padding-left:15px; + padding-top:1px; +} +ul.blockList, ul.blockListLast { + margin:10px 0 10px 0; + padding:0; +} +ul.blockList li.blockList, ul.blockListLast li.blockList { + list-style:none; + margin-bottom:15px; + line-height:1.4; +} +ul.blockList ul.blockList li.blockList, ul.blockList ul.blockListLast li.blockList { + padding:0px 20px 5px 10px; + border:1px solid #ededed; + background-color:#f8f8f8; +} +ul.blockList ul.blockList ul.blockList li.blockList, ul.blockList ul.blockList ul.blockListLast li.blockList { + padding:0 0 5px 8px; + background-color:#ffffff; + border:none; +} +ul.blockList ul.blockList ul.blockList ul.blockList li.blockList { + margin-left:0; + padding-left:0; + padding-bottom:15px; + border:none; +} +ul.blockList ul.blockList ul.blockList ul.blockList li.blockListLast { + list-style:none; + border-bottom:none; + padding-bottom:0; +} +table tr td dl, table tr td dl dt, table tr td dl dd { + margin-top:0; + margin-bottom:1px; +} +/* +Table styles +*/ +.overviewSummary, .memberSummary, .typeSummary, .useSummary, .constantsSummary, .deprecatedSummary { + width:100%; + border-left:1px solid #EEE; + border-right:1px solid #EEE; + border-bottom:1px solid #EEE; +} +.overviewSummary, .memberSummary { + padding:0px; +} +.overviewSummary caption, .memberSummary caption, .typeSummary caption, +.useSummary caption, .constantsSummary caption, .deprecatedSummary caption { + position:relative; + text-align:left; + background-repeat:no-repeat; + color:#253441; + font-weight:bold; + clear:none; + overflow:hidden; + padding:0px; + padding-top:10px; + padding-left:1px; + margin:0px; + white-space:pre; +} +.overviewSummary caption a:link, .memberSummary caption a:link, .typeSummary caption a:link, +.useSummary caption a:link, .constantsSummary caption a:link, .deprecatedSummary caption a:link, +.overviewSummary caption a:hover, .memberSummary caption a:hover, .typeSummary caption a:hover, +.useSummary caption a:hover, .constantsSummary caption a:hover, .deprecatedSummary caption a:hover, +.overviewSummary caption a:active, .memberSummary caption a:active, .typeSummary caption a:active, +.useSummary caption a:active, .constantsSummary caption a:active, .deprecatedSummary caption a:active, +.overviewSummary caption a:visited, .memberSummary caption a:visited, .typeSummary caption a:visited, +.useSummary caption a:visited, .constantsSummary caption a:visited, .deprecatedSummary caption a:visited { + color:#FFFFFF; +} +.overviewSummary caption span, .memberSummary caption span, .typeSummary caption span, +.useSummary caption span, .constantsSummary caption span, .deprecatedSummary caption span { + white-space:nowrap; + padding-top:5px; + padding-left:12px; + padding-right:12px; + padding-bottom:7px; + display:inline-block; + float:left; + background-color:#F8981D; + border: none; + height:16px; +} +.memberSummary caption span.activeTableTab span { + white-space:nowrap; + padding-top:5px; + padding-left:12px; + padding-right:12px; + margin-right:3px; + display:inline-block; + float:left; + background-color:#F8981D; + height:16px; +} +.memberSummary caption span.tableTab span { + white-space:nowrap; + padding-top:5px; + padding-left:12px; + padding-right:12px; + margin-right:3px; + display:inline-block; + float:left; + background-color:#4D7A97; + height:16px; +} +.memberSummary caption span.tableTab, .memberSummary caption span.activeTableTab { + padding-top:0px; + padding-left:0px; + padding-right:0px; + background-image:none; + float:none; + display:inline; +} +.overviewSummary .tabEnd, .memberSummary .tabEnd, .typeSummary .tabEnd, +.useSummary .tabEnd, .constantsSummary .tabEnd, .deprecatedSummary .tabEnd { + display:none; + width:5px; + position:relative; + float:left; + background-color:#F8981D; +} +.memberSummary .activeTableTab .tabEnd { + display:none; + width:5px; + margin-right:3px; + position:relative; + float:left; + background-color:#F8981D; +} +.memberSummary .tableTab .tabEnd { + display:none; + width:5px; + margin-right:3px; + position:relative; + background-color:#4D7A97; + float:left; + +} +.overviewSummary td, .memberSummary td, .typeSummary td, +.useSummary td, .constantsSummary td, .deprecatedSummary td { + text-align:left; + padding:0px 0px 12px 10px; +} +th.colOne, th.colFirst, th.colLast, .useSummary th, .constantsSummary th, +td.colOne, td.colFirst, td.colLast, .useSummary td, .constantsSummary td{ + vertical-align:top; + padding-right:0px; + padding-top:8px; + padding-bottom:3px; +} +th.colFirst, th.colLast, th.colOne, .constantsSummary th { + background:#dee3e9; + text-align:left; + padding:8px 3px 3px 7px; +} +td.colFirst, th.colFirst { + white-space:nowrap; + font-size:13px; +} +td.colLast, th.colLast { + font-size:13px; +} +td.colOne, th.colOne { + font-size:13px; +} +.overviewSummary td.colFirst, .overviewSummary th.colFirst, +.useSummary td.colFirst, .useSummary th.colFirst, +.overviewSummary td.colOne, .overviewSummary th.colOne, +.memberSummary td.colFirst, .memberSummary th.colFirst, +.memberSummary td.colOne, .memberSummary th.colOne, +.typeSummary td.colFirst{ + width:25%; + vertical-align:top; +} +td.colOne a:link, td.colOne a:active, td.colOne a:visited, td.colOne a:hover, td.colFirst a:link, td.colFirst a:active, td.colFirst a:visited, td.colFirst a:hover, td.colLast a:link, td.colLast a:active, td.colLast a:visited, td.colLast a:hover, .constantValuesContainer td a:link, .constantValuesContainer td a:active, .constantValuesContainer td a:visited, .constantValuesContainer td a:hover { + font-weight:bold; +} +.tableSubHeadingColor { + background-color:#EEEEFF; +} +.altColor { + background-color:#FFFFFF; +} +.rowColor { + background-color:#EEEEEF; +} +/* +Content styles +*/ +.description pre { + margin-top:0; +} +.deprecatedContent { + margin:0; + padding:10px 0; +} +.docSummary { + padding:0; +} + +ul.blockList ul.blockList ul.blockList li.blockList h3 { + font-style:normal; +} + +div.block { + font-size:14px; + font-family:'DejaVu Serif', Georgia, "Times New Roman", Times, serif; +} + +td.colLast div { + padding-top:0px; +} + + +td.colLast a { + padding-bottom:3px; +} +/* +Formatting effect styles +*/ +.sourceLineNo { + color:green; + padding:0 30px 0 0; +} +h1.hidden { + visibility:hidden; + overflow:hidden; + font-size:10px; +} +.block { + display:block; + margin:3px 10px 2px 0px; + color:#474747; +} +.deprecatedLabel, .descfrmTypeLabel, .memberNameLabel, .memberNameLink, +.overrideSpecifyLabel, .packageHierarchyLabel, .paramLabel, .returnLabel, +.seeLabel, .simpleTagLabel, .throwsLabel, .typeNameLabel, .typeNameLink { + font-weight:bold; +} +.deprecationComment, .emphasizedPhrase, .interfaceName { + font-style:italic; +} + +div.block div.block span.deprecationComment, div.block div.block span.emphasizedPhrase, +div.block div.block span.interfaceName { + font-style:normal; +} + +div.contentContainer ul.blockList li.blockList h2{ + padding-bottom:0px; +} diff --git a/docs/man/3.x/autocomplete.html b/docs/man/3.x/autocomplete.html new file mode 100644 index 000000000..2b8ec33b5 --- /dev/null +++ b/docs/man/3.x/autocomplete.html @@ -0,0 +1,1155 @@ + + + + + + + +Autocomplete for Java Command Line Applications + + + + + + + +
+
+
+
+
+Fork me on GitHub +
+
+
+
+Every main method deserves picocli! +
+
+
+
+
+

1. Command Line Completion

+
+
+

Starting from version 1.0.0, picocli-based applications can have command line completion in Bash or ZSH Unix shells. +Picocli can generate an autocompletion script tailored to your application.

+
+
+

With this script installed, users can type the first few letters of a subcommand or an option, +then press the TAB key, and the Unix shell will complete the subcommand or option.

+
+
+

In the case of multiple possible completions, the Unix shell will display all subcommands or options beginning +with those few characters. The user can type more characters and press TAB again to see a new, narrowed-down +list if the typed characters are still ambiguous, or else complete the subcommand or option.

+
+
+

Autocompletion demo animation

+
+
+
+
+

2. Quick Start Tutorial

+
+
+

This tutorial uses the CheckSum example application from the picocli user manual. We created a class com.myproject.CheckSum and put it in a jar file, myproject.jar.

+
+
+

Follow these steps to give this application command line autocompletion.

+
+
+

2.1. Create Command

+
+

First, create an executable command that runs the main application class. For this tutorial, the command name is jchecksum.

+
+
+

We use an alias here to create the command (see alternatives):

+
+
+
+
alias jchecksum='java -cp "picocli-1.0.0.jar;myproject.jar" com.myproject.CheckSum'
+
+
+
+

Let’s test that the command works:

+
+
+
+
$ jchecksum --help
+Usage: jchecksum [-h] [-a=<algorithm>] <file>
+Prints the checksum (MD5 by default) of a file to STDOUT.
+      file                    The file whose checksum to calculate.
+  -a, --algorithm=<algorithm> MD5, SHA-1, SHA-256, ...
+  -h, --help                  Show this help message and exit.
+
+
+
+
+

2.2. Generate Completion Script

+
+

To generate the completion script, run the picocli.AutoComplete class as a java application. Pass it the command name and the fully qualified class name of the annotated command class. (See also full description for using AutoComplete.)

+
+
+
+
java -cp "picocli-1.0.0.jar;myproject.jar" picocli.AutoComplete -n jchecksum com.myproject.CheckSum
+
+
+
+

This generated a jchecksum_completion script in the current directory. To verify:

+
+
+
+
$ ls
+jchecksum_completion  myproject.jar  picocli-1.0.0.jar
+
+
+
+
+

2.3. Install Completion Script

+
+

Finally, source the completion script:

+
+
+
Bash
+
+
. jchecksum_completion
+
+
+
+
ZSH
+
+
autoload -U +X compinit && compinit
+autoload -U +X bashcompinit && bashcompinit
+. ./jchecksum_completion
+
+
+
+

…​and you are done. The jchecksum command now has autocompletion:

+
+
+
+
$ jchecksum <TAB><TAB>
+-a           --algorithm  -h           --help
+
+
+
+
+

2.4. Permanent Installation

+
+

The above will last for the duration of your shell session. If you want to make this permanent you need to modify your ~/.bashrc or ~/.zshrc file to add a line that defines the command alias and a line that sources the completion script:

+
+
+
Bash
+
+
echo "alias jchecksum='java -cp \"picocli-1.0.0.jar;myproject.jar\" com.myproject.CheckSum'" >> ~/.bashrc
+echo ". jchecksum_completion" >> ~/.bashrc
+
+
+
+

Make sure to use >> (append), using a single > would overwrite the file.

+
+
+

~/.bashrc indicates .bashrc is in your home directory.

+
+
+

(See detailed Bash installation, Installing Completion Scripts Permanently in ZSH.)

+
+
+
+
+
+

3. Designing for Completion

+
+
+

When writing a picocli-based command line application there are a few things to consider to facilitate autocompletion.

+
+
+

3.1. Register Subcommands Declaratively

+
+

Register subcommands declaratively in your application with @Command(subcommands = { …​ }) annotations where possible.

+
+
+

This way, you can generate a completion script by passing a single command class name to picocli.AutoComplete, and picocli will be able to infer the full hierarchy of command and subcommands from that top-level command class.

+
+
+

If your application registers subcommands programmatically, you can still generate a completion script, it is just more work.

+
+
+
+

3.2. Use Strong Typing

+
+

When generating the completion script, picocli inspects the type of the fields annotated with @Option. For some types, +tab completion can also generate possible option values.

+
+
+

Picocli can generate completion matches for the following types:

+
+
+
    +
  • +

    java.io.File

    +
    • +
  • +

    java.nio.file.Path

    +
    • +
  • +

    java.net.InetAddress

    +
    • +
  • +

    any java enum

    +
    • +
+
+
+

3.2.1. Files and Directories

+
+

Generating autocomplete matches for @Option fields of type java.io.File or java.nio.file.Path will display a list of all files and directories in the current directory.

+
+
+
+
$ demo --file <TAB><TAB>
+basic.bash              hierarchy               nestedSubcommands.bash
+
+
+
+
+

3.2.2. Host Names

+
+

Generating autocomplete matches for @Option fields of type java.net.InetAddress will display a list of known hosts (from your /etc/hosts file).

+
+
+
+
$ demo --host <TAB><TAB>
+cluster-p-1                          openvpn-client.myvpn.picocli.com
+cluster-p-2                          picop1
+cluster-p-3                          picop2
+cluster-p-4                          picop3
+cluster-scm-1                        picop4
+client.openvpn.net                   picoscm1
+
+
+
+
+

3.2.3. Java enum Values

+
+

Generating autocomplete matches for @Option fields of any Java enum type will display the list of enum values.

+
+
+

For example:

+
+
+
+
$ demo --timeUnit <TAB><TAB>
+DAYS     HOURS     MICROSECONDS  MILLISECONDS  MINUTES    NANOSECONDS   SECONDS
+
+
+
+
+
+

3.3. Other Completion Candidates

+
+

Picocli 3.2 introduces a completionCandidates API that can be used to generate completion candidates +regardless of the type of the option or positional parameter.

+
+
+

Picocli calls this iterator when the completion script is generated.

+
+
+
+
+
+

4. Alternative Ways to Define Commands

+
+
+

This section describes creating commands in more depth than the Quick Start Tutorial.

+
+
+

In Bash and ZSH, there are multiple ways to create an executable command for a java class.

+
+
+

4.1. Alias

+
+

One way is to define an alias:

+
+
+
+
alias jchecksum='java -cp "picocli-1.0.0.jar;myproject.jar" com.myproject.CheckSum'
+
+
+
+

Be aware that the alias only lasts as long as the current shell session. +To make it permanent, add it to your ~/.bashrc or ~/.zshrc file.

+
+
+

You may also want to specify the full path to the jar files in the classpath so that the command can be executed anywhere.

+
+
+
+

4.2. Function

+
+

Another way is to define a function:

+
+
+
+
jchecksum() {
+    java -cp "picocli-1.0.0.jar;myproject.jar" com.myproject.CheckSum "$@"
+}
+
+
+
+

To make it permanent, add it to your ~/.bashrc or ~/.zshrc file.

+
+
+
+

4.3. Script

+
+

Yet another way is to create a script:

+
+
+
+
$ echo '#!/usr/bin/env bash' > jchecksum
+$ echo 'java -cp "picocli-1.0.0.jar;myproject.jar" com.myproject.CheckSum $@' >> jchecksum
+$ chmod 755 jchecksum
+
+$ cat jchecksum
+#!/usr/bin/env bash
+java -cp "picocli-1.0.0.jar;myproject.jar" com.myproject.CheckSum $@
+
+
+
+
+
+
+

5. Completion Script Generation Details

+
+
+

This section describes generating completion scripts in more depth than the Quick Start Tutorial.

+
+
+

5.1. Running AutoComplete

+
+

To generate the completion script, run the picocli.AutoComplete class as a java application, passing it +the fully qualified class name of the annotated command object.

+
+
+
+
$ java -cp "picocli-1.0.0.jar;myproject.jar" picocli.AutoComplete com.myproject.CheckSum
+
+
+
+

This will instantiate your command, and inspect it for @Option +and @Command annotations. +Based on these annotations it will generate a completion script in the current directory.

+
+
+

Because of this, the command class needs to be on the classpath when running the picocli.AutoComplete class.

+
+
+
+

5.2. Command Name

+
+

The name of the generated completion script is based on the @Command(name ="<COMMAND-NAME>") annotation, or, if that is missing, the command class name. +Use the -n or --name option to control the name of the command that the completion script is for.

+
+
+
+
$ java -cp "picocli-1.0.0.jar;myproject.jar" picocli.AutoComplete -n jchecksum com.myproject.CheckSum
+
+
+
+

This will generate a jchecksum_completion script in the current directory.

+
+
+

Other options are:

+
+
+
    +
  • +

    Use -o or --completionScript to specify the full path to the completion script to generate.

    +
    • +
  • +

    Use the -f or --force option to overwrite existing files.

    +
    • +
  • +

    Use the -w, --writeCommandScript option to generate a sample command script.

    +
    • +
+
+
+
+

5.3. Subcommands

+
+

For commands with subcommands, bear in mind that the class that generates the completion script (picocli.AutoComplete) +needs the full hierarchy of command and subcommands to generate a completion script that also works for the subcommands.

+
+
+

The above will work when subcommands are registered declaratively with annotations like @Command(subcommands = { …​ }).

+
+
+
+

5.4. Programmatically Registered Subcommands

+
+

When subcommands are not registered declaratively, you need to do a bit more work. You need to create a small program that does the following:

+
+
+
    +
  • +

    Create a CommandLine instance with the full hierarchy of nested subcommands.

    +
    • +
+
+
+
+
// programmatically (see above for declarative example)
+CommandLine hierarchy = new CommandLine(new TopLevel())
+        .addSubcommand("sub1", new Subcommand1())
+        .addSubcommand("sub2", new Subcommand2());
+
+
+
+
    +
  • +

    Pass this CommandLine instance and the name of the script to the picocli.AutoComplete::bash method. The method will return the source code of a completion script. Save the source code to a file and install it.

    +
    • +
+
+
+
+
+
+

6. Installing Completion Scripts Permanently in Bash

+
+
+

This section describes installing completion scripts in more depth than the Quick Start Tutorial.

+
+
+

Make sure bash completion is installed.

+
+
+

Source the generated completion script to install it in your current bash session.

+
+
+

To install it more permanently, place the completion script file in /etc/bash_completion.d (or /usr/local/etc/bash_completion.d on a Mac). If bash-completion is installed, placing the completion script in either of these directories should be sufficient. (Source your ~/.bash_profile or launch a new terminal to start using this completion script.)

+
+
+

Alternatively, make a directory mkdir ~/bash_completion.d, and place the completion script in this directory. Edit your ~/.bashrc file and add the following:

+
+
+
+
for bcfile in ~/bash_completion.d/* ; do
+  . $bcfile
+done
+
+
+
+

All completion scripts in the ~/bash_completion.d directory will now be available every time you launch a new shell.

+
+
+

Source your ~/.bash_profile or launch a new terminal to start using this completion script.

+
+
+
+
+

7. Installing Completion Scripts Permanently in ZSH

+
+
+

This section describes installing completion scripts in more depth than the Quick Start Tutorial.

+
+
+

Zsh can handle bash completions functions. The latest development version of zsh has a function bashcompinit, that when run will allow zsh to read bash completion specifications and functions. The zshcompsys man page has details. To use it, run bashcompinit at any time after compinit. It will define complete and compgen functions corresponding to the bash builtins.

+
+
+

Source the generated completion script to install it in your current shell session.

+
+
+

To install it more permanently, make a directory mkdir ~/bash_completion.d, and place the completion script in this directory. Edit your ~/.zshrc file and add the following:

+
+
+
+
autoload -U +X compinit && compinit
+autoload -U +X bashcompinit && bashcompinit
+for bcfile in ~/bash_completion.d/* ; do
+  . $bcfile
+done
+
+
+
+

All completion scripts in the ~/bash_completion.d directory will now be available every time you launch a new shell.

+
+
+

Then reload your shell:

+
+
+
+
exec $SHELL -l
+
+
+
+
+
+

8. Generating Completion Scripts During the Build

+
+
+

It may be useful to generate your completion scripts automatically during the build. +Below is an example Maven snippet that demonstrates how to achieve this.

+
+
+

8.1. Maven Example

+
+ + + + + +
+ + +Setting system property picocli.autocomplete.systemExitOnError ensures the build fails if there is any problem generating the completion script (requires picocli v3.9.1). +
+
+
+
+
<plugin>
+  <groupId>org.codehaus.mojo</groupId>
+  <artifactId>exec-maven-plugin</artifactId>
+  <version>${exec-maven-plugin.version}</version>
+  <executions>
+    <execution>
+      <id>generate-autocompletion-script</id>
+      <phase>package</phase>
+      <goals>
+        <goal>exec</goal>
+      </goals>
+    </execution>
+  </executions>
+  <configuration>
+    <executable>java</executable>
+    <arguments>
+      <argument>-Dpicocli.autocomplete.systemExitOnError</argument>
+      <argument>-cp</argument>
+      <classpath/>
+      <argument>picocli.AutoComplete</argument>
+      <argument>--force</argument><!-- overwrite if exists -->
+      <argument>--completionScript</argument>
+      <argument>${project.build.directory}/mycommand_completion.sh</argument>
+      <argument>mypackage.MyCommand</argument><!-- replace with your class -->
+    </arguments>
+  </configuration>
+</plugin>
+
+
+
+
+
+
+

9. Picocli User Manual

+
+
+

The picocli user manual explains how to build Java command line applications with picocli.

+
+
+
+
+

10. GitHub Project

+
+
+

The GitHub project has the source code, tests, build scripts, etc.

+
+
+

Star or fork this project on GitHub if you like it! +(Projects with many forks are easier to find on GitHub Search.)

+
+
+
+
+

11. Issue Tracker

+
+
+

Please use the Issue Tracker to report bugs or request features.

+
+
+
+
+

12. License

+
+
+

Picocli is licensed under the Apache License 2.0.

+
+
+
+
+

13. Releases

+
+
+

Previous versions are available from the GitHub project Releases.

+
+
+
+
+ + + \ No newline at end of file diff --git a/docs/man/3.x/groovy-2.5-clibuilder-renewal-part1.html b/docs/man/3.x/groovy-2.5-clibuilder-renewal-part1.html new file mode 100644 index 000000000..bfc564393 --- /dev/null +++ b/docs/man/3.x/groovy-2.5-clibuilder-renewal-part1.html @@ -0,0 +1,964 @@ + + + + + + + +Groovy 2.5 CliBuilder Renewal (Part 1) + + + + + + + +
+
+
+
+

The CliBuilder class for quickly and concisely building command line applications has been renewed in Apache Groovy 2.5. +This two-part article highlights what is new. +Part 2 explains how to leverage some of the advanced features of the underlying libraries from CliBuilder.

+
+
+
+CliBuilder2.5 cygwin +
+
+
+
+
+

The groovy.util.CliBuilder Class is Deprecated

+
+
+

Previous versions of CliBuilder used Apache Commons CLI as the underlying parser library. +From Groovy 2.5, there is an alternative version of CliBuilder based on the picocli parser.

+
+
+

Going forward, it is recommended that applications explicitly import either groovy.cli.picocli.CliBuilder or groovy.cli.commons.CliBuilder. The groovy.util.CliBuilder class is deprecated and delegates to the Commons CLI version for backwards compatibility.

+
+
+

New features will likely only be added to the picocli version, and groovy.util.CliBuilder may be removed in a future version of Groovy. +The Commons CLI version is intended for applications that rely on the internals of the Commons CLI implementation of CliBuilder and cannot easily migrate to the picocli version.

+
+
+

Next, let’s look at some new features in Groovy 2.5 CliBuilder.

+
+
+
+
+

Typed Options

+
+
+
+Type +
+
+
+

Options can be boolean flags or they can take one or more option parameters. +In previous versions of CliBuilder, you would have to specify args: 1 for options that need a parameter, or +args: '+' for options that accept multiple parameters.

+
+
+

This version of CliBuilder adds support for typed options. This is convenient when processing parse results, +but additionally, the number of arguments is inferred from the type, +so if the type is specified, args can be omitted.

+
+
+

For example:

+
+
+
+
def cli = new CliBuilder()
+cli.a(type: String, 'a-arg')
+cli.b(type: boolean, 'b-arg')
+cli.c(type: Boolean, 'c-arg')
+cli.d(type: int, 'd-arg')
+cli.e(type: Long, 'e-arg')
+cli.f(type: Float, 'f-arg')
+cli.g(type: BigDecimal, 'g-arg')
+cli.h(type: File, 'h-arg')
+cli.i(type: RoundingMode, 'i-arg')
+
+def argz = '''-a John -b -d 21 -e 1980 -f 3.5 -g 3.14159
+    -h cv.txt -i DOWN and some more'''.split()
+
+def options = cli.parse(argz)
+assert options.a == 'John'
+assert options.b
+assert !options.c
+assert options.d == 21
+assert options.e == 1980L
+assert options.f == 3.5f
+assert options.g == 3.14159
+assert options.h == new File('cv.txt')
+assert options.i == RoundingMode.DOWN
+assert options.arguments() == ['and', 'some', 'more']
+
+
+
+

Supported Types

+
+

The Commons CLI-based CliBuilder supports primitives, numeric types, files, enums and arrays thereof +(using StringGroovyMethods#asType(String, Class)). +The picocli-based CliBuilder supports those and more.

+
+
+
+

Adding More Types

+
+

If the built-in types don’t meet your needs, it is easy to register a custom converter. Specify a convert Closure to convert the String argument to any other type. For example:

+
+
+
+
import java.nio.file.Paths
+import java.time.LocalTime
+
+def cli = new CliBuilder()
+cli.a(convert: { it.toUpperCase() }, 'a-arg')    (1)
+cli.p(convert: { Paths.get(it) }, 'p-arg')       (2)
+cli.t(convert: { LocalTime.parse(it) }, 't-arg') (3)
+
+def options = cli.parse('-a abc -p /usr/home -t 15:31:59'.split())
+assert options.a == 'ABC'
+assert options.p.absolute && options.p.parent == Paths.get('/usr')
+assert options.t.hour == 15 && options.t.minute == 31
+
+
+
+ + + + + + + + + + + + + +
1Convert one String to another
2Option value is converted to a java.nio.file.Path
3Option value is converted to a java.time.LocalTime
+
+
+
+
+
+

Annotations

+
+
+
+Annotations +
+
+
+

From this release, Groovy offers an annotation API for processing command line arguments.

+
+
+

Applications can annotate fields or methods with @groovy.cli.Option for named options +or @groovy.cli.Unparsed for positional parameters. +When the parser matches a command line argument with an option name or positional parameter, the value is converted +to the correct type and injected into the field or method.

+
+
+

Annotating Methods of an Interface

+
+

One way to use the annotations is on "getter-like" methods (methods that return a value) of an interface. For example:

+
+
+
+
import groovy.cli.*
+
+interface IHello {
+    @Option(shortName='h', description='display usage') Boolean help()   (1)
+    @Option(shortName='u', description='user name')     String user()    (2)
+    @Unparsed(description = 'positional parameters')    List remaining() (3)
+}
+
+
+
+ + + + + + + + + + + + + +
1Method returns true if -h or --help was specified on the command line.
2Method returns the parameter value that was specified for the -u or --user option.
3Any remaining parameters will be returned as a list from this method.
+
+
+

How to use this interface (using the picocli version to demonstrate its usage help):

+
+
+
+
import groovy.cli.picocli.CliBuilder
+
+def cli = new CliBuilder(name: 'groovy Greeter')
+def argz = '--user abc'.split()
+IHello hello = cli.parseFromSpec(IHello, argz)
+assert hello.user() == 'abc'
+
+hello = cli.parseFromSpec(GreeterI, ['--help', 'Some', 'Other', 'Args'] as String[])
+assert hello.help()
+cli.usage()
+assert hello.remaining() == ['Some', 'Other', 'Args']
+
+
+
+

This prints the following usage help message:

+
+
+
+
Usage: groovy Greeter [-h] [-u=<user>] [<remaining>...]
+      [<remaining>...]   positional parameters
+  -u, --user=<user>      user name
+  -h, --help             display usage
+
+
+
+

When parseFromSpec is called, CliBuilder reads the annotations, parses the command line arguments +and returns an instance of the interface. +The interface methods return the option values matched on the command line.

+
+
+
+

Annotating Properties or Setter Methods of a Class

+
+

Another way to use the annotations is on the properties or "setter-like" methods (void methods with a single parameter) of a class. For example:

+
+
+
+
class Hello {
+    @Option(shortName='h', description='display usage') (1)
+    Boolean help
+
+    private String user
+    @Option(shortName='u', description='user name')     (2)
+    void setUser(String user) {
+        this.user = user
+    }
+    String getUser() { user }
+
+    @Unparsed(description = 'positional parameters')    (3)
+    List remaining
+}
+
+
+
+ + + + + + + + + + + + + +
1The help Boolean property is set to true if -h or --help was specified on the command line.
2The setUser property setter method is invoked with the -u or --user option parameter value.
3The remaining property is set to a new List containing the remaining args, if any.
+
+
+

The annotated class can be used as follows:

+
+
+
+
String[] argz = ['--user', 'abc', 'foo']
+
+def cli = new CliBuilder(usage: 'groovy Greeter [option]') (1)
+Hello greeter = cli.parseFromInstance(new Hello(), argz)   (2)
+assert greeter.user == 'abc'                               (3)
+assert greeter.remaining == ['foo']                        (4)
+
+
+
+ + + + + + + + + + + + + + + + + +
1Create a CliBuilder instance.
2Extract options from the annotated instance, parse arguments, and populate and return the supplied instance.
3Verify that the String option value has been assigned to the property.
4Verify the remaining arguments property.
+
+
+

When parseFromInstance is called, CliBuilder again reads the annotations, parses the command line +arguments and finally returns the instance. The annotated fields and setter methods are initialized with the values +matched for the associated option.

+
+
+
+

Script Annotations

+
+
+Script +
+
+
+

Groovy 2.5 also offers new annotations for Groovy scripts.

+
+
+

@OptionField is equivalent to combining @groovy.transform.Field and @Option, whereas @UnparsedField is equivalent to combining @Field and @Unparsed.

+
+
+

Use these annotations to turn script variables into fields so that the variables can be populated by CliBuilder. For example:

+
+
+
+
import groovy.cli.OptionField
+import groovy.cli.UnparsedField
+
+@OptionField String user
+@OptionField Boolean help
+@UnparsedField List remaining
+
+String[] argz = ['--user', 'abc', 'foo']
+
+new CliBuilder().parseFromInstance(this, argz)
+assert user == 'abc'
+assert remaining == ['foo']
+
+
+
+
+
+
+

Typed Positional Parameters

+
+
+

This version of CliBuilder offers some limited support for strongly typed positional parameters.

+
+
+

If all positional parameters have the same type, the @Unparsed annotation can be used with an array type other than String[]. +Again, the type conversion is done using StringGroovyMethods#asType(String, Class) +in the Commons CLI version, while the picocli version of CliBuilder supports a superset of those types.

+
+
+

This functionality is only available for the annotations API, not for the dynamic API. +Here is an example of an interface that can capture strongly typed positional parameters:

+
+
+
+
interface TypedPositionals {
+    @Unparsed Integer[] nums()
+}
+
+
+
+

The code below demonstrates the type conversion:

+
+
+
+
def argz = '12 34 56'.split()
+def cli = new CliBuilder()
+def options = cli.parseFromSpec(TypedPositionals, argz)
+assert options.nums() == [12, 34, 56]
+
+
+
+
+
+

Gotchas/Incompatibilities

+
+
+
+incompatible +
+
+
+

There are a few areas where the new versions of CliBuilder are not compatible with previous versions or with each other.

+
+
+

Properties options and formatter Unavailable in Picocli Version

+
+

The Commons CLI version of CliBuilder, and previous versions of CliBuilder, expose an options property of type org.apache.commons.cli.Options, that can be used to configure the underlying Commons CLI parser without going through the CliBuilder API. This property is not available in the picocli version of CliBuilder. +Applications that read or write this property must import groovy.cli.commons.CliBuilder +or modify the application.

+
+
+

Additionally, the formatter property of type org.apache.commons.cli.HelpFormatter is not available in the picocli version of CliBuilder. If your application uses this property, consider using the usageMessage property instead, or import groovy.cli.commons.CliBuilder.

+
+
+
+

Property parser Differs in Picocli and Commons CLI Versions

+
+

The picocli version of CliBuilder has a parser property that exposes a picocli.CommandLine.Model.ParserSpec object +that can be used to configure the parser behavior.

+
+
+

The Commons CLI version of CliBuilder, and previous versions of CliBuilder, expose a parser property of type org.apache.commons.cli.CommandLineParser. This functionality is not available in the picocli version of CliBuilder.

+
+
+

If your application uses the parser property to set a different Commons CLI parser, consider using the posix property instead, or import groovy.cli.commons.CliBuilder.

+
+
+
+

Different Parser Behavior for longOption

+
+

The Commons CLI DefaultParser recognizes longOption option names prefixed with a single hypen (e.g., -option) +as well as options prefixed with a double hyphen (e.g., --option). +This is not always obvious since the usage help message only shows the double hyphen prefix for longOption option names.

+
+
+

For backwards compatibility, the picocli version of CliBuilder has an acceptLongOptionsWithSingleHyphen property: +set this property to true if the parser should recognize long option names with both +a single hyphen and a double hyphen prefix. The default is false, +so only long option names with a double hypen prefix (--option) are recognized.

+
+
+
+
+
+

Wait, There’s More…​

+
+
+

Part 2 of this article explains how to leverage some of the advanced features of the underlying libraries from CliBuilder. This is where you can make your command line application really shine. Stay tuned…​

+
+
+ + + + + +
+ + +For more information, visit the Groovy site and +GitHub project, +and the picocli site and picocli GitHub project. +Please star the projects if you like what you see! +
+
+
+
+
+ + + \ No newline at end of file diff --git a/docs/man/3.x/groovy-2.5-clibuilder-renewal-part2.html b/docs/man/3.x/groovy-2.5-clibuilder-renewal-part2.html new file mode 100644 index 000000000..a0747a3dc --- /dev/null +++ b/docs/man/3.x/groovy-2.5-clibuilder-renewal-part2.html @@ -0,0 +1,970 @@ + + + + + + + +Groovy 2.5 CliBuilder Renewal (Part 2) + + + + + + + +
+
+
+
+

The CliBuilder class for quickly and concisely building command line applications has been renewed in Apache Groovy 2.5. +This is the second of a two-part article series that highlights what is new. +In case you missed it, Part 1 is here. This article shows some of the advanced features of the underlying libraries from CliBuilder.

+
+
+
+CliBuilder2.5 cygwin +
+
+
+

A quick recap of part 1: The groovy.util.CliBuilder class is deprecated. Instead there are now two CliBuilder implementations in different modules, one with Apache Commons CLI as the underlying parser library, and a new one based on the picocli parser.

+
+
+

It is recommended that applications explicitly import either groovy.cli.picocli.CliBuilder or groovy.cli.commons.CliBuilder. +The groovy.util.CliBuilder class is deprecated and delegates to the Commons CLI version for backwards compatibility.

+
+
+

New features will likely only be added to the picocli version, and groovy.util.CliBuilder may be removed in a future version of Groovy. The Commons CLI version is intended for applications that rely on the internals of the Commons CLI implementation of CliBuilder and cannot easily migrate to the picocli version.

+
+
+

Next, let’s take a look at some advanced features offered by these underlying command line parsing libraries.

+
+
+
+
+

Apache Commons CLI Features

+
+
+
+FeatureIconAdvancedOptions +
+
+
+

Sometimes you may want to use advanced features of the underlying parsing library. +For example, you may have a command line application with mutually exclusive options. +The below code shows how to achieve this using the Apache Commons CLI OptionGroup API:

+
+
+
+
import groovy.cli.commons.CliBuilder
+import org.apache.commons.cli.*
+
+def cli = new CliBuilder()
+def optionGroup = new OptionGroup()
+optionGroup.with {
+  addOption cli.option('s', [longOpt: 'silent'], 's option')
+  addOption cli.option('v', [longOpt: 'verbose'], 'v option')
+}
+cli.options.addOptionGroup optionGroup
+
+assert !cli.parse('--silent --verbose'.split()) (1)
+
+
+
+ + + + + +
1Parsing this input will fail because two mutually exclusive options were specified.
+
+
+
+
+

Picocli CliBuilder Features

+
+
+
+FeatureIconAdvancedOptions +
+
+
+

Strongly Typed Lists

+
+
+list +
+
+
+

Options with multiple values often use an array or a List to capture the values. +Arrays can be strongly typed, that is, contain elements other than String. +The picocli version of CliBuilder lets you do the same with Lists. +The auxiliaryType specifies the type that the elements should be converted to. +For example:

+
+
+
+
import groovy.cli.picocli.CliBuilder
+
+def cli = new CliBuilder()
+cli.T(type: List, auxiliaryTypes: Long, 'typed list')  (1)
+
+def options = cli.parse('-T 1 -T 2 -T 3'.split())      (2)
+assert options.Ts == [ 1L, 2L, 3L ]                    (3)
+
+
+
+ + + + + + + + + + + + + +
1Define an option that can have multiple integer values.
2An example command line.
3The option values as a List<Integer>.
+
+
+
+

Strongly Typed Maps

+
+
+map +
+
+
+

The picocli version of CliBuilder offers native support for Map options. +This is as simple as specifying Map as the option type. +By default, both keys and values are stored as Strings in the Map, +but it’s possible to use auxiliaryType to specify the types that the keys and values should be converted to.

+
+
+
+
import groovy.cli.picocli.CliBuilder
+
+def cli = new CliBuilder()
+cli.D(args: 2,   valueSeparator: '=', 'Commons CLI style map')                 (1)
+cli.X(type: Map, 'picocli style map support')                                  (2)
+cli.Z(type: Map, auxiliaryTypes: [TimeUnit, Integer].toArray(), 'typed map')   (3)
+
+def options = cli.parse('-Da=b -Dc=d -Xx=y -Xi=j -ZDAYS=2 -ZHOURS=23'.split()) (4)
+assert options.Ds == ['a', 'b', 'c', 'd']                                      (5)
+assert options.Xs == [ 'x':'y', 'i':'j' ]                                      (6)
+assert options.Zs == [ (DAYS as TimeUnit):2, (HOURS as TimeUnit):23 ]          (7)
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
1Commons CLI has map-like options by specifying that each option must have two parameters, with some separator.
2The picocli version of CliBuilder has native support for Map options.
3The key type and value type can be specified for strongly-typed maps.
4An example command line.
5The Commons CLI style option gives a list of [key, value, key, value, …​] objects.
6The picocli style option gives the result as a Map<String, String>.
7When auxiliaryTypes are specified, the keys and values of the map are converted to the specified types, giving you a Map<TimeUnit, Integer>.
+
+
+
+

Usage Help with Detailed Synopsis

+
+
+iceberg +
+
+
+

CliBuilder has always supported a usage property to display the usage help synopsis of a command:

+
+
+
+
// the old way
+new CliBuilder(usage: 'myapp [options]').usage()
+
+
+
+

The above program prints:

+
+
+
+
Usage: myapp [options]
+
+
+
+

This still works, but the picocli version has a better alternative with the name property. +If you specify name instead of usage, picocli will show all options in a succinct synopsis with square brackets [ and ] for optional elements and ellipsis …​ for elements that can be repeated one or more times. For example:

+
+
+
+
// the new way
+def cli = new CliBuilder(name: 'myapp') // detailed synopsis
+cli.a('option a description')
+cli.b('option b description')
+cli.c(type: List, 'option c description')
+cli.usage()
+
+
+
+

The above program prints:

+
+
+
+
Usage: myapp [-ab] [-c=PARAM]...
+  -a           option a description
+  -b           option b description
+  -c= PARAM    option c description
+
+
+
+
+

Use Any Option Names

+
+
+freedom c PsychoShadow www.bigstockphoto.com +
+
+
+

Image credit: (c) PsychoShadow - www.bigstockphoto.com

+
+
+

Before, if an option had multiple names with a single hyphen, you had no choice but to declare the option multiple times:

+
+
+
+
// before: split -cp, -classpath into two options
+def cli = new CliBuilder(usage: 'groovyConsole [options] [filename]')
+cli.classpath('Where to find the class files')
+cli.cp(longOpt: 'classpath', 'Aliases for '-classpath')
+
+
+
+

The picocli version of CliBuilder supports a names property that can have any number of option names that can take any prefix. For example:

+
+
+
+
// after: an option can have many names with any prefix
+def cli = new CliBuilder(usage: 'groovyConsole [options] [filename]')
+cli._(names: ['-cp', '-classpath', '--classpath'], 'Where to find the class files')
+
+
+
+
+

Fine-grained Usage Help Message

+
+
+sift +
+
+
+

Picocli offers fine-grained control over the usage help message format and this functionality is exposed via the usageMessage CliBuilder property.

+
+
+

The usage message has a number of sections: header, synopsis, description, parameters, options and finally the footer. Each section has a heading, that precedes the first line of its section. For example:

+
+
+
+
import groovy.cli.picocli.CliBuilder
+
+def cli = new CliBuilder()
+cli.name = "groovy clidemo"
+cli.usageMessage.with {                (1)
+    headerHeading("Header heading:%n") (2)
+    header("header 1", "header 2")     (3)
+    synopsisHeading("%nUSAGE: ")
+    descriptionHeading("%nDescription heading:%n")
+    description("description 1", "description 2")
+    optionListHeading("%nOPTIONS:%n")
+    footerHeading("%nFooter heading:%n")
+    footer("footer 1", "footer 2")
+}
+cli.a(longOpt: 'aaa', 'a-arg')         (4)
+cli.b(longOpt: 'bbb', 'b-arg')
+cli.usage()
+
+
+
+ + + + + + + + + + + + + + + + + +
1Use the usageMessage CliBuilder property to customize the usage help message.
2Headings can contain string format specifiers like the %n newline.
3Sections are multi-line: each string will be rendered on a separate line.
4Define some options.
+
+
+

This prints the following output:

+
+
+
+
Header heading:
+header 1
+header 2
+
+USAGE: groovy clidemo [-ab]
+
+Description heading:
+description 1
+description 2
+
+OPTIONS:
+  -a, --aaa    a-arg
+  -b, --bbb    b-arg
+
+Footer heading:
+footer 1
+footer 2
+
+
+
+
+

Usage Help with ANSI Colors

+
+

Out of the box, the command name, option names and parameter labels in the usage help message are rendered with ANSI styles and colors. +The color scheme for these elements can be configured with system properties.

+
+
+

Other than that, you can use colors and styles in the descriptions and other sections of the usage help message, +using a simple markup notation. The example below demonstrates:

+
+
+
+
def cli = new groovy.cli.picocli.CliBuilder(name: 'myapp')
+cli.usageMessage.with {
+    headerHeading("@|bold,red,underline Header heading|@:%n")
+    header($/@|bold,green \
+  ___ _ _ ___      _ _    _
+ / __| (_) _ )_  _(_) |__| |___ _ _
+| (__| | | _ \ || | | / _` / -_) '_|
+ \___|_|_|___/\_,_|_|_\__,_\___|_|
+|@/$)
+    synopsisHeading("@|bold,underline Usage|@: ")
+    descriptionHeading("%n@|bold,underline Description heading|@:%n")
+    description("Description 1", "Description 2")      // after the synopsis
+    optionListHeading("%n@|bold,underline Options heading|@:%n")
+    footerHeading("%n@|bold,underline Footer heading|@:%n")
+    footer($/@|bold,blue \
+   ___                         ___   ___
+  / __|_ _ ___  _____ ___  _  |_  ) | __|
+ | (_ | '_/ _ \/ _ \ V / || |  / / _|__ \
+  \___|_| \___/\___/\_/ \_, | /___(_)___/
+                        |__/             |@/$)
+}
+cli.a('option a description')
+cli.b('option b description')
+cli.c(type: List, 'option c description')
+cli.usage()
+
+
+
+

The code above gives the following output:

+
+
+
+CliBuilder2.5 cygwin +
+
+
+

(Credit to http://patorjk.com/software/taag/ for the ASCII art.)

+
+
+
+

New errorWriter Property

+
+
+error +
+
+
+

When the user provided invalid input, the picocli version of CliBuilder writes an error message and the usage help message to the new errorWriter property (set to System.err by default). +When the user requests help, and the application calls CliBuilder.usage(), the usage help message is printed to the writer property (System.out by default).

+
+
+

Previous versions of CliBuilder used the writer property for both invalid input and user-requested help.

+
+
+

Why this change? This helps command line application authors to follow standard practice and separate diagnostic output from the program output: If the output of a Groovy program is piped to another program, +sending error messages to STDERR prevents the downstream program from inadvertently trying to parse error output. +On the other hand, when users request help with --help or --version, the output should be sent to STDOUT, +because the user may want to pipe the output to a utility like less or grep.

+
+
+

For backwards compatibility, setting the writer property to another value will also set the errorWriter to the same value. +(You can still set the errorWriter to another value afterwards if desired.)

+
+
+
+
+
+

Conclusion

+
+
+

Groovy 2.5 CliBuilder offers a host of exciting new features. +Try it out and let us know what you think!

+
+
+

This is part 2 of a two-part article. In case you missed it, here is Part 1.

+
+
+ + + + + +
+ + +For more information, visit the Groovy site and +GitHub project, +and the picocli site and picocli GitHub project. +Please star the projects if you like what you see! +
+
+
+
+
+ + + \ No newline at end of file diff --git a/docs/man/3.x/groovy-2.5-clibuilder-renewal.html b/docs/man/3.x/groovy-2.5-clibuilder-renewal.html new file mode 100644 index 000000000..aef940a01 --- /dev/null +++ b/docs/man/3.x/groovy-2.5-clibuilder-renewal.html @@ -0,0 +1,1341 @@ + + + + + + + +Groovy 2.5 CliBuilder Renewal + + + + + + + +
+
+
+
+

The CliBuilder class for quickly and concisely building command line applications has been renewed in Apache Groovy 2.5. +This article highlights what is new.

+
+
+
+CliBuilder2.5 cygwin +
+
+
+
+
+

The groovy.util.CliBuilder Class is Deprecated

+
+
+

Previous versions of CliBuilder used Apache Commons CLI as the underlying parser library. +From Groovy 2.5, there is an alternative version of CliBuilder based on the picocli parser.

+
+
+

Going forward, it is recommended that applications explicitly import either groovy.cli.picocli.CliBuilder or groovy.cli.commons.CliBuilder. The groovy.util.CliBuilder class is deprecated and delegates to the Commons CLI version for backwards compatibility.

+
+
+

New features will likely only be added to the picocli version, and groovy.util.CliBuilder may be removed in a future version of Groovy. +The Commons CLI version is intended for applications that rely on the internals of the Commons CLI implementation of CliBuilder and cannot easily migrate to the picocli version.

+
+
+

Next, let’s look at some new features in Groovy 2.5 CliBuilder.

+
+
+
+
+

Typed Options

+
+
+
+Type +
+
+
+

Options can be boolean flags or they can take one or more option parameters. +In previous versions of CliBuilder, you would have to specify args: 1 for options that need a parameter, or +args: '+' for options that accept multiple parameters.

+
+
+

This version of CliBuilder adds support for typed options. This is convenient when processing parse results, +but additionally, the number of arguments is inferred from the type, +so if the type is specified, args can be omitted.

+
+
+

For example:

+
+
+
+
def cli = new CliBuilder()
+cli.a(type: String, 'a-arg')
+cli.b(type: boolean, 'b-arg')
+cli.c(type: Boolean, 'c-arg')
+cli.d(type: int, 'd-arg')
+cli.e(type: Long, 'e-arg')
+cli.f(type: Float, 'f-arg')
+cli.g(type: BigDecimal, 'g-arg')
+cli.h(type: File, 'h-arg')
+cli.i(type: RoundingMode, 'i-arg')
+
+def argz = '''-a John -b -d 21 -e 1980 -f 3.5 -g 3.14159
+    -h cv.txt -i DOWN and some more'''.split()
+
+def options = cli.parse(argz)
+assert options.a == 'John'
+assert options.b
+assert !options.c
+assert options.d == 21
+assert options.e == 1980L
+assert options.f == 3.5f
+assert options.g == 3.14159
+assert options.h == new File('cv.txt')
+assert options.i == RoundingMode.DOWN
+assert options.arguments() == ['and', 'some', 'more']
+
+
+
+

Supported Types

+
+

The Commons CLI-based CliBuilder supports primitives, numeric types, files, enums and arrays thereof +(using StringGroovyMethods#asType(String, Class)). +The picocli-based CliBuilder supports those and more.

+
+
+
+

Adding More Types

+
+

If the built-in types don’t meet your needs, it is easy to register a custom converter. Specify a convert Closure to convert the String argument to any other type. For example:

+
+
+
+
import java.nio.file.Paths
+import java.time.LocalTime
+
+def cli = new CliBuilder()
+cli.a(convert: { it.toUpperCase() }, 'a-arg')    (1)
+cli.p(convert: { Paths.get(it) }, 'p-arg')       (2)
+cli.t(convert: { LocalTime.parse(it) }, 't-arg') (3)
+
+def options = cli.parse('-a abc -p /usr/home -t 15:31:59'.split())
+assert options.a == 'ABC'
+assert options.p.absolute && options.p.parent == Paths.get('/usr')
+assert options.t.hour == 15 && options.t.minute == 31
+
+
+
+ + + + + + + + + + + + + +
1Convert one String to another
2Option value is converted to a java.nio.file.Path
3Option value is converted to a java.time.LocalTime
+
+
+
+
+
+

Annotations

+
+
+
+Annotations +
+
+
+

From this release, Groovy offers an annotation API for processing command line arguments.

+
+
+

Applications can annotate fields or methods with @groovy.cli.Option for named options +or @groovy.cli.Unparsed for positional parameters. +When the parser matches a command line argument with an option name or positional parameter, the value is converted +to the correct type and injected into the field or method.

+
+
+

Annotating Methods of an Interface

+
+

One way to use the annotations is on "getter-like" methods (methods that return a value) of an interface. For example:

+
+
+
+
import groovy.cli.*
+
+interface IHello {
+    @Option(shortName='h', description='display usage') Boolean help()   (1)
+    @Option(shortName='u', description='user name')     String user()    (2)
+    @Unparsed(description = 'positional parameters')    List remaining() (3)
+}
+
+
+
+ + + + + + + + + + + + + +
1Method returns true if -h or --help was specified on the command line.
2Method returns the parameter value that was specified for the -u or --user option.
3Any remaining parameters will be returned as a list from this method.
+
+
+

How to use this interface (using the picocli version to demonstrate its usage help):

+
+
+
+
import groovy.cli.picocli.CliBuilder
+
+def cli = new CliBuilder(name: 'groovy Greeter')
+def argz = '--user abc'.split()
+IHello hello = cli.parseFromSpec(IHello, argz)
+assert hello.user() == 'abc'
+
+hello = cli.parseFromSpec(GreeterI, ['--help', 'Some', 'Other', 'Args'] as String[])
+assert hello.help()
+cli.usage()
+assert hello.remaining() == ['Some', 'Other', 'Args']
+
+
+
+

This prints the following usage help message:

+
+
+
+
Usage: groovy Greeter [-h] [-u=<user>] [<remaining>...]
+      [<remaining>...]   positional parameters
+  -u, --user=<user>      user name
+  -h, --help             display usage
+
+
+
+

When parseFromSpec is called, CliBuilder reads the annotations, parses the command line arguments +and returns an instance of the interface. +The interface methods return the option values matched on the command line.

+
+
+
+

Annotating Properties or Setter Methods of a Class

+
+

Another way to use the annotations is on the properties or "setter-like" methods (void methods with a single parameter) of a class. For example:

+
+
+
+
class Hello {
+    @Option(shortName='h', description='display usage') (1)
+    Boolean help
+
+    private String user
+    @Option(shortName='u', description='user name')     (2)
+    void setUser(String user) {
+        this.user = user
+    }
+    String getUser() { user }
+
+    @Unparsed(description = 'positional parameters')    (3)
+    List remaining
+}
+
+
+
+ + + + + + + + + + + + + +
1The help Boolean property is set to true if -h or --help was specified on the command line.
2The setUser property setter method is invoked with the -u or --user option parameter value.
3The remaining property is set to a new List containing the remaining args, if any.
+
+
+

The annotated class can be used as follows:

+
+
+
+
String[] argz = ['--user', 'abc', 'foo']
+
+def cli = new CliBuilder(usage: 'groovy Greeter [option]') (1)
+Hello greeter = cli.parseFromInstance(new Hello(), argz)   (2)
+assert greeter.user == 'abc'                               (3)
+assert greeter.remaining == ['foo']                        (4)
+
+
+
+ + + + + + + + + + + + + + + + + +
1Create a CliBuilder instance.
2Extract options from the annotated instance, parse arguments, and populate and return the supplied instance.
3Verify that the String option value has been assigned to the property.
4Verify the remaining arguments property.
+
+
+

When parseFromInstance is called, CliBuilder again reads the annotations, parses the command line +arguments and finally returns the instance. The annotated fields and setter methods are initialized with the values +matched for the associated option.

+
+
+
+

Script Annotations

+
+
+Script +
+
+
+

Groovy 2.5 also offers new annotations for Groovy scripts.

+
+
+

@OptionField is equivalent to combining @groovy.transform.Field and @Option, whereas @UnparsedField is equivalent to combining @Field and @Unparsed.

+
+
+

Use these annotations to turn script variables into fields so that the variables can be populated by CliBuilder. For example:

+
+
+
+
import groovy.cli.OptionField
+import groovy.cli.UnparsedField
+
+@OptionField String user
+@OptionField Boolean help
+@UnparsedField List remaining
+
+String[] argz = ['--user', 'abc', 'foo']
+
+new CliBuilder().parseFromInstance(this, argz)
+assert user == 'abc'
+assert remaining == ['foo']
+
+
+
+
+
+
+

Typed Positional Parameters

+
+
+

This version of CliBuilder offers some limited support for strongly typed positional parameters.

+
+
+

If all positional parameters have the same type, the @Unparsed annotation can be used with an array type other than String[]. +Again, the type conversion is done using StringGroovyMethods#asType(String, Class) +in the Commons CLI version, while the picocli version of CliBuilder supports a superset of those types.

+
+
+

This functionality is only available for the annotations API, not for the dynamic API. +Here is an example of an interface that can capture strongly typed positional parameters:

+
+
+
+
interface TypedPositionals {
+    @Unparsed Integer[] nums()
+}
+
+
+
+

The code below demonstrates the type conversion:

+
+
+
+
def argz = '12 34 56'.split()
+def cli = new CliBuilder()
+def options = cli.parseFromSpec(TypedPositionals, argz)
+assert options.nums() == [12, 34, 56]
+
+
+
+
+
+

Apache Commons CLI Features

+
+
+
+FeatureIconAdvancedOptions +
+
+
+

Sometimes you may want to use advanced features of the underlying parsing library. +For example, you may have a command line application with mutually exclusive options. +The below code shows how to achieve this using the Apache Commons CLI OptionGroup API:

+
+
+
+
import groovy.cli.commons.CliBuilder
+import org.apache.commons.cli.*
+
+def cli = new CliBuilder()
+def optionGroup = new OptionGroup()
+optionGroup.with {
+  addOption cli.option('s', [longOpt: 'silent'], 's option')
+  addOption cli.option('v', [longOpt: 'verbose'], 'v option')
+}
+cli.options.addOptionGroup optionGroup
+
+assert !cli.parse('--silent --verbose'.split()) (1)
+
+
+
+ + + + + +
1Parsing this input will fail because two mutually exclusive options were specified.
+
+
+
+
+

Picocli CliBuilder Features

+
+
+
+FeatureIconAdvancedOptions +
+
+
+

Strongly Typed Lists

+
+
+list +
+
+
+

Options with multiple values often use an array or a List to capture the values. +Arrays can be strongly typed, that is, contain elements other than String. +The picocli version of CliBuilder lets you do the same with Lists. +The auxiliaryType specifies the type that the elements should be converted to. +For example:

+
+
+
+
import groovy.cli.picocli.CliBuilder
+
+def cli = new CliBuilder()
+cli.T(type: List, auxiliaryTypes: Long, 'typed list')  (1)
+
+def options = cli.parse('-T 1 -T 2 -T 3'.split())      (2)
+assert options.Ts == [ 1L, 2L, 3L ]                    (3)
+
+
+
+ + + + + + + + + + + + + +
1Define an option that can have multiple integer values.
2An example command line.
3The option values as a List<Integer>.
+
+
+
+

Strongly Typed Maps

+
+
+map +
+
+
+

The picocli version of CliBuilder offers native support for Map options. +This is as simple as specifying Map as the option type. +By default, both keys and values are stored as Strings in the Map, +but it’s possible to use auxiliaryType to specify the types that the keys and values should be converted to.

+
+
+
+
import groovy.cli.picocli.CliBuilder
+
+def cli = new CliBuilder()
+cli.D(args: 2,   valueSeparator: '=', 'Commons CLI style map')                 (1)
+cli.X(type: Map, 'picocli style map support')                                  (2)
+cli.Z(type: Map, auxiliaryTypes: [TimeUnit, Integer].toArray(), 'typed map')   (3)
+
+def options = cli.parse('-Da=b -Dc=d -Xx=y -Xi=j -ZDAYS=2 -ZHOURS=23'.split()) (4)
+assert options.Ds == ['a', 'b', 'c', 'd']                                      (5)
+assert options.Xs == [ 'x':'y', 'i':'j' ]                                      (6)
+assert options.Zs == [ (DAYS as TimeUnit):2, (HOURS as TimeUnit):23 ]          (7)
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
1Commons CLI has map-like options by specifying that each option must have two parameters, with some separator.
2The picocli version of CliBuilder has native support for Map options.
3The key type and value type can be specified for strongly-typed maps.
4An example command line.
5The Commons CLI style option gives a list of [key, value, key, value, …​] objects.
6The picocli style option gives the result as a Map<String, String>.
7When auxiliaryTypes are specified, the keys and values of the map are converted to the specified types, giving you a Map<TimeUnit, Integer>.
+
+
+
+

Usage Help with Detailed Synopsis

+
+
+iceberg +
+
+
+

CliBuilder has always supported a usage property to display the usage help synopsis of a command:

+
+
+
+
// the old way
+new CliBuilder(usage: 'myapp [options]').usage()
+
+
+
+

The above program prints:

+
+
+
+
Usage: myapp [options]
+
+
+
+

This still works, but the picocli version has a better alternative with the name property. +If you specify name instead of usage, picocli will show all options in a succinct synopsis with square brackets [ and ] for optional elements and ellipsis …​ for elements that can be repeated one or more times. For example:

+
+
+
+
// the new way
+def cli = new CliBuilder(name: 'myapp') // detailed synopsis
+cli.a('option a description')
+cli.b('option b description')
+cli.c(type: List, 'option c description')
+cli.usage()
+
+
+
+

The above program prints:

+
+
+
+
Usage: myapp [-ab] [-c=PARAM]...
+  -a           option a description
+  -b           option b description
+  -c= PARAM    option c description
+
+
+
+
+

Use Any Option Names

+
+
+freedom c PsychoShadow www.bigstockphoto.com +
+
+
+

Image credit: (c) PsychoShadow - www.bigstockphoto.com

+
+
+

Before, if an option had multiple names with a single hyphen, you had no choice but to declare the option multiple times:

+
+
+
+
// before: split -cp, -classpath into two options
+def cli = new CliBuilder(usage: 'groovyConsole [options] [filename]')
+cli.classpath('Where to find the class files')
+cli.cp(longOpt: 'classpath', 'Aliases for '-classpath')
+
+
+
+

The picocli version of CliBuilder supports a names property that can have any number of option names that can take any prefix. For example:

+
+
+
+
// after: an option can have many names with any prefix
+def cli = new CliBuilder(usage: 'groovyConsole [options] [filename]')
+cli._(names: ['-cp', '-classpath', '--classpath'], 'Where to find the class files')
+
+
+
+
+

Fine-grained Usage Help Message

+
+
+sift +
+
+
+

Picocli offers fine-grained control over the usage help message format and this functionality is exposed via the usageMessage CliBuilder property.

+
+
+

The usage message has a number of sections: header, synopsis, description, parameters, options and finally the footer. Each section has a heading, that precedes the first line of its section. For example:

+
+
+
+
import groovy.cli.picocli.CliBuilder
+
+def cli = new CliBuilder()
+cli.name = "groovy clidemo"
+cli.usageMessage.with {                (1)
+    headerHeading("Header heading:%n") (2)
+    header("header 1", "header 2")     (3)
+    synopsisHeading("%nUSAGE: ")
+    descriptionHeading("%nDescription heading:%n")
+    description("description 1", "description 2")
+    optionListHeading("%nOPTIONS:%n")
+    footerHeading("%nFooter heading:%n")
+    footer("footer 1", "footer 2")
+}
+cli.a(longOpt: 'aaa', 'a-arg')         (4)
+cli.b(longOpt: 'bbb', 'b-arg')
+cli.usage()
+
+
+
+ + + + + + + + + + + + + + + + + +
1Use the usageMessage CliBuilder property to customize the usage help message.
2Headings can contain string format specifiers like the %n newline.
3Sections are multi-line: each string will be rendered on a separate line.
4Define some options.
+
+
+

This prints the following output:

+
+
+
+
Header heading:
+header 1
+header 2
+
+USAGE: groovy clidemo [-ab]
+
+Description heading:
+description 1
+description 2
+
+OPTIONS:
+  -a, --aaa    a-arg
+  -b, --bbb    b-arg
+
+Footer heading:
+footer 1
+footer 2
+
+
+
+
+

Usage Help with ANSI Colors

+
+

Out of the box, the command name, option names and parameter labels in the usage help message are rendered with ANSI styles and colors. +The color scheme for these elements can be configured with system properties.

+
+
+

Other than that, you can use colors and styles in the descriptions and other sections of the usage help message, +using a simple markup notation. The example below demonstrates:

+
+
+
+
def cli = new groovy.cli.picocli.CliBuilder(name: 'myapp')
+cli.usageMessage.with {
+    headerHeading("@|bold,red,underline Header heading|@:%n")
+    header($/@|bold,green \
+  ___ _ _ ___      _ _    _
+ / __| (_) _ )_  _(_) |__| |___ _ _
+| (__| | | _ \ || | | / _` / -_) '_|
+ \___|_|_|___/\_,_|_|_\__,_\___|_|
+|@/$)
+    synopsisHeading("@|bold,underline Usage|@: ")
+    descriptionHeading("%n@|bold,underline Description heading|@:%n")
+    description("Description 1", "Description 2")      // after the synopsis
+    optionListHeading("%n@|bold,underline Options heading|@:%n")
+    footerHeading("%n@|bold,underline Footer heading|@:%n")
+    footer($/@|bold,blue \
+   ___                         ___   ___
+  / __|_ _ ___  _____ ___  _  |_  ) | __|
+ | (_ | '_/ _ \/ _ \ V / || |  / / _|__ \
+  \___|_| \___/\___/\_/ \_, | /___(_)___/
+                        |__/             |@/$)
+}
+cli.a('option a description')
+cli.b('option b description')
+cli.c(type: List, 'option c description')
+cli.usage()
+
+
+
+

The code above gives the following output:

+
+
+
+CliBuilder2.5 cygwin +
+
+
+

(Credit to http://patorjk.com/software/taag/ for the ASCII art.)

+
+
+
+

New errorWriter Property

+
+
+error +
+
+
+

When the user provided invalid input, the picocli version of CliBuilder writes an error message and the usage help message to the new errorWriter property (set to System.err by default). +When the user requests help, and the application calls CliBuilder.usage(), the usage help message is printed to the writer property (System.out by default).

+
+
+

Previous versions of CliBuilder used the writer property for both invalid input and user-requested help.

+
+
+

Why this change? This helps command line application authors to follow standard practice and separate diagnostic output from the program output: If the output of a Groovy program is piped to another program, +sending error messages to STDERR prevents the downstream program from inadvertently trying to parse error output. +On the other hand, when users request help with --help or --version, the output should be sent to STDOUT, +because the user may want to pipe the output to a utility like less or grep.

+
+
+

For backwards compatibility, setting the writer property to another value will also set the errorWriter to the same value. +(You can still set the errorWriter to another value afterwards if desired.)

+
+
+
+
+
+

Gotchas/Incompatibilities

+
+
+
+incompatible +
+
+
+

There are a few areas where the new versions of CliBuilder are not compatible with previous versions or with each other.

+
+
+

Properties options and formatter Unavailable in Picocli Version

+
+

The Commons CLI version of CliBuilder, and previous versions of CliBuilder, expose an options property of type org.apache.commons.cli.Options, that can be used to configure the underlying Commons CLI parser without going through the CliBuilder API. This property is not available in the picocli version of CliBuilder. +Applications that read or write this property must import groovy.cli.commons.CliBuilder +or modify the application.

+
+
+

Additionally, the formatter property of type org.apache.commons.cli.HelpFormatter is not available in the picocli version of CliBuilder. If your application uses this property, consider using the usageMessage property instead, or import groovy.cli.commons.CliBuilder.

+
+
+
+

Property parser Differs in Picocli and Commons CLI Versions

+
+

The picocli version of CliBuilder has a parser property that exposes a picocli.CommandLine.Model.ParserSpec object +that can be used to configure the parser behavior.

+
+
+

The Commons CLI version of CliBuilder, and previous versions of CliBuilder, expose a parser property of type org.apache.commons.cli.CommandLineParser. This functionality is not available in the picocli version of CliBuilder.

+
+
+

If your application uses the parser property to set a different Commons CLI parser, consider using the posix property instead, or import groovy.cli.commons.CliBuilder.

+
+
+
+

Different Parser Behavior for longOption

+
+

The Commons CLI DefaultParser recognizes longOption option names prefixed with a single hypen (e.g., -option) +as well as options prefixed with a double hyphen (e.g., --option). +This is not always obvious since the usage help message only shows the double hyphen prefix for longOption option names.

+
+
+

For backwards compatibility, the picocli version of CliBuilder has an acceptLongOptionsWithSingleHyphen property: +set this property to true if the parser should recognize long option names with both +a single hyphen and a double hyphen prefix. The default is false, +so only long option names with a double hypen prefix (--option) are recognized.

+
+
+
+
+
+

Conclusion

+
+
+

Groovy 2.5 CliBuilder offers a host of exciting new features. Try it out and let us know what you think!

+
+
+

For reference: Groovy site and GitHub project, +picocli site and GitHub project.

+
+
+
+
+ + + \ No newline at end of file diff --git a/docs/man/3.x/images/1x1.png b/docs/man/3.x/images/1x1.png new file mode 100644 index 000000000..1914264c0 Binary files /dev/null and b/docs/man/3.x/images/1x1.png differ diff --git a/docs/man/3.x/images/256colors.png b/docs/man/3.x/images/256colors.png new file mode 100644 index 000000000..3c04a3588 Binary files /dev/null and b/docs/man/3.x/images/256colors.png differ diff --git a/docs/man/3.x/images/AllYourBase.png b/docs/man/3.x/images/AllYourBase.png new file mode 100644 index 000000000..e24546f07 Binary files /dev/null and b/docs/man/3.x/images/AllYourBase.png differ diff --git a/docs/man/3.x/images/AskingForHelp.jpg b/docs/man/3.x/images/AskingForHelp.jpg new file mode 100644 index 000000000..d70a6c1f6 Binary files /dev/null and b/docs/man/3.x/images/AskingForHelp.jpg differ diff --git a/docs/man/3.x/images/AutoHelpDemo-usage-screenshot.png b/docs/man/3.x/images/AutoHelpDemo-usage-screenshot.png new file mode 100644 index 000000000..72151fc0b Binary files /dev/null and b/docs/man/3.x/images/AutoHelpDemo-usage-screenshot.png differ diff --git a/docs/man/3.x/images/AutoHelpDemo-version-screenshot.png b/docs/man/3.x/images/AutoHelpDemo-version-screenshot.png new file mode 100644 index 000000000..d1c733b66 Binary files /dev/null and b/docs/man/3.x/images/AutoHelpDemo-version-screenshot.png differ diff --git a/docs/man/3.x/images/CliBuilder2.5-cygwin.png b/docs/man/3.x/images/CliBuilder2.5-cygwin.png new file mode 100644 index 000000000..31012c4f4 Binary files /dev/null and b/docs/man/3.x/images/CliBuilder2.5-cygwin.png differ diff --git a/docs/man/3.x/images/DescriptionWithColors.png b/docs/man/3.x/images/DescriptionWithColors.png new file mode 100644 index 000000000..55236e585 Binary files /dev/null and b/docs/man/3.x/images/DescriptionWithColors.png differ diff --git a/docs/man/3.x/images/ExampleUsageANSI.png b/docs/man/3.x/images/ExampleUsageANSI.png new file mode 100644 index 000000000..7545b3c3f Binary files /dev/null and b/docs/man/3.x/images/ExampleUsageANSI.png differ diff --git a/docs/man/3.x/images/FeatureIconAdvancedOptions.png b/docs/man/3.x/images/FeatureIconAdvancedOptions.png new file mode 100644 index 000000000..88f76ac1b Binary files /dev/null and b/docs/man/3.x/images/FeatureIconAdvancedOptions.png differ diff --git a/docs/man/3.x/images/Greet-screenshot.png b/docs/man/3.x/images/Greet-screenshot.png new file mode 100644 index 000000000..95997f97c Binary files /dev/null and b/docs/man/3.x/images/Greet-screenshot.png differ diff --git a/docs/man/3.x/images/GroovyChecksum.png b/docs/man/3.x/images/GroovyChecksum.png new file mode 100644 index 000000000..6af27bf45 Binary files /dev/null and b/docs/man/3.x/images/GroovyChecksum.png differ diff --git a/docs/man/3.x/images/GroovyChecksumWithBanner.png b/docs/man/3.x/images/GroovyChecksumWithBanner.png new file mode 100644 index 000000000..5f7da58dd Binary files /dev/null and b/docs/man/3.x/images/GroovyChecksumWithBanner.png differ diff --git a/docs/man/3.x/images/GroovyScript.png b/docs/man/3.x/images/GroovyScript.png new file mode 100644 index 000000000..7c4b7080a Binary files /dev/null and b/docs/man/3.x/images/GroovyScript.png differ diff --git a/docs/man/3.x/images/GroovyScriptAnnotations.png b/docs/man/3.x/images/GroovyScriptAnnotations.png new file mode 100644 index 000000000..a11de1d64 Binary files /dev/null and b/docs/man/3.x/images/GroovyScriptAnnotations.png differ diff --git a/docs/man/3.x/images/OptionsAndParameters.png b/docs/man/3.x/images/OptionsAndParameters.png new file mode 100644 index 000000000..c6952c41d Binary files /dev/null and b/docs/man/3.x/images/OptionsAndParameters.png differ diff --git a/docs/man/3.x/images/OptionsAndParameters2.png b/docs/man/3.x/images/OptionsAndParameters2.png new file mode 100644 index 000000000..1a4aadff0 Binary files /dev/null and b/docs/man/3.x/images/OptionsAndParameters2.png differ diff --git a/docs/man/3.x/images/Type.jpg b/docs/man/3.x/images/Type.jpg new file mode 100644 index 000000000..8ab9845fe Binary files /dev/null and b/docs/man/3.x/images/Type.jpg differ diff --git a/docs/man/3.x/images/UsageHelpSubcommands.png b/docs/man/3.x/images/UsageHelpSubcommands.png new file mode 100644 index 000000000..c344952ce Binary files /dev/null and b/docs/man/3.x/images/UsageHelpSubcommands.png differ diff --git a/docs/man/3.x/images/UsageHelpWithCustomLayout.png b/docs/man/3.x/images/UsageHelpWithCustomLayout.png new file mode 100644 index 000000000..7a33336ae Binary files /dev/null and b/docs/man/3.x/images/UsageHelpWithCustomLayout.png differ diff --git a/docs/man/3.x/images/UsageHelpWithStyle.png b/docs/man/3.x/images/UsageHelpWithStyle.png new file mode 100644 index 000000000..ab885726d Binary files /dev/null and b/docs/man/3.x/images/UsageHelpWithStyle.png differ diff --git a/docs/man/3.x/images/VersionInfoWithColors.png b/docs/man/3.x/images/VersionInfoWithColors.png new file mode 100644 index 000000000..2e9ffe4dc Binary files /dev/null and b/docs/man/3.x/images/VersionInfoWithColors.png differ diff --git a/docs/man/3.x/images/WhereIsMyCode.png b/docs/man/3.x/images/WhereIsMyCode.png new file mode 100644 index 000000000..19077dabd Binary files /dev/null and b/docs/man/3.x/images/WhereIsMyCode.png differ diff --git a/docs/man/3.x/images/a-annotations.png b/docs/man/3.x/images/a-annotations.png new file mode 100644 index 000000000..aea67396a Binary files /dev/null and b/docs/man/3.x/images/a-annotations.png differ diff --git a/docs/man/3.x/images/apache-hive-logo.png b/docs/man/3.x/images/apache-hive-logo.png new file mode 100644 index 000000000..faf05f138 Binary files /dev/null and b/docs/man/3.x/images/apache-hive-logo.png differ diff --git a/docs/man/3.x/images/apache-ozone-logo.png b/docs/man/3.x/images/apache-ozone-logo.png new file mode 100644 index 000000000..cdc8e4e73 Binary files /dev/null and b/docs/man/3.x/images/apache-ozone-logo.png differ diff --git a/docs/man/3.x/images/ballerina-logo.png b/docs/man/3.x/images/ballerina-logo.png new file mode 100644 index 000000000..2c62cbc4d Binary files /dev/null and b/docs/man/3.x/images/ballerina-logo.png differ diff --git a/docs/man/3.x/images/binoculars.jpg b/docs/man/3.x/images/binoculars.jpg new file mode 100644 index 000000000..e9a7b62a8 Binary files /dev/null and b/docs/man/3.x/images/binoculars.jpg differ diff --git a/docs/man/3.x/images/checkstyle-logo-260x50.png b/docs/man/3.x/images/checkstyle-logo-260x50.png new file mode 100644 index 000000000..4266f9991 Binary files /dev/null and b/docs/man/3.x/images/checkstyle-logo-260x50.png differ diff --git a/docs/man/3.x/images/checkstyle-usage.png b/docs/man/3.x/images/checkstyle-usage.png new file mode 100644 index 000000000..4865f7e51 Binary files /dev/null and b/docs/man/3.x/images/checkstyle-usage.png differ diff --git a/docs/man/3.x/images/checksum-help.png b/docs/man/3.x/images/checksum-help.png new file mode 100644 index 000000000..deccf9b1c Binary files /dev/null and b/docs/man/3.x/images/checksum-help.png differ diff --git a/docs/man/3.x/images/class-diagram-definition.png b/docs/man/3.x/images/class-diagram-definition.png new file mode 100644 index 000000000..d1467d127 Binary files /dev/null and b/docs/man/3.x/images/class-diagram-definition.png differ diff --git a/docs/man/3.x/images/class-diagram-parsing.png b/docs/man/3.x/images/class-diagram-parsing.png new file mode 100644 index 000000000..39a83e398 Binary files /dev/null and b/docs/man/3.x/images/class-diagram-parsing.png differ diff --git a/docs/man/3.x/images/cli.jpg b/docs/man/3.x/images/cli.jpg new file mode 100644 index 000000000..b7911dbbf Binary files /dev/null and b/docs/man/3.x/images/cli.jpg differ diff --git a/docs/man/3.x/images/command-methods.png b/docs/man/3.x/images/command-methods.png new file mode 100644 index 000000000..5619740c6 Binary files /dev/null and b/docs/man/3.x/images/command-methods.png differ diff --git a/docs/man/3.x/images/convert.png b/docs/man/3.x/images/convert.png new file mode 100644 index 000000000..d507fd58f Binary files /dev/null and b/docs/man/3.x/images/convert.png differ diff --git a/docs/man/3.x/images/debian-logo-192x50.png b/docs/man/3.x/images/debian-logo-192x50.png new file mode 100644 index 000000000..4f3b9ce73 Binary files /dev/null and b/docs/man/3.x/images/debian-logo-192x50.png differ diff --git a/docs/man/3.x/images/debian-logo-50.png b/docs/man/3.x/images/debian-logo-50.png new file mode 100644 index 000000000..411c9d964 Binary files /dev/null and b/docs/man/3.x/images/debian-logo-50.png differ diff --git a/docs/man/3.x/images/declare.jpg b/docs/man/3.x/images/declare.jpg new file mode 100644 index 000000000..957b2fac9 Binary files /dev/null and b/docs/man/3.x/images/declare.jpg differ diff --git a/docs/man/3.x/images/downloads-201807.png b/docs/man/3.x/images/downloads-201807.png new file mode 100644 index 000000000..dc6e00138 Binary files /dev/null and b/docs/man/3.x/images/downloads-201807.png differ diff --git a/docs/man/3.x/images/downloads-201808.png b/docs/man/3.x/images/downloads-201808.png new file mode 100644 index 000000000..903d08e6a Binary files /dev/null and b/docs/man/3.x/images/downloads-201808.png differ diff --git a/docs/man/3.x/images/downloads-201812.png b/docs/man/3.x/images/downloads-201812.png new file mode 100644 index 000000000..dda47f305 Binary files /dev/null and b/docs/man/3.x/images/downloads-201812.png differ diff --git a/docs/man/3.x/images/downloads-201901.png b/docs/man/3.x/images/downloads-201901.png new file mode 100644 index 000000000..e3b4dfa6a Binary files /dev/null and b/docs/man/3.x/images/downloads-201901.png differ diff --git a/docs/man/3.x/images/empower_developers.png b/docs/man/3.x/images/empower_developers.png new file mode 100644 index 000000000..87e3cb483 Binary files /dev/null and b/docs/man/3.x/images/empower_developers.png differ diff --git a/docs/man/3.x/images/error.png b/docs/man/3.x/images/error.png new file mode 100644 index 000000000..ec05fb79c Binary files /dev/null and b/docs/man/3.x/images/error.png differ diff --git a/docs/man/3.x/images/freedom-c-PsychoShadow-www.bigstockphoto.com.jpg b/docs/man/3.x/images/freedom-c-PsychoShadow-www.bigstockphoto.com.jpg new file mode 100644 index 000000000..d99091bba Binary files /dev/null and b/docs/man/3.x/images/freedom-c-PsychoShadow-www.bigstockphoto.com.jpg differ diff --git a/docs/man/3.x/images/groovy-logo.png b/docs/man/3.x/images/groovy-logo.png new file mode 100644 index 000000000..54af4c185 Binary files /dev/null and b/docs/man/3.x/images/groovy-logo.png differ diff --git a/docs/man/3.x/images/iceberg.png b/docs/man/3.x/images/iceberg.png new file mode 100644 index 000000000..6cdf56498 Binary files /dev/null and b/docs/man/3.x/images/iceberg.png differ diff --git a/docs/man/3.x/images/incompatible.jpg b/docs/man/3.x/images/incompatible.jpg new file mode 100644 index 000000000..7ed47b3a1 Binary files /dev/null and b/docs/man/3.x/images/incompatible.jpg differ diff --git a/docs/man/3.x/images/jlink-455x207.png b/docs/man/3.x/images/jlink-455x207.png new file mode 100644 index 000000000..0483f8ef0 Binary files /dev/null and b/docs/man/3.x/images/jlink-455x207.png differ diff --git a/docs/man/3.x/images/jlink-87x40.png b/docs/man/3.x/images/jlink-87x40.png new file mode 100644 index 000000000..24007eaba Binary files /dev/null and b/docs/man/3.x/images/jlink-87x40.png differ diff --git a/docs/man/3.x/images/junit5logo-172x50.png b/docs/man/3.x/images/junit5logo-172x50.png new file mode 100644 index 000000000..43c50b5c2 Binary files /dev/null and b/docs/man/3.x/images/junit5logo-172x50.png differ diff --git a/docs/man/3.x/images/junit5logo.png b/docs/man/3.x/images/junit5logo.png new file mode 100644 index 000000000..b361ee3af Binary files /dev/null and b/docs/man/3.x/images/junit5logo.png differ diff --git a/docs/man/3.x/images/karate-logo.png b/docs/man/3.x/images/karate-logo.png new file mode 100644 index 000000000..85eab33c7 Binary files /dev/null and b/docs/man/3.x/images/karate-logo.png differ diff --git a/docs/man/3.x/images/karate-logo.svg b/docs/man/3.x/images/karate-logo.svg new file mode 100644 index 000000000..5c2d51d3c --- /dev/null +++ b/docs/man/3.x/images/karate-logo.svg @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/docs/man/3.x/images/list.png b/docs/man/3.x/images/list.png new file mode 100644 index 000000000..77a4bc773 Binary files /dev/null and b/docs/man/3.x/images/list.png differ diff --git a/docs/man/3.x/images/location.jpg b/docs/man/3.x/images/location.jpg new file mode 100644 index 000000000..a39ef5fd2 Binary files /dev/null and b/docs/man/3.x/images/location.jpg differ diff --git a/docs/man/3.x/images/logo/horizontal-400x150.png b/docs/man/3.x/images/logo/horizontal-400x150.png new file mode 100644 index 000000000..a809cf15e Binary files /dev/null and b/docs/man/3.x/images/logo/horizontal-400x150.png differ diff --git a/docs/man/3.x/images/logo/horizontal.png b/docs/man/3.x/images/logo/horizontal.png new file mode 100644 index 000000000..2088e883c Binary files /dev/null and b/docs/man/3.x/images/logo/horizontal.png differ diff --git a/docs/man/3.x/images/logo/horizontal2.png b/docs/man/3.x/images/logo/horizontal2.png new file mode 100644 index 000000000..46c31aea1 Binary files /dev/null and b/docs/man/3.x/images/logo/horizontal2.png differ diff --git a/docs/man/3.x/images/logo/horizontalv2.png b/docs/man/3.x/images/logo/horizontalv2.png new file mode 100644 index 000000000..17c9a2dd2 Binary files /dev/null and b/docs/man/3.x/images/logo/horizontalv2.png differ diff --git a/docs/man/3.x/images/logo/icon-400x250.png b/docs/man/3.x/images/logo/icon-400x250.png new file mode 100644 index 000000000..cd6f59c3f Binary files /dev/null and b/docs/man/3.x/images/logo/icon-400x250.png differ diff --git a/docs/man/3.x/images/logo/icon-square-160x160.png b/docs/man/3.x/images/logo/icon-square-160x160.png new file mode 100644 index 000000000..02ad4e7c1 Binary files /dev/null and b/docs/man/3.x/images/logo/icon-square-160x160.png differ diff --git a/docs/man/3.x/images/logo/icon.png b/docs/man/3.x/images/logo/icon.png new file mode 100644 index 000000000..63fbced7a Binary files /dev/null and b/docs/man/3.x/images/logo/icon.png differ diff --git a/docs/man/3.x/images/map.png b/docs/man/3.x/images/map.png new file mode 100644 index 000000000..e45121804 Binary files /dev/null and b/docs/man/3.x/images/map.png differ diff --git a/docs/man/3.x/images/name.jpg b/docs/man/3.x/images/name.jpg new file mode 100644 index 000000000..fef89ebc4 Binary files /dev/null and b/docs/man/3.x/images/name.jpg differ diff --git a/docs/man/3.x/images/pexels-photo-1210532.jpeg b/docs/man/3.x/images/pexels-photo-1210532.jpeg new file mode 100644 index 000000000..f668507e0 Binary files /dev/null and b/docs/man/3.x/images/pexels-photo-1210532.jpeg differ diff --git a/docs/man/3.x/images/pexels-photo-97077.jpeg b/docs/man/3.x/images/pexels-photo-97077.jpeg new file mode 100644 index 000000000..a5a367188 Binary files /dev/null and b/docs/man/3.x/images/pexels-photo-97077.jpeg differ diff --git a/docs/man/3.x/images/picocli-autocompletion-demo.gif b/docs/man/3.x/images/picocli-autocompletion-demo.gif new file mode 100644 index 000000000..270ca75e9 Binary files /dev/null and b/docs/man/3.x/images/picocli-autocompletion-demo.gif differ diff --git a/docs/man/3.x/images/picocli-on-graalvm.png b/docs/man/3.x/images/picocli-on-graalvm.png new file mode 100644 index 000000000..6b2541a44 Binary files /dev/null and b/docs/man/3.x/images/picocli-on-graalvm.png differ diff --git a/docs/man/3.x/images/picocli.Demo.png b/docs/man/3.x/images/picocli.Demo.png new file mode 100644 index 000000000..2b14a71df Binary files /dev/null and b/docs/man/3.x/images/picocli.Demo.png differ diff --git a/docs/man/3.x/images/pikotaro.jpg b/docs/man/3.x/images/pikotaro.jpg new file mode 100644 index 000000000..ab0c5e494 Binary files /dev/null and b/docs/man/3.x/images/pikotaro.jpg differ diff --git a/docs/man/3.x/images/pipeline.jpg b/docs/man/3.x/images/pipeline.jpg new file mode 100644 index 000000000..d05883241 Binary files /dev/null and b/docs/man/3.x/images/pipeline.jpg differ diff --git a/docs/man/3.x/images/processing_results.jpg b/docs/man/3.x/images/processing_results.jpg new file mode 100644 index 000000000..f3e020667 Binary files /dev/null and b/docs/man/3.x/images/processing_results.jpg differ diff --git a/docs/man/3.x/images/seeing-the-future.jpg b/docs/man/3.x/images/seeing-the-future.jpg new file mode 100644 index 000000000..7e24d4251 Binary files /dev/null and b/docs/man/3.x/images/seeing-the-future.jpg differ diff --git a/docs/man/3.x/images/sift.png b/docs/man/3.x/images/sift.png new file mode 100644 index 000000000..6a481029d Binary files /dev/null and b/docs/man/3.x/images/sift.png differ diff --git a/docs/man/3.x/images/strong_leadership.jpg b/docs/man/3.x/images/strong_leadership.jpg new file mode 100644 index 000000000..52e8e6f4e Binary files /dev/null and b/docs/man/3.x/images/strong_leadership.jpg differ diff --git a/docs/man/3.x/images/whisk.png b/docs/man/3.x/images/whisk.png new file mode 100644 index 000000000..f178602c9 Binary files /dev/null and b/docs/man/3.x/images/whisk.png differ diff --git a/docs/man/3.x/index.html b/docs/man/3.x/index.html new file mode 100644 index 000000000..6a1dbd791 --- /dev/null +++ b/docs/man/3.x/index.html @@ -0,0 +1,5658 @@ + + + + + + + +picocli - a mighty tiny command line interface + + + + + + + +
+
+
+
+
+Fork me on GitHub +
+
+
+
+Every main method deserves picocli! +
+
+
+

picocli the Mighty Tiny Command Line Interface

+
+
+

The user manual for the latest release is at http://picocli.info. +For the busy and impatient: there is also a Quick Guide.

+
+
+
+
+

1. Introduction

+
+
+

Picocli is a one-file framework for creating Java command line applications with almost zero code. +Supports a variety of command line syntax styles including POSIX, GNU, MS-DOS and more. +Generates highly customizable usage help messages with ANSI colors and styles. +Picocli-based applications can have command line TAB completion showing available options, option parameters and subcommands, for any level of nested subcommands.

+
+
+

Screenshot of usage help with Ansi codes enabled

+
+
+

A distinguishing feature of picocli is how it aims +to let users run picocli-based applications without requiring picocli as an external dependency: +all the source code lives in a single file, to encourage application authors to include it in source form.

+
+
+

How it works: annotate your class and picocli initializes it from the command line arguments, +converting the input to strongly typed values in the fields of your class.

+
+
+
+
import picocli.CommandLine.Option;
+import picocli.CommandLine.Parameters;
+import java.io.File;
+
+public class Example {
+    @Option(names = { "-v", "--verbose" }, description = "Be verbose.")
+    private boolean verbose = false;
+
+    @Parameters(arity = "1..*", paramLabel = "FILE", description = "File(s) to process.")
+    private File[] inputFiles;
+    ...
+}
+
+
+
+

Then invoke CommandLine.parse or CommandLine.populateCommand with the command line parameters and an object you want to initialize.

+
+
+
+
String[] args = { "-v", "inputFile1", "inputFile2" };
+Example app = CommandLine.populateCommand(new Example(), args);
+assert  app.verbose;
+assert  app.inputFiles != null && app.inputFiles.length == 2;
+
+
+
+

Here is a small example application that uses the CommandLine.call convenience method +to do parsing and error handling in one line of code. The mixinStandardHelpOptions attribute is all +that is needed to give your application usage help and version help.

+
+
+
+
@Command(description = "Prints the checksum (MD5 by default) of a file to STDOUT.",
+         name = "checksum", mixinStandardHelpOptions = true, version = "checksum 3.0")
+class CheckSum implements Callable<Void> {
+
+    @Parameters(index = "0", description = "The file whose checksum to calculate.")
+    private File file;
+
+    @Option(names = {"-a", "--algorithm"}, description = "MD5, SHA-1, SHA-256, ...")
+    private String algorithm = "MD5";
+
+    public static void main(String[] args) throws Exception {
+        // CheckSum implements Callable, so parsing, error handling and handling user
+        // requests for usage help or version help can be done with one line of code.
+        CommandLine.call(new CheckSum(), args);
+    }
+
+    @Override
+    public Void call() throws Exception {
+        // your business logic goes here...
+        byte[] fileContents = Files.readAllBytes(file.toPath());
+        byte[] digest = MessageDigest.getInstance(algorithm).digest(fileContents);
+        System.out.println(javax.xml.bind.DatatypeConverter.printHexBinary(digest));
+        return null;
+    }
+}
+
+
+
+
+
+

2. Options and Parameters

+
+
+

Command line arguments can be separated into options and positional parameters. +Options have a name, positional parameters are usually the values that follow the options, +but they may be mixed.

+
+
+

Example command with annotated @Option and @Parameters

+
+
+

Picocli has separate annotations for options and positional parameters.

+
+
+

2.1. Options

+
+

An option must have one or more names. +Picocli lets you use any option name you want.

+
+
+ + + + + +
+ + +You may be interested in this list of common option names. Following these conventions may make your application more intuitive to use for experienced users. +
+
+
+

The below example shows options with one or more names, options that take an option parameter, and a help option.

+
+
+
+
class Tar {
+    @Option(names = "-c", description = "create a new archive")
+    boolean create;
+
+    @Option(names = { "-f", "--file" }, paramLabel = "ARCHIVE", description = "the archive file")
+    File archive;
+
+    @Parameters(paramLabel = "FILE", description = "one ore more files to archive")
+    File[] files;
+
+    @Option(names = { "-h", "--help" }, usageHelp = true, description = "display a help message")
+    private boolean helpRequested = false;
+}
+
+
+
+

Picocli matches the option names to set the field values.

+
+
+
+
String[] args = { "-c", "--file", "result.tar", "file1.txt", "file2.txt" };
+Tar tar = new Tar();
+new CommandLine(tar).parse(args);
+
+assert !tar.helpRequested;
+assert  tar.create;
+assert  tar.archive.equals(new File("result.tar"));
+assert  Arrays.equals(tar.files, new File[] {new File("file1.txt"), new File("file2.txt")});
+
+
+
+
+

2.2. Interactive (Password) Options

+
+

Picocli 3.5 introduced 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 password value and presses enter, the call() method is invoked, which prints something like the following:

+
+
+
+
Hi user123, your passphrase is hashed to 75K3eLr+dx6JJFuJ7LwIpEpOFmwGZZkRiB84PURz6U8=.
+
+
+
+ + + + + +
+ + +
Supporting both Interactive and Batch (Script) Mode
+
+

Interactive options will cause the application to wait for input on stdin. If your command also needs to be run in (non-interactive) batch mode, it should provide additional non-interactive alternative options to allow end users to run the command interactively as well as in batch mode.

+
+
+

In the above example, one idea is to add a --password:file option that takes a File or Path parameter, where the application reads the password from the specified file. +Another idea is to add a --password:env option that takes an environment variable name parameter, where the application gets the password from the user’s environment variables.

+
+
+

A command that combines either of these with an interactive --password option allows end users to provide a password without specifying it in plain text on the command line, and can be executed both interactively and in batch mode.

+
+
+
+
+
+

2.3. Short Options

+
+

Picocli supports POSIX clustered short options: +one or more single-character options without option-arguments, followed by at most one option with an option-argument, can be grouped behind one '-' delimiter.

+
+
+

For example, given this annotated class:

+
+
+
+
class ClusteredShortOptions {
+    @Option(names = "-a") boolean aaa;
+    @Option(names = "-b") boolean bbb;
+    @Option(names = "-c") boolean ccc;
+    @Option(names = "-f") String  file;
+}
+
+
+
+

The following command line arguments are all equivalent and parsing them will give the same result:

+
+
+
+
<command> -abcfInputFile.txt
+<command> -abcf=InputFile.txt
+<command> -abc -f=InputFile.txt
+<command> -ab -cf=InputFile.txt
+<command> -a -b -c -fInputFile.txt
+<command> -a -b -c -f InputFile.txt
+<command> -a -b -c -f=InputFile.txt
+...
+
+
+
+
+

2.4. Positional Parameters

+
+

Any command line arguments that are not subcommands or options (or option parameters) are interpreted as positional parameters. +Positional parameters generally follow the options but from picocli v2.0, positional parameters can be mixed with options on the command line.

+
+
+

Use the (zero-based) index attribute to specify exactly which parameters to capture. +Omitting the index attribute means the field captures all positional parameters. +Array or collection fields can capture multiple values.

+
+
+

The index attribute accepts range values, so an annotation like @Parameters(index="2..4") captures the arguments at index 2, 3 and 4. Range values can be open-ended. For example, @Parameters(index="3..*") captures all arguments from index 3 and up.

+
+
+

For example:

+
+
+
+
class PositionalParameters {
+    @Parameters(hidden = true)  // "hidden": don't show this parameter in usage help message
+    List<String> allParameters; // no "index" attribute: captures _all_ arguments (as Strings)
+
+    @Parameters(index = "0")    InetAddress host;
+    @Parameters(index = "1")    int port;
+    @Parameters(index = "2..*") File[] files;
+}
+
+
+
+

Picocli initializes fields with the values at the specified index in the arguments array.

+
+
+
+
String[] args = { "localhost", "12345", "file1.txt", "file2.txt" };
+PositionalParameters params = CommandLine.populateCommand(new PositionalParameters(), args);
+
+assert params.host.getHostName().equals("localhost");
+assert params.port == 12345;
+assert Arrays.equals(params.files, new File[] {new File("file1.txt"), new File("file2.txt")});
+assert params.allParameters.equals(Arrays.asList("localhost", "12345", "file1.txt", "file2.txt"));
+
+
+
+

See Strongly Typed Everything for which types are supported out of the box and how to add custom types.

+
+
+
+

2.5. Mixing Options and Positional Parameters

+
+

From picocli v2.0, positional parameters can be mixed with options on the command line.

+
+
+

For example:

+
+
+
+
class Mixed {
+    @Parameters
+    List<String> positional;
+
+    @Option(names = "-o")
+    List<String> options;
+}
+
+
+
+

Any command line argument that is not an option or subcommand is interpreted as a positional parameter.

+
+
+
+
String[] args = { "param0", "-o", "AAA", "param1", "param2", "-o", "BBB", "param3" };
+Mixed mixed = new Mixed();
+new CommandLine(mixed).parse(args);
+
+assert mixed.positional.equals(Arrays.asList("param0", "param1", "param2", "param3");
+assert mixed.options.equals   (Arrays.asList("AAA", "BBB"));
+
+
+
+
+

2.6. Double dash (--)

+
+

When one of the command line arguments is just two dashes without any characters attached (--), +picocli interprets all following arguments as positional parameters, even arguments that match an option name.

+
+
+
+
class DoubleDashDemo {
+    @Option(names = "-v")     boolean verbose;
+    @Option(names = "-files") List<String> files;
+    @Parameters               List<String> params;
+}
+
+
+
+

The -- end-of-options delimiter clarifies which of the arguments are positional parameters:

+
+
+
+
String[] args = { "-v", "--", "-files", "file1", "file2" };
+DoubleDashDemo demo = new DoubleDashDemo();
+new CommandLine(demo).parse(args);
+
+assert demo.verbose;
+assert demo.files == null;
+assert demo.params.equals(Arrays.asList("-files", "file1", "file2"));
+
+
+
+

A custom delimiter can be configured with CommandLine.setEndOfOptionsDelimiter(String).

+
+
+
+

2.7. @-files

+
+

2.7.1. Argument Files for Long Command Lines

+
+

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 v2.1.0, 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.

+
+
+

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. +Within quoted values, backslashes need to be escaped with another backslash.

+
+
+

For example, it is possible to have a path with a space, +such as c:\Program Files that can be specified as either "c:\\Program Files" or, +to avoid an escape, c:\Program" "Files.

+
+
+

Lines starting with # are comments and are ignored. +The comment character can be configured with CommandLine.setAtFileCommentChar(Character), +and comments can be switched off by setting the comment character to null.

+
+
+

The file may itself contain additional @-file arguments; any such arguments will be processed recursively.

+
+
+

If the file does not exist, or cannot be read, then the argument will be treated literally, and not removed. +Multiple @-files may be specified on the command line. The specified path may be relative (to the current directory) or absolute.

+
+
+

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"
+
+
+
+

@-file expansion can be switched off by calling CommandLine::setExpandAtFiles with false. +If turned on, you can still pass a real parameter with an initial '@' character by escaping it +with an additional '@' symbol, e.g. '@@somearg' will become '@somearg' and not be subject to expansion.

+
+
+

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.

+
+
+
+

2.7.2. Simplified Format

+
+

From picocli 3.8.1, a simpler argument file format is also supported where every line (except empty lines and comment lines) +is interpreted as a single argument. Arguments containing whitespace do not need to be quoted, +but it is not possible to have arguments with embedded newlines or to have empty string arguments without quotes. +From picocli 3.9, this simpler argument format is fully compatible with JCommander's @-file argument file format.

+
+
+

You can tell picocli to use the simplified argument file format programmatically with CommandLine.setUseSimplifiedAtFiles(true), +or by setting system property picocli.useSimplifiedAtFiles without a value or with value "true" +(case-insensitive). The system property is useful to allow end users control over the format.

+
+
+
+
+
+
+

3. Strongly Typed Everything

+
+
+

When command line options and positional parameters are mapped to the annotated fields, +the text value is converted to the type of the annotated field.

+
+
+

3.1. Built-in Types

+
+

Out of the box, picocli can convert command line argument strings to a number of common data types.

+
+
+

Most of the built-in types work with Java 5, but picocli also has some default converters for Java 7 types like Path and Java 8 types like Duration, etc. These converters are loaded using reflection and are only available when running on a Java version that supports them. See the below list for details.

+
+
+
    +
  • +

    any Java primitive type or their wrapper

    +
    • +
  • +

    any enum

    +
    • +
  • +

    String, StringBuilder, CharSequence

    +
    • +
  • +

    java.math.BigDecimal, java.math.BigInteger

    +
    • +
  • +

    java.nio.Charset

    +
    • +
  • +

    java.io.File

    +
    • +
  • +

    java.net.InetAddress

    +
    • +
  • +

    java.util.regex.Pattern

    +
    • +
  • +

    java.util.Date (for values in "yyyy-MM-dd" format)

    +
    • +
  • +

    java.net.URL, java.net.URI

    +
    • +
  • +

    java.util.UUID

    +
    • +
  • +

    java.lang.Class (from picocli 2.2, for the fully qualified class name)

    +
    • +
  • +

    java.nio.ByteOrder (from picocli 2.2, for the Strings "BIG_ENDIAN" or "LITTLE_ENDIAN")

    +
    • +
  • +

    java.util.Currency (from picocli 2.2, for the ISO 4217 code of the currency)

    +
    • +
  • +

    java.net.NetworkInterface (from picocli 2.2, for the InetAddress or name of the network interface)

    +
    • +
  • +

    java.util.TimeZoneConverter (from picocli 2.2, for the ID for a TimeZone)

    +
    • +
+
+
+

Converters loaded using reflection:

+
+
+
    +
  • +

    java.nio.file.Path (from picocli 2.2, requires Java 7 or higher)

    +
    • +
  • +

    java.time value objects: Duration, Instant, LocalDate, LocalDateTime, LocalTime, MonthDay, OffsetDateTime, OffsetTime, Period, Year, YearMonth, ZonedDateTime, ZoneId, ZoneOffset (from picocli 2.2, requires Java 8 or higher, invokes the parse method of these classes)

    +
    • +
  • +

    java.sql.Time (for values in any of the "HH:mm", "HH:mm:ss", "HH:mm:ss.SSS", or "HH:mm:ss,SSS" formats)

    +
    • +
  • +

    java.sql.Timestamp (from picocli 2.2, for values in the "yyyy-MM-dd HH:mm:ss" or "yyyy-MM-dd HH:mm:ss.fffffffff" formats)

    +
    • +
  • +

    java.sql.Connection (from picocli 2.2, for a database url of the form jdbc:subprotocol:subname)

    +
    • +
  • +

    java.sql.Driver (from picocli 2.2, for a database URL of the form jdbc:subprotocol:subname)

    +
    • +
+
+
+ + + + + +
+ + +Sometimes loading converters with reflection is not desirable. +Use system property picocli.converters.excludes to specify a comma-separated list of fully qualified class names for which the converter should not be loaded. +Regular expressions are supported. +For example, invoking the program with -Dpicocli.converters.excludes=java.sql.Ti.* will not load type converters for java.sql.Time and java.sql.Timestamp. +
+
+
+
+

3.2. Custom Type Converters

+
+

Register a custom type converter to handle data types other than the above built-in ones.

+
+
+

Custom converters need to implement the picocli.CommandLine.ITypeConverter interface:

+
+
+
+
public interface ITypeConverter<K> {
+    /**
+     * Converts the specified command line argument value to some domain object.
+     * @param value the command line argument String value
+     * @return the resulting domain object
+     * @throws Exception an exception detailing what went wrong during the conversion
+     */
+    K convert(String value) throws Exception;
+}
+
+
+
+

Custom type converters can be registered with the CommandLine.registerConverter(Class<K> cls, ITypeConverter<K> converter) method. All options and positional parameters with the specified type will be converted by the specified converter.

+
+
+ + + + + +
+ + +Java 8 lambdas make it easy to register custom converters: +
+
+
+
+
CommandLine cl = new CommandLine(app)
+cl.registerConverter(Locale.class, s -> new Locale.Builder().setLanguageTag(s).build());
+cl.registerConverter(Cipher.class, s -> Cipher.getInstance(s));
+
+
+
+

After registering custom converters, call the parse(String…​) method on the CommandLine instance where the converters are registered. (The static populateCommand method cannot be used.) For example:

+
+
+
+
class App {
+    @Parameters java.util.Locale locale;
+    @Option(names = "-a") javax.crypto.Cipher cipher;
+}
+
+
+
+
+
App app = new App();
+CommandLine commandLine = new CommandLine(app)
+    .registerConverter(Locale.class, s -> new Locale.Builder().setLanguageTag(s).build())
+    .registerConverter(Cipher.class, s -> Cipher.getInstance(s));
+
+commandLine.parse("-a", "AES/CBC/NoPadding", "en-GB");
+assert app.locale.toLanguageTag().equals("en-GB");
+assert app.cipher.getAlgorithm().equals("AES/CBC/NoPadding"));
+
+
+
+ + + + + +
+ + +Note on subcommands: the specified converter will be registered with the CommandLine object +and all subcommands (and nested sub-subcommands) that were added before the converter was registered. +Subcommands added later will not have the converter added automatically. +To ensure a custom type converter is available to all subcommands, register the type converter last, after adding subcommands. +
+
+
+
+

3.3. Option-specific Type Converters

+
+

Picocli 2.2 added a converter attribute to the @Option and @Parameter annotations. This allows a specific option or positional parameter to use a different converter than would be used by default based on the type of the field.

+
+
+

For example, for a specific field you may want to use a converter that maps the constant names defined in java.sql.Types to the int value of these constants, but any other int fields should not be affected by this and should continue to use the standard int converter that parses numeric values.

+
+
+

Example usage:

+
+
+
+
class App {
+    @Option(names = "--sqlType", converter = SqlTypeConverter.class)
+    int sqlType;
+}
+
+
+
+

Example implementation:

+
+
+
+
class SqlTypeConverter implements ITypeConverter<Integer> {
+    public Integer convert(String value) throws Exception {
+        switch (value) {
+            case "ARRAY"  : return Types.ARRAY;
+            case "BIGINT" : return Types.BIGINT;
+            case "BINARY" : return Types.BINARY;
+            case "BIT"    : return Types.BIT;
+            case "BLOB"   : return Types.BLOB;
+            ...
+        }
+    }
+}
+
+
+
+

This may also be useful for applications that need a custom type converter but want to use the static convenience methods (populateCommand, run, call, invoke). The converter annotation does not require a CommandLine instance so it can be used with the static convenience methods.

+
+
+

Type converters declared with the converter attribute need to have a public no-argument constructor to be instantiated, unless a Custom Factory is installed to instantiate classes.

+
+
+
+

3.4. Arrays, Collections, Maps

+
+ + + + + +
+ + +Starting from picocli v2.0, the type attribute is no longer necessary for Collection and Map fields: +picocli will infer the collection element type from the generic type. +(The type attribute still works as before, it is just optional in most cases.) +
+
+
+

3.4.1. Arrays and Collections

+
+

Multiple parameters can be captured together in a single array or Collection field. +The array or collection elements can be any type for which a converter is registered. +For example:

+
+
+
+
import java.util.regex.Pattern;
+import java.io.File;
+
+class Convert {
+    @Option(names = "-patterns", description = "the regex patterns to use");
+    Pattern[] patterns;
+
+    @Parameters(/* type = File.class, */ description = "the files to convert")
+    List<File> files; // picocli infers type from the generic type
+}
+
+
+
+
+
String[] args = { "-patterns", "a*b", "-patterns", "[a-e][i-u]", "file1.txt", "file2.txt" };
+Convert convert = CommandLine.populateCommand(new Convert(), args);
+
+// convert.patterns now has two Pattern objects
+// convert.files now has two File objects
+
+
+
+ + + + + +
+ + +If a collection is returned from a type converter, the contents of the collection are added to the field or method parameter, not the collection itself. +
+
+
+

If the field or method parameter is null, picocli will instantiate it when the option or positional parameter is successfully matched. +If the Collection type is not a concrete class, picocli will make a best effort to instantiate it based on the field type: +List → ArrayList, OrderedSet → TreeSet, Set → LinkedHashSet, Queue → LinkedList, otherwise, ArrayList.

+
+
+
+

3.4.2. Maps

+
+

Picocli v1.0 introduced support for Map fields similar to Java’s system properties -Dkey=value or Gradle’s project properties -Pmyprop=myvalue.

+
+
+

Map fields may have any type for their key and value +as long as a converter is registered for both the key and the value type. +Key and value types are inferred from the map’s generic type parameters. +For example:

+
+
+
+
import java.net.InetAddress;
+import java.net.Proxy.Type;
+import java.util.concurrent.TimeUnit;
+
+class MapDemo {
+    @Option(names = {"-p", "--proxyHost"});
+    Map<Proxy.Type, InetAddress> proxies;
+
+    @Option(names = {"-u", "--timeUnit"});
+    Map<TimeUnit, Long> timeout;
+}
+
+
+
+

Map options may be specified multiple times with different key-value pairs. (See Multiple Values.)

+
+
+
+
<command> -p HTTP=123.123.123.123 --proxyHost SOCKS=212.212.212.212
+<command> -uDAYS=3 -u HOURS=23 -u=MINUTES=59 --timeUnit=SECONDS=13
+
+
+
+

If the field is null, picocli will instantiate it when the option or positional parameter is matched. +If the type is not a concrete class, picocli will instantiate a LinkedHashMap to preserve the input ordering.

+
+
+ + + + + +
+ + +On the command line, the key and the value must be separated by a = character. +
+
+
+
+
+

3.5. Abstract Field Types

+
+

The field’s type can be an interface or an abstract class. +The type attribute can be used to control for each field what concrete class the string value should be converted to. +For example:

+
+
+
+
class App {
+    @Option(names = "--big", type = BigDecimal.class) // concrete Number subclass
+    Number[] big; // array type with abstract component class
+
+    @Option(names = "--small", type = Short.class) // other Number subclass
+    Number[] small;
+
+    @Parameters(type = StringBuilder.class) // StringBuilder implements CharSequence
+    CharSequence address; // interface type
+}
+
+
+
+

3.5.1. Maps and Collections with Abstract Elements

+
+

For raw maps and collections, or when using generics with unbounded wildcards like Map<?, ?>, or when the type parameters are themselves abstract classes like List<CharSequence> or Map<? extends Number, ? super Number>, there is not enough information to convert to a stronger type. By default, the raw String values are added as is to such collections.

+
+
+

The type attribute can be specified to convert to a stronger type than String. For example:

+
+
+
+
class TypeDemo {
+    @Option(names = "-x"); // not enough information to convert
+    Map<?, ?> weaklyTyped; // String keys and values are added as is
+
+    @Option(names = "-y", type = {Short.class, BigDecimal.class});
+    Map<? extends Number, ? super Number> stronglyTyped;
+
+    @Option(names = "-s", type = CharBuffer.class);
+    List<CharSequence> text;
+}
+
+
+
+
+
+

3.6. Enum Types

+
+

It is encouraged to use enum types for options or positional parameters with a limited set of valid values. +Not only will picocli validate the input, it allows you to show all values in the usage help message with @Option(description = "Valid values: ${COMPLETION-CANDIDATES}"). It also allows command line completion to suggest completion candidates for the values of this option.

+
+
+

Enum value matching is case-sensitive by default, but from 3.4 this can be controlled with CommandLine::setCaseInsensitiveEnumValuesAllowed and CommandSpec::caseInsensitiveEnumValuesAllowed.

+
+
+
+
+
+

4. Default Values

+
+
+

It is possible to define a default value for an option or positional parameter, that is assigned when the user did not specify this option or positional parameter on the command line.

+
+
+

4.1. Field Values

+
+

For annotated fields, it is simplest to declare the field with a value:

+
+
+
+
@Option(names = "-c", description = "The count (default: ${DEFAULT-VALUE})")
+int count = 123; // default value is 123
+
+
+
+
+

4.2. defaultValue Annotation

+
+

For @Option and @Parameters-annotated methods and @Command-annotated methods, use the defaultValue annotation attribute. For example, for an annotated interface:

+
+
+
+
interface Spec {
+    @Option(names = "-c", defaultValue = "123", description = "... ${DEFAULT-VALUE} ...")
+    int count();
+}
+
+
+
+

Or similarly for an annotated concrete class:

+
+
+
+
class Impl {
+    int count;
+
+    @Option(names = "-c", defaultValue = "123", description = "... ${DEFAULT-VALUE} ...")
+    void setCount(int count) {
+        this.count = count;
+    }
+}
+
+
+
+

And finally for a command method:

+
+
+
+
class CommandMethod {
+    @Command(description = "Do something.")
+    void doit(@Option(names = "-c", defaultValue = "123") int count) {
+        // ...
+    }
+}
+
+
+
+

Note that you can use the ${DEFAULT-VALUE} variable in the description of the option or positional parameter and picocli will show the actual default value.

+
+
+
+

4.3. Default Provider

+
+

Finally, you can 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;
+}
+
+
+
+
+
+
+

5. Multiple Values

+
+
+

Multi-valued options and positional parameters are annotated fields that can capture multiple values from the command line.

+
+
+

5.1. Multiple Occurrences

+
+

5.1.1. Repeated Options

+
+

The simplest way to create a multi-valued option is to declare an annotated field whose type is an array, collection or a map.

+
+
+
+
@Option(names = "-option")
+int[] values;
+
+
+
+

Users may specify the same option multiple times. For example:

+
+
+
+
<command> -option 111 -option 222 -option 333
+
+
+
+

Each value is appended to the array or collection.

+
+
+
+

5.1.2. Multiple Positional Parameters

+
+

Similarly for multi-valued positional parameters:

+
+
+
+
@Parameters
+List<TimeUnit> units;
+
+
+
+

Users may specify multiple positional parameters. For example:

+
+
+
+
<command> SECONDS HOURS DAYS
+
+
+
+

Again, each value is appended to the array or collection.

+
+
+
+

5.1.3. Repeated Boolean Options

+
+

Boolean options with multiple values are supported from picocli v2.1.0.

+
+
+
+
@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.

+
+
+
+
+

5.2. Split Regex

+
+

Options and parameters may also specify a split regular expression used to split each option parameter into smaller substrings. +Each of these substrings is converted to the type of the collection or array. See Arrays and Collections.

+
+
+
+
@Option(names = "-option", split = ",")
+int[] values;
+
+
+
+

A single command line argument like the following will be split up and three int values are added to the array:

+
+
+
+
-option 111,222,333
+
+
+
+

Similarly for Maps:

+
+
+
+
@Option(names = "-fix", split = "\\|")
+Map<Integer, String> message;
+
+
+
+

With the above option, command line arguments like the following are interpreted as a set of key-value pairs instead of a single string:

+
+
+
+
-fix 8=FIX.4.4|9=69|35=A|49=MBT|56=TargetCompID|34=9|52=20130625-04:05:32.682|98=0|108=30|10=052
+
+
+
+

See Quoted Values for details on handling more complex cases.

+
+
+
+

5.3. Arity

+
+

Sometimes you want to define an option that requires more than one option parameter for each option occurrence on the command line.

+
+
+

The arity attribute lets you control exactly how many parameters to consume for each option occurrence.

+
+
+

The arity attribute can specify an exact number of required parameters, or a range with a minimum and a maximum number of parameters. +The maximum can be an exact upper bound, or it can be "*" to denote any number of parameters. For example:

+
+
+
+
class ArityDemo {
+    @Parameters(arity = "1..3", descriptions = "one to three Files")
+    File[] files;
+
+    @Option(names = "-f", arity = "2", description = "exactly two floating point numbers")
+    double[] doubles;
+
+    @Option(names = "-s", arity = "1..*", description = "at least one string")
+    String[] strings;
+}
+
+
+
+

A MissingParameterException is thrown when fewer than the miminum number of parameters is specified on the command line.

+
+
+

Once the minimum number of parameters is consumed, picocli will check each subsequent command line argument to see whether it is an additional parameter, or a new option. For example:

+
+
+
+
ArityDemo -s A B C -f 1.0 2.0 /file1 /file2
+
+
+
+

Option -s has arity "1..*" but instead of consuming all parameters, +the -f argument is recognized as a separate option.

+
+
+
+

5.4. Default Arity

+
+

If no arity is specified, the number of parameters depends on the field’s type.

+
+
+

5.4.1. Option Arity

+ + +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1. Default arity for @Option fields
@Option Field TypeDefault ArityNotes

boolean

0

Boolean options by default don’t require an option parameter. The field is toggled to its logical negative when the option name is recognized. (This can be switched off.)

Single-valued type (e.g., int, String, File)

1

The option name must be followed by a value.

Multi-valued type (arrays, collections or maps)

1

The option name must be followed by a value.

+
+ + + + + +
+ + +Prior to picocli v2.0, multi-valued options used to greedily consume as many arguments as possible until +encountering another option or subcommand. +If your application relies on the previous behaviour, you need to explicitly specify an option arity of 0..* when migrating to picocli v2.0. +
+
+
+
+

5.4.2. Positional Parameter Arity

+ + +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Table 2. Default arity for @Parameters fields
@Parameters Field TypeDefault ArityNotes

boolean

1

Positional parameters of type boolean or Boolean require a value. Only true or false (case insensitive) are valid values.

Single-valued type (e.g., int, String, File)

1

One parameter required for each position.

Multi-valued type (arrays, collections or maps)

0..1

For multi-valued positional parameters (arrays, collections or maps), values are optional, not required.

+
+

@Parameters fields are applied to a command line argument if their index matches the argument’s position. +The default index is *, meaning all positions. +A @Parameters field with index = "*" is applied multiple times: once for each positional parameter on the command line.

+
+
+

When a @Parameters field is applied (because its index matches the index of the positional parameter), the field may consume zero, one or more arguments, depending on its arity.

+
+
+
+
+

5.5. Optional Values

+
+

If an option is defined with arity = "0..1", it may or not have a parameter value. +If such an option is specified without a value on the command line, it is assigned an empty String (starting from picocli 2.3). +If the option is not specified, it keeps its default value. For example:

+
+
+
+
class OptionalValueDemo implements Runnable {
+    @Option(names = "-x", arity = "0..1", description = "optional parameter")
+    String x;
+
+    public void run() { System.out.printf("x = '%s'%n", x); }
+
+    public static void main(String... args) {
+       CommandLine.run(new OptionalValueDemo(), args);
+    }
+}
+
+
+
+

Gives the following results:

+
+
+
+
java OptionalValueDemo -x value
+x = 'value'
+
+java OptionalValueDemo -x
+x = ''
+
+java OptionalValueDemo
+x = 'null'
+
+
+
+

From picocli 3.0, options with non-String types can specify a type converter to convert the empty String to a strongly typed value when the option is specified without a value.

+
+
+
+
+
+

6. Required Arguments

+
+
+

6.1. Required Options

+
+

Options can be marked required to make it mandatory for the user to specify them on the command line. When a required option is not specified, a MissingParameterException is thrown from the parse method. For example:

+
+
+
+
class MandatoryOption {
+    @Option(names = "-n", required = true, description = "mandatory number")
+    int number;
+
+    @Parameters
+    File[] files;
+}
+
+
+
+

The following command line arguments would result in an exception complaining that number is missing:

+
+
+
+
// invalid: missing option -n
+<command> file1 file2 file3
+
+
+
+

The following command line arguments would be accepted:

+
+
+
+
// valid: required option -n has a value
+<command> -n 123 file1 file2 file3
+
+
+
+
+

6.2. Required Parameters

+
+

Use the arity attribute to make @Parameters mandatory:

+
+
+
+
class BothOptionAndParametersMandatory {
+    @Parameters(arity = "1..*", descriptions = "at least one File")
+    File[] files;
+
+    @Option(names = "-n", required = true, description = "mandatory number")
+    int number;
+}
+
+
+
+

The following command line arguments would result in an exception complaining that files are missing:

+
+
+
+
// invalid: missing file parameters
+<command> -n 123
+
+
+
+

The following command line arguments would be accepted:

+
+
+
+
// valid: both required fields have a value
+<command> -n 123 file1
+
+
+
+
+
+
+

7. Parser Configuration

+
+
+

7.1. Overwriting Single Options

+
+

When a single-value option is specified multiple times on the command line, the default parser behaviour is +to throw an OverwrittenOptionException. For example:

+
+
+
+
@Option(name = "-p") int port;
+
+
+
+

The following input results in an OverwrittenOptionException:

+
+
+
+
<command> -p 80 -p 8080
+
+
+
+

Applications can change this by calling CommandLine.setOverwrittenOptionsAllowed(true) before parsing the input. +When overwritten options are allowed, the last specified value takes effect (the above input will set the port field to 8080) +and a WARN level message is printed to the console. (See Tracing for how to switch off the warnings.)

+
+
+
+

7.2. Stop At Positional

+
+

By default, positional parameters can be mixed with options on the command line, but this is not always desirable. +From picocli 2.3, applications can call CommandLine.setStopAtPositional(true) +to force the parser to treat all values following the first positional parameter as positional parameters.

+
+
+

When this flag is set, the first positional parameter effectively serves as an "end of options" marker.

+
+
+
+

7.3. Unmatched Input

+
+

By default, an UnmatchedArgumentException is thrown when a command line argument cannot be assigned to +an option or positional parameter. For example:

+
+
+
+
class OnlyThree {
+    @Parameters(arity = "3") String[] values;
+}
+
+
+
+

The command has only one annotated field, values, and it expects exactly three arguments, +so the following input results in an UnmatchedArgumentException:

+
+
+
+
java OnlyThree 1 2 3 4 5
+
+
+
+

Applications can change this by calling CommandLine.setUnmatchedArgumentsAllowed(true) before parsing the input. +When unmatched arguments are allowed, the above input will be accepted and a WARN level message is printed to the console. +(See Tracing for how to switch off the warnings.)

+
+
+

The unmatched argument values can be obtained with the CommandLine.getUnmatchedArguments() method.

+
+
+
+

7.4. @Unmatched annotation

+
+

From picocli 3.0, 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. +If no unmatched arguments are found, the value of the field annotated with @Unmatched is unchanged.

+
+
+
+

7.5. Unknown Options

+
+

A special case of unmatched input are arguments that resemble options but don’t match any of the defined options. +For example:

+
+
+
+
@Option(names = "-a") String alpha;
+@Option(names = "-b") String beta;
+@Parameters String[] remainder;
+
+
+
+

The above defines options -a and -b, but what should the parser do with input like this?

+
+
+
+
<command> -x -a AAA
+
+
+
+

The -x argument "looks like" an option but there is no -x option defined…​

+
+
+

One possibility is to silently accept such values as positional parameters but this is often not desirable. +From version 1.0, picocli determines if the unmatched argument "resembles an option" +by comparing its leading characters to the prefix characters of the known options.

+
+
+

When the unmatched value is similar to the known options, picocli throws an UnmatchedArgumentException +rather than treating it as a positional parameter.

+
+
+

As usual, CommandLine.setUnmatchedArgumentsAllowed(true) will accept unmatched input and +display a WARN-level message on the console.

+
+
+

Arguments that are not considered similar to the known options are interpreted as positional parameters:

+
+
+
+
<command> x -a AAA
+
+
+
+

The above input is treated by the parser as one positional parameter (x) followed by the -a option and its value.

+
+
+

Picocli 3.0 introduced a CommandLine.setUnmatchedOptionsArePositionalParams(boolean) method that can be used to +force the parser to treat arguments resembling an option as positional parameters. For example:

+
+
+
+
<command> -x -a AAA
+
+
+
+

When unmatchedOptionsArePositionalParams is set to true, the unknown option -x is treated as a positional parameter. +The next argument -a is recognized and processed as a known option like you would expect.

+
+
+
+

7.6. Stop At Unmatched

+
+

From picocli 2.3, applications can call CommandLine.setStopAtUnmatched(true) to force the parser to stop interpreting +options and positional parameters as soon as it encounters an unmatched argument.

+
+
+

When this flag is set, the first unmatched argument and all subsequent command line arguments are added to the +unmatched arguments list returned by CommandLine.getUnmatchedArguments().

+
+
+
+

7.7. Toggle Boolean Flags

+
+

By default, boolean flag options without a parameter are "toggled" when the option is matched on the command line: +if the previous value was true it is set to false, and when the value was false it is set to true. +From picocli 3.0, applications can call CommandLine.setToggleBooleanFlags(false) to switch this behaviour off. +If toggling is off, flags are simply set to true when the option is matched on the command line.

+
+
+
+

7.8. POSIX Clustered Short Options

+
+

By default, the picocli parser allows POSIX clustered short options, so short options like -x -v -f SomeFile can be clustered together like -xvfSomeFile. +From picocli 3.0, applications can call CommandLine.setPosixClusteredShortOptionsAllowed(false) to enforce that options must be separated with whitespace on the command line. +(This also means that option parameters must be separated from the option name by whitespace or the = separator character, so -D key=value and -D=key=value will be recognized but -Dkey=value will not.)

+
+
+
+

7.9. Lenient Mode (Incubating)

+
+

From picocli 3.2, the parser can be configured 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!

+
+
+
+

7.10. Quoted Values

+
+

From picocli 3.7, quotes around command line parameters are preserved by default (previously they were removed). This can be configured with CommandLine::setTrimQuotes.

+
+
+

Also, when splitting parameters, quoted strings are no longer split. This can be configured with CommandLine::setSplitQuotedStrings.

+
+
+

Example:

+
+
+
+
@Option(names = "-x", split = ",")
+String[] parts;
+
+
+
+

Given input like below:

+
+
+
+
<command> -x "-Dvalues=a,b,c","-Dother=1,2"
+
+
+
+

This results in the parts array having the following values:

+
+
+
+
"-Dvalues=a,b,c"
+"-Dother=1,2"
+
+
+
+

Given input like below:

+
+
+
+
<command> -x a,b,"c,d,e",f,"xxx,yyy"
+
+
+
+

This results in the parts array having the following values:

+
+
+
+
a
+b
+"c,d,e"
+f
+"xxx,yyy"
+
+
+
+

When the splitQuotedStrings parser attribute is set to true the split regex is applied to the parameter value regardless of quotes. +This can be useful when using a regular expression that is designed to handle quotes.

+
+
+
+
+
+

8. Help

+
+
+

8.1. Help Options

+
+

Applications can define help options by setting attribute versionHelp = true, usageHelp = true or help = true. +If one of the arguments specified on the command line is a "help" option, picocli will not throw a MissingParameterException when required options are missing.

+
+
+

For example:

+
+
+
+
@Option(names = {"-V", "--version"}, versionHelp = true, description = "display version info")
+boolean versionInfoRequested;
+
+@Option(names = {"-h", "--help"}, usageHelp = true, description = "display this help message")
+boolean usageHelpRequested;
+
+
+
+

Use these attributes for options that request the usage help message or version information to be shown on the console.

+
+
+
+
App app = CommandLine.populateCommand(new App(), args);
+if (app.usageHelpRequested) {
+   CommandLine.usage(new App(), System.out);
+   return;
+}
+
+
+
+

The CommandLine class offers two methods that allow external components to detect whether +usage help or version information was requested (without inspecting the annotated domain object):

+
+
+
    +
  • +

    CommandLine.isUsageHelpRequested() returns true if the parser matched an option annotated with usageHelp=true

    +
    • +
  • +

    CommandLine.isVersionHelpRequested() returns true if the parser matched an option annotated with versionHelp=true

    +
    • +
+
+
+
+
CommandLine commandLine = new CommandLine(new App());
+commandLine.parse(args);
+if (commandLine.isUsageHelpRequested()) {
+   commandLine.usage(System.out);
+   return;
+} else if (commandLine.isVersionHelpRequested()) {
+   commandLine.printVersionHelp(System.out);
+   return;
+}
+// ... run App's business logic
+
+
+
+

See also Printing Help Automatically.

+
+
+
+

8.2. Mixin Standard Help Options

+
+

Picocli 3.0 introduced 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.
+
+
+
+
+

8.3. Built-in Help Subcommand

+
+

From 3.0, picocli provides a help subcommand (picocli.CommandLine.HelpCommand) that can be installed as a subcommand +on any application command. It prints usage help for the parent command or sibling subcommands. For example:

+
+
+
+
import picocli.CommandLine.HelpCommand;
+
+@Command(name = "myapp", subcommands = {HelpCommand.class, Subcommand.class})
+class MyCommand implements Runnable {
+    // ...
+}
+
+
+
+

For example, the following command prints usage help for a subcommand:

+
+
+
+
myapp help subcommand
+
+
+
+

To print usage help for the main command:

+
+
+
+
myapp help
+
+
+
+
+

8.4. Custom Help Subcommands

+
+

Custom help subcommands should mark themselves as a help command to tell picocli not to throw a MissingParameterException when required options are missing.

+
+
+
+
@Command(helpCommand = true)
+
+
+
+

Picocli 3.0 introduced a new interface picocli.CommandLine.IHelpCommandInitializable that provides custom help +commands with access to the parent command and sibling commands, whether to use Ansi colors or not, and the streams to print the usage help message to.

+
+
+
+
public interface IHelpCommandInitializable {
+    /**
+     * Initializes this object with the information needed to implement a help command that
+     * provides usage help for other commands.
+     *
+     * @param helpCommandLine provides access to this command's parent and sibling commands
+     * @param ansi whether to use Ansi colors or not
+     * @param out the stream to print the usage help message to
+     * @param err the error stream to print any error messages to
+     */
+    void init(CommandLine helpCommandLine, Help.Ansi ansi, PrintStream out, PrintStream err);
+}
+
+
+
+
+

8.5. Printing Help Automatically

+
+

From picocli v2.0, the convenience methods will automatically print usage help and version information +when a help option was specified on the command line (options annotated with the versionHelp or usageHelp attribute - but not the help attribute).

+
+
+

The same holds for the mixinStandardHelpOptions attribute, the built-in HelpCommand and any custom help subcommands marked as a help command.

+
+
+

The following convenience methods automatically print help:

+
+
+
    +
  • +

    CommandLine::call

    +
    • +
  • +

    CommandLine::run

    +
    • +
  • +

    CommandLine::invoke

    +
    • +
  • +

    CommandLine::parseWithHandler (with the built-in Run…​ handlers)

    +
    • +
  • +

    CommandLine::parseWithHandlers (with the built-in Run…​ handlers)

    +
    • +
+
+
+

The following methods do not automatically print help:

+
+
+
    +
  • +

    CommandLine::parse

    +
    • +
  • +

    CommandLine::parseArgs

    +
    • +
  • +

    CommandLine::populateCommand

    +
    • +
+
+
+

When using the last three methods, applications need to query the parse result to detect whether usage help or version help +was requested, and invoke CommandLine::usage or CommandLine::printVersionHelp to actually print the requested help message.

+
+
+
+
+
+

9. Version Help

+
+
+

9.1. Static Version Information

+
+

Since v0.9.8, applications can specify version information in the version attribute of the @Command annotation.

+
+
+
+
@Command(version = "1.0")
+class VersionedCommand {
+    @Option(names = { "-V", "--version" }, versionHelp = true,
+            description = "print version information and exit")
+    boolean versionRequested;
+    ...
+
+
+
+

The CommandLine.printVersionHelp(PrintStream) method extracts the version information from this +annotation and prints it to the specified PrintStream.

+
+
+
+
CommandLine commandLine = new CommandLine(new VersionedCommand());
+commandLine.parse(args);
+if (commandLine.isVersionHelpRequested()) {
+    commandLine.printVersionHelp(System.out);
+    return;
+}
+
+
+
+

The version may specify multiple Strings. Each will be printed on a separate line.

+
+
+
+
@Command(version = { "Versioned Command 1.0", "Build 12345", "(c) 2017" })
+class VersionedCommand { ... }
+
+
+
+

The CommandLine.printVersionHelp(PrintStream) method will print the above as:

+
+
+
+
Versioned Command 1.0
+Build 12345
+(c) 2017
+
+
+
+

The version strings may contain markup to show ANSI styles and colors. For example:

+
+
+
+
@Command(version = {
+        "@|yellow Versioned Command 1.0|@",
+        "@|blue Build 12345|@",
+        "@|red,bg(white) (c) 2017|@" })
+class VersionedCommand { ... }
+
+
+
+

The markup will be rendered as ANSI escape codes on supported systems.

+
+
+

Screenshot of version information containing markup with Ansi styles and colors

+
+
+

From picocli v1.0, the version may contain format specifiers:

+
+
+
+
@Command(version = {
+    "Versioned Command 1.0",
+    "Build %1$s",
+    "(c) 2017, licensed to %2$s" })
+class VersionedCommand { ... }
+
+
+
+

Format argument values can be passed to the printVersionHelp method:

+
+
+
+
String[] args = {"1234", System.getProperty("user.name")};
+new CommandLine(new VersionedCommand())
+    .printVersionHelp(System.out, Help.Ansi.AUTO, args);
+
+
+
+
+

9.2. Dynamic Version Information

+
+

From picocli 2.2, the @Command annotation supports a versionProvider attribute. +Applications may specify a IVersionProvider implementation in this attribute, and picocli will instantiate this class +and invoke it to collect version information.

+
+
+
+
@Command(versionProvider = com.my.custom.ManifestVersionProvider.class)
+class App { ... }
+
+
+
+

This is useful when the version of an application should be detected dynamically at runtime. +For example, an implementation may return version information obtained from the JAR manifest, a properties file or some other source.

+
+
+

Custom version providers need to implement the picocli.CommandLine.IVersionProvider interface:

+
+
+
+
public interface IVersionProvider {
+    /**
+     * Returns version information for a command.
+     * @return version information (each string in the array is displayed on a separate line)
+     * @throws Exception an exception detailing what went wrong when obtaining version information
+     */
+    String[] getVersion() throws Exception;
+}
+
+
+
+

Version providers declared with the versionProvider attribute need to have a public no-argument constructor to be instantiated, unless a Custom Factory is installed to instantiate classes.

+
+
+

The GitHub project has a manifest file-based +example +and a build-generated version properties file-based +example version provider implementation.

+
+
+
+
+
+

10. Usage Help

+
+
+

10.1. Compact Example

+
+

A default picocli usage help message looks like this:

+
+
+
+
Usage: cat [-AbeEnstTuv] [--help] [--version] [FILE...]
+Concatenate FILE(s), or standard input, to standard output.
+      FILE                 Files whose contents to display
+  -A, --show-all           equivalent to -vET
+  -b, --number-nonblank    number nonempty output lines, overrides -n
+  -e                       equivalent to -vET
+  -E, --show-ends          display $ at end of each line
+  -n, --number             number all output lines
+  -s, --squeeze-blank      suppress repeated empty output lines
+  -t                       equivalent to -vT
+  -T, --show-tabs          display TAB characters as ^I
+  -u                       (ignored)
+  -v, --show-nonprinting   use ^ and M- notation, except for LDF and TAB
+      --help               display this help and exit
+      --version            output version information and exit
+Copyright(c) 2017
+
+
+
+

The usage help message is generated from annotation attributes, like below:

+
+
+
+
@Command(name = "cat", footer = "Copyright(c) 2017",
+         description = "Concatenate FILE(s), or standard input, to standard output.")
+class Cat {
+
+  @Parameters(paramLabel = "FILE", description = "Files whose contents to display")
+  List<File> files;
+
+  @Option(names = "--help", usageHelp = true, description = "display this help and exit")
+  boolean help;
+
+  @Option(names = "-t",                 description = "equivalent to -vT")  boolean t;
+  @Option(names = "-e",                 description = "equivalent to -vET") boolean e;
+  @Option(names = {"-A", "--show-all"}, description = "equivalent to -vET") boolean all;
+
+  // ...
+}
+
+
+
+
+

10.2. Command Name

+
+

In the above example, the program name is taken from the name attribute of the Command annotation:

+
+
+
+
@Command(name = "cat")
+
+
+
+

Without a name attribute, picocli will show a generic <main class> in the synopsis:

+
+
+
+
Usage: <main class> [-AbeEnstTuv] [--help] [--version] [FILE...]
+
+
+
+
+

10.3. Parameter Labels

+
+

Non-boolean options require a value. The usage help should explain this, and picocli shows the option parameter +in the synopsis and in the option list. By default, the field name is shown in < and > fish brackets. +Use the paramLabel attribute to display a different name. For example:

+
+
+
+
Usage: <main class> [-f=FILE] [-n=<number>] NUM <host>
+      NUM        number param
+      host       the host parameter
+  -f= FILE       a file
+  -n= <number>   a number option
+
+
+
+

Some annotated fields in the below example class have a paramLabel attribute and others don’t:

+
+
+
+
@Command()
+class ParamLabels {
+    @Option(names = "-f",    description = "a file",       paramLabel = "FILE") File f;
+    @Option(names = "-n",    description = "a number option")                   int number;
+    @Parameters(index = "0", description = "number param", paramLabel = "NUM")  int n;
+    @Parameters(index = "1", description = "the host parameter")                InetAddress host;
+}
+
+
+
+ + + + + +
+ + +For demonstration purposes the above example mixes the all-uppercase (e.g., NUM) style label and the fish bracket (e.g., <number>) style labels. For real applications, mixing these label styles should be avoided. An application should consistently use only one style. +
+
+
+
+

10.4. Unsorted Option List

+
+

By default the options list displays options in alphabetical order. Use the sortOptions = false attribute to display options in the order they are declared in your class.

+
+
+
+
@Command(sortOptions = false)
+
+
+
+
+

10.5. Reordering Options

+
+

When mixing @Option methods and @Option fields, options do not reliably appear in declaration order.

+
+
+

The @Option(order = <int>) attribute can be used to explicitly control the position in the usage help message at which the option should be shown. +Options with a lower number are shown before options with a higher number.

+
+
+
+

10.6. Abbreviated Synopsis

+
+

If a command is very complex and has many options, it is sometimes desirable to suppress details from the synopsis with the abbreviateSynopsis attribute. For example:

+
+
+
+
Usage: <main class> [OPTIONS] [<files>...]
+
+
+
+

Note that the positional parameters are not abbreviated.

+
+
+
+
@Command(abbreviateSynopsis = true)
+class App {
+    @Parameters File[] files;
+    @Option(names = {"--count", "-c"}) int count;
+    ....
+}
+
+
+
+
+

10.7. Custom Synopsis

+
+

For even more control of the synopsis, use the customSynopsis attribute to specify one ore more synopsis lines. For example:

+
+
+
+
Usage: ln [OPTION]... [-T] TARGET LINK_NAME   (1st form)
+  or:  ln [OPTION]... TARGET                  (2nd form)
+  or:  ln [OPTION]... TARGET... DIRECTORY     (3rd form)
+  or:  ln [OPTION]... -t DIRECTORY TARGET...  (4th form)
+
+
+
+

To produce a synopsis like the above, specify the literal text in the customSynopsis attribute:

+
+
+
+
@Command(synopsisHeading = "", customSynopsis = {
+        "Usage: ln [OPTION]... [-T] TARGET LINK_NAME   (1st form)",
+        "  or:  ln [OPTION]... TARGET                  (2nd form)",
+        "  or:  ln [OPTION]... TARGET... DIRECTORY     (3rd form)",
+        "  or:  ln [OPTION]... -t DIRECTORY TARGET...  (4th form)",
+})
+class Ln { ... }
+
+
+
+
+

10.8. Header and Footer

+
+

The header will be shown at the top of the usage help message (before the synopsis). The first header line is also the line shown in the subcommand list if your command has subcommands (see Usage Help for Subcommands).

+
+
+

Use the footer attribute to specify one or more lines to show below the generated usage help message.

+
+
+

Each element of the attribute String array is displayed on a separate line.

+
+
+
+

10.9. Format Specifiers

+
+

All usage help message elements can have embedded line separator (%n) format specifiers. +These are converted to the platform-specific line separator when the usage help message is printed.

+
+
+

Version help may have format specifiers that format additional arguments passed to the printVersionHelp method.

+
+
+

See the java.util.Formatter javadoc for details.

+
+
+ + + + + +
+ + +Note that to show percent '%' characters in the usage help message, they need to be escaped with another %. For example: @Parameters(description = "%%-age of the total") is rendered as %-age of the total. +
+
+
+

An alternative way to control the layout of the usage help message is that some sections (header, footer, and description) can be specified as an array of Strings, +where each element of the array is displayed on a separate line in the usage help message.

+
+
+
+

10.10. Section Headings

+
+

Section headers can be used to make usage message layout appear more spacious. The example below demonstrates the use of embedded line separator (%n) format specifiers:

+
+
+
+
@Command(name = "commit",
+        sortOptions = false,
+        headerHeading = "Usage:%n%n",
+        synopsisHeading = "%n",
+        descriptionHeading = "%nDescription:%n%n",
+        parameterListHeading = "%nParameters:%n",
+        optionListHeading = "%nOptions:%n",
+        header = "Record changes to the repository.",
+        description = "Stores the current contents of the index in a new commit " +
+                "along with a log message from the user describing the changes.")
+class GitCommit { ... }
+
+
+
+

The usage help message generated from this class is shown below in Expanded Example.

+
+
+
+

10.11. Expanded Example

+
+

The below example demonstrates what a customized usage message can look like. +Note how section headings with line separators can create a more spacious usage message, +and also that options are listed in declaration order (instead of in alphabetic order).

+
+
+
+
Usage:
+
+Record changes to the repository.
+
+git commit [-ap] [--fixup=<commit>] [--squash=<commit>] [-c=<commit>]
+           [-C=<commit>] [-F=<file>] [-m[=<msg>...]] [<files>...]
+
+Description:
+
+Stores the current contents of the index in a new commit along with a log
+message from the user describing the changes.
+
+Parameters:
+      <files>                 the files to commit
+
+Options:
+  -a, --all                   Tell the command to automatically stage files
+                                that have been modified and deleted, but new
+                                files you have not told Git about are not
+                                affected.
+  -p, --patch                 Use the interactive patch selection interface to
+                                chose which changes to commit
+  -C, --reuse-message=<commit>
+                              Take an existing commit object, and reuse the log
+                                message and the authorship information
+                                (including the timestamp) when creating the
+                                commit.
+  -c, --reedit-message=<commit>
+                              Like -C, but with -c the editor is invoked, so
+                                that the user canfurther edit the commit
+                                message.
+      --fixup=<commit>        Construct a commit message for use with rebase
+                                --autosquash.
+      --squash=<commit>        Construct a commit message for use with rebase
+                                --autosquash. The commitmessage subject line is
+                                taken from the specified commit with a prefix
+                                of "squash! ". Can be used with additional
+                                commit message options (-m/-c/-C/-F).
+  -F, --file=<file>           Take the commit message from the given file. Use
+                                - to read the message from the standard input.
+  -m, --message[=<msg>...]     Use the given <msg> as the commit message. If
+                                multiple -m options are given, their values are
+                                concatenated as separate paragraphs.
+
+
+
+

The annotated class that this usage help message is generated from is shown in Section Headings.

+
+
+
+

10.12. Option-Parameter Separators

+
+

The separator displayed between options and option parameters (= by default) +in the synopsis and the option list can be configured with the separator attribute.

+
+
+
+
@Command(separator = " ")
+
+
+
+ + + + + +
+ + +the @Command(separator = " ") annotation also affects how picocli parses the command line. See also Custom Separators. +
+
+
+
+

10.13. Hidden Options and Parameters

+
+

Options and Parameters with the hidden attribute set to true will not be shown in the usage help message. +This is useful for example when a parameter at some index is captured into multiple fields: +by default each of these fields would be shown in the usage message, which would be confusing for users.

+
+
+

For example, the all field below is annotated as hidden = true:

+
+
+
+
@Command()
+class App {
+    @Parameters(index = "0",    description = "destination host")  InetAddress host;
+    @Parameters(index = "1",    description = "destination port")  int port;
+    @Parameters(index = "2..*", description = "files to transfer") String[] files;
+
+    @Parameters(hidden = true) String[] all;
+}
+
+
+
+

The above will generate the following usage help message, where the all field is not shown:

+
+
+
+
Usage: <main class> <host> <port> [<files>...]
+      host    destination host
+      port    destination port
+      files   files to transfer
+
+
+
+
+

10.14. Show Default Values

+
+

10.14.1. ${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)
+
+
+
+
+

10.14.2. ${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
+
+
+
+
+

10.14.3. Legacy Configuration for Displaying Default Values

+
+

Prior to picocli 3.2, you need to use the @Command(showDefaultValues = true) attribute to append the default value of + all non-null options and positional parameters to the description column.

+
+
+

Additionally, picocli 3.0 introduced 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:

+
+
+
    +
  • +

    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

    +
    • +
  • +

    NEVER - don’t show the default value for this option or positional parameter, regardless what value of showDefaultValues was specified on the command

    +
    • +
  • +

    ON_DEMAND - (this is the default) only show the default value for this option or positional parameter if showDefaultValues was specified on the command

    +
    • +
+
+
+

These legacy mechanisms still work but for maximum flexibility use the variables explained above.

+
+
+
+
+

10.15. Required-Option Marker

+
+

Required options can be marked in the option list by the character specified with the requiredOptionMarker attribute. By default options are not marked because the synopsis shows users which options are required and which are optional. This feature may be useful in combination with abbreviatedSynopsis. For example:

+
+
+
+
@Command(requiredOptionMarker = '*', abbreviateSynopsis = true)
+class Example {
+    @Option(names = {"-a", "--alpha"}, description = "optional alpha") String alpha;
+    @Option(names = {"-b", "--beta"}, required = true, description = "mandatory beta") String beta;
+}
+
+
+
+

Produces the following usage help message:

+
+
+
+
Usage: <main class> [OPTIONS]
+  -a, --alpha=<alpha>   optional alpha
+* -b, --beta=<beta>     mandatory beta
+
+
+
+
+

10.16. Usage Width

+
+

The default width of the usage help message is 80 characters. +System property picocli.usage.width can be used to specify a custom width. +The minimum width that can be configured is 55 characters.

+
+
+

Picocli 3.0 also introduced programmatic API for this via the CommandLine::setUsageHelpWidth and UsageMessageSpec::width methods.

+
+
+
+
+
+

11. ANSI Colors and Styles

+
+
+

11.1. Colorized Example

+
+

Below shows the same usage help message as shown in Expanded Example, with ANSI escape codes enabled.

+
+
+

Screenshot of usage help with Ansi codes enabled

+
+
+
+

11.2. Usage Help with Styles and Colors

+
+

You can use colors and styles in the descriptions, header and footer +of the usage help message.

+
+
+

Picocli supports a custom markup notation for mixing colors and styles in text, +following a convention introduced by Jansi, where +@| starts a styled section, and |@ ends it. +Immediately following the @| is a comma-separated list of colors and styles, so @|STYLE1[,STYLE2]…​ text|@. +For example:

+
+
+
+
@Command(description = "Custom @|bold,underline styles|@ and @|fg(red) colors|@.")
+
+
+
+

Description with Ansi styles and colors

+
+ + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3. Pre-defined styles and colors that can be used in descriptions and headers using the @|STYLE1[,STYLE2]…​ text|@ notation
Pre-defined StylesPre-defined Colors

bold

black

faint

red

underline

green

italic

yellow

blink

blue

reverse

magenta

reset

cyan

white

+
+

Colors are applied as foreground colors by default. +You can set background colors by specifying bg(<color>). +For example, @|bg(red) text with red background|@. +Similarly, fg(<color>) explicitly sets the foreground color.

+
+
+

The example below shows how this markup can be used to add colors and styles to the headings and descriptions of a usage help message:

+
+
+
+
@Command(name = "commit",
+        sortOptions = false,
+        headerHeading = "@|bold,underline Usage|@:%n%n",
+        synopsisHeading = "%n",
+        descriptionHeading = "%n@|bold,underline Description|@:%n%n",
+        parameterListHeading = "%n@|bold,underline Parameters|@:%n",
+        optionListHeading = "%n@|bold,underline Options|@:%n",
+        header = "Record changes to the repository.",
+        description = "Stores the current contents of the index in a new commit " +
+                "along with a log message from the user describing the changes.")
+class GitCommit { ... }
+
+
+
+ + + + + +
+ + +Markup styles cannot be nested, for example: @|bold this @|underline that|@|@ will not work. You can achieve the same by combining styles, for example: @|bold this|@ @|bold,underline that|@ will work fine. +
+
+
+
+

11.3. More Colors

+
+

Most terminals support a 256 color indexed palette:

+
+
+
+
0x00-0x07:  standard colors (the named colors)
+0x08-0x0F:  high intensity colors (often similar to named colors + bold style)
+0x10-0xE7:  6 × 6 × 6 cube (216 colors): 16 + 36 × r + 6 × g + b (0 ≤ r, g, b ≤ 5)
+0xE8-0xFF:  grayscale from black to white in 24 steps
+
+
+
+

Colors from the 256 color palette can be specified by their index values or by their RGB components. +RGB components must be separated by a semicolon ; and each component must be between 0 and 5, inclusive.

+
+
+

For example, @|bg(0;5;0) text with red=0, green=5, blue=0 background|@, +or @|fg(46) the same color by index, as foreground color|@.

+
+
+

256 color indexed palette

+
+
+
+

11.4. Configuring Fixed Elements

+
+

11.4.1. Color Scheme

+
+

Picocli uses a default color scheme for options, parameters and commands. +There are no annotations to modify this color scheme, but it can be changed programmatically.

+
+
+

The below code snippet shows how a custom color scheme can be specified to configure the usage help message style:

+
+
+
+
// see also CommandLine.Help.defaultColorScheme()
+ColorScheme colorScheme = new ColorScheme()
+        .commands    (Style.bold, Style.underline)    // combine multiple styles
+        .options     (Style.fg_yellow)                // yellow foreground color
+        .parameters  (Style.fg_yellow)
+        .optionParams(Style.italic);
+
+CommandLine.usage(annotatedObject, System.out, colorScheme);
+...
+
+
+
+
+

11.4.2. Color Scheme Overrides

+
+

The following system properties override the color scheme styles. This allows end users to adjust for their individual terminal color setup.

+
+
+
System Properties to Override the Color Scheme
+
+
picocli.color.commands
+picocli.color.options
+picocli.color.parameters
+picocli.color.optionParams
+
+
+
+

For example:

+
+
+
+
java -Dpicocli.color.options=blink,blue -Dpicocli.color.parameters=reverse com.app.Main
+
+
+
+

System property values may specify multiple comma separated styles.

+
+
+
+
+

11.5. Supported Platforms

+
+

Picocli will only emit ANSI escape codes on supported platforms.

+
+
+

11.5.1. Unix and Linux

+
+

Most Unix and Linux platforms support ANSI colors natively. +On Windows, when picocli detects it is running under a Unix variant like Cygwin or MSYS(2) on Windows + it will display ANSI colors and styles, otherwise it will not emit ANSI codes.

+
+
+
+

11.5.2. Windows

+
+

Starting from Windows 10 the Windows console supports ANSI escape sequences, +but it’s not enabled by default. +Unless the specific software you’re using (e.g. java) enables ANSI processing by calling the SetConsoleMode API with the ENABLE_VIRTUAL_TERMINAL_PROCESSING (0x0400) flag (java doesn’t), you won’t see colors or get ANSI processing for that application. +Note that there is a registry setting to change the global default from opt in to opt out.

+
+
+

For Windows version below 10, the Windows command console doesn’t support output coloring by default. One option is to install either Cmder, ConEmu, ANSICON or Mintty (used by default in GitBash and Cygwin) to add coloring support to their Windows command console.

+
+
+

Another option is to use Jansi in your application. For example:

+
+
+
+
import org.fusesource.jansi.AnsiConsole;
+...
+public static void main(String[] args) {
+    AnsiConsole.systemInstall(); // Jansi magic
+    CommandLine.run(new WindowsJansiDemo(), System.err, Ansi.ON, args);
+    AnsiConsole.systemUninstall();
+}
+
+
+
+ + + + + +
+ + +None of the above is mandatory. If not supported, picocli will simply not emit ANSI escape codes, and everything will work without colors. +
+
+
+
+
+

11.6. Forcing ANSI On/Off

+
+

You can force picocli to either always use ANSI codes or never use ANSI codes regardless of the platform:

+
+
+
    +
  • +

    Setting system property picocli.ansi to true forces picocli to use ANSI codes; setting picocli.ansi to false forces picocli to not use ANSI codes. This may be a useful facility for users of your command line application.

    +
    • +
  • +

    You can decide to force disable or force enable ANSI escape codes programmatically by specifying Ansi.ON or Ansi.OFF when invoking CommandLine.usage. +This overrides the value of system property picocli.ansi. For example:

    +
    • +
+
+
+
+
import picocli.CommandLine.Help.Ansi;
+
+// print usage help message to STDOUT without ANSI escape codes
+CommandLine.usage(new App(), System.out, Ansi.OFF);
+
+
+
+
+

11.7. Heuristics for Enabling ANSI

+
+

Below is the exact sequence of steps picocli uses to determine whether or not to emit ANSI escape codes.

+
+
+
    +
  1. +

    If Ansi.ON or Ansi.OFF is explicitly specified, either via system property picocli.ansi or programmatically, this value is used.

    +
    2. +
  2. +

    ANSI is disabled when environment variable NO_COLOR is defined (regardless of its value).

    +
    3. +
  3. +

    ANSI is enabled when environment variable CLICOLOR_FORCE is defined and has any value other than 0 (zero).

    +
    4. +
  4. +

    ANSI is enabled when system property os.name starts with "Windows" and JAnsi Console is installed.

    +
    5. +
  5. +

    ANSI is disabled when environment variable CLICOLOR == 0.

    +
    6. +
  6. +

    ANSI is disabled when environment variable ConEmuANSI == OFF.

    +
    7. +
  7. +

    ANSI is disabled when Picocli guesses the program’s output stream is not connected to a terminal: when System.console() returns null. This check is omitted if picocli guesses the program is running in a Windows Cygwin or MSYS environment: when system property os.name starts with "Windows" and either environment variable TERM starts with xterm or environment variable OSTYPE is defined.

    +
    8. +
  8. +

    ANSI is enabled when environment variable ANSICON is defined.

    +
    9. +
  9. +

    ANSI is enabled when environment variable CLICOLOR == 1.

    +
    10. +
  10. +

    ANSI is enabled when environment variable ConEmuANSI == ON.

    +
    11. +
  11. +

    ANSI is enabled when picocli detects the program is running in a non-Windows OS (system property os.name does not start with "Windows").

    +
    12. +
  12. +

    ANSI is enabled when picocli guesses the program is running in a Cygwin or MSYS environment (either environment variable TERM starts with xterm or environment variable OSTYPE is defined).

    +
    13. +
+
+
+

ANSI escape codes are not emitted if none of the above apply.

+
+
+
+
+
+

12. Usage Help API

+
+
+

For further customization of the usage help message, picocli has a Help API. +The Help class provides a number of high-level operations, and a set of components like Layout, TextTable, IOptionRenderer, etc., that can be used to build custom help messages. +Details of the Help API are out of scope for this document, but the following sections give some idea of what is possible.

+
+
+

12.1. Reordering Sections

+
+

One thing you may want to do is reorder sections of the usage message or add custom sections.

+
+
+

Picocli 3.9 introduces new API to facilitate customizing the usage help message: +IHelpFactory allows applications to plug in Help subclasses, and +IHelpSectionRenderer allows applications to add custom sections to the usage help message, or redefine existing sections.

+
+
+

The usage help message is no longer hard-coded, but is now constructed from the section renderers defined in CommandLine::getHelpSectionMap (or UsageMessageSpec::sectionMap for a single CommandSpec). +By default this map contains the predefined section renderers:

+
+
+
+
// The default section renderers delegate to methods in Help for their implementation
+// (using Java 8 lambda notation for brevity):
+Map<String, IHelpSectionRenderer> map = new HashMap<>();
+map.put(SECTION_KEY_HEADER_HEADING,         help -> help.headerHeading());
+map.put(SECTION_KEY_HEADER,                 help -> help.header());
+
+//e.g. Usage:
+map.put(SECTION_KEY_SYNOPSIS_HEADING,       help -> help.synopsisHeading());
+
+//e.g. <cmd> [OPTIONS] <subcmd> [COMMAND-OPTIONS] [ARGUMENTS]
+map.put(SECTION_KEY_SYNOPSIS,               help -> help.synopsis(help.synopsisHeadingLength()));
+
+//e.g. %nDescription:%n%n
+map.put(SECTION_KEY_DESCRIPTION_HEADING,    help -> help.descriptionHeading());
+
+//e.g. {"Converts foos to bars.", "Use options to control conversion mode."}
+map.put(SECTION_KEY_DESCRIPTION,            help -> help.description());
+
+//e.g. %nPositional parameters:%n%n
+map.put(SECTION_KEY_PARAMETER_LIST_HEADING, help -> help.parameterListHeading());
+
+//e.g. [FILE...] the files to convert
+map.put(SECTION_KEY_PARAMETER_LIST,         help -> help.parameterList());
+
+//e.g. %nOptions:%n%n
+map.put(SECTION_KEY_OPTION_LIST_HEADING,    help -> help.optionListHeading());
+
+//e.g. -h, --help   displays this help and exits
+map.put(SECTION_KEY_OPTION_LIST,            help -> help.optionList());
+
+//e.g. %nCommands:%n%n
+map.put(SECTION_KEY_COMMAND_LIST_HEADING,   help -> help.commandListHeading());
+
+//e.g.    add       adds the frup to the frooble
+map.put(SECTION_KEY_COMMAND_LIST,           help -> help.commandList());
+map.put(SECTION_KEY_FOOTER_HEADING,         help -> help.footerHeading());
+map.put(SECTION_KEY_FOOTER,                 help -> help.footer());
+
+
+
+

Applications can add, remove or replace sections in this map. The CommandLine::getHelpSectionKeys method (or UsageMessageSpec::sectionKeys for a single CommandSpec) returns the section keys in the order that the usage help message should render the sections. The default keys are (in order):

+
+
+
    +
  1. +

    SECTION_KEY_HEADER_HEADING

    +
    2. +
  2. +

    SECTION_KEY_HEADER

    +
    3. +
  3. +

    SECTION_KEY_SYNOPSIS_HEADING

    +
    4. +
  4. +

    SECTION_KEY_SYNOPSIS

    +
    5. +
  5. +

    SECTION_KEY_DESCRIPTION_HEADING

    +
    6. +
  6. +

    SECTION_KEY_DESCRIPTION

    +
    7. +
  7. +

    SECTION_KEY_PARAMETER_LIST_HEADING

    +
    8. +
  8. +

    SECTION_KEY_PARAMETER_LIST

    +
    9. +
  9. +

    SECTION_KEY_OPTION_LIST_HEADING

    +
    10. +
  10. +

    SECTION_KEY_OPTION_LIST

    +
    11. +
  11. +

    SECTION_KEY_COMMAND_LIST_HEADING

    +
    12. +
  12. +

    SECTION_KEY_COMMAND_LIST

    +
    13. +
  13. +

    SECTION_KEY_FOOTER_HEADING

    +
    14. +
  14. +

    SECTION_KEY_FOOTER

    +
    15. +
+
+
+

This ordering may be modified with the CommandLine::setHelpSectionKeys setter method (or UsageMessageSpec::sectionKeys(List) for a single CommandSpec).

+
+
+
+

12.2. Custom Layout

+
+

Picocli also supports unconventional option list layouts. An example of an unconventional layout is the zip application, which shows multiple options per row:

+
+
+
+
CommandLine.usage(new ZipHelpDemo(), System.out);
+
+
+
+
+
Copyright (c) 1990-2008 Info-ZIP - Type 'zip "-L"' for software license.
+Zip 3.0 (July 5th 2008). Command:
+zip [-options] [-b path] [-t mmddyyyy] [-n suffixes] [zipfile list] [-xi list]
+  The default action is to add or replace zipfile entries from list, which
+  can include the special name - to compress standard input.
+  If zipfile and list are omitted, zip compresses stdin to stdout.
+  -f   freshen: only changed files  -u   update: only changed or new files
+  -d   delete entries in zipfile    -m   move into zipfile (delete OS files)
+  -r   recurse into directories     -j   junk (don't record) directory names
+  -0   store only                   -l   convert LF to CR LF (-ll CR LF to LF)
+  -1   compress faster              -9   compress better
+  -q   quiet operation              -v   verbose operation/print version info
+  -c   add one-line comments        -z   add zipfile comment
+  -@   read names from stdin        -o   make zipfile as old as latest entry
+  -x   exclude the following names  -i   include only the following names
+  -F   fix zipfile (-FF try harder) -D   do not add directory entries
+  -A   adjust self-extracting exe   -J   junk zipfile prefix (unzipsfx)
+  -T   test zipfile integrity       -X   eXclude eXtra file attributes
+  -y   store symbolic links as the link instead of the referenced file
+  -e   encrypt                      -n   don't compress these suffixes
+  -h2  show more help
+
+
+
+

This can be achieved in picocli by subclassing the Help.Layout class. +See the picocli tests for how to achieve this.

+
+
+
+
+
+

13. Subcommands

+
+
+

13.1. Registering Subcommands Programmatically

+
+

Subcommands can be registered with the CommandLine.addSubcommand method. +You pass in the name of the command and the annotated object to populate with the subcommand options. +The specified name is used by the parser to recognize subcommands in the command line arguments.

+
+
+
+
CommandLine commandLine = new CommandLine(new Git())
+        .addSubcommand("status",   new GitStatus())
+        .addSubcommand("commit",   new GitCommit())
+        .addSubcommand("add",      new GitAdd())
+        .addSubcommand("branch",   new GitBranch())
+        .addSubcommand("checkout", new GitCheckout())
+        .addSubcommand("clone",    new GitClone())
+        .addSubcommand("diff",     new GitDiff())
+        .addSubcommand("merge",    new GitMerge())
+        .addSubcommand("push",     new GitPush())
+        .addSubcommand("rebase",   new GitRebase())
+        .addSubcommand("tag",      new GitTag());
+
+
+
+

It is strongly recommended that subcommands have a @Command annotation with name and description attributes.

+
+
+

From picocli 3.1, the usage help synopsis of the subcommand shows not only the subcommand name but also the parent command name. +For example, if the git command has a commit subcommand, the usage help for the commit subcommand shows Usage: git commit <options>.

+
+
+ + + + + +
+ + +Note on custom type converters: custom type converters are registered only with the subcommands and nested +sub-subcommands that were added before the custom type was registered. +To ensure a custom type converter is available to all subcommands, register the type converter last, after +adding subcommands. +
+
+
+
+

13.2. Registering Subcommands Declaratively

+
+

From v0.9.8, picocli supports registering subcommands declaratively with the @Command annotation’s subcommands attribute.

+
+
+
+
@Command(subcommands = {
+    GitStatus.class,
+    GitCommit.class,
+    GitAdd.class,
+    GitBranch.class,
+    GitCheckout.class,
+    GitClone.class,
+    GitDiff.class,
+    GitMerge.class,
+    GitPush.class,
+    GitRebase.class,
+    GitTag.class
+})
+public class Git { ... }
+
+
+
+

The declared subcommands are automatically instantiated and added when the new CommandLine(new Git()) instance is constructed. The result is the same as if subcommands were added programmatically.

+
+
+

Subcommands referenced in a subcommands attribute must have a @Command annotation with a name attribute, or an exception is thrown from the CommandLine constructor. This name will be used both for generating usage help and for recognizing subcommands when parsing the command line.

+
+
+

Custom type converters registered on a CommandLine instance will apply to all subcommands that were declared on the main command with the subcommands annotation.

+
+
+

Subcommands referenced in a subcommands attribute need to have a public no-argument constructor to be instantiated, unless a Custom Factory is installed to instantiate classes.

+
+
+
+

13.3. Subcommand Aliases

+
+

Commands may optionally define an aliases attribute to provide alternate names for commands that will be recognized by the parser. Aliases are displayed in the default help output. For example:

+
+
+
+
@Command(name = "status", aliases = {"st"}, description = "Show the working tree status.")
+class GitStatus { ... }
+
+
+
+

Would result in this help fragment:

+
+
+
+
status, st    Show the working tree status.
+
+
+
+
+

13.4. Subcommands as Methods

+
+

From picocli 3.6 it is possible to register subcommands in a very compact manner by having a @Command class with @Command-annotated methods. The methods are automatically registered as subcommands of the @Command class.

+
+
+
+

13.5. Parsing Subcommands

+
+

For this example, we assume we created an alias git that invokes our Java application. This could also be a script or a function that calls our Java program:

+
+
+
+
alias git='java picocli.Demo$Git'
+
+
+
+

Next, we call our command with some arguments like this:

+
+
+
+
git --git-dir=/home/rpopma/picocli status -sb -uno
+
+
+
+

Where git (actually java picocli.Demo$Git) is the top-level command, followed by a global option and a subcommand status with its own options.

+
+
+

Setting up the parser and parsing the command line could look like this:

+
+
+
+
public static void main(String... args) {
+    // Set up the parser
+    CommandLine commandLine = new CommandLine(new Git());
+
+    // add subcommands programmatically (not necessary if the parent command
+    // declaratively registers the subcommands via annotation)
+    commandLine.addSubcommand("status",   new GitStatus())
+               .addSubcommand("commit",   new GitCommit())
+                ...
+
+    // Invoke the parse method to parse the arguments
+    List<CommandLine> parsed = commandLine.parse(args);
+    handleParseResult(parsed);
+}
+
+
+
+

The CommandLine.parse method returns a List with the recognized commands. The top-level command (the Java class invoked by git in this example) is always the first element in the returned list.

+
+
+

The returned List also contains all matched subcommands. Your application needs to inspect this list to see what subcommand was invoked and take appropriate action. For example:

+
+
+
+
private void handleParseResult(List<CommandLine> parsed) {
+    assert parsed.size() == 2 : "1 command and 1 subcommand found"
+
+    assert parsed.get(0).getCommand().getClass() == Git.class       : "main command"
+    assert parsed.get(1).getCommand().getClass() == GitStatus.class : "subcommand"
+
+    Git git = (Git) parsed.get(0).getCommand();
+    assert git.gitDir.equals(new File("/home/rpopma/picocli"));
+
+    GitStatus gitstatus = (GitStatus) parsed.get(1).getCommand();
+    assert  gitstatus.shortFormat              : "git status -s"
+    assert  gitstatus.branchInfo               : "git status -b"
+    assert !gitstatus.showIgnored              : "git status --showIgnored not specified"
+    assert  gitstatus.mode == GitStatusMode.no : "git status -u=no"
+}
+
+
+
+

You may be interested in the convenience methods for subcommands to reduce error handling and other boilerplate code in your application.

+
+
+
+

13.6. @ParentCommand Annotation

+
+

In command line applications with subcommands, options of the top level command are often intended as "global" options that apply to all the subcommands. Prior to picocli 2.2, subcommands had no easy way to access their parent command options unless the parent command made these values available in a global variable.

+
+
+

The @ParentCommand annotation introduced in picocli 2.2 makes it easy for subcommands to access their parent command options: subcommand fields annotated with @ParentCommand are initialized with a reference to the parent command. For example:

+
+
+
+
@Command(name = "fileutils", subcommands = List.class)
+class FileUtils {
+
+    @Option(names = {"-d", "--directory"},
+            description = "this option applies to all subcommands")
+    File baseDirectory;
+}
+
+
+
+

The above top-level command has a --directory option that applies to its subcommands. +The List subcommand can use the @ParentCommand annotation to get a reference to the parent command, so it can easily access the parent command options.

+
+
+
+
@Command(name = "list")
+class List implements Runnable {
+
+    @ParentCommand
+    private FileUtils parent; // picocli injects reference to parent command
+
+    @Option(names = {"-r", "--recursive"},
+            description = "Recursively list subdirectories")
+    private boolean recursive;
+
+    @Override
+    public void run() {
+        list(new File(parent.baseDirectory, "."));
+    }
+
+    private void list(File dir) {
+        System.out.println(dir.getAbsolutePath());
+        if (dir.isDirectory()) {
+            for (File f : dir.listFiles()) {
+                if (f.isDirectory() && recursive) {
+                    list(f);
+                } else {
+                    System.out.println(f.getAbsolutePath());
+                }
+            }
+        }
+    }
+}
+
+
+
+
+

13.7. Usage Help for Subcommands

+
+

After registering subcommands, calling the commandLine.usage method will show a usage help message that includes all registered subcommands. For example:

+
+
+
+
CommandLine commandLine = new CommandLine(new Git());
+
+// add subcommands programmatically (not necessary if the parent command
+// declaratively registers the subcommands via annotation)
+commandLine.addSubcommand("status",   new GitStatus());
+commandLine.addSubcommand("commit",   new GitCommit());
+...
+commandLine.usage(System.out);
+
+
+
+

The usage help message shows the commands in the order they were registered:

+
+
+
+
Usage: git [-hV] [--git-dir=<gitDir>]
+Git is a fast, scalable, distributed revision control system with an unusually
+rich command set that provides both high-level operations and full access to
+internals.
+      --git-dir=<gitDir>   Set the path to the repository.
+  -h, --help               Show this help message and exit.
+  -V, --version            Print version information and exit.
+
+Commands:
+
+The most commonly used git commands are:
+  help      Displays help information about the specified command
+  status    Show the working tree status.
+  commit    Record changes to the repository.
+  add       Add file contents to the index.
+  branch    List, create, or delete branches.
+  checkout  Checkout a branch or paths to the working tree.
+  clone     Clone a repository into a new directory.
+  diff      Show changes between commits, commit and working tree, etc.
+  merge     Join two or more development histories together.
+  push      Update remote refs along with associated objects.
+  rebase    Forward-port local commits to the updated upstream head.
+  tag       Create, list, delete or verify a tag object signed with GPG.
+
+
+
+

The description of each subcommand in the command list is taken from the subcommand’s first header line, or the first description line if it does not have a header defined.

+
+
+

The above usage help message is produced from the annotations on the class below:

+
+
+
+
@Command(name = "git", mixinStandardHelpOptions = true,
+        version = "subcommand demo - picocli 3.0",
+        subcommands = HelpCommand.class,
+        description = "Git is a fast, scalable, distributed revision control " +
+                      "system with an unusually rich command set that provides both " +
+                      "high-level operations and full access to internals.",
+        commandListHeading = "%nCommands:%n%nThe most commonly used git commands are:%n")
+class Git {
+
+  @Option(names = "--git-dir", description = "Set the path to the repository.")
+  private File gitDir;
+}
+
+
+
+

The above example uses the mixinStandardHelpOptions attribute to mix in +usageHelp and versionHelp options and registers the help subcommand.

+
+
+ + + + + +
+ + +Use the @Spec annotation for subcommands that need to show the usage help message explicitly. +
+
+
+

From picocli 3.1, the usage help synopsis of the subcommand shows not only the subcommand name but also the parent command name. +For example, if the git command has a commit subcommand, the usage help for the commit subcommand shows Usage: git commit <options>.

+
+
+

If a subcommand explicitly wants to show the usage help message, the @Spec annotation may be useful. +The injected CommandSpec has its parent command initialized correctly, so the usage help can show the fully qualified name of the subcommand.

+
+
+
+
@Command(name = "commit", description = "...")
+class Commit implements Runnable {
+    @Spec CommandSpec spec;
+
+    public void run() {
+        if (shouldShowHelp()) {
+            spec.commandLine().usage(System.out);
+        }
+    }
+}
+
+
+
+

For example, see Section Headings for an example subcommand (git commit), which produces the help message shown +in Expanded Example.

+
+
+
+

13.8. Hidden Subcommands

+
+

Commands with the hidden attribute set to true will not be shown in the usage help message of their parent command.

+
+
+

For example, the bar subcommand below is annotated as hidden = true:

+
+
+
+
@Command(name = "foo", description = "This is a visible subcommand")
+class Foo { }
+
+@Command(name = "bar", description = "This is a hidden subcommand", hidden = true)
+class Bar { }
+
+@Command(name = "app", subcommands = {Foo.class, Bar.class})
+class App { }
+
+
+
+

The usage help message for App looks like the below. Note that the bar subcommand is not shown:

+
+
+
+
Usage: app
+Commands:
+  foo  This is a visible subcommand
+
+
+
+
+

13.9. Help Subcommands

+
+

Commands with the helpCommand attribute set to true are treated as help commands. +When picocli encounters a help command on the command line, required options and required positional parameters of the parent command +are not validated (similar to help options).

+
+
+

See Custom Help Subcommands for more details on creating help subcommands.

+
+
+
+
@Command(helpCommand = true)
+
+
+
+
+

13.10. Nested sub-Subcommands

+
+

The specified object can be an annotated object or a +CommandLine instance with its own nested subcommands. For example:

+
+
+
+
CommandLine commandLine = new CommandLine(new MainCommand())
+    .addSubcommand("cmd1",                 new ChildCommand1())
+    .addSubcommand("cmd2",                 new ChildCommand2())
+    .addSubcommand("cmd3", new CommandLine(new ChildCommand3())
+        .addSubcommand("cmd3sub1",                 new GrandChild3Command1())
+        .addSubcommand("cmd3sub2",                 new GrandChild3Command2())
+        .addSubcommand("cmd3sub3", new CommandLine(new GrandChild3Command3())
+            .addSubcommand("cmd3sub3sub1", new GreatGrandChild3Command3_1())
+            .addSubcommand("cmd3sub3sub2", new GreatGrandChild3Command3_2())
+        )
+    );
+
+
+
+

Declaratively, subcommands can be nested by specifying the subcommands attribute on subcommand classes:

+
+
+
+
@Command(name = "main", subcommands = {
+    ChildCommand1.class,
+    ChildCommand2.class,
+    ChildCommand3.class })
+class MainCommand { }
+
+@Command(name = "cmd3", subcommands = {
+    GrandChild3Command1.class,
+    GrandChild3Command2.class,
+    GrandChild3Command3.class })
+class ChildCommand3 { }
+
+@Command(name = "cmd3sub3", subcommands = {
+    GreatGrandChild3Command3_1.class,
+    GreatGrandChild3Command3_2.class })
+class GrandChild3Command3 { }
+...
+
+
+
+

By default, the usage help message only shows the subcommands of the specified command, +and not the nested sub-subcommands. This can be customized by specifying your own IHelpSectionRenderer for the command list section. +The picocli-examples module has an example that shows how to accomplish this.

+
+
+
+
+
+

14. Reuse

+
+
+

You may find yourself defining the same options, parameters or command attributes in many command line applications. +To reduce duplication, picocli supports both subclassing and mixins as ways to reuse such options and attributes.

+
+
+

For both mechanisms, the first step is to extract these options, parameters and command attributes into a separate class. Below is an example class, ReusableOptions, that we will use in example scenarios in this chapter:

+
+
+
+
@Command(synopsisHeading      = "%nUsage:%n%n",
+         descriptionHeading   = "%nDescription:%n%n",
+         parameterListHeading = "%nParameters:%n%n",
+         optionListHeading    = "%nOptions:%n%n",
+         commandListHeading   = "%nCommands:%n%n")
+public class ReusableOptions {
+
+    @Option(names = { "-v", "--verbose" }, description = {
+        "Specify multiple -v options to increase verbosity.",
+        "For example, `-v -v -v` or `-vvv`" })
+    protected boolean[] verbosity = new boolean[0];
+}
+
+
+
+

This defines some usage help attributes that give a spacious layout, and a verbosity option that makes the operation more talkative.

+
+
+

14.1. Subclassing

+
+

One way to reuse the above option and attributes is to extend the class. Picocli will walk the class hierarchy to check for annotations, so @Options, @Parameters and @Command attributes declared on a superclass are available in all subclasses.

+
+
+

For example, all commands that extend the above sample ReusableOptions class will inherit the --verbose option, and generate a usage help message in the same spacious style. Example code:

+
+
+
+
@Command(name = "zip", description = "Example reuse by subclassing")
+public class MyCommand extends ReusableOptions { ... }
+
+
+
+
+

14.2. Mixins

+
+

Picocli 3.0 introduces the concept of "mixins". Mixins are a convenient alternative to subclassing: +picocli annotations from any class can be added to ("mixed in" with) another command. +This includes options, positional parameters, subcommands and command attributes. +Picocli mixinStandardHelpOptions internally uses a mixin.

+
+
+

A mixin is a separate class with options, positional parameters, subcommands and command attributes +that you want to reuse in other commands. +Mixins can be installed by calling the CommandLine.addMixin method with an object of this class, or annotating a field in your command with @Mixin.

+
+
+

14.2.1. Adding Mixins Programmatically

+
+

The below example shows how a mixin can be added programmatically with the CommandLine.addMixin method. +We use the sample ReusableOptions class defined above as the mixin:

+
+
+
+
CommandLine commandLine = new CommandLine(new MyCommand());
+
+ReusableOptions mixin = new ReusableOptions();
+commandline.addMixin("myMixin", mixin);
+
+
+
+

Programmatically added mixins can be accessed via the map returned by CommandLine.getMixins. Continuing from the previous example:

+
+
+
+
commandLine.parse("-vvv");
+
+// the options defined in ReusableOptions have been added to the zip command
+assert mixin == commandLine.getMixins().get("myMixin");
+assert mixin.verbosity.length == 3;
+
+
+
+
+

14.2.2. @Mixin Annotation

+
+

A command can also include a mixin by annotating a field with @Mixin. All picocli annotations found in the mixin class +are added to the command that has a field annotated with @Mixin. For example, again using the sample ReusableOptions class defined above:

+
+
+
+
@Command(name = "zip", description = "Example reuse with @Mixin annotation.")
+public class MyCommand {
+
+    // adds the options defined in ReusableOptions to this command
+    @Mixin
+    private ReusableOptions myMixin;
+    ...
+}
+
+
+
+

In addition to adding the options, subcommands and command attributes of the mixed-in object to the command, +the mixed-in object is also injected into the field annotated with @Mixin, making it trival for the command to reference the mixed-in object if necessary.

+
+
+
+
MyCommand zip = new MyCommand();
+CommandLine commandLine = new CommandLine(zip);
+commandLine.parse("-vvv");
+
+// the options defined in ReusableOptions have been added to the zip command
+assert zip.myMixin.verbosity.length == 3;
+
+
+
+

Mixins added with the @Mixin annotation can also be accessed via the map returned by CommandLine.getMixins.

+
+
+
+
+

14.3. Reuse Combinations

+
+

The above mechanisms can be combined in any way. Mixins can be nested, and there is no limitation to how deeply mixins can be nested. A mixin may also inherit options, positional parameters and command attributes from a super class.

+
+
+

An option with the same name should not be defined multiple times or a DuplicateOptionAnnotationsException is thrown during initialization. Positional parameters for the same position may be defined multiple times, they can co-exist.

+
+
+

Command attributes may be defined multiple times, but only one value is preserved. In case a command attribute is defined multiple times, the definition earlier in the following list takes priority over later in the list:

+
+
+
    +
  1. +

    @Command attributes of the command itself

    +
    2. +
  2. +

    Attributes on the @Mixin commands

    +
    3. +
  3. +

    Attributes on a @Mixin nested in a @Mixin of the command

    +
    4. +
  4. +

    Attributes on superclass of nested @Mixin

    +
    5. +
  5. +

    Attributes on superclass of @Mixin

    +
    6. +
  6. +

    Attributes on superclass of the command

    +
    7. +
  7. +

    Attributes on programmatically added mixins

    +
    8. +
+
+
+
+
+
+

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

+
+
+

15.1. Configuration

+
+

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"));
+
+
+
+
+

15.2. Example Resource Bundle

+
+

Example properties resource bundle:

+
+
+
+
# Usage Help Message Sections
+# ---------------------------
+# Numbered resource keys can be used to create multi-line sections.
+usage.headerHeading = This is my app. It does stuff. Good stuff.%n
+usage.header   = header first line
+usage.header.0 = header second line
+usage.descriptionHeading = Description:%n
+usage.description.0 = first line
+usage.description.1 = second line
+usage.description.2 = third line
+usage.synopsisHeading = Usage:\u0020
+
+# Leading whitespace is removed by default.
+# Start with \u0020 to keep the leading whitespace.
+usage.customSynopsis.0 =      Usage: ln [OPTION]... [-T] TARGET LINK_NAME   (1st form)
+usage.customSynopsis.1 = \u0020 or:  ln [OPTION]... TARGET                  (2nd form)
+usage.customSynopsis.2 = \u0020 or:  ln [OPTION]... TARGET... DIRECTORY     (3rd form)
+
+# Headings can contain the %n character to create multi-line values.
+usage.parameterListHeading = %nPositional parameters:%n
+usage.optionListHeading = %nOptions:%n
+usage.commandListHeading = %nCommands:%n
+usage.footerHeading = Powered by picocli%n
+usage.footer = footer
+
+# Option Descriptions
+# -------------------
+# Use numbered keys to create multi-line descriptions.
+help = Show this help message and exit.
+version = Print version information and exit.
+
+
+
+

For options and positional parameters, the descriptionKey can be used to localize the description.

+
+
+

When the descriptionKey is omitted, the fallback for options is any option name without the leading dashes, for example:

+
+
+
+
# For @Option(names = {"-v", "--verbose) boolean[] verbose;
+verbose = Show more detail during execution. \
+          May be specified multiple times for increasing verbosity.
+
+
+
+

For positional parameters the fallback key is the paramLabel + [ index ], for example:

+
+
+
+
# For @Parameters(paramLabel="FILES") File[];
+FILES[0..*] = The files to process.
+
+
+
+
+

15.3. Shared Resource Bundles

+
+

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 alternatively, keys can be prefixed with +command name + "." to specify different values for different commands. +The most specific key wins. For example:

+
+
+
+
jfrog.rt.usage.header = Artifactory commands
+jfrog.rt.config.usage.header = Configure Artifactory details.
+jfrog.rt.upload.usage.header = Upload files.
+
+# shared between all commands
+usage.footerHeading = Environment Variables:
+usage.footer.0 = footer line 0
+usage.footer.1 = footer line 1
+
+
+
+
+

15.4. Localizing the Built-In Help

+
+

The built-in picocli.CommandLine.HelpCommand can be localized as follows:

+
+
+
    +
  • +

    help.usage.header controls the help command summary in the subcommand list

    +
    • +
  • +

    helpCommand.help is the resource bundle key for the --help option of the help subcommand

    +
    • +
  • +

    helpCommand.command is the resource bundle key for the COMMAND positional parameter of the help subcommand

    +
    • +
+
+
+
+
# for a specific subcommand, e.g., `parent help`
+parent.help.usage.header=This is the `help` subcommand of the `parent` command
+parent.help.helpCommand.help = Specialized description of --help option of help subcommand for parent command
+parent.help.helpCommand.command = Specialized description of COMMAND parameter of help subcommand for parent command
+
+# or have one global entry for the `help` subcommand (for any and all commands)
+help.usage.header=This is the `help` subcommand
+helpCommand.help = Shared description of --help option of built-in help subcommand
+helpCommand.command = Shared description of COMMAND parameter of built-in help subcommand
+
+
+
+
+

15.5. Localizing Default Values

+
+

Options with a default value can use the ${DEFAULT-VALUE} variable in the localized option description in the resource bundle:

+
+
+
+
userName=Specify the user name. The default is ${DEFAULT-VALUE}.
+
+
+
+
+
+
+

16. Tips & Tricks

+
+
+

16.1. @Option and @Parameters Methods

+
+

From version 3.2, @Option and @Parameters 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.

+
+
+

16.1.1. 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
+
+
+
+
+

16.1.2. 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
+
+
+
+

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 {
+    private Map<String, String> properties = new LinkedHashMap<>();
+
+    @Spec private CommandSpec spec; // injected by picocli
+
+    @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));
+        }
+    }
+    // ...
+}
+
+
+
+
+
+

16.2. @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.

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

16.2.1. Subcommand Methods

+
+

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

+
+
+
+
@Command(name = "git", mixinStandardHelpOptions = true,
+         resourceBundle = "Git_Messages", 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.

+
+
+
+

16.2.2. Description Text in ResourceBundle

+
+

The usage help of the above git commit example command is very minimal:

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

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

16.2.3. Mixin Support in @Command Methods

+
+

From picocli 3.8, @Command methods accept @Mixin parameters. +All options and positional parameters defined in the mixin class are added to the command.

+
+
+

Example:

+
+
+
+
class CommonParams {
+    @Option(names = "-x") int x;
+    @Option(names = "-y") int y;
+}
+
+class App {
+    @Command
+    public void doit(@Mixin CommonParams params, @Option(names = "-z") int z) {}
+}
+
+
+
+

In the above example, the -x and -y options are added to the other options of the doit command.

+
+
+
+
+

16.3. Less Boilerplate

+
+

You can omit some of the boilerplate code from your application when the annotated object implements Runnable or Callable:

+
+
+
Before
+
+
Callable<Object> callable = new MyCallable();
+CommandLine cmd = new CommandLine(callable);
+try {
+    cmd.parse(args);
+    if (cmd.isUsageHelpRequested()) {
+        cmd.usage(System.out);
+        return null;
+    } else if (cmd.isVersionHelpRequested()) {
+        cmd.printVersionHelp(System.out);
+        return null;
+    }
+    return callable.call();
+} catch (ParameterException ex) {
+    System.err.println(ex.getMessage());
+    if (!UnmatchedArgumentException.printSuggestions(ex, System.err)) {
+        ex.getCommandLine().usage(System.err);
+    }
+    return null;
+} catch (Exception ex) {
+    throw new ExecutionException(cmd, "Error while calling " + callable, ex);
+}
+
+
+
+
After
+
+
Object result = CommandLine.call(new MyCallable(), args);
+
+
+
+

The CommandLine.call method returns the result of the Callable, or null if the command line options were invalid. An error message and a usage help message are printed when the command line options were invalid. Exceptions thrown from the Callable.call method are caught, wrapped in an ExecutionException and rethrown.

+
+
+

When the annotated object implements Runnable, use the run method. For example:

+
+
+
+
CommandLine.run(new MyRunnable(), args);
+
+
+
+

If the command class has subcommands, the CommandLine::call and CommandLine::run convenience methods will execute the most specific subcommand on the command line. For example:

+
+
+
+
<command> -g global_option subcommand -x -y -z subsubcommand param1 param2
+
+
+
+

In the above example, the subsubcommand is the most specific subcommand, and only the Runnable or Callable associated with that subcommand will be executed by the CommandLine::call and CommandLine::run convenience methods.

+
+
+
+

16.4. Convenience Methods for Subcommands

+
+

Picocli v2.0 introduced the CommandLine::parseWithHandler and CommandLine::parseWithHandlers convenience methods. +These methods are intended to offer the same ease of use as the run and call methods, but with more flexibility and better support for nested subcommands.

+
+
+

For example:

+
+
+
+
CommandLine cmd = new CommandLine(MyTopLevelCommand())
+        .addSubcommand("status",   new GitStatus())
+        .addSubcommand("commit",   new GitCommit())
+        .addSubcommand("add",      new GitAdd());
+List<Object> result = cmd.parseWithHandler(new RunAll(), args);
+
+
+
+

The CommandLine::parseWithHandler method will take care of the following:

+
+
+
    +
  • +

    parse the specified command line arguments

    +
    • +
  • +

    if the input was invalid, delegate to DefaultExceptionHandler, which will print the error message followed by the usage help message

    +
    • +
  • +

    otherwise, if the command line arguments were parsed successfully, let the specified IParseResultHandler2 handle the parse result

    +
    • +
+
+
+

Picocli provides some default IParseResultHandler2 implementations for common tasks:

+
+
+
    +
  • +

    the RunLast handler prints help if requested, and otherwise gets the last specified command or subcommand and tries to execute it as a Runnable or Callable

    +
    • +
  • +

    the RunFirst handler prints help if requested, and otherwise executes the top-level command as a Runnable or Callable

    +
    • +
  • +

    the RunAll handler prints help if requested, and otherwise executes all commands and subcommands that the user specified on the command line as Runnable or Callable tasks

    +
    • +
+
+
+
+

16.5. Stdout or Stderr

+
+

From picocli v3.0, the run, call and invoke 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),
+                CommandLine.defaultExceptionHandler().useErr(myErr).useAnsi(Help.Ansi.OFF),
+                args);
+    }
+}
+
+
+
+
+

16.6. Exit Code

+
+

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),
+                CommandLine.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.

+
+
+
+

16.7. @Spec Annotation

+
+

Picocli 3.2 introduces a @Spec annotation for injecting 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
+   }
+}
+
+
+
+
+

16.8. Custom Factory

+
+

Declaratively registered subcommands, type converters and version providers must be instantiated somehow. From picocli 2.2, a custom factory can be specified when constructing a CommandLine instance. This allows full control over object creation and opens possibilities for Inversion of Control and Dependency Injection (see next section). For example:

+
+
+
+
IFactory myFactory = getCustomFactory();
+CommandLine cmdLine = new CommandLine(new Git(), myFactory);
+
+
+
+

Custom factories need to implement the picocli.CommandLine.IFactory interface:

+
+
+
+
public interface IFactory {
+    /**
+     * Creates and returns an instance of the specified class.
+     * @param cls the class to instantiate
+     * @param <K> the type to instantiate
+     * @return the new instance
+     * @throws Exception an exception detailing what went wrong when creating the instance
+     */
+    <K> K create(Class<K> clazz) throws Exception;
+}
+
+
+
+

If no factory is specified, a default factory is used. The default factory requires that the classes to instantiate have a public no-argument constructor: it instantiates the class by calling first calling clazz.newInstance(), and if that fails, clazz.getDeclaredConstructor().newInstance().

+
+
+
+

16.9. Boolean Options with Parameters

+
+

By default the value of a boolean field is toggled to its logical negative when the field’s option is specified on the command line.

+
+
+

It is possible to let end users explicitly specify "true" or "false" as a parameter for a boolean option by defining an explicit Arity attribute. A boolean option with arity = "0..1" accepts zero to one parameters, arity = "1" means the option must have one parameter. For example:

+
+
+
+
class BooleanOptionWithParameters {
+    @Option(names = "-x", arity = "1", description = "1 mandatory parameter")
+    boolean x;
+
+    @Option(names = "-y", arity = "0..1", description = "min 0 and max 1 parameter")
+    boolean y;
+}
+
+
+
+

The following ways to invoke the program will be accepted (values are not case sensitive):

+
+
+
+
<command> -x true
+<command> -x FALSE
+<command> -x TRUE -y
+<command> -x True -y False
+
+
+
+

But trying to specify the -x option without a parameter, or with a value other than "true" or "false" (case insensitive) will result in a ParameterException.

+
+
+
+

16.10. Hexadecimal Values

+
+

Numeric values are interpreted as decimal numbers by default. If you want picocli to be more flexible, you can +register a custom type converter that delegates to the decode method to convert strings to numbers.

+
+
+ + + + + +
+ + +The decode method looks at the prefix to determine the radix, so numbers +starting with 0x, 0X or # are interpreted as hexadecimal numbers, numbers starting with 0 are interpreted +as octal numbers, and otherwise the number is interpreted as a decimal number. +
+
+
+

Java 8-style lambdas:

+
+
+
+
new CommandLine(obj)
+        .registerConverter(Byte.class,    s -> Byte::decode)
+        .registerConverter(Byte.TYPE,     s -> Byte::decode)
+        .registerConverter(Short.class,   s -> Short::decode)
+        .registerConverter(Short.TYPE,    s -> Short::decode)
+        .registerConverter(Integer.class, s -> Integer::decode)
+        .registerConverter(Integer.TYPE,  s -> Integer::decode)
+        .registerConverter(Long.class,    s -> Long::decode)
+        .registerConverter(Long.TYPE,     s -> Long::decode);
+
+
+
+

In Java 5:

+
+
+
+
ITypeConverter<Integer> intConverter = new ITypeConverter<Integer>() {
+    public Integer convert(String s) {
+        return Integer.decode(s);
+    }
+};
+commandLine.registerConverter(Integer.class, intConverter);
+commandLine.registerConverter(Integer.TYPE,  intConverter);
+...
+
+
+
+
+

16.11. Option-Parameter Separators

+
+

16.11.1. Default Separators

+
+

Options may take an option parameter (also called option-argument). +For POSIX-style short options (like -f or -c), the option parameter may be attached to the option, +or it may be separated by a space or the separator string (= by default). +That is, all of the below are equivalent:

+
+
+
+
<command> -foutput.txt
+<command> -f output.txt
+<command> -f=output.txt
+
+
+
+

Long option names (like --file) must be separated from their option parameter by a space or the +separator string (= by default). That is, the first two below examples are valid but the last example is invalid:

+
+
+
+
// valid (separator between --file and its parameter)
+<command> --file output.txt
+<command> --file=output.txt
+
+// invalid (picocli will not recognize the --file option when attached to its parameter)
+<command> --fileoutput.txt
+
+
+
+
+

16.11.2. Custom Separators

+
+

The separator string can be customized programmatically or declaratively.

+
+
+

Use the separator attribute of the @Command annotation to declaratively set a separator string:

+
+
+
+
@Command(separator = ":")  // declaratively set a separator
+class OptionArg {
+    @Option(names = { "-f", "--file" }) String file;
+}
+
+
+
+
+
OptionArg optionArg = CommandLine.populateCommand(new OptionArg(), "-f:output.txt");
+assert optionArg.file.equals("output.txt");
+
+
+
+

Alternatively, the separator string can be changed programmatically with the CommandLine.setSeparator(String separator) method. +For example:

+
+
+
+
OptionArg optionArg     = new OptionArg();
+CommandLine commandLine = new CommandLine(optionArg);
+
+commandLine.setSeparator(":"); // programmatically set a separator
+commandLine.parse("-f:output.txt");
+assert optionArg.file.equals("output.txt");
+
+
+
+
+
+

16.12. Best Practices for Command Line Interfaces

+
+

When designing your command line application, +the GNU recommendations for command line interfaces and POSIX Utility Guidelines may be useful.

+
+
+

Generally, many applications use options for optional values and parameters for mandatory values. +However, picocli lets you make options required if you want to, see Required Arguments.

+
+
+
+
+
+

17. Dependency Injection

+
+
+

17.1. Guice Example

+
+

The below example shows how to create a custom 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;
+
+    public static void main(String[] args) {
+        CommandLine.run(Runnable.class, new GuiceFactory(), args);
+    }
+
+    @Override
+    public void run() {
+        assert list instanceof java.util.LinkedList;
+    }
+}
+
+
+
+
+

17.2. Spring Boot Example

+
+

A custom factory is not always necessary. +The below example shows how to use picocli with Spring Boot:

+
+
+
+
import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import picocli.CommandLine;
+
+@SpringBootApplication
+public class MySpringBootApp implements CommandLineRunner {
+
+    @Autowired
+    private MyCommand myCommand;
+
+    public static void main(String[] args) {
+        // let Spring instantiate and inject dependencies
+        SpringApplication.run(MySpringBootApp.class, args);
+    }
+
+    @Override
+    public void run(String... args) {
+        // let picocli parse command line args and run the business logic
+        CommandLine.call(myCommand, args);
+    }
+}
+
+
+
+ + + + + +
+ + +
+

It may be a good idea to define an option --spring.config.location in your command. +Spring Boot allows end users to specify the spring.config.location Spring environment property as a command line option to specify an alternative location for the application.properties file. +Defining this option prevents picocli from throwing an UnmatchedArgumentException ("Unknown option") when it sees an option it cannot match. +You can make it a hidden option so it is not shown in the usage help message, or add a description that explains its meaning.

+
+
+

Alternatively, you can define an unmatched field to capture all unknown options (and positional parameters):

+
+
+
+
@Unmatched List<String> unmatched;
+
+
+
+
+
+

When your command is annotated with @org.springframework.stereotype.Component Spring can autodetect it for dependency injection. +The business logic of your command looks like any other picocli command with options and parameters.

+
+
+
+
import org.springframework.stereotype.Component;
+import org.springframework.beans.factory.annotation.Autowired;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+import java.util.concurrent.Callable;
+
+@Component
+@Command(name = "myCommand")
+public class MyCommand implements Callable<Void> {
+
+    @Autowired
+    private SomeService someService;
+
+    // Prevent "Unknown option" error when users use
+    // the Spring Boot parameter 'spring.config.location' to specify
+    // an alternative location for the application.properties file.
+    @Option(names = "--spring.config.location", hidden = true)
+    private String springConfigLocation;
+
+    @Option(names = { "-x", "--option" }, description = "example option")
+    private boolean flag;
+
+    public Void call() throws Exception {
+        // business logic here
+        return null;
+    }
+}
+
+
+
+
+

17.3. Micronaut Example

+
+

The Micronaut microservices framework provides built-in support for picocli with its PicocliRunner class.

+
+
+
+
import io.micronaut.configuration.picocli.PicocliRunner;
+import io.micronaut.http.annotation.*;
+import io.micronaut.http.client.*;
+import javax.inject.Inject;
+
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+
+@Command(name = "myMicronautApp")
+public class MyMicronautApp implements Runnable {
+
+    @Client("https://api.github.com")
+    @Inject RxHttpClient client;
+
+    @Option(names = {"-x", "--option"}, description = "example option")
+    boolean flag;
+
+    public static void main(String[] args) throws Exception {
+        // let Micronaut instantiate and inject services
+        PicocliRunner.run(MyMicronautApp.class, args);
+    }
+
+    public void run() {
+        // business logic here
+    }
+}
+
+
+
+
+
+
+

18. Tracing

+
+
+

Picocli v1.0 introduced support for parser tracing to facilitate troubleshooting.

+
+
+

System property picocli.trace controls the trace level. Supported levels are OFF, WARN, INFO, and DEBUG. The default trace level is WARN.

+
+
+

Specifying system property -Dpicocli.trace without a value will set the trace level to INFO.

+
+
+
    +
  • +

    DEBUG: Shows details of the decisions made by the parser during command line parsing.

    +
    • +
  • +

    INFO: Shows a high-level overview of what happens during command line parsing.

    +
    • +
  • +

    WARN: The default. Shows warnings instead of errors when lenient parsing is enabled: +when single-value options were specified multiple times (and CommandLine.overwrittenOptionsAllowed is true), +or when command line arguments could not be matched as an option or positional parameter +(and CommandLine.unmatchedArgumentsAllowed is true).

    +
    • +
  • +

    OFF: Suppresses all tracing including warnings.

    +
    • +
+
+
+

Example:

+
+
+
+
# create a custom 'git' command that invokes picocli.Demo$Git with tracing switched on
+alias git='java -Dpicocli.trace -cp picocli-all.jar picocli.Demo$Git'
+
+# invoke our command with some parameters
+git --git-dir=/home/rpopma/picocli commit -m "Fixed typos" -- src1.java src2.java src3.java
+
+# remove our 'git' pseudonym from the current shell environment
+unalias git
+
+
+
+

Output:

+
+
+
+
[picocli INFO] Parsing 8 command line args [--git-dir=/home/rpopma/picocli, commit, -m, "Fixed typos", --, src1.java, src2.java, src3.java]
+[picocli INFO] Setting File field 'Git.gitDir' to '\home\rpopma\picocli' for option --git-dir
+[picocli INFO] Adding [Fixed typos] to List<String> field 'GitCommit.message' for option -m
+[picocli INFO] Found end-of-options delimiter '--'. Treating remainder as positional parameters.
+[picocli INFO] Adding [src1.java] to List<String> field 'GitCommit.files' for args[0..*]
+[picocli INFO] Adding [src2.java] to List<String> field 'GitCommit.files' for args[0..*]
+[picocli INFO] Adding [src3.java] to List<String> field 'GitCommit.files' for args[0..*]
+
+
+
+
+
+

19. TAB Autocomplete

+
+
+

Picocli-based applications can now have command line completion in Bash or Zsh Unix shells. +See the Autocomplete for Java Command Line Applications manual for how to generate an autocompletion script tailored to your application.

+
+
+
+
+

20. Picocli in Other Languages

+
+
+

Picocli may be used in other JVM languages that support annotations.

+
+
+

20.1. Groovy

+
+

In Groovy, use [ and ] to surround array values, instead of the { and } used in Java.

+
+
+
+
@Command(name = "MyApp", version = "Groovy picocli v3.0 demo",
+         mixinStandardHelpOptions = true, // add --help and --version options
+         description = "@|bold Groovy|@ @|underline picocli|@ example")
+class MyApp implements Runnable {
+
+    @Option(names = ["-c", "--count"], description = "number of repetitions")
+    int count = 1
+
+    void run() {
+        count.times {
+            println("hello world $it...")
+        }
+    }
+    static void main(String[] args) {
+        CommandLine.run(new MayApp(), args)
+    }
+}
+
+
+
+

Picocli 2.0 introduced 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.

+
+
+
+
@Grab('info.picocli:picocli:3.9.5')
+@Command(name = "myScript",
+        mixinStandardHelpOptions = true, // add --help and --version options
+        description = "@|bold Groovy script|@ @|underline picocli|@ example")
+@picocli.groovy.PicocliScript
+import groovy.transform.Field
+import static picocli.CommandLine.*
+
+@Option(names = ["-c", "--count"], description = "number of repetitions")
+@Field int count = 1;
+
+// PicocliBaseScript prints usage help or version if requested by the user
+
+count.times {
+   println "hi"
+}
+// the CommandLine that parsed the args is available as a property
+assert this.commandLine.commandName == "myScript"
+
+
+
+ + + + + +
+ + +When using a Groovy version older than 2.4.7, use this workaround for the Grape bug that causes this error: +java.lang.ClassNotFoundException: # Licensed to the Apache Software Foundation (ASF) under one or more. +
+
+
+
+
@Grab('info.picocli:picocli:3.9.5')
+@GrabExclude('org.codehaus.groovy:groovy-all') // work around GROOVY-7613
+...
+
+
+
+
+

20.2. Kotlin

+
+

Kotlin 1.2 (released Nov 28, 2017) officially supports array literals in annotations, allowing a more compact notation:

+
+
+
+
@Command(name = "MyApp", version = ["Kotlin picocli v3.0 demo"],
+        mixinStandardHelpOptions = true, // add --help and --version options
+        description = ["@|bold Kotlin|@ @|underline picocli|@ example"])
+class MyApp : Runnable {
+
+    @Option(names = ["-c", "--count"], description = ["number of repetitions"])
+    private var count: Int = 1
+
+    override fun run() {
+        for (i in 0 until count) {
+            println("hello world $i...")
+        }
+    }
+}
+fun main(args: Array<String>) = CommandLine.run(MyApp(), *args)
+
+
+
+

When specify a class as an argument of an annotation, use a Kotlin class (KClass). +The Kotlin compiler will automatically convert it to a Java class, so that the Java code will be able to see the annotations and arguments normally.

+
+
+
+
@Command(name = "top", // ...
+        subcommands = [SubCmd::class, picocli.CommandLine.HelpCommand::class])
+class TopCmd { // ...
+}
+
+@Command(name = "sub", /* ... */)
+class SubCmd { // ...
+}
+
+
+
+

Kotlin versions prior to 1.2 did not allow the array literal syntax in annotations, so with older versions of Kotlin you will have to write arrayOf(…​) for the names, description and type attributes.

+
+
+
+
@Command(name = "MyApp", version = arrayOf("picocli demo for Kotlin v1.0 and Kotlin v1.1"),
+        mixinStandardHelpOptions = true, // add --help and --version options
+        description = arrayOf("@|bold Kotlin|@ @|underline picocli|@ example"))
+class MyApp : Runnable {
+
+    @Option(names = arrayOf("-c", "--count"),
+            description = arrayOf("number of repetitions"))
+    private var count: Int = 1
+
+    override fun run() {
+        for (i in 0 until count) {
+            println("hello world $i...")
+        }
+    }
+}
+fun main(args: Array<String>) = CommandLine.run(MyApp(), *args)
+
+
+
+
+

20.3. Scala

+
+

Scala does not allow specifying array annotation attribute as a single value, +so be aware that you will have to write Array(…​) for the names, description and type attributes.

+
+
+
+
@Command(name = "MyApp", version = Array("Scala picocli v3.0 demo"),
+    mixinStandardHelpOptions = true, // add --help and --version options
+    description = Array("@|bold Scala|@ @|underline picocli|@ example"))
+class MyApp extends Runnable {
+
+    @Option(names = Array("-c", "--count"),
+            description = Array("number of repetitions"))
+    private var count: Int = 1
+
+    def run() : Unit = {
+        for (i <- 0 until count) {
+            println(s"hello world $i...")
+        }
+    }
+}
+object MyApp {
+    def main(args: Array[String]) {
+        CommandLine.run(new MyApp(), args: _*)
+    }
+}
+
+
+
+
+
+
+

21. API Javadoc

+
+
+

Picocli API Javadoc can be found here.

+
+
+
+
+

22. GitHub Project

+
+
+

The GitHub project has the source code, tests, build scripts, etc.

+
+
+

Star and/or fork this project on GitHub if you like it!

+
+
+
+
+

23. Issue Tracker

+
+
+

The GitHub Issue Tracker can be used to report bugs or request features. There is also a Mailing List, and for questions where the user community may know the answer, StackOverflow is both a good resource and a great way to build an online knowledge base.

+
+
+
+
+

24. Mailing List

+
+
+

Join the picocli Google group if you are interested in discussing anything picocli-related and receiving announcements on new releases.

+
+
+
+
+

25. License

+
+
+

Picocli is licensed under the Apache License 2.0.

+
+
+
+
+

26. Releases

+
+
+

Previous versions are available from the GitHub project Releases.

+
+
+
+
+

27. Download

+
+
+

You can add picocli as an external dependency to your project, or you can include it as source. +See the source code below. Copy and paste it into a file called CommandLine.java, add it to your project, and enjoy!

+
+
+

27.1. Gradle

+
+
+
compile 'info.picocli:picocli:3.9.5'
+
+
+
+
+

27.2. Maven

+
+
+
<dependency>
+  <groupId>info.picocli</groupId>
+  <artifactId>picocli</artifactId>
+  <version>3.9.5</version>
+</dependency>
+
+
+
+
+

27.3. Scala SBT

+
+
+
libraryDependencies += "info.picocli" % "picocli" % "3.9.5"
+
+
+
+
+

27.4. Ivy

+
+
+
<dependency org="info.picocli" name="picocli" rev="3.9.5" />
+
+
+
+
+

27.5. Source

+
+

Picocli has only one source file: CommandLine.java. +This facilitates including it in your project in source form to avoid having an external dependency on picocli.

+
+
+
+
+
+ + + \ No newline at end of file diff --git a/docs/man/3.x/migrating-from-commons-cli.html b/docs/man/3.x/migrating-from-commons-cli.html new file mode 100644 index 000000000..c94317410 --- /dev/null +++ b/docs/man/3.x/migrating-from-commons-cli.html @@ -0,0 +1,961 @@ + + + + + + + + +Migrating from Commons CLI to picocli + + + + + + + +
+
+
+
+

Apache Commons CLI, initially released in 2002, is perhaps the most widely used java command line parser, but its API shows its age. +Applications looking for a modern approach with a minimum of boilerplate code may be interested in picocli. Why is it worth the trouble to migrate, and how do you migrate your Commons CLI-based application to picocli? Picocli offers a fluent API with strong typing, usage help with ANSI colors, autocompletion and a host of other features. Let’s take a look using Checkstyle as an example.

+
+
+
+
+

Why Migrate?

+
+
+

Is migrating from Commons CLI to picocli worth the trouble? What is the benefit of moving from one command line parser to another? Is this more than just redecorating the living room of our application?

+
+
+

End User Experience

+
+

pexels photo 1210532

+
+
+

What are the benefits for end users?

+
+
+

Command line completion. Picocli-based applications can have command line completion in bash and zsh shells, as well as in JLine-based interactive shell applications.

+
+
+

Beautiful, highly readable usage help messages. The usage help generated by Commons CLI is a bit minimalistic. Out of the box, picocli generates help that uses ANSI styles and colors for contrast to emphasize important information like commands, options, and parameters. The help message layout is easy to customize using the annotations. Additionally, there is a Help API in case you want something different. See the picocli README for some example screenshots.

+
+
+

Support for very large command lines via @-files, or "argument files". Sometimes users need to specify command lines that are longer than supported by the operating system or the shell. When picocli encounters an argument beginning with the character @, it expands the contents of that file into the argument list. This allows applications to handle command lines of arbitrary length.

+
+
+
+

Developer Experience

+
+

empower developers

+
+
+

What are the benefits for you as developer?

+
+
+

Generally a picocli application will have a lot less code than the Commons CLI equivalent. The picocli annotations allow applications to define options and positional parameters in a declarative way where all information is in one place. Also, picocli offers a number of conveniences like type conversion and automatic help that take care of some mechanics so the application can focus more on the business logic. The rest of this article will show this in more detail.

+
+
+

Documentation: picocli has an extensive user manual and detailed javadoc.

+
+
+

Troubleshooting. Picocli has a built-in tracing facility to facilitate troubleshooting. End users can use system property picocli.trace to control the trace level. Supported levels are OFF, WARN, INFO, and DEBUG. The default trace level is WARN.

+
+
+
+

Future Expansion

+
+

seeing the future

+
+
+

Finally, other than the immediate pay-off, are there any future benefits to be gained by migrating from Commons CLI to picocli?

+
+
+

Picocli has a lot of advanced features. Your application may not use these features yet, but if you want to expand your application in the future, picocli has support for nested subcommands (and sub-subcommands to any depth), mixins for reuse, can easily integrate with Dependency Injection containers, and a growing tool framework to generate source code, documentation and configuration files from a picocli CommandSpec model.

+
+
+

Finally, picocli is actively maintained, whereas Commons CLI seems to be near-dormant with 6 releases in 16 years.

+
+
+
+
+
+

An Example Migration: CheckStyle

+
+
+

checkstyle logo 260x50

+
+
+

A command line application needs to do three things:

+
+
+
    +
  1. +

    Define the supported options

    +
    2. +
  2. +

    Parse the command line arguments

    +
    3. +
  3. +

    Process the results

    +
    4. +
+
+
+

Let’s compare how this is done in Commons CLI and in picocli, using CheckStyle’s com.puppycrawl.tools.checkstyle.Main command line utility as an example.

+
+
+

The full source code before and after the migration is on GitHub.

+
+
+

Defining Options and Positional Parameters

+
+

Defining Options with Commons CLI

+
+

Commons CLI has multiple ways to define options: Options.addOption, constructing a new Options(…​) and invoking methods on this object, the deprecated OptionBuilder class, and the recommended Option.Builder class.

+
+
+

The Checkstyle Main class uses the Options.addOption method. It starts by defining a number of constants for the option names:

+
+
+
+
/** Name for the option 's'. */
+private static final String OPTION_S_NAME = "s";
+
+/** Name for the option 't'. */
+private static final String OPTION_T_NAME = "t";
+
+/** Name for the option '--tree'. */
+private static final String OPTION_TREE_NAME = "tree";
+
+... // and more. Checkstyle Main has 26 options in total.
+
+
+
+

The Main.buildOptions method uses these constants to construct and return a Commons CLI Options object that defines the supported options:

+
+
+
+
private static Options buildOptions() {
+    final Options options = new Options();
+    options.addOption(OPTION_C_NAME, true, "Sets the check configuration file to use.");
+    options.addOption(OPTION_O_NAME, true, "Sets the output file. Defaults to stdout");
+    ...
+    options.addOption(OPTION_V_NAME, false, "Print product version and exit");
+    options.addOption(OPTION_T_NAME, OPTION_TREE_NAME, false,
+            "Print Abstract Syntax Tree(AST) of the file");
+    ...
+    return options;
+}
+
+
+
+
+

Defining Options with Picocli

+
+

In picocli you can define supported options either programmatically with builders, similar to the Commons CLI approach, or declaratively with annotations.

+
+
+

Picocli’s programmatic API may be useful for dynamic applications where not all options are known in advance. If you’re interested in the programmatic approach, take a look at the CommandSpec, OptionSpec and PositionalParamSpec classes. See also Programmatic API for more detail.

+
+
+

In this article we will use the picocli annotations. For the CheckStyle example, this would look something like the below:

+
+
+
+
@Option(names = "-c", description = "Sets the check configuration file to use.")
+private File configurationFile;
+
+@Option(names = "-o", description = "Sets the output file. Defaults to stdout")
+private File outputFile;
+
+@Option(names = "-v", versionHelp = true, description = "Print product version and exit")
+private boolean versionHelpRequested;
+
+@Option(names = {"-t", "--tree"}, description = "Print Abstract Syntax Tree(AST) of the file")
+private boolean printAST;
+
+
+
+
+

Comparison

+
+
Declarative
+
+

declare

+
+
+

With Commons CLI, you build a specification by calling a method with String values. One drawback of an API like this is that good style compels client code to define constants to avoid "magic values", like the Checkstyle Main class dutifully does.

+
+
+

With picocli, all information is in one place. Annotations only accept String literals, so definition and usage are automatically placed together without the need to declare constants. This results in cleaner and less code.

+
+
+
+
Strongly Typed
+
+
+Type +
+
+
+

Commons CLI uses a boolean flag to denote whether the option takes an argument or not.

+
+
+

Picocli lets you use types directly. Based on the type, picocli "knows" how many arguments the option needs: boolean fields don’t have an argument, Collection, Map and array fields can have zero to any number of arguments, and any other type means the options takes a single argument. This can be customized (see arity) but most of the time the default is good enough.

+
+
+

Picocli encourages you to use enum types for options or positional parameters with a limited set of valid values. Not only will picocli validate the input for you, you can also show all values in the usage help message with @Option(description = "Valid values: ${COMPLETION-CANDIDATES}"). Enums also allow command line completion to suggest completion candidates for the values of the option.

+
+
+
+
Less Code
+
+

convert

+
+
+

Picocli converts the option parameter String value to the field type. Not only does it save the application from doing this work, it also provides some minimal validation on the user input. If the conversion fails, a ParameterException is thrown with a user-friendly error message.

+
+
+

Let’s look at an example to see how useful this is. The Checkstyle Main class defines a -x, --exclude-regexp option that allows uses to specify a number of regular expressions for directories to exclude.

+
+
+

With Commons CLI, you need to convert the String values that were matched on the command line to java.util.regex.Pattern objects in the application:

+
+
+
+
/**
+ * Gets the list of exclusions from the parse results.
+ * @param commandLine object representing the result of parsing the command line
+ * @return List of exclusion patterns.
+ */
+private static List<Pattern> getExclusions(CommandLine commandLine) {
+    final List<Pattern> result = new ArrayList<>();
+
+    if (commandLine.hasOption(OPTION_X_NAME)) {
+        for (String value : commandLine.getOptionValues(OPTION_X_NAME)) {
+            result.add(Pattern.compile(value));
+        }
+    }
+    return result;
+}
+
+
+
+

By contract, in picocli you would simply declare the option on a List<Pattern> (or a Pattern[] array) field. +Since picocli has a built-in converter for java.util.regex.Pattern, all that is needed is to declare the option. The conversion code goes away completely. Picocli will instantiate and populate the list if one or more -x options are specified on the command line.

+
+
+
+
/** Option that allows users to specify a regex of paths to exclude. */
+@Option(names = {"-x", "--exclude-regexp"},
+        description = "Regular expression of directory to exclude from CheckStyle")
+private List<Pattern> excludeRegex;
+
+
+
+
+
Option Names
+
+

name

+
+
+

Commons CLI supports "short" and "long" options, like -t and --tree. This is not always what you want.

+
+
+

Picocli lets an option have any number of names, with any prefix. For example, this would be perfectly fine in picocli:

+
+
+
+
@Option(names = {"-cp", "-classpath", "--class-path"})
+
+
+
+
+
Positional Parameters
+
+

location

+
+
+

In Commons CLI you cannot define positional parameters up front. Instead, its CommandLine parse result class has a method getArgs that returns the positional parameters as an array of Strings. The Checkstyle Main class uses this to create the list of File objects to process.

+
+
+

In picocli, positional parameters are first-class citizens, like named options. Not only can they be strongly typed, parameters at different positions can have different types, and each will have a separate entry and description listed in the usage help message.

+
+
+

For example, the Checkstyle Main class needs a list of files to process, so we declare a field and annotate it with @Parameters. The arity = "1..*" attribute means that at least one file must be specified, or picocli will show an error message about the missing argument.

+
+
+
+
@Parameters(paramLabel = "file", arity = "1..*", description = "The files to process")
+private List<File> filesToProcess;
+
+
+
+
+
Help Options
+
+

AskingForHelp

+
+
+

It is surprisingly difficult in Commons CLI to create an application with a required option that also has a --help option. Commons CLI has no special treatment for help options and will complain about the missing required option when the user specifies <command> --help.

+
+
+

Picocli has built-in support for common (and custom) help options.

+
+
+
+
+
+

Parsing the Command Line Arguments

+
+

pipeline

+
+
+

Commons CLI has a CommandLineParser interface with a parse method that returns a CommandLine representing the parse result. The application then calls CommandLine.hasOption(String) to see if a flag was set, or CommandLine.getOptionValue(String) to get the option value.

+
+
+

Picocli populates the annotated fields as it parses the command line arguments. Picocli’s parse…​ methods also return a ParseResult that can be queried on what options were specified and what value they had, but most applications don’t actually need to use the ParseResult class since they can simply inspect the value that were injected into the annotated fields during parsing.

+
+
+
+

Processing the Results

+
+

processing results

+
+
+

When the parser is done, the application needs to run its business logic, but first there are some things to check:

+
+
+
    +
  • +

    Was version info or usage help requested? If so, print out the requested information and quit.

    +
    • +
  • +

    Was the user input invalid? Print out an error message with the details, print the usage help message and quit.

    +
    • +
  • +

    Finally run the business logic - and deal with errors thrown by the business logic.

    +
    • +
+
+
+

With Commons CLI, this looks something like this:

+
+
+
+
int exitStatus;
+try {
+    CommandLine commandLine = new DefaultParser().parse(buildOptions(), args);
+
+    if (commandLine.hasOption(OPTION_VERSION)) { // --version
+        System.out.println("Checkstyle version: " + version());
+        exitStatus = 0;
+    } else if (commandLine.hasOption(OPTION_HELP)) { // --help
+        printUsage(System.out);
+        exitStatus = 0;
+    } else {
+        exitStatus = runBusinessLogic(); // business logic
+    }
+} catch (ParseException pex) { // invalid input
+    exitStatus = EXIT_WITH_CLI_VIOLATION;
+    System.err.println(pex.getMessage());
+    printUsage(System.err);
+} catch (CheckstyleException ex) { // business logic exception
+    exitStatus = EXIT_WITH_CHECKSTYLE_EXCEPTION_CODE;
+    ex.printStackTrace();
+}
+System.exit(exitStatus);
+
+
+
+

Picocli offers some convenience methods that take care of most of the above. By making your command implement Runnable or Callable, the application can focus on the business logic. At its simplest, this can look something like this:

+
+
+
+
public class Main implements Callable<Integer> {
+    public static void main(String[] args) {
+        CommandLine.call(new Main(), args);
+    }
+
+    public Integer call() throws CheckstyleException {
+        // business logic here
+    }
+}
+
+
+
+

The Checkstyle Main class needs to control the exit code, and has some strict internal requirements for error handling, so we ended up not using the convenience methods and kept the parse result processing very similar to what it was with Commons CLI. Improving this area is on the picocli todo list.

+
+
+
+
+
+

Usage Help Message

+
+
+

Picocli uses ANSI colors and styles in the usage help message on supported platforms. +This doesn’t just look good, it also reduces the cognitive load on the user: the contrast make the important information like commands, options, and parameters stand out from the surrounding text.

+
+
+

Applications can also use ANSI colors and styles in the description or other sections of the usage help message with a simple markup like @|bg(red) text with red background|@. See the relevant section of the user manual.

+
+
+

For CheckStyle, we kept it to the bare minimum, and the resulting output for CheckStyle looks like this:

+
+
+

checkstyle usage

+
+
+
+
+

Wrapping Up: a Final Tip

+
+
+

Be aware that the Commons CLI default parser will recognize both single hyphen (-) and double hyphen (--) long options, even though the usage help message will only show options with double hyphens. You need to decide whether to continue to support this.

+
+
+

In picocli you can use @Option(names = "-xxx", hidden = true) to declare long options with a single hyphen if you want to mimic the exact same behaviour as Commons CLI: hidden options in picocli are not shown in the usage help message.

+
+
+
+
+

Conclusion

+
+
+

Migrating from Commons CLI to picocli can give end users a better user experience, and can give developers significant benefits in increased maintainability and potential for future expansion. Migration is a manual process, but is relatively straightforward.

+
+
+

Update: the CheckStyle project accepted a pull request with the changes in this article. From CheckStyle 8.15 its command line tools will use picocli. It looks like the CheckStyle maintainers were happy with the result:

+
+
+
+
+

Checkstyle migrated from Apache CLI to @picocli (will be released in 8.15), finally documentation of CLI arguments is now well organized in declarative way in code, and checkstyle’s CLI is following CLI best practices.

+
+
+
+— CheckStyle maintainer Roman Ivanov
+https://twitter.com/checkstyle_java/status/1057246772089606144 +
+
+
+

If you like what you see, please star picocli on GitHub and tell your friends!

+
+
+
+
+ + + \ No newline at end of file diff --git a/docs/man/3.x/picocli-2.0-do-more-with-less.html b/docs/man/3.x/picocli-2.0-do-more-with-less.html new file mode 100644 index 000000000..ec18688c8 --- /dev/null +++ b/docs/man/3.x/picocli-2.0-do-more-with-less.html @@ -0,0 +1,906 @@ + + + + + + + +Picocli 2.0: Do More With Less + + + + + + + +
+
+

Introduction

+
+
+

Picocli is a one-file command line parsing framework that allows you to create command line applications with almost no code. Annotate fields in your application with @Option or @Parameters, and picocli will populate these fields with command line options and positional parameters respectively. For example:

+
+
+
+
@Command(name = "Greet", header = "%n@|green Hello world demo|@")
+class Greet implements Runnable {
+
+  @Option(names = {"-u", "--user"}, required = true, description = "The user name.")
+  String userName;
+
+  public void run() {
+    System.out.println("Hello, " + userName);
+  }
+
+  public static void main(String... args) {
+    CommandLine.run(new Greet(), System.err, args);
+  }
+}
+
+
+
+

When we execute this program, picocli parses the command line and populates the userName field before invoking the run method:

+
+
+
+
$ java Greet -u picocli
+
+Hello, picocli
+
+
+
+

Picocli generates usage help messages with Ansi colors and styles. If we run the above program with invalid input (missing the required user name option), picocli prints an error and the usage help message:

+
+
+

Screenshot of error message and usage help for Greet application

+
+
+

Picocli can generate an autocompletion script that allows end users to use <TAB> command line completion to discover which options and subcommands are available. You may also like picocli’s support for subcommands and nested sub-subcommands to any level of depth.

+
+
+

The user manual describes picocli’s functionality in detail. This article highlights new and noteworthy features introduced with the picocli 2.0 release.

+
+
+
+
+

Mixing Options With Positional Parameters

+
+
+

The parser has been improved and positional parameters can now be mixed with options on the command line.

+
+
+

whisk

+
+
+

Previously, positional parameters had to follow options. +From this release, any command line argument that is not an option or subcommand is interpreted as a positional parameter.

+
+
+

For example:

+
+
+
+
class MixDemo implements Runnable {
+  @Option(names = "-o")
+  List<String> options;
+
+  @Parameters
+  List<String> positional;
+
+  public void run() {
+    System.out.println("positional: " + positional);
+    System.out.println("options   : " + options);
+  }
+
+  public static void main(String[] args) {
+    CommandLine.run(new MixDemo(), System.err, args);
+  }
+}
+
+
+
+

Running the above class with a mixture of options and positional parameters shows that non-options are recognized as positional parameters. For example:

+
+
+
+
$ java MixDemo param0 -o AAA param1 param2 -o BBB param3
+
+positional: [param0, param1, param2, param3]
+options   : [AAA, BBB]
+
+
+
+

To support mixing options with positional parameters, the parser has changed. From picocli 2.0, multi-value options (array, list and map fields) are not greedy by default any more. The 2.0 release notes describe this change and other potential breaking changes in detail.

+
+
+
+
+

Discovering Collection Types

+
+
+

Picocli performs automatic type conversion of command line arguments to the type of the annotated field. Both named options and positional parameters can be strongly typed.

+
+
+

binoculars

+
+
+

Prior to v2.0, picocli needed Collection and Map fields to be annotated with the type attribute to be able to do type conversion. For fields with other types, like array fields and single-value fields like int or java.io.File fields, picocli automatically detects the target type from the field type, but collections and maps needed more verbose annotation. For example:

+
+
+
+
class Before {
+    @Option(names = "-u", type = {TimeUnit.class, Long.class})
+    Map<TimeUnit, Long> timeout;
+
+    @Parameters(type = File.class)
+    List<File> files;
+}
+
+
+
+

From v2.0, the type attribute is no longer necessary for Collection and Map fields: picocli will infer the collection element type from the generic type. The type attribute still works as before, it is just optional in most cases.

+
+
+

Omitting the type attribute removes some duplication and results in simpler and cleaner code:

+
+
+
+
class Current {
+    @Option(names = "-u")
+    Map<TimeUnit, Long> timeout;
+
+    @Parameters
+    List<File> files;
+}
+
+
+
+

In the above example, picocli 2.0 is able to automatically discover that command line arguments need to be converted to File before adding them to the list, and for the map, that keys need to be converted to TimeUnit and values to Long.

+
+
+
+
+

Automatic Help

+
+
+

Picocli provides a number of convenience methods like run and call that parse the command line arguments, take care of error handling, and invoke an interface method to execute the application.

+
+
+

From this release, the convenience methods will also automatically print usage help and version information +when the user specifies an option annotated with the versionHelp or usageHelp attribute on the command line.

+
+
+

AskingForHelp

+
+
+

The example program below demonstrates automatic help:

+
+
+
+
@Command(version = "Help demo v1.2.3", header = "%nAutomatic Help Demo%n",
+         description = "Prints usage help and version help when requested.%n")
+class AutomaticHelpDemo implements Runnable {
+
+    @Option(names = "--count", description = "The number of times to repeat.")
+    int count;
+
+    @Option(names = {"-h", "--help"}, usageHelp = true,
+            description = "Print usage help and exit.")
+    boolean usageHelpRequested;
+
+    @Option(names = {"-V", "--version"}, versionHelp = true,
+            description = "Print version information and exit.")
+    boolean versionHelpRequested;
+
+    public void run() {
+        // NOTE: code like below is no longer required:
+        //
+        // if (usageHelpRequested) {
+        //     new CommandLine(this).usage(System.err);
+        // } else if (versionHelpRequested) {
+        //     new CommandLine(this).printVersionHelp(System.err);
+        // } else { ... the business logic
+
+        for (int i = 0; i < count; i++) {
+            System.out.println("Hello world");
+        }
+    }
+
+    public static void main(String... args) {
+        CommandLine.run(new AutomaticHelpDemo(), System.err, args);
+    }
+}
+
+
+
+

When executed with -h or --help, the program prints usage help:

+
+
+

Usage help message for AutomaticHelpDemo

+
+
+

Similarly, when executed with -V or --version, the program prints version information:

+
+
+

Version information for AutomaticHelpDemo

+
+
+

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

    +
    • +
+
+
+
+
+

Better Subcommand Support

+
+
+

This release adds new CommandLine::parseWithHandler methods. These methods offer the same ease of use as the run and call methods, but with more flexibility and better support for nested subcommands.

+
+
+

strong leadership

+
+
+

Consider what an application with subcommands needs to do:

+
+
+
    +
  1. +

    Parse the command line.

    +
    2. +
  2. +

    If user input was invalid, print the error message and the usage help message for the subcommand where the parsing failed.

    +
    3. +
  3. +

    If parsing succeeded, check if the user requested usage help or version information for the top-level command or a subcommand. If so, print the requested information and exit.

    +
    4. +
  4. +

    Otherwise, execute the business logic. Usually this means executing the most specific subcommand.

    +
    5. +
+
+
+

Picocli provides some building blocks to accomplish this, but it was up to the application to wire them together. This wiring is essentially boilerplate and is very similar between applications. For example, previously, an application with subcommands would typically contain code like this:

+
+
+
+
public static void main(String... args) {
+    // 1. parse the command line
+    CommandLine top = new CommandLine(new YourApp());
+    List<CommandLine> parsedCommands;
+    try {
+        parsedCommands = top.parse(args);
+    } catch (ParameterException ex) {
+        // 2. handle incorrect user input for one of the subcommands
+        System.err.println(ex.getMessage());
+        ex.getCommandLine().usage(System.err);
+        return;
+    }
+    // 3. check if the user requested help
+    for (CommandLine parsed : parsedCommands) {
+        if (parsed.isUsageHelpRequested()) {
+            parsed.usage(System.err);
+            return;
+        } else if (parsed.isVersionHelpRequested()) {
+            parsed.printVersionHelp(System.err);
+            return;
+        }
+    }
+    // 4. execute the most specific subcommand
+    Object last = parsedCommands.get(parsedCommands.size() - 1).getCommand();
+    if (last instanceof Runnable) {
+        ((Runnable) last).run();
+    } else if (last instanceof Callable) {
+        Object result = ((Callable) last).call();
+        // ... do something with result
+    } else {
+        throw new ExecutionException("Not a Runnable or Callable");
+    }
+}
+
+
+
+

This is quite a lot of boilerplate code. Picocli 2.0 provides a convenience method that allows you to reduce all of the above to a single line of code so you can focus on the business logic of your application:

+
+
+
+
public static void main(String... args) {
+    // This handles all of the above in one line:
+    // 1. parse the command line
+    // 2. handle incorrect user input for one of the subcommands
+    // 3. automatically print help if requested
+    // 4. execute one or more subcommands
+    new CommandLine(new YourApp()).parseWithHandler(new RunLast(), System.err, args);
+}
+
+
+
+

The new convenience method is parseWithHandler. You can create your own custom handler or use one of the built-in handlers. Picocli provides handler implementations for some common use cases.

+
+
+

The built-in handlers are RunFirst, RunLast and RunAll. All of these provide automatic help: if the user requests usageHelp or versionHelp, the requested information is printed and the handler returns without further processing. The handlers expect all commands to implement either java.lang.Runnable or java.util.concurrent.Callable.

+
+
+
    +
  • +

    RunLast executes the most specific command or subcommand. For example, if the user invoked java Git commit -m "commit message", picocli considers Git the top-level command and commit a subcommand. In this example, the commit subcommand is the most specific command, so RunLast would only execute that subcommand. If there are no subcommands, the top-level command is executed. RunLast is now used internally by picocli to implement the existing CommandLine::run and CommandLine::call convenience methods.

    +
    • +
  • +

    RunFirst only executes the first, top-level, command and ignores subcommands.

    +
    • +
  • +

    RunAll executes the top-level command and all subcommands that appeared on the command line.

    +
    • +
+
+
+

There is also a parseWithHandlers method, which is similar but additionally lets you specify a custom handler for incorrect user input.

+
+
+

Improved run and call Methods

+
+

The CommandLine::call and CommandLine::run convenience methods 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.

+
+
+
+

Improved Exceptions

+
+

Finally, from this release, all 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.

+
+
+
+
+
+

Conclusion

+
+
+

If you are already using picocli, v2.0 is an essential upgrade. +If you haven’t used picocli before, I hope the above made you interested to give it a try.

+
+
+

Many of these improvements originated in user feedback and subsequent discussions. Please don’t hesitate to ask questions, request features or give other feedback on the picocli issue tracker.

+
+
+

Please star the project on GitHub if you like it and tell your friends!

+
+
+
+
+ + + \ No newline at end of file diff --git a/docs/man/3.x/picocli-2.0-groovy-scripts-on-steroids.html b/docs/man/3.x/picocli-2.0-groovy-scripts-on-steroids.html new file mode 100644 index 000000000..94c434b21 --- /dev/null +++ b/docs/man/3.x/picocli-2.0-groovy-scripts-on-steroids.html @@ -0,0 +1,796 @@ + + + + + + + +Picocli 2.0: Groovy Scripts on Steroids + + + + + + + +
+
+
+
+

Picocli 2.0 adds improved support for other JVM languages, especially Groovy. +Why use picocli when the Groovy language has built-in CLI support with the CliBuilder class?

+
+
+

You may like picocli’s usage help, which shows ANSI colors and styles +by default. Another feature you may fancy is the command line +TAB autocompletion. Finally, there is a slew of smaller features, +like the fact that your script needs zero lines of command line parsing code, +picocli’s subcommand support, +type conversion for both options and positional parameters, +and parser tracing, to name a few.

+
+
+

cli

+
+
+
+
+

Example

+
+
+

Let’s take a look at an example. The checksum.groovy script below takes one or more file parameters, +and for each file prints out a checksum and the file name. The "checksum" algorithm is MD5 by default, +but users may specify a different MessageDigest algorithm. Users can request usage help with the +-h or --help option.

+
+
+
+
@Grab('info.picocli:picocli:2.0.3')
+@picocli.groovy.PicocliScript
+import groovy.transform.Field
+import java.security.MessageDigest
+import static picocli.CommandLine.*
+
+@Parameters(arity="1", paramLabel="FILE", description="The file(s) whose checksum to calculate.")
+@Field File[] files
+
+@Option(names = ["-a", "--algorithm"], description = [
+        "MD2, MD5, SHA-1, SHA-256, SHA-384, SHA-512,",
+        "  or any other MessageDigest algorithm."])
+@Field String algorithm = "MD5"
+
+@Option(names= ["-h", "--help"], usageHelp= true, description= "Show this help message and exit.")
+@Field boolean helpRequested
+
+files.each {
+  println MessageDigest.getInstance(algorithm).digest(it.bytes).encodeHex().toString() + "\t" + it
+}
+
+
+
+

When run in the $picocli-home/examples/src/main/groovy/picocli/examples directory, +this example script gives the following results:

+
+
+
+
$ groovy checksum.groovy *.*
+4995d24bbb3adf67e2120c36dd3027b7        checksum.groovy
+a03c852de017f9303fcc373c7adafac6        checksum-with-banner.groovy
+1ee567193bf41cc835ce76b6ca29ed30        checksum-without-base.groovy
+
+
+
+

Invoking the script with the -h or --help option shows the usage help message +with ANSI colors and styles below:

+
+
+

Usage help with ANSI colors and styles

+
+
+
+
+

Where’s the Code?

+
+
+

You may have noticed that the above script does not contain any logic for parsing the command +line arguments or for handling requests for usage help.

+
+
+

Dude

+
+
+

Without the @picocli.groovy.PicocliScript annotation, the script code would look something like this:

+
+
+
+
class Checksum {
+    @Parameters(arity = "1", paramLabel = "FILE", description = "...")
+    File[] files
+
+    @Option(names = ["-a", "--algorithm"], description = ["..."])
+    String algorithm = "MD5"
+
+    @Option(names = ["-h", "--help"], usageHelp = true, description = "...")
+    boolean helpRequested
+}
+Checksum checksum = new Checksum()
+CommandLine commandLine = new CommandLine(checksum)
+try {
+    commandLine.parse(args)
+    if (commandLine.usageHelpRequested) {
+        commandLine.usage(System.out)
+    } else {
+        checksum.files.each {
+            byte[] digest = MessageDigest.getInstance(checksum.algorithm).digest(it.bytes)
+            println digest.encodeHex().toString() + "\t" + it
+        }
+    }
+} catch (ParameterException ex) {
+    println ex.message
+    commandLine.usage(System.out)
+}
+
+
+
+

The above example has explicit code to parse the command line, deal with invalid user input, +and check for usage help requests. +The first version of the script did not have any of this boilerplate code.

+
+
+

Let’s take a look at how this works.

+
+
+
+
+

Basescript

+
+
+

Scripts annotated with @picocli.groovy.PicocliScript are automatically transformed to use +picocli.groovy.PicocliBaseScript as their base class. +This turns a Groovy script into a picocli-based command line application.

+
+
+

AllYourBase

+
+
+

When the script is run, Groovy calls the script’s run method. +The PicocliBaseScript::run method takes care of parsing the command line and populating the script +fields with the results. The run method does the following:

+
+
+
    +
  • +

    First, @Field variables annotated with @Option or @Parameters are initialized from the command line arguments.

    +
    • +
  • +

    If the user input was invalid, an error message is printed followed by the usage help message.

    +
    • +
  • +

    If the user requested usage help or version information, this is printed to the console and the script exits.

    +
    • +
  • +

    Otherwise, the script body is executed.

    +
    • +
+
+
+

This behavior can be customized, see the PicocliBaseScript javadoc for more details.

+
+
+

In addition to changing the script base class, the @PicocliScript annotation also allows Groovy +scripts to use the @Command annotation directly, without introducing a helper class. +The picocli parser will look for this annotation on the +class containing the @Option and @Parameters-annotated fields. The same custom +AST transformation +that changes the script’s base class also moves any @Command annotation in the script to this +transformed class so the picocli parser can pick it up.

+
+
+
+
+

Usage Help With Colors

+
+
+

The @Command annotation lets you customize parts of the usage help message like command name, description, headers, footers etc.

+
+
+

Let’s add some bells and whistles to the example script. +(Credit to http://patorjk.com/software/taag/ for the ASCII Art Generator.)

+
+
+
+
@Grab('info.picocli:picocli:2.0.3')
+@Command(header = [
+        $/@|bold,green    ___                            ___ _           _                  |@/$,
+        $/@|bold,green   / __|_ _ ___  _____ ___  _     / __| |_  ___ __| |__ ____  _ _ __  |@/$,
+        $/@|bold,green  | (_ | '_/ _ \/ _ \ V / || |   | (__| ' \/ -_) _| / /(_-< || | '  \ |@/$,
+        $/@|bold,green   \___|_| \___/\___/\_/ \_, |    \___|_||_\___\__|_\_\/__/\_,_|_|_|_||@/$,
+        $/@|bold,green                         |__/                                         |@/$
+        ],
+        description = "Print a checksum of each specified FILE.",
+        version = 'checksum v1.2.3', showDefaultValues = true,
+        footerHeading = "%nFor more details, see:%n",
+        footer = ["[1] https://docs.oracle.com/javase/9/docs/specs/security/standard-names.html",
+                "ASCII Art thanks to http://patorjk.com/software/taag/"]
+)
+@picocli.groovy.PicocliScript
+import groovy.transform.Field
+import java.security.MessageDigest
+import static picocli.CommandLine.*
+
+@Parameters(arity="1", paramLabel="FILE", description="The file(s) whose checksum to calculate.")
+@Field private File[] files
+
+@Option(names = ["-a", "--algorithm"], description = [
+        "MD2, MD5, SHA-1, SHA-256, SHA-384, SHA-512, or",
+        "  any other MessageDigest algorithm. See [1] for more details."])
+@Field private String algorithm = "MD5"
+
+@Option(names= ["-h", "--help"], usageHelp=true, description="Show this help message and exit.")
+@Field private boolean helpRequested
+
+@Option(names= ["-V", "--version"], versionHelp=true, description="Show version info and exit.")
+@Field private boolean versionInfoRequested
+
+files.each {
+  println MessageDigest.getInstance(algorithm).digest(it.bytes).encodeHex().toString() + "\t" + it
+}
+
+
+
+

The new version of the script adds a header and footer, and the ability to print version information. +All text displayed in the usage help message and version information may contain format specifiers +like the %n line separator.

+
+
+

The usage help message can also display ANSI colors and styles. +Picocli supports a simple markup syntax where @| starts an ANSI styled section and |@ ends it. +Immediately following the @| is a comma-separated list of colors and styles, +like @|STYLE1[,STYLE2]…​ text|@. +See the picocli user manual for details on what colors and styles are available.

+
+
+

The usage help message for the new script looks like this:

+
+
+

Customized header and footer with styles and colors

+
+
+

The @Command annotation also has a version = "checksum v1.2.3" attribute. +This version string is printed when the user specifies --version on the command line because +we declared an @Option with that name with attribute versionHelp = true.

+
+
+
+
$ groovy checksum-with-banner.groovy --version
+checksum v1.2.3
+
+
+
+

For more details, see the Version Help section of the user manual.

+
+
+
+
+

Conclusion

+
+
+

The @PicocliScript annotation allows Groovy scripts to omit boilerplate code and while adding powerful common command line application functionality. +In the final version of our example script, most of the code is actually description text for the usage help message.

+
+
+

There is a lot more to picocli, give it a try!

+
+
+

Please star the project on GitHub if you like it and tell your friends!

+
+
+
+
+ + + \ No newline at end of file diff --git a/docs/man/3.x/picocli-3.0-programmatic-api.html b/docs/man/3.x/picocli-3.0-programmatic-api.html new file mode 100644 index 000000000..06fb2affa --- /dev/null +++ b/docs/man/3.x/picocli-3.0-programmatic-api.html @@ -0,0 +1,1030 @@ + + + + + + + +Programmatic API + + + + + + + +
+
+
+
+ + + + + +
+ + +For most applications the annotations API is a better fit than the programmatic API: the annotation syntax is more compact, easier to read, and easier to maintain. See this introductory article and for more details, the user manual. +
+
+
+

Picocli 3.0 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.

+
+
+
+
+

1. 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);
+
+// processing parse results can be done manually
+// or delegated to a handler
+class Handler extends AbstractParseResultHandler<Integer> {
+    protected Handler self() { return this; }
+
+    public Integer handle(ParseResult pr) {
+        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.println(i + " " + f.getName());
+            }
+        }
+        return files.size();
+    }
+}
+
+// using a handler gives fine-grained control
+// over which streams to use and exit codes
+Integer processed = commandLine.parseWithHandlers(
+        new Handler().useOut(System.out).andExit(123),
+        new DefaultExceptionHandler<Integer>().andExit(567),
+        args);
+
+
+
+
+
+

2. Configuration

+
+
+

The following classes are the main model classes used to configure the parser:

+
+
+
    +
  • +

    CommandSpec

    +
    • +
  • +

    OptionSpec

    +
    • +
  • +

    PositionalParamSpec

    +
    • +
+
+
+

2.1. CommandSpec

+
+

2.1.1. Command Name and Version

+
+

CommandSpec models a command. It has a name and a version, both of which may be empty. For example:

+
+
+
+
CommandSpec cmd = CommandSpec.create()
+    .name("mycommand")
+    .version("My Command v1.0");
+
+
+
+

It also has a UsageMessageSpec to configure aspects of the usage help message.

+
+
+
+

2.1.2. Usage Help

+
+
+
cmd.usageMessage()
+        .headerHeading("Header heading%n")
+        .header("header line 1", "header line 2")
+        .descriptionHeading("Description heading%n")
+        .description("description line 1", "description line 2")
+        .optionListHeading("Options%n")
+        .parameterListHeading("Positional Parameters%n");
+        .footerHeading("Footer heading%n")
+        .footer("footer line 1", "footer line 2");
+
+
+
+

The ParserSpec can be used to control the behaviour of the parser to some extent.

+
+
+
+

2.1.3. Parser Options

+
+
+
cmd.parser()
+        .unmatchedArgumentsAllowed(true)
+        .overwrittenOptionsAllowed(true);
+
+
+
+
+

2.1.4. Mixins

+
+

CommandSpec has methods to add options (OptionSpec objects) and positional parameters (PositionalParamSpec objects). A CommandSpec can be mixed in with another CommandSpec, so its options, positional parameters and usage help attributes are merged into the other CommandSpec.

+
+
+
+
CommandSpec standardHelpOptions = CommandSpec.create()
+    .addOption(OptionSpec.builder("-h", "--help")
+        .usageHelp(true)
+        .description("Show this help message and exit.").build())
+    .addOption(OptionSpec.builder("-V", "--version")
+        .versionHelp(true)
+        .description("Print version information and exit.").build());
+
+CommandSpec cmd = CommandSpec.create()
+    .name("mycommand")
+    .addMixin("standardHelpOptions", standardHelpOptions);
+
+
+
+

Actually, since these options are extremely common, CommandSpec provides a convenience method to quickly add these standard help options:

+
+
+
+
CommandSpec spec = CommandSpec.create();
+spec.mixinStandardHelpOptions(true); // usageHelp and versionHelp options
+
+
+
+
+

2.1.5. Subcommands

+
+

Finally, CommandSpec objects can be subcommands of other CommandSpecs. There is no limit to the depth of a hierarchy of command and subcommands. CommandSpec also allows registration of type converters that are used while parsing the command line arguments to convert a command line argument string to the strongly typed value of a OptionSpec or PositionalParamSpec

+
+
+
+
CommandSpec helpSubcommand = CommandSpec.forAnnotatedObject(
+        new picocli.CommandLine.HelpCommand());
+
+CommandSpec cmd = CommandSpec.create()
+    .name("mycommand")
+    .addSubcommand("help", helpSubcommand);
+
+
+
+
+
+

2.2. OptionSpec

+
+

OptionSpec models a command option. 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.

+
+
+

Once an OptionSpec is constructed, its configuration becomes immutable, but its value can still be modified. Usually the value is set during command line parsing when a command line argument matches one of the option names.

+
+
+

The value is set via the getter and setter bindings. We’ll come back to bindings later in this document.

+
+
+

Similar to the annotation API, OptionSpec objects have help, usageHelp and versionHelp attributes. When the parser matches an option that was marked with any of these attributes, it will no longer validate that all required arguments exist. See the section below on the parseWithHandler(s) methods that automatically print help when requested.

+
+
+
+

2.3. PositionalParamSpec

+
+

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.

+
+
+

The value is set via getter and setter bindings. We’ll look at bindings next.

+
+
+
+

2.4. Bindings

+
+

Bindings decouple the option and positional parameter specification from the place where their value is held.

+
+
+

Option specifications and positional parameter specifications created from annotated objects have a FieldBinding (and in the near future they can have a MethodBinding), so when the value is set on an option specification, the field’s value is set (or the setter method is invoked).

+
+
+

Option specifications and positional parameter specifications created programmatically without annotated object by default have an ObjectBinding that simply stores the value in a field of the ObjectBinding.

+
+
+

You may create a custom binding that delegates to some other data structure to retrieve and store the value.

+
+
+

A binding is either a getter or a setter:

+
+
+
+
public static interface IGetter {
+    /** Returns the current value of the binding. For multi-value options and positional
+     * parameters, this method returns an array, collection or map to add values to.
+     * @throws PicocliException if a problem occurred while obtaining the current value
+     * @throws Exception internally, picocli call sites will catch any exceptions
+     *         thrown from here and rethrow them wrapped in a PicocliException */
+    <T> T get() throws Exception;
+}
+
+
+
+
+
public static interface ISetter {
+    /** Sets the new value of the option or positional parameter.
+     *
+     * @param value the new value of the option or positional parameter
+     * @param <T> type of the value
+     * @return the previous value of the binding (if supported by this binding)
+     * @throws PicocliException if a problem occurred while setting the new value
+     * @throws Exception internally, picocli call sites will catch any exceptions
+     *         thrown from here and rethrow them wrapped in a PicocliException */
+    <T> T set(T value) throws Exception;
+}
+
+
+
+

For single-value options, picocli will simply invoke the setter when an option or positional parameter is matched on the command line.

+
+
+

For multi-value options or positional parameters, picocli will call the getter to get the current value, add the newly matched value, and call the setter with the result. +For arrays, this means the existing elements are copied into a new array that is one element larger, and this new array is then set. +For collections and maps, the new value is added to the collection returned by the getter. +If the getter returns null, a new array, collection, or map is created.

+
+
+
+
+
+

3. Parse Result

+
+
+

For the below examples, we use the following parser configuration:

+
+
+
+
CommandSpec spec = CommandSpec.create();
+spec.addOption(OptionSpec.builder("-V", "--verbose").build());
+spec.addOption(OptionSpec.builder("-f", "--file")
+        .paramLabel("FILES")
+        .type(List.class)
+        .auxiliaryTypes(File.class) // this option is of type List<File>
+        .description("The files to process").build());
+spec.addOption(OptionSpec.builder("-n", "--num")
+        .paramLabel("COUNT")
+        .type(int[].class)
+        .splitRegex(",")
+        .description("Comma-separated list of integers").build());
+CommandLine commandLine = new CommandLine(spec);
+
+
+
+

3.1. Querying for Options

+
+

The CommandLine::parseArgs method returns a ParseResult object that allows client code to query which options and positional parameters were matched for a given command.

+
+
+
+
String[] args = { "--verbose", "-f", "file1", "--file=file2", "-n1,2,3" };
+ParseResult pr = commandLine.parseArgs(args);
+
+List<String> originalArgs = pr.originalArgs(); // lists all command line args
+assert Arrays.asList(args).equals(originalArgs);
+
+assert pr.hasMatchedOption("--verbose"); // as specified on command line
+assert pr.hasMatchedOption("-V");        // other aliases work also
+assert pr.hasMatchedOption('V');         // single-character alias works too
+assert pr.hasMatchedOption("verbose");   // and, command name without hyphens
+
+
+
+
+

3.2. Matched Option Values

+
+

The matchedOptionValue method returns the command line value or values, converted to the option’s type. This method requires a default value, which will be returned in case the option was not matched on the command line. In the above example, we defined the --file option to be of type List<File>, so we pass in an empty list as the default value:

+
+
+
+
ParseResult pr = commandLine.parseArgs("-f", "file1", "--file=file2", "-n1,2,3");
+
+List<File> defaultValue = Collections.emptyList();
+List<File> expected     = Arrays.asList(new File("file1"), new File("file2"));
+
+assert expected.equals(pr.matchedOptionValue('f', defaultValue));
+assert expected.equals(pr.matchedOptionValue("--file", defaultValue));
+
+assert Arrays.equals(new int[]{1,2,3}, pr.matchedOptionValue('n', new int[0]));
+
+
+
+
+

3.3. Original Option Values

+
+

Use the OptionSpec.stringValues() or OptionSpec.originalStringValues() method to get a list of all values specified on the command line for an option. +The stringValues() method returns the arguments after splitting but before type conversion, while +the originalStringValues() method returns the matched arguments as specified on the command line (before splitting).

+
+
+
+
ParseResult pr = commandLine.parseArgs("-f", "file1", "--file=file2", "-n1,2,3");
+
+// Command line arguments after splitting but before type conversion
+assert "1".equals(pr.matchedOption('n').stringValues().get(0));
+assert "2".equals(pr.matchedOption('n').stringValues().get(1));
+assert "3".equals(pr.matchedOption('n').stringValues().get(2));
+
+// Command line arguments as found on the command line
+assert "1,2,3".equals(pr.matchedOption("--num").originalStringValues().get(0));
+
+
+
+
+

3.4. Subcommands

+
+

Use the hasSubcommand method to determine whether the command line contained subcommands. The subcommand method returns a different ParseResult object that can be used to query which options and positional parameters were matched for the subcommand.

+
+
+
+
class App {
+    @Option(names = "-x") String x;
+}
+class Sub {
+    @Parameters String[] all;
+}
+CommandLine cmd = new CommandLine(new App());
+cmd.addSubcommand("sub", new Sub());
+ParseResult parseResult = cmd.parseArgs("-x", "xval", "sub", "1", "2", "3");
+
+assert parseResult.hasMatchedOption("-x");
+assert "xval".equals(parseResult.matchedOptionValue("-x", "default"));
+
+assert parseResult.hasSubcommand();
+ParseResult subResult = parseResult.subcommand();
+
+assert  subResult.hasMatchedPositional(0);
+assert  subResult.hasMatchedPositional(1);
+assert  subResult.hasMatchedPositional(2);
+assert !subResult.hasMatchedPositional(3);
+
+
+
+
+
+
+

4. Parsing and Result Processing

+
+
+

4.1. Basic Processing

+
+

The most basic way to parse the command line is to call the CommandLine::parseArgs method and inspect the resulting ParseResult object.

+
+
+

For example:

+
+
+
+
CommandSpec spec = CommandSpec.create();
+// add options and positional parameters
+
+CommandLine commandLine = new CommandLine(spec);
+try {
+    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 (ParameterException invalidInput) {
+    System.err.println(invalidInput.getMessage());
+    invalidInput.getCommandLine().usage(System.err);
+}
+
+
+
+
+

4.2. Convenience Methods

+
+

There are a number of parseWithHandler convenience methods to reduce some boilerplate when processing the ParseResult programmatically. The convenience methods take care of printing help when requested by the user, and handle invalid input.

+
+
+

4.2.1. Handlers

+
+

It is possible for the parse result processing logic to return a result. To accomplish this, call the CommandLine::parseWithHandler method with a class that extends AbstractParseResultHandler.

+
+
+

Example:

+
+
+
+
CommandSpec spec = CommandSpec.create();
+// add options and positional parameters
+
+CommandLine commandLine = new CommandLine(spec);
+
+class Handler extends AbstractParseResultHandler<Integer> {
+    protected Handler self() { return this; }
+
+    public Integer handle(ParseResult pr) {
+        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.println(i + " " + f.getName());
+            }
+        }
+        return files.size();
+    }
+}
+
+int processed = commandLine.parseWithHandler(new Handler(), args);
+// do something with result...
+
+
+
+

This method also has a variation, parseWithHandlers, which additionally takes an IExceptionHandler2 to customize how invalid input should be handled and optionally set an exit code.

+
+
+

Example:

+
+
+
+
CommandSpec spec = CommandSpec.create();
+// add options and positional parameters
+
+CommandLine commandLine = new CommandLine(spec);
+Integer result = commandLine.parseWithHandlers(
+        new MyHandler().useOut(System.out).andExit(123),
+        new DefaultExceptionHandler<Integer>().andExit(567),
+        args);
+// do something with result...
+
+
+
+
+
+
+
+ + + \ No newline at end of file diff --git a/docs/man/3.x/picocli-on-graalvm.html b/docs/man/3.x/picocli-on-graalvm.html new file mode 100644 index 000000000..3dedccad5 --- /dev/null +++ b/docs/man/3.x/picocli-on-graalvm.html @@ -0,0 +1,644 @@ + + + + + + + +Picocli on GraalVM: Blazingly Fast Command Line Apps + + + + + +
+
+
+
+
+picocli on graalvm +
+
+
+
+
+

GraalVM

+
+
+

GraalVM allows you to compile your programs ahead-of-time into a native executable. The resulting program has faster startup time and lower runtime memory overhead compared to a Java VM. This is especially useful for command line utilities, which are often short-lived.

+
+
+

GraalVM has limited support for Java reflection and it needs to know ahead of time the reflectively accessed program elements.

+
+
+
+
+

Reflective Access

+
+
+

Picocli currently uses reflection to discover +classes and methods +annotated with @Command, and fields, +methods or +method parameters annotated with @Option and @Parameters and other picocli annotations. A future picocli release may include an annotation processor to do this work at compile time, but as it stands, it uses reflection.

+
+
+
+
+

ReflectionConfigGenerator Tool

+
+
+

Picocli 3.7.0 includes a picocli-codegen module, with a tool that generates a GraalVM configuration file.

+
+
+

ReflectionConfigGenerator generates a JSON String with the program elements that will be accessed reflectively in a picocli-based application, in order to compile this application ahead-of-time into a native executable with GraalVM.

+
+
+

The output of ReflectionConfigGenerator is intended to be passed to the -H:ReflectionConfigurationFiles=/path/to/reflectconfig option of the native-image GraalVM utility. This allows picocli-based applications to be compiled to a native image.

+
+
+

Example Usage

+
+

We will use the picocli.codegen.aot.graalvm.Example class that is in the tests for the picocli-codegen module as an example. First, we will generate a reflect.json configuration file with the ReflectionConfigGenerator tool. Next, we will compile the Example class to a native application, and finally we will run this application and see what the difference is in startup time between the native application and running on Hotspot.

+
+
+
+

Generating the Configuration File

+
+

Run the ReflectionConfigGenerator tool and specify one or more fully qualified class names of the @Command-annotated classes. The output is printed to System.out, so you will want to redirect it to a file:

+
+
+
+
java -cp \
+picocli-3.7.0.jar:picocli-codegen-3.7.0-tests.jar:picocli-codegen-3.7.0.jar \
+picocli.codegen.aot.graalvm.ReflectionConfigGenerator picocli.codegen.aot.graalvm.Example > reflect.json
+
+
+
+

The generated reflect.json files looks something like this:

+
+
+
+
[
+  {
+    "name" : "picocli.codegen.aot.graalvm.Example",
+    "allDeclaredConstructors" : true,
+    "allPublicConstructors" : true,
+    "allDeclaredMethods" : true,
+    "allPublicMethods" : true,
+    "fields" : [
+        { "name" : "spec" },
+        { "name" : "unmatched" },
+        { "name" : "timeUnit" },
+        { "name" : "file" }
+    ],
+    "methods" : [
+        { "name" : "setMinimum", "parameterTypes" : ["int"] },
+        { "name" : "setOtherFiles", "parameterTypes" : ["[Ljava.io.File;"] },
+        { "name" : "multiply", "parameterTypes" : ["int", "int"] }
+    ]
+  },
+...
+]
+
+
+
+ + + + + +
+
Tip
+		 +If necessary, it is possible to exclude classes with system property picocli.codegen.excludes, which accepts a comma-separated list of regular expressions of the fully qualified class names that should not be included in the resulting JSON String. +
+
+
+
+

Compiling a Native Image

+
+

This assumes you have GraalVM installed, with prerequisites. From the site:

+
+
+
+
+

To build a native image of the program use the native-image utility located in the bin directory of the GraalVM distribution. For compilation native-image depends on the local toolchain, so please make sure: glibc-devel, zlib-devel (header files for the C library and zlib) and gcc are available on your system.

+
+
+
+
+

I also needed the static packages glibc-static and zlib-static, other than the devel packages.

+
+
+

We compile the example class with the following command:

+
+
+
+
graalvm-ce-1.0.0-rc6/bin/native-image \
+    -cp picocli-3.7.0.jar:picocli-codegen-3.7.0-tests.jar \
+    -H:ReflectionConfigurationFiles=reflect.json -H:+ReportUnsupportedElementsAtRuntime \
+    --static --no-server picocli.codegen.aot.graalvm.Example
+
+
+
+

The reflect.json is in the current directory, and I added -H:+ReportUnsupportedElementsAtRuntime to get a useful error message in case something goes wrong.

+
+
+ + + + + +
+
Tip
+		 +native-image --expert-options shows a list of other compilation options not shown in the output of native-image --help. +
+
+
+
+

Running the Native Image

+
+

If compilation went well, we now have a native executable picocli.codegen.aot.graalvm.example in the current directory:

+
+
+
+
$ ls -alh picocli*
+-rwxrwxr-x 1 remko remko 15M Oct  4 21:35 picocli.codegen.aot.graalvm.example
+
+
+
+

The name of the executable is derived from the main class name. If the jar is an executable jar (with the Main-Class specified in the manifest), we could have run native-image [options] -jar jarfile to build an image for the jar file.

+
+
+

Let’s first run the application in Java, and time it to see how long it takes to start up.

+
+
+
+
$ time java -cp  picocli-3.7.0.jar:picocli-codegen-3.7.0-tests.jar \
+    picocli.codegen.aot.graalvm.Example --version
+3.7.0
+
+real    0m0.492s
+user    0m0.847s
+sys     0m0.070s
+
+
+
+

On Java Hotspot, it takes about half a second to run. Now, we run the native image:

+
+
+
+
$ time ./picocli.codegen.aot.graalvm.example --version
+3.7.0
+
+real    0m0.003s
+user    0m0.000s
+sys     0m0.004s
+
+
+
+

The startup time is now down to 3 milliseconds!

+
+
+

All command line parsing functionality works as expected, with type conversion, validation and help with ANSI colors. This is exciting news when you want to write command line applications and services in Java and have them run instantaneously.

+
+
+
+
+
+

Conclusion

+
+
+

GraalVM is an exciting new technology that allows Java programs to run as native code. This gives reduced memory usage and startup time, which is especially useful for short-running programs like command line utilities.

+
+
+

The ReflectionConfigGenerator tool included in the picocli-codegen module allows picocli-based applications to be compiled to native executables with extremely fast startup times.

+
+
+

Please star ☆ GraalVM and picocli on GitHub if you like the projects!

+
+
+
+
+ + + + + + \ No newline at end of file diff --git a/docs/man/3.x/quick-guide.html b/docs/man/3.x/quick-guide.html new file mode 100644 index 000000000..09422aa2c --- /dev/null +++ b/docs/man/3.x/quick-guide.html @@ -0,0 +1,2004 @@ + + + + + + + +Quick Guide + + + + + + + +
+
+
+
+

This is the Quick Guide. For more detail, see the full user manual at http://picocli.info.

+
+
+
+
+

1. What is picocli

+
+
+

Picocli is a Java library and mini-framework for creating command line applications with almost no code.

+
+
+

Picocli supports a variety of command line syntax styles including POSIX, GNU, MS-DOS and more. +It generates highly customizable usage help messages with ANSI colors and styles. +Picocli-based applications can have command line TAB completion showing available options, option parameters and subcommands, for any level of nested subcommands.

+
+
+
Example usage help message
+

Screenshot of usage help with Ansi codes enabled

+
+
+
+
+

2. How to Use it

+
+
+

Create a class and annotate its fields or methods with @Option or @Parameters to declare what options and positional parameters your application expects. +While parsing the command line, picocli will initialize these fields based on the command line arguments. +If your class implements Runnable or Callable, you can let picocli kick off your application after parsing is successfully completed.

+
+
+ + + + + +
+ + +For applications that cannot use the annotations, there is also a programmatic API for defining what options and positional parameters to expect, and a programmatic API for handling parse results. The programmatic API is not covered in this Quick Guide. +
+
+
+

2.1. Example

+
+

Here is a small example application that uses the CommandLine.call convenience method +to do parsing and error handling in one line of code. The mixinStandardHelpOptions attribute +adds usage help and version help options your application.

+
+
+
Example Callable application
+
+
@Command(description = "Prints the checksum (MD5 by default) of a file to STDOUT.",
+         name = "checksum", mixinStandardHelpOptions = true, version = "checksum 3.0")
+class CheckSum implements Callable<Void> {
+
+    @Parameters(index = "0", description = "The file whose checksum to calculate.")
+    private File file;
+
+    @Option(names = {"-a", "--algorithm"}, description = "MD5, SHA-1, SHA-256, ...")
+    private String algorithm = "SHA-1";
+
+    public static void main(String[] args) throws Exception {
+        CommandLine.call(new CheckSum(), args);
+    }
+
+    @Override
+    public Void call() throws Exception {
+        byte[] fileContents = Files.readAllBytes(file.toPath());
+        byte[] digest = MessageDigest.getInstance(algorithm).digest(fileContents);
+        System.out.println(javax.xml.bind.DatatypeConverter.printHexBinary(digest));
+        return null;
+    }
+}
+
+
+
+
+
+
+

3. Options and Parameters

+
+
+

Command line arguments can be separated into options and positional parameters. +Options have a name, positional parameters are usually the values that follow the options, +but they may be mixed.

+
+
+

Example command with annotated @Option and @Parameters

+
+
+

Picocli has separate annotations for options and positional parameters.

+
+
+

3.1. Options

+
+

An option must have one or more names. +Option names commonly start with - or --, but picocli lets you use any option name you want.

+
+
+

The below example shows options with one or more names, options that take an option parameter, and a help option.

+
+
+
+
class Tar {
+    @Option(names = "-c", description = "create a new archive")
+    boolean create;
+
+    @Option(names = { "-f", "--file" }, paramLabel = "ARCHIVE", description = "the archive file")
+    File archive;
+
+    @Parameters(paramLabel = "FILE", description = "one ore more files to archive")
+    File[] files;
+
+    @Option(names = { "-h", "--help" }, usageHelp = true, description = "display a help message")
+    private boolean helpRequested;
+}
+
+
+
+

Picocli matches the option names to set the field values.

+
+
+
+
String[] args = { "-c", "--file", "result.tar", "file1.txt", "file2.txt" };
+Tar tar = new Tar();
+new CommandLine(tar).parse(args);
+
+assert !tar.helpRequested;
+assert  tar.create;
+assert  tar.archive.equals(new File("result.tar"));
+assert  Arrays.equals(tar.files, new File[] {new File("file1.txt"), new File("file2.txt")});
+
+
+
+

Picocli supports POSIX clustered short options: +one or more single-character options without option-arguments, followed by at most one option with an option-argument, can be grouped behind one ‘-’ dash.

+
+
+

For example, for the Tar example above, the following command line invocations are equivalent:

+
+
+
Example commands with clustered short options
+
+
tar -c -f result.tar f1.txt f2.txt
+tar -cf result.tar f1.txt f2.txt
+tar -cfresult.tar f1.txt f2.txt
+
+
+
+
+

3.2. Interactive (Password) Options

+
+

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.

+
+
+

The user manual has an example.

+
+
+
+

3.3. Positional Parameters

+
+

Any command line arguments that are not subcommands, options or option parameters are interpreted as positional parameters.

+
+
+

Use the (zero-based) index attribute to specify exactly which parameters to capture. +Omitting the index attribute means the field captures all positional parameters. +Array or collection fields can capture multiple values.

+
+
+

The index attribute accepts range values, so an annotation like @Parameters(index = "2..4") captures the arguments at index 2, 3 and 4. Range values can be open-ended. For example, @Parameters(index = "3..*") captures all arguments from index 3 and up.

+
+
+

For example:

+
+
+
+
class PositionalDemo {
+    @Parameters(index = "0")    InetAddress host;
+    @Parameters(index = "1")    int port;
+    @Parameters(index = "2..*") List<File> files;
+}
+
+
+
+

Picocli initializes fields with the values at the specified index in the arguments array.

+
+
+
+
String[] args = { "localhost", "12345", "file1.txt", "file2.txt" };
+PositionalDemo params = CommandLine.populateCommand(new PositionalDemo(), args);
+
+assert params.host.getHostName().equals("localhost");
+assert params.port == 12345;
+assert params.files.equals(Arrays.asList(new File("file1.txt"), new File("file2.txt")));
+
+
+
+

The user manual has more details about options and positional parameters, as well as the -- end-of-options delimiter and parameter files (@-files).

+
+
+
+
+
+

4. Strongly Typed Everything

+
+
+

When command line options and positional parameters are mapped to the annotated fields, +the text value is converted to the type of the annotated field.

+
+
+

4.1. Type Conversion

+
+

Out of the box, picocli can convert command line argument strings to a number of common data types.

+
+
+

See the user manual for the full list of built-in types, but in general all primitive types and their Object equivalent, +any enum, and common classes like File, Date, URL, BigDecimal, regex Pattern etc. can be used as is. +Applications running on Java 7 can use Path, and on Java 8 the new java.time classes can be used.

+
+
+

You can also use a custom type converter to handle data types other than the above built-in ones.

+
+
+
+

4.2. Collections and Maps

+
+

If an option or positional parameter can have multiple values, the field type must be an array, a Collection or a Map. +Any Collection subclass like List, Set, or Queue can be used.

+
+
+

A common requirement is to have options with key-value pairs similar to Java’s system properties, like -Dkey=value. +To achieve this, all you need to do is use a Map field.

+
+
+

Map fields may have any type for their key and value +as long as a type converter is registered for both the key and the value type. +Key and value types are inferred from the map’s generic type parameters. +For example:

+
+
+
+
class MapDemo {
+    @Option(names = {"-u", "--timeUnit"});
+    Map<java.util.concurrent.TimeUnit, Long> timeout;
+}
+
+
+
+

The following command line would result in four key-value entries in the map:

+
+
+
+
<command> -uDAYS=3 -u HOURS=23 -u=MINUTES=59 --timeUnit=SECONDS=13
+
+
+
+
+
+
+

5. Required Arguments

+
+
+

5.1. Required Options

+
+

Options can be marked required to make it mandatory for the user to specify them on the command line. When a required option is not specified, a MissingParameterException is thrown from the parse method. For example:

+
+
+
+
@Option(names = "-n", required = true, description = "mandatory number")
+int number;
+
+
+
+
+

5.2. Required Parameters

+
+

Use the arity attribute to make @Parameters mandatory:

+
+
+
+
@Parameters(arity = "1..*", descriptions = "at least one File")
+List<File> files;
+
+
+
+
+
+
+

6. Multiple Values

+
+
+

Multi-valued options and positional parameters are annotated fields that can capture multiple values from the command line.

+
+
+

6.1. Repeated Options

+
+

The simplest way to create a multi-valued option is to declare an annotated field whose type is an array, collection or a map.

+
+
+
+
@Option(names = "-option")
+int[] values;
+
+
+
+

Users may specify the same option multiple times. For example:

+
+
+
+
<command> -option 111 -option 222 -option 333
+
+
+
+

Each value is appended to the array or collection.

+
+
+
+

6.2. Split Regex

+
+

Options and parameters may also specify a split regular expression used to split each option parameter into smaller substrings. +Each of these substrings is converted to the type of the collection or array. See Collections and Maps.

+
+
+
+
@Option(names = "-option", split = ",")
+int[] values;
+
+
+
+

A single command line argument like the following will be split up and three int values are added to the array:

+
+
+
+
-option 111,222,333
+
+
+
+
+

6.3. Arity

+
+

Sometimes you want to define an option that requires more than one option parameter for each option occurrence on the command line.

+
+
+

The arity attribute lets you control exactly how many parameters to consume for each option occurrence.

+
+
+

The arity attribute can specify an exact number of required parameters, or a range with a minimum and a maximum number of parameters. +The maximum can be an exact upper bound, or it can be "*" to denote any number of parameters. For example:

+
+
+
+
class ArityDemo {
+    @Parameters(arity = "1..3", descriptions = "one to three Files")
+    File[] files;
+
+    @Option(names = "-f", arity = "2", description = "exactly two floating point numbers")
+    double[] doubles;
+
+    @Option(names = "-s", arity = "1..*", description = "at least one string")
+    String[] strings;
+}
+
+
+
+

A MissingParameterException is thrown when fewer than the miminum number of parameters is specified on the command line.

+
+
+

6.3.1. Default Arity

+
+

If no arity is specified, the number of parameters depends on the field’s type. +The user manual has more details on arity.

+
+
+
+
+
+
+

7. Help Options

+
+
+

7.1. Mixin Standard Help Options

+
+

When the mixinStandardHelpOptions command 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() { ... }
+}
+
+
+
+

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

7.2. Custom Help Options

+
+

Applications can define custom help options by setting attribute versionHelp = true, usageHelp = true or help = true. +If one of the arguments specified on the command line is a "help" option, picocli will not throw a MissingParameterException when required options are missing.

+
+
+

For example:

+
+
+
+
@Option(names = {"-V", "--version"}, versionHelp = true, description = "display version info")
+boolean versionInfoRequested;
+
+@Option(names = {"?", "-h", "--help"}, usageHelp = true, description = "display this help message")
+boolean usageHelpRequested;
+
+
+
+

Use these attributes for options that request the usage help message or version information to be shown on the console.

+
+
+

The CommandLine class offers two methods that allow external components to detect whether +usage help or version information was requested (without inspecting the annotated domain object):

+
+
+
    +
  • +

    CommandLine.isUsageHelpRequested() returns true if the parser matched an option annotated with usageHelp=true

    +
    • +
  • +

    CommandLine.isVersionHelpRequested() returns true if the parser matched an option annotated with versionHelp=true

    +
    • +
+
+
+
+
CommandLine commandLine = new CommandLine(new App());
+commandLine.parse(args);
+if (commandLine.isUsageHelpRequested()) {
+   commandLine.usage(System.out);
+   return;
+} else if (commandLine.isVersionHelpRequested()) {
+   commandLine.printVersionHelp(System.out);
+   return;
+}
+// ... run App's business logic
+
+
+
+

See also Parsing and Runnable and Callable for how picocli can help reduce boilerplate code.

+
+
+
+
+
+

8. Version Help

+
+
+

8.1. Static Version Information

+
+

Applications can specify version information in the version attribute of the @Command annotation.

+
+
+
+
@Command(version = "1.0")
+class VersionedCommand { ... }
+
+
+
+

The CommandLine.printVersionHelp(PrintStream) method extracts the version information from this +annotation and prints it to the specified PrintStream.

+
+
+
+
CommandLine commandLine = new CommandLine(new VersionedCommand());
+//...
+commandLine.printVersionHelp(System.out);
+
+
+
+

The version may specify multiple Strings, and may contain markup to show ANSI styles and colors. For example:

+
+
+
+
@Command(version = {
+        "@|yellow Versioned Command 1.0|@",
+        "@|blue Build 12345|@",
+        "@|red,bg(white) (c) 2017|@" })
+class VersionedCommand { ... }
+
+
+
+

The markup will be rendered as ANSI escape codes on supported systems.

+
+
+

Screenshot of version information containing markup with Ansi styles and colors

+
+
+
+

8.2. Dynamic Version Information

+
+

The @Command annotation supports a versionProvider attribute. +Applications may specify a IVersionProvider implementation in this attribute, and picocli will instantiate this class +and invoke it to collect version information.

+
+
+

The GitHub project has an +example +implementation that gets the version from the manifest file and another +example +that gets version information from a build-generated version properties file.

+
+
+
+
+
+

9. Usage Help

+
+
+

9.1. Example Usage Message

+
+

Picocli makes it easy for your application to generate a usage help message like this:

+
+
+
+
Usage: cat [-AbeEnstTuv] [--help] [--version] [FILE...]
+Concatenate FILE(s), or standard input, to standard output.
+      FILE                 Files whose contents to display
+  -A, --show-all           equivalent to -vET
+  -b, --number-nonblank    number nonempty output lines, overrides -n
+  -e                       equivalent to -vET
+  -E, --show-ends          display $ at end of each line
+  -n, --number             number all output lines
+  -s, --squeeze-blank      suppress repeated empty output lines
+  -t                       equivalent to -vT
+  -T, --show-tabs          display TAB characters as ^I
+  -u                       (ignored)
+  -v, --show-nonprinting   use ^ and M- notation, except for LDF and TAB
+      --help               display this help and exit
+      --version            output version information and exit
+Copyright(c) 2017
+
+
+
+

The usage help message is generated from annotation attributes, like below:

+
+
+
+
@Command(name = "cat", footer = "Copyright(c) 2017",
+         description = "Concatenate FILE(s), or standard input, to standard output.")
+class Cat {
+
+  @Parameters(paramLabel = "FILE", description = "Files whose contents to display")
+  List<File> files;
+
+  @Option(names = "--help", usageHelp = true, description = "display this help and exit")
+  boolean help;
+
+  @Option(names = "-t",                 description = "equivalent to -vT")  boolean t;
+  @Option(names = "-e",                 description = "equivalent to -vET") boolean e;
+  @Option(names = {"-A", "--show-all"}, description = "equivalent to -vET") boolean all;
+
+  // ...
+}
+
+
+
+
+

9.2. Usage Help Message Elements

+
+

The various elements of the usage help message are easily customized with annotations.

+
+
+

9.2.1. Command Name

+
+

In the above example, the program name is taken from the name attribute of the Command annotation:

+
+
+
+
@Command(name = "cat")
+
+
+
+

Without a name attribute, picocli will show a generic <main class> in the synopsis:

+
+
+
+
Usage: <main class> [-AbeEnstTuv] [--help] [--version] [FILE...]
+
+
+
+
+

9.2.2. Parameter Labels

+
+

Non-boolean options require a value. The usage help should explain this, and picocli shows the option parameter +in the synopsis and in the option list. By default, the field name is shown in < and > fish brackets. +Use the paramLabel attribute to display a different name. For example:

+
+
+
+
Usage: <main class> [-f=FILE] [-n=<number>] NUM <host>
+      NUM        number param
+      host       the host
+  -f= FILE       a file
+  -n= <number>   number option
+
+
+
+

Some annotated fields in the below example class have a paramLabel attribute and others don’t:

+
+
+
+
@Command()
+class ParamLabels {
+    @Option(names = "-f",    description = "a file",       paramLabel = "FILE") File f;
+    @Option(names = "-n",    description = "number option")                     int number;
+    @Parameters(index = "0", description = "number param", paramLabel = "NUM")  int n;
+    @Parameters(index = "1", description = "the host")                          InetAddress host;
+}
+
+
+
+
+

9.2.3. Unsorted Option List

+
+

By default the options list displays options in alphabetical order. Use the sortOptions = false attribute to display options in the order they are declared in your class.

+
+
+
+
@Command(sortOptions = false)
+
+
+
+
+

9.2.4. Abbreviated Synopsis

+
+

If a command is very complex and has many options, it is sometimes desirable to suppress details from the synopsis with the abbreviateSynopsis attribute. For example:

+
+
+
+
@Command(abbreviateSynopsis = true)
+class App { ... }
+
+
+
+

This shows the below synopsis. +Positional parameters are not abbreviated.

+
+
+
+
Usage: <main class> [OPTIONS] [<files>...]
+
+
+
+
+

9.2.5. Custom Synopsis

+
+

For even more control of the synopsis, use the customSynopsis attribute to specify one ore more synopsis lines. For example:

+
+
+
+
Usage: ln [OPTION]... [-T] TARGET LINK_NAME   (1st form)
+  or:  ln [OPTION]... TARGET                  (2nd form)
+  or:  ln [OPTION]... TARGET... DIRECTORY     (3rd form)
+  or:  ln [OPTION]... -t DIRECTORY TARGET...  (4th form)
+
+
+
+

To produce a synopsis like the above, specify the literal text in the customSynopsis attribute:

+
+
+
+
@Command(synopsisHeading = "", customSynopsis = {
+        "Usage: ln [OPTION]... [-T] TARGET LINK_NAME   (1st form)",
+        "  or:  ln [OPTION]... TARGET                  (2nd form)",
+        "  or:  ln [OPTION]... TARGET... DIRECTORY     (3rd form)",
+        "  or:  ln [OPTION]... -t DIRECTORY TARGET...  (4th form)",
+})
+class Ln { ... }
+
+
+
+
+

9.2.6. Header and Footer

+
+

The header will be shown at the top of the usage help message (before the synopsis). The first header line is also the line shown in the subcommand list if your command has subcommands (see Usage Help for Subcommands).

+
+
+

Use the footer attribute to specify one or more lines to show below the generated usage help message. +Each element of the attribute String array is displayed on a separate line.

+
+
+

The headerHeading and footerHeading may contain format specifiers. See Section Headings.

+
+
+
+

9.2.7. Section Headings

+
+

Section headers can be used to make usage message layout appear more spacious. Section headings may contain embedded line separator (%n) format specifiers:

+
+
+
+
@Command(name = "commit",
+        sortOptions = false,
+        headerHeading = "Usage:%n%n",
+        synopsisHeading = "%n",
+        descriptionHeading = "%nDescription:%n%n",
+        parameterListHeading = "%nParameters:%n",
+        optionListHeading = "%nOptions:%n",
+        header = "Record changes to the repository.",
+        description = "Stores the current contents of the index in a new commit " +
+                "along with a log message from the user describing the changes.")
+class GitCommit { ... }
+
+
+
+

The usage help message generated from this class is shown below in Expanded Example in the user manual.

+
+
+
+

9.2.8. Option-Parameter Separators

+
+

The separator displayed between options and option parameters (= by default) +in the synopsis and the option list can be configured with the separator attribute.

+
+
+
+
@Command(separator = ":")
+
+
+
+
+

9.2.9. Hidden Options and Parameters

+
+

Options and Parameters with the hidden attribute set to true will not be shown in the usage help message. +See the user manual for details.

+
+
+
+

9.2.10. Show Default Values

+
+

The default value for an option or positional parameter +can be embedded in the description by specifying the variable ${DEFAULT-VALUE} in the description text. +See the user manual for details.

+
+
+

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. +See the user manual for details.

+
+
+
+

9.2.11. Required-Option Marker

+
+

Required options can be marked in the option list by the character specified with the requiredOptionMarker attribute. +See the user manual for details.

+
+
+
+

9.2.12. Usage Width

+
+

The default width of the usage help message is 80 characters. +System property picocli.usage.width can be used to specify a custom width. +The minimum width that can be configured is 55 characters.

+
+
+

The width can also be set programmatically via the CommandLine::setUsageHelpWidth and UsageMessageSpec::width methods.

+
+
+
+
+
+
+

10. ANSI Colors and Styles

+
+
+

10.1. Colorized Example

+
+

Below shows the same usage help message as shown in the Expanded Example in the user manual, with ANSI escape codes enabled.

+
+
+

Screenshot of usage help with Ansi codes enabled

+
+
+
+

10.2. Usage Help with Styles and Colors

+
+

You can use colors and styles in the descriptions, header and footer +of the usage help message.

+
+
+

Picocli supports a custom markup notation for mixing colors and styles in text, +following a convention introduced by Jansi, where +@| starts a styled section, and |@ ends it. +Immediately following the @| is a comma-separated list of colors and styles, so @|STYLE1[,STYLE2]…​ text|@. +For example:

+
+
+
+
@Command(description = "Custom @|bold,underline styles|@ and @|fg(red) colors|@.")
+
+
+
+

Description with Ansi styles and colors

+
+ + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1. Pre-defined styles and colors that can be used in descriptions and headers using the @|STYLE1[,STYLE2]…​ text|@ notation
Pre-defined StylesPre-defined Colors

bold

black

faint

red

underline

green

italic

yellow

blink

blue

reverse

magenta

reset

cyan

white

+
+

Colors are applied as foreground colors by default. +You can set background colors by specifying bg(<color>). +For example, @|bg(red) text with red background|@. +Similarly, fg(<color>) explicitly sets the foreground color.

+
+
+

The example below shows how this markup can be used to add colors and styles to the headings and descriptions of a usage help message:

+
+
+
+
@Command(name = "commit",
+        sortOptions = false,
+        headerHeading = "@|bold,underline Usage|@:%n%n",
+        synopsisHeading = "%n",
+        descriptionHeading = "%n@|bold,underline Description|@:%n%n",
+        parameterListHeading = "%n@|bold,underline Parameters|@:%n",
+        optionListHeading = "%n@|bold,underline Options|@:%n",
+        header = "Record changes to the repository.",
+        description = "Stores the current contents of the index in a new commit " +
+                "along with a log message from the user describing the changes.")
+class GitCommit { ... }
+
+
+
+ + + + + +
+ + +Markup styles cannot be nested, for example: @|bold this @|underline that|@|@ will not work. You can achieve the same by combining styles, for example: @|bold this|@ @|bold,underline that|@ will work fine. +
+
+
+

10.2.1. More Colors

+
+

There are only eight pre-defined named colors, but most terminals support a 256 color indexed palette.

+
+
+

See the More Colors section of the user manual for using these colors as foreground or background colors.

+
+
+

256 color indexed palette

+
+
+
+

10.2.2. Color Scheme for Fixed Elements

+
+

Picocli uses a default color scheme for options, parameters and commands. +There are no annotations to modify this color scheme, but it can be changed programmatically and with system properties. +For details, see the Color Scheme section of the user manual.

+
+
+
+
+

10.3. Supported Platforms

+
+

Picocli will only emit ANSI escape codes on supported platforms. +This includes most Unix and Linux platforms. +See the Windows section of the user manual for the various options available to add coloring support to the Windows command console.

+
+
+
+

10.4. Forcing ANSI On/Off

+
+

You can force picocli to either always use ANSI codes or never use ANSI codes regardless of the platform:

+
+
+
    +
  • +

    Setting system property picocli.ansi to true forces picocli to use ANSI codes; setting picocli.ansi to false forces picocli to not use ANSI codes. This may be a useful facility for users of your command line application.

    +
    • +
  • +

    You can decide to force disable or force enable ANSI escape codes programmatically by specifying Ansi.ON or Ansi.OFF when invoking CommandLine.usage. +This overrides the value of system property picocli.ansi. For example:

    +
    • +
+
+
+
+
import picocli.CommandLine.Help.Ansi;
+
+App app = CommandLine.usage(new App(), System.out, Ansi.OFF, args);
+
+
+
+
+
+
+

11. Subcommands

+
+
+

11.1. Registering Subcommands

+
+

Subcommands can be registered programmatically or declaratively

+
+
+

11.1.1. Programmatically

+
+

Subcommands can be registered with the CommandLine.addSubcommand method. +You pass in the name of the command and the annotated object to populate with the subcommand options. +The specified name is used by the parser to recognize subcommands in the command line arguments.

+
+
+
+
CommandLine commandLine = new CommandLine(new Git())
+        .addSubcommand("status",   new GitStatus())
+        .addSubcommand("commit",   new GitCommit())
+        .addSubcommand("add",      new GitAdd())
+        .addSubcommand("branch",   new GitBranch())
+        .addSubcommand("checkout", new GitCheckout())
+        .addSubcommand("clone",    new GitClone())
+        .addSubcommand("diff",     new GitDiff())
+        .addSubcommand("merge",    new GitMerge())
+        .addSubcommand("push",     new GitPush())
+        .addSubcommand("rebase",   new GitRebase())
+        .addSubcommand("tag",      new GitTag());
+
+
+
+ + + + + +
+ + +Note on custom type converters: custom type converters are registered only with the subcommands and nested +sub-subcommands that were added before the custom type was registered. +To ensure a custom type converter is available to all subcommands, register the type converter last, after +adding subcommands. +
+
+
+
+

11.1.2. Declaratively

+
+

Subcommands can be registered declaratively with the @Command annotation’s subcommands attribute.

+
+
+
+
@Command(name = "git", subcommands = {
+    GitStatus.class,
+    GitCommit.class,
+    GitAdd.class,
+    GitBranch.class,
+    GitCheckout.class,
+    GitClone.class,
+    GitDiff.class,
+    GitMerge.class,
+    GitPush.class,
+    GitRebase.class,
+    GitTag.class
+})
+public class Git { ... }
+
+
+
+

The declared subcommands are automatically instantiated and added when the new CommandLine(new Git()) instance is constructed.

+
+
+

Subcommands referenced in a subcommands attribute must have a @Command annotation with a name attribute, or an exception is thrown from the CommandLine constructor.

+
+
+
+

11.1.3. Nesting Subcommands

+
+

Subcommands can be nested to any arbitrary level of depth. See the Nested sub-Subcommands section of the user manual for details.

+
+
+
+
+

11.2. Parsing Subcommands

+
+

For this example, we assume we created an alias git that invokes our Java application. This could also be a script or a function that calls our Java program:

+
+
+
+
alias git='java picocli.Demo$Git'
+
+
+
+

Next, we call our command with some arguments like this:

+
+
+
+
git --git-dir=/home/rpopma/picocli status -sb -uno
+
+
+
+

Where git (actually java picocli.Demo$Git) is the top-level command, followed by a global option and a subcommand status with its own options.

+
+
+

Setting up the parser and parsing the command line could look like this:

+
+
+
+
public static void main(String... args) {
+    // Set up the parser
+    CommandLine commandLine = new CommandLine(new Git());
+
+    // add subcommands programmatically (not necessary if the parent command
+    // declaratively registers the subcommands via annotation)
+    commandLine.addSubcommand("status",   new GitStatus())
+               .addSubcommand("commit",   new GitCommit())
+                ...
+
+    // Invoke the parse method to parse the arguments
+    List<CommandLine> parsed = commandLine.parse(args);
+    handleParseResult(parsed);
+}
+
+
+
+

The CommandLine.parse method returns a List with the recognized commands. The top-level command (the Java class invoked by git in this example) is always the first element in the returned list.

+
+
+

The returned List also contains all matched subcommands. Your application needs to inspect this list to see what subcommand was invoked and take appropriate action. For example:

+
+
+
+
private void handleParseResult(List<CommandLine> parsed) {
+    assert parsed.size() == 2 : "1 command and 1 subcommand found"
+
+    assert parsed.get(0).getCommand().getClass() == Git.class       : "main command"
+    assert parsed.get(1).getCommand().getClass() == GitStatus.class : "subcommand"
+
+    Git git = (Git) parsed.get(0).getCommand();
+    assert git.gitDir.equals(new File("/home/rpopma/picocli"));
+
+    GitStatus gitstatus = (GitStatus) parsed.get(1).getCommand();
+    assert  gitstatus.shortFormat              : "git status -s"
+    assert  gitstatus.branchInfo               : "git status -b"
+    assert !gitstatus.showIgnored              : "git status --showIgnored not specified"
+    assert  gitstatus.mode == GitStatusMode.no : "git status -u=no"
+}
+
+
+
+

You may be interested in the convenience methods for subcommands to reduce error handling and other boilerplate code in your application.

+
+
+
+

11.3. @ParentCommand Annotation

+
+

In command line applications with subcommands, options of the top level command are often intended as "global" options that apply to all the subcommands. +The @ParentCommand annotation makes it easy for subcommands to access their parent command options: subcommand fields annotated with @ParentCommand are initialized with a reference to the parent command. +The user manual has an example showing how to use the @ParentCommand annotation.

+
+
+
+

11.4. Usage Help for Subcommands

+
+

After registering subcommands, calling the commandLine.usage method will show a usage help message that includes all subcommands in the order they were registered. For example:

+
+
+
+
Usage: git [-hV] [--git-dir=<gitDir>]
+Git is a fast, scalable, distributed revision control system with an unusually
+rich command set that provides both high-level operations and full access to
+internals.
+      --git-dir=<gitDir>   Set the path to the repository.
+  -h, --help               Show this help message and exit.
+  -V, --version            Print version information and exit.
+
+Commands:
+
+The most commonly used git commands are:
+  help      Displays help information about the specified command
+  status    Show the working tree status.
+  commit    Record changes to the repository.
+  add       Add file contents to the index.
+  branch    List, create, or delete branches.
+  checkout  Checkout a branch or paths to the working tree.
+  clone     Clone a repository into a new directory.
+  diff      Show changes between commits, commit and working tree, etc.
+  merge     Join two or more development histories together.
+  push      Update remote refs along with associated objects.
+  rebase    Forward-port local commits to the updated upstream head.
+  tag       Create, list, delete or verify a tag object signed with GPG.
+
+
+
+

The description for the subcommand in the list is taken from the subcommand’s first header line, or, if the subcommand does not have a header annotation, from the description.

+
+
+

11.4.1. Hidden Subcommands

+
+

Commands with the hidden attribute set to true will not be shown in the usage help message of their parent command. +See the Hidden Subcommands section of the user manual for details.

+
+
+
+

11.4.2. Help Subcommands

+
+

Picocli has a built-in Help subcommand, +but see the Help Subcommands section of the user manual if you’re interested in creating a custom help command.

+
+
+
+
+
+
+

12. Reuse

+
+
+

You may find yourself defining the same options, parameters or command attributes in many command line applications. +To reduce duplication, picocli supports both subclassing and mixins as ways to reuse such options and attributes.

+
+
+

One way to reuse the above option and attributes is to extend the class. Picocli will walk the class hierarchy to check for annotations, so @Options, @Parameters and @Command attributes declared on a superclass are available in all subclasses.

+
+
+

A command can also include a mixin by annotating a field with @Mixin. All picocli annotations found in the mixin class +are added to the command that has a field annotated with @Mixin. For example:

+
+
+
+
@Command(name = "zip", description = "Example reuse with @Mixin annotation.")
+public class MyCommand {
+
+    // adds the options defined in ReusableOptions to this command
+    @Mixin
+    private ReusableOptions myMixin;
+    ...
+}
+
+
+
+

The Reuse section of the user manual has more extensive examples.

+
+
+
+
+

13. Parsing

+
+
+

When parsing the command line, an application needs to take care of the following:

+
+
+
    +
  • +

    If usage help was requested - show help message and exit

    +
    • +
  • +

    If version help was requested - show version information and exit

    +
    • +
  • +

    If the user input was invalid - show an error describing the problem and show the usage help

    +
    • +
  • +

    Execute the business logic

    +
    • +
+
+
+

In Java code, that roughly looks like the below:

+
+
+ + + + + +
+ + +In the next section we will show how to do the same in a single line of code, so keep reading…​ +
+
+
+
Before
+
+
Callable<Object> callable = new MyCallable();
+CommandLine cmd = new CommandLine(callable);
+try {
+    cmd.parse(args);
+    if (cmd.isUsageHelpRequested()) {
+        cmd.usage(System.out);
+        return null;
+    } else if (cmd.isVersionHelpRequested()) {
+        cmd.printVersionHelp(System.out);
+        return null;
+    }
+    return callable.call();
+} catch (ParameterException ex) {
+    System.err.println(ex.getMessage());
+    if (!UnmatchedArgumentException.printSuggestions(ex, System.err)) {
+        ex.getCommandLine().usage(System.err);
+    }
+    return null;
+} catch (Exception ex) {
+    throw new ExecutionException(cmd, "Error while calling " + callable, ex);
+}
+
+
+
+

13.1. Runnable and Callable

+
+

You can omit some of the boilerplate code from your application when the annotated object implements Runnable or Callable:

+
+
+
After
+
+
Object result = CommandLine.call(new MyCallable(), args);
+
+
+
+

The CommandLine.call method returns the result of the Callable, or null if the command line options were invalid. An error message and a usage help message are printed when the command line options were invalid. Exceptions thrown from the Callable.call method are caught, wrapped in an ExecutionException and rethrown.

+
+
+

When the annotated object implements Runnable, use the run method. For example:

+
+
+
+
CommandLine.run(new MyRunnable(), args);
+
+
+
+
+

13.2. Convenience Methods for Subcommands

+
+

If the command class has subcommands, the CommandLine::call and CommandLine::run convenience methods will execute the most specific subcommand on the command line. For example:

+
+
+
+
<command> -g global_option subcommand -x -y -z subsubcommand param1 param2
+
+
+
+

In the above example, the subsubcommand is the most specific subcommand, and only the Runnable or Callable associated with that subcommand will be executed by the CommandLine::call and CommandLine::run convenience methods.

+
+
+

The CommandLine::parseWithHandler and CommandLine::parseWithHandlers convenience methods are intended to offer the same ease of use as the run and call methods, but with more flexibility and better support for nested subcommands.

+
+
+

For example:

+
+
+
+
CommandLine cmd = new CommandLine(MyTopLevelCommand())
+        .addSubcommand("status",   new GitStatus())
+        .addSubcommand("commit",   new GitCommit())
+        .addSubcommand("add",      new GitAdd());
+List<Object> result = cmd.parseWithHandler(new RunAll(), args);
+
+
+
+

The CommandLine::parseWithHandler method will take care of the following:

+
+
+
    +
  • +

    parse the specified command line arguments

    +
    • +
  • +

    if the input was invalid, delegate to DefaultExceptionHandler, which will print the error message followed by the usage help message

    +
    • +
  • +

    otherwise, if the command line arguments were parsed successfully, let the specified IParseResultHandler2 handle the parse result

    +
    • +
+
+
+

Picocli provides some default IParseResultHandler2 implementations for common tasks:

+
+
+
    +
  • +

    the RunLast handler prints help if requested, and otherwise gets the last specified command or subcommand and tries to execute it as a Runnable or Callable

    +
    • +
  • +

    the RunFirst handler prints help if requested, and otherwise executes the top-level command as a Runnable or Callable

    +
    • +
  • +

    the RunAll handler prints help if requested, and otherwise executes all commands and subcommands that the user specified on the command line as Runnable or Callable tasks

    +
    • +
+
+
+
+

13.3. Parser Configuration

+
+

The picocli parser can be configured to be more strict or lenient. +You can instruct the parser to allow unknown options and other unmatched arguments, disallow POSIX clustered short options, and stop looking for options once a positional parameter or unmatched argument is found. +See the Parser Configuration section of the user manual for details.

+
+
+
+
+
+

14. Tracing

+
+
+

Picocli supports parser tracing to facilitate troubleshooting. +System property picocli.trace controls the trace level. Supported levels are OFF, WARN, INFO, and DEBUG. The default trace level is WARN.

+
+
+

Specifying system property -Dpicocli.trace without a value will set the trace level to INFO.

+
+
+
    +
  • +

    DEBUG: Shows details of the decisions made by the parser during command line parsing.

    +
    • +
  • +

    INFO: Shows a high-level overview of what happens during command line parsing.

    +
    • +
  • +

    WARN: The default. Shows warnings instead of errors when lenient parsing is enabled: +when single-value options were specified multiple times (and CommandLine.overwrittenOptionsAllowed is true), +or when command line arguments could not be matched as an option or positional parameter +(and CommandLine.unmatchedArgumentsAllowed is true).

    +
    • +
  • +

    OFF: Suppresses all tracing including warnings.

    +
    • +
+
+
+

Example:

+
+
+
+
# create a custom 'mygit' command that invokes picocli.Demo$Git with tracing switched on
+alias mygit='java -Dpicocli.trace -cp picocli-all.jar picocli.Demo$Git'
+
+# invoke our command with some parameters
+mygit --git-dir=/home/rpopma/picocli commit -m "Fixed typos" -- src1.java src2.java src3.java
+
+
+
+

Output:

+
+
+
+
[picocli INFO] Parsing 8 command line args [--git-dir=/home/rpopma/picocli, commit, -m, "Fixed typos", --, src1.java, src2.java, src3.java]
+[picocli INFO] Setting File field 'Git.gitDir' to '\home\rpopma\picocli' for option --git-dir
+[picocli INFO] Adding [Fixed typos] to List<String> field 'GitCommit.message' for option -m
+[picocli INFO] Found end-of-options delimiter '--'. Treating remainder as positional parameters.
+[picocli INFO] Adding [src1.java] to List<String> field 'GitCommit.files' for args[0..*]
+[picocli INFO] Adding [src2.java] to List<String> field 'GitCommit.files' for args[0..*]
+[picocli INFO] Adding [src3.java] to List<String> field 'GitCommit.files' for args[0..*]
+
+
+
+
+
+

15. TAB Autocomplete

+
+
+

Picocli-based applications can now have command line completion in Bash or Zsh Unix shells. +See the Autocomplete for Java Command Line Applications manual for how to generate an autocompletion script tailored to your application.

+
+
+
+
+

16. More

+
+
+

To keep this Quick Guide short (or at least, short-ish) some things had to be left out. Here are some quick links in case you are interested:

+
+
+ +
+
+

Don’t forget to star the project on GitHub if you like it! +Your stars keep me going! :-)

+
+
+
+
+ + + \ No newline at end of file