Class CommandLine

public CommandLine addSubcommand(String name, Object command)

Registers a subcommand with the specified name.For example:

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()) //... ;

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()) // subcommand .addSubcommand("cmd2", new ChildCommand2()) .addSubcommand("cmd3", new CommandLine(new ChildCommand3()) // subcommand with nested sub-subcommands .addSubcommand("cmd3sub1", new GrandChild3Command1()) .addSubcommand("cmd3sub2", new GrandChild3Command2()) .addSubcommand("cmd3sub3", new CommandLine(new GrandChild3Command3()) // deeper nesting .addSubcommand("cmd3sub3sub1", new GreatGrandChild3Command3_1()) .addSubcommand("cmd3sub3sub2", new GreatGrandChild3Command3_2()) ) );

The default type converters are available on all subcommands and nested sub-subcommands, but custom type converters are registered only with the subcommand hierarchy as it existed when the custom type was registered. To ensure a custom type converter is available to all subcommands, register the type converter last, after adding subcommands.

See also the Command#subcommands() annotation to register subcommands declaratively.

Parameters:

name - the string to recognize on the command line as a subcommand. If null, the name of the specified subcommand is used; if this is also null, the first alias is used.

command - the object to initialize with command line arguments following the subcommand name. This may be a Class that has a @Command annotation, or an instance of such a class, or a CommandSpec or CommandLine instance with its own (nested) subcommands.

Returns:

this CommandLine object, to allow method chaining

Since:

0.9.7

See Also:

registerConverter

subcommands

addSubcommand

public CommandLine addSubcommand(String name, Object command, String[] aliases)

Registers a subcommand with the specified name and all specified aliases.See also addSubcommand.addSubcommand.

Parameters:

name - the string to recognize on the command line as a subcommand. If null, the name of the specified subcommand is used; if this is also null, the first alias is used.

command - the object to initialize with command line arguments following the subcommand name. This may be a Class that has a @Command annotation, or an instance of such a class, or a CommandSpec or CommandLine instance with its own (nested) subcommands.

aliases - zero or more alias names that are also recognized on the command line as this subcommand

Returns:

this CommandLine object, to allow method chaining

Since:

3.1

See Also:

getSubcommands

public Map<String, CommandLine> getSubcommands()

Returns a map with the subcommands addSubcommand.addSubcommand on this instance.

Returns:

a map with the registered subcommands

Since:

0.9.7

getParent

public CommandLine getParent()

Returns the command that this is a subcommand of, or null if this is a top-level command.

Returns:

the command that this is a subcommand of, or null if this is a top-level command

Since:

0.9.8

See Also:

allowSubcommandsAsOptionParameters

subcommands

getCommand

public T getCommand()

Returns the annotated user object that this CommandLine instance was constructed with.

Returns:

the annotated object that this CommandLine instance was constructed with

Since:

0.9.7

getFactory

public IFactory getFactory()

Returns the factory that this CommandLine was constructed with.

Returns:

the factory that this CommandLine was constructed with, never null

Since:

4.6

isUsageHelpRequested

public boolean isUsageHelpRequested()

Returns true if an option annotated with Option#usageHelp() was specified on the command line.

Returns:

whether the parser encountered an option annotated with Option#usageHelp().

Since:

0.9.8

isVersionHelpRequested

public boolean isVersionHelpRequested()

Returns true if an option annotated with Option#versionHelp() was specified on the command line.

Returns:

whether the parser encountered an option annotated with Option#versionHelp().

Since:

0.9.8

getHelp

public Help getHelp()

Returns a new Help object created by the IHelpFactory with the CommandSpec and ColorScheme of this command.

Since:

4.1

See Also:

getHelpFactory

public IHelpFactory getHelpFactory()

Returns the IHelpFactory that is used to construct the usage help message.

Since:

3.9

See Also:

setHelpFactory

public CommandLine setHelpFactory(IHelpFactory helpFactory)

Sets a new IHelpFactory to customize the usage help message.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

helpFactory - the new help factory. Must be non-null.

Returns:

this CommandLine object, to allow method chaining

Since:

3.9

getHelpSectionKeys

public List<String> getHelpSectionKeys()

Returns the section keys in the order that the usage help message should render the sections.This ordering may be modified with setHelpSectionKeys.setHelpSectionKeys. The default keys are (in order):

UsageMessageSpec#SECTION_KEY_HEADER_HEADING UsageMessageSpec#SECTION_KEY_HEADER UsageMessageSpec#SECTION_KEY_SYNOPSIS_HEADING UsageMessageSpec#SECTION_KEY_SYNOPSIS UsageMessageSpec#SECTION_KEY_DESCRIPTION_HEADING UsageMessageSpec#SECTION_KEY_DESCRIPTION UsageMessageSpec#SECTION_KEY_PARAMETER_LIST_HEADING UsageMessageSpec#SECTION_KEY_AT_FILE_PARAMETER UsageMessageSpec#SECTION_KEY_PARAMETER_LIST UsageMessageSpec#SECTION_KEY_OPTION_LIST_HEADING UsageMessageSpec#SECTION_KEY_OPTION_LIST UsageMessageSpec#SECTION_KEY_COMMAND_LIST_HEADING UsageMessageSpec#SECTION_KEY_COMMAND_LIST UsageMessageSpec#SECTION_KEY_EXIT_CODE_LIST_HEADING UsageMessageSpec#SECTION_KEY_EXIT_CODE_LIST UsageMessageSpec#SECTION_KEY_FOOTER_HEADING UsageMessageSpec#SECTION_KEY_FOOTER

Since:

3.9

setHelpSectionKeys

public CommandLine setHelpSectionKeys(List<String> keys)

Sets the section keys in the order that the usage help message should render the sections.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Use UsageMessageSpec#sectionKeys(List) to customize a command without affecting its subcommands.

Since:

3.9

See Also:

getHelpSectionKeys

getHelpSectionMap

public Map<String, IHelpSectionRenderer> getHelpSectionMap()

Returns the map of section keys and renderers used to construct the usage help message.The usage help message can be customized by adding, replacing and removing section renderers from this map. Sections can be reordered with setHelpSectionKeys.setHelpSectionKeys. Sections that are either not in this map or not in the list returned by getHelpSectionKeys.getHelpSectionKeys are omitted.

NOTE: By modifying the returned Map, only the usage help message of this command is affected. Use setHelpSectionMap.setHelpSectionMap to customize the usage help message for this command and all subcommands.

Since:

3.9

setHelpSectionMap

public CommandLine setHelpSectionMap(Map<String, IHelpSectionRenderer> map)

Sets the map of section keys and renderers used to construct the usage help message.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Use UsageMessageSpec#sectionMap(Map) to customize a command without affecting its subcommands.

Since:

3.9

See Also:

getHelpSectionMap

isAdjustLineBreaksForWideCJKCharacters

public boolean isAdjustLineBreaksForWideCJKCharacters()

Returns whether line breaks should take wide Chinese, Japanese and Korean characters into account for line-breaking purposes.The default is true.

Returns:

true if wide Chinese, Japanese and Korean characters are counted as double the size of other characters for line-breaking purposes

Since:

4.0

setAdjustLineBreaksForWideCJKCharacters

public CommandLine setAdjustLineBreaksForWideCJKCharacters(boolean adjustForWideChars)

Sets whether line breaks should take wide Chinese, Japanese and Korean characters into account, and returns this UsageMessageSpec.The default is true.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

adjustForWideChars - if true, wide Chinese, Japanese and Korean characters are counted as double the size of other characters for line-breaking purposes

Since:

4.0

isToggleBooleanFlags

public boolean isToggleBooleanFlags()

Returns whether the value of boolean flag options should be "toggled" when the option is matched.From 4.0, this is false by default, and when a flag option is specified on the command line picocli will set its value to the opposite of its default value. If this method returns true, flags are toggled, so if the value is true it is set to false, and when the value is false it is set to true. When toggling is enabled, specifying a flag option twice on the command line will have no effect because they cancel each other out.

Returns:

true the value of boolean flag options should be "toggled" when the option is matched, false otherwise

Since:

3.0

setToggleBooleanFlags

public CommandLine setToggleBooleanFlags(boolean newValue)

Sets whether the value of boolean flag options should be "toggled" when the option is matched.The default is false, and when a flag option is specified on the command line picocli will set its value to the opposite of its default value.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

newValue - the new setting

Returns:

this CommandLine object, to allow method chaining

Since:

3.0

isInterpolateVariables

public boolean isInterpolateVariables()

Returns whether variables should be interpolated in String values.The default is true.

Since:

4.0

setInterpolateVariables

public CommandLine setInterpolateVariables(boolean interpolate)

Sets whether variables should be interpolated in String values.The default is true.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Since:

4.0

isOverwrittenOptionsAllowed

public boolean isOverwrittenOptionsAllowed()

Returns whether options for single-value fields can be specified multiple times on the command line.The default is false and a OverwrittenOptionException is thrown if this happens. When true, the last specified value is retained.

Returns:

true if options for single-value fields can be specified multiple times on the command line, false otherwise

Since:

0.9.7

setOverwrittenOptionsAllowed

public CommandLine setOverwrittenOptionsAllowed(boolean newValue)

Sets whether options for single-value fields can be specified multiple times on the command line without a OverwrittenOptionException being thrown.The default is false.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

newValue - the new setting

Returns:

this CommandLine object, to allow method chaining

Since:

0.9.7

isPosixClusteredShortOptionsAllowed

public boolean isPosixClusteredShortOptionsAllowed()

Returns whether the parser accepts clustered short options.The default is true.

Returns:

true if short options like -x -v -f SomeFile can be clustered together like -xvfSomeFile, false otherwise

Since:

3.0

setPosixClusteredShortOptionsAllowed

public CommandLine setPosixClusteredShortOptionsAllowed(boolean newValue)

Sets whether short options like -x -v -f SomeFile can be clustered together like -xvfSomeFile.The default is true.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

newValue - the new setting

Returns:

this CommandLine object, to allow method chaining

Since:

3.0

isCaseInsensitiveEnumValuesAllowed

public boolean isCaseInsensitiveEnumValuesAllowed()

Returns whether the parser should ignore case when converting arguments to enum values.The default is false.

Returns:

true if enum values can be specified that don't match the toString() value of the enum constant, false otherwise; e.g., for an option of type java.time.DayOfWeek, values MonDaY, monday and MONDAY are all recognized if true.

Since:

3.4

setCaseInsensitiveEnumValuesAllowed

public CommandLine setCaseInsensitiveEnumValuesAllowed(boolean newValue)

Sets whether the parser should ignore case when converting arguments to enum values.The default is false. When set to true, for example, for an option of type java.time.DayOfWeek, values MonDaY, monday and MONDAY are all recognized if true.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

newValue - the new setting

Returns:

this CommandLine object, to allow method chaining

Since:

3.4

isTrimQuotes

public boolean isTrimQuotes()

Returns whether the parser should trim quotes from command line arguments.The default is read from the system property "picocli.trimQuotes" and will be true if the property is present and empty, or if its value is "true".

If this property is set to true, the parser will remove quotes from the command line arguments, as follows:

if the command line argument contains just the leading and trailing quote, these quotes are removed if the command line argument contains more quotes than just the leading and trailing quote, the parser first tries to process the parameter with the quotes intact. For example, the split regular expression inside a quoted region should be ignored, so arguments like "a,b","x,y" are handled correctly. For arguments with nested quotes, quotes are removed later in the processing pipeline, after split operations are applied.

Returns:

true if the parser should trim quotes from command line arguments before processing them, false otherwise;

Since:

3.7

See Also:

trimQuotes

setTrimQuotes

public CommandLine setTrimQuotes(boolean newValue)

Sets whether the parser should trim quotes from command line arguments before processing them.The default is read from the system property "picocli.trimQuotes" and will be true if the property is set and empty, or if its value is "true".

If this property is set to true, the parser will remove quotes from the command line arguments, as follows:

if the command line argument contains just the leading and trailing quote, these quotes are removed if the command line argument contains more quotes than just the leading and trailing quote, the parser first tries to process the parameter with the quotes intact. For example, the split regular expression inside a quoted region should be ignored, so arguments like "a,b","x,y" are handled correctly. For arguments with nested quotes, quotes are removed later in the processing pipeline, after split operations are applied.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Calling this method will cause the "picocli.trimQuotes" property to have no effect.

Parameters:

newValue - the new setting

Returns:

this CommandLine object, to allow method chaining

Since:

3.7

See Also:

trimQuotes

isSplitQuotedStrings

public boolean isSplitQuotedStrings()

Returns whether the parser is allowed to split quoted Strings or not.The default is false, so quotes are respected: quoted strings are treated as a single value that should not be broken up.

For example, take a single command line parameter "a,b","x,y". With a comma split regex, the default of splitQuotedStrings = false means that this value will be split into two strings: "a,b" and "x,y". This is usually what you want.

If splitQuotedStrings is set to true, quotes are not respected, and the value is split up into four parts: the first is "a, the second is b", the third is "x, and the last part is y". This is generally not what you want.

Deprecation

Most applications should not change the default. The rare application that does need to split parameter values

without respecting quotes should use ParserSpec#splitQuotedStrings(boolean).

Returns:

true if the parser is allowed to split quoted Strings, false otherwise;

Since:

3.7

See Also:

splitRegex

splitQuotedStrings

setSplitQuotedStrings

public CommandLine setSplitQuotedStrings(boolean newValue)

Sets whether the parser is allowed to split quoted Strings.The default is false, so quotes are respected: quoted strings are treated as a single value that should not be broken up.

For example, take a single command line parameter "a,b","x,y". With a comma split regex, the default of splitQuotedStrings = false means that this value will be split into two strings: "a,b" and "x,y". This is usually what you want.

However, if splitQuotedStrings is set to true, quotes are not respected, and the value is split up into four parts: the first is "a, the second is b", the third is "x, and the last part is y". This is generally not what you want.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Deprecation

Most applications should not change the default. The rare application that does need to split parameter values

without respecting quotes should use ParserSpec#splitQuotedStrings(boolean).

Parameters:

newValue - the new setting

Returns:

this CommandLine object, to allow method chaining

Since:

3.7

See Also:

splitRegex

splitQuotedStrings

getEndOfOptionsDelimiter

public String getEndOfOptionsDelimiter()

Returns the end-of-options delimiter that signals that the remaining command line arguments should be treated as positional parameters.

Returns:

the end-of-options delimiter. The default is "--".

Since:

3.5

setEndOfOptionsDelimiter

public CommandLine setEndOfOptionsDelimiter(String delimiter)

Sets the end-of-options delimiter that signals that the remaining command line arguments should be treated as positional parameters.

Parameters:

delimiter - the end-of-options delimiter; must not be null. The default is "--".

Returns:

this CommandLine object, to allow method chaining

Since:

3.5

isSubcommandsCaseInsensitive

public boolean isSubcommandsCaseInsensitive()

Returns whether upper case and lower case should be ignored when matching subcommands.The default is false.

Returns:

true if subcommands can be matched when they differ only in case from the getCommandName() value of a registered one, false otherwise. For example, if true, for a subcommand with name help, inputs like help, HeLp and HELP are all recognized.

Since:

4.3

setSubcommandsCaseInsensitive

public CommandLine setSubcommandsCaseInsensitive(boolean newValue)

Sets whether upper case and lower case should be ignored when matching subcommands.The default is false. For example, when set to true, for a subcommand with name help, inputs like help, HeLp and HELP are all recognized.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

newValue - the new setting

Returns:

this CommandLine object, to allow method chaining

Since:

4.3

isOptionsCaseInsensitive

public boolean isOptionsCaseInsensitive()

Returns whether upper case and lower case should be ignored when matching option names.The default is false.

Returns:

true if options can be matched when they differ only in case from the names() value of a registered one, false otherwise; For example, if true, for an option with name -h, inputs like -h, -H are both recognized.

Since:

4.3

setOptionsCaseInsensitive

public CommandLine setOptionsCaseInsensitive(boolean newValue)

Sets whether upper case and lower case should be ignored when matching option names.The default is false. For example, when set to true, for an option with name -h, inputs like -h, -H are both recognized.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands. Note that changing case sensitivity will also change the case sensitivity of negatable options: any custom INegatableOptionTransformer that was previously installed will be replaced by the case-insensitive version of the default transformer. To ensure your custom transformer is used, install it last, after changing case sensitivity.

Parameters:

newValue - the new setting

Returns:

this CommandLine object, to allow method chaining

Since:

4.3

isAbbreviatedSubcommandsAllowed

public boolean isAbbreviatedSubcommandsAllowed()

Returns whether abbreviation of subcommands should be allowed when matching subcommands.The default is false.

Returns:

true if subcommands can be matched when they are abbreviations of the getCommandName() value of a registered one, false otherwise. For example, if true, for a subcommand with name helpCommand, inputs like h, h-c and hC are all recognized.

Since:

4.4

setAbbreviatedSubcommandsAllowed

public CommandLine setAbbreviatedSubcommandsAllowed(boolean newValue)

Sets whether abbreviated subcommands should be matched.The default is false. For example, when set to true, for a subcommand helpCommand, inputs like h, h-c and hC are all recognized.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

newValue - the new setting

Returns:

this CommandLine object, to allow method chaining

Since:

4.4

isAbbreviatedOptionsAllowed

public boolean isAbbreviatedOptionsAllowed()

Returns whether abbreviation of option names should be allowed when matching options.The default is false.

Returns:

true if options can be matched when they are abbreviations of the names() value of a registered one, false otherwise. For example, if true, for a subcommand with name --helpMe, inputs like --h, --h-m and --hM are all recognized.

Since:

4.4

setAbbreviatedOptionsAllowed

public CommandLine setAbbreviatedOptionsAllowed(boolean newValue)

Sets whether abbreviated option names should be matched.The default is false. For example, when set to true, for an option with name --helpMe, inputs like --h, --h-m and --hM are all recognized.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

newValue - the new setting

Returns:

this CommandLine object, to allow method chaining

Since:

4.4

getDefaultValueProvider

public IDefaultValueProvider getDefaultValueProvider()

Returns the default value provider for the command, or null if none has been set.

Returns:

the default value provider for this command, or null

Since:

3.6

See Also:

defaultValueProvider

defaultValueString

setDefaultValueProvider

public CommandLine setDefaultValueProvider(IDefaultValueProvider newValue)

Sets a default value provider for the command and sub-commands

The specified setting will be registered with this CommandLine and the full hierarchy of its sub-commands and nested sub-subcommands at the moment this method is called. Sub-commands added later will have the default setting. To ensure a setting is applied to all sub-commands, call the setter last, after adding sub-commands.

Parameters:

newValue - the default value provider to use

Returns:

this CommandLine object, to allow method chaining

Since:

3.6

isStopAtPositional

public boolean isStopAtPositional()

Returns whether the parser interprets the first positional parameter as "end of options" so the remaining arguments are all treated as positional parameters.The default is false.

Returns:

true if all values following the first positional parameter should be treated as positional parameters, false otherwise

Since:

2.3

setStopAtPositional

public CommandLine setStopAtPositional(boolean newValue)

Sets whether the parser interprets the first positional parameter as "end of options" so the remaining arguments are all treated as positional parameters.The default is false.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

newValue - true if all values following the first positional parameter should be treated as positional parameters, false otherwise

Returns:

this CommandLine object, to allow method chaining

Since:

2.3

isStopAtUnmatched

public boolean isStopAtUnmatched()

Returns whether the parser should stop interpreting options and positional parameters as soon as it encounters an unmatched option.Unmatched options are arguments that look like an option but are not one of the known options, or positional arguments for which there is no available slots (the command has no positional parameters or their size is limited). The default is false.

Setting this flag to true automatically sets the isUnmatchedArgumentsAllowed.isUnmatchedArgumentsAllowed flag to true also.

Returns:

true when an unmatched option should result in the remaining command line arguments to be added to the getUnmatchedArguments.getUnmatchedArguments

Since:

2.3

setStopAtUnmatched

public CommandLine setStopAtUnmatched(boolean newValue)

Sets whether the parser should stop interpreting options and positional parameters as soon as it encounters an unmatched option.Unmatched options are arguments that look like an option but are not one of the known options, or positional arguments for which there is no available slots (the command has no positional parameters or their size is limited). The default is false.

Setting this flag to true automatically sets the setUnmatchedArgumentsAllowed.setUnmatchedArgumentsAllowed flag to true also.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

newValue - true when an unmatched option should result in the remaining command line arguments to be added to the getUnmatchedArguments.getUnmatchedArguments

Returns:

this CommandLine object, to allow method chaining

Since:

2.3

isAllowSubcommandsAsOptionParameters

public boolean isAllowSubcommandsAsOptionParameters()

Returns whether options can have parameter values that match subcommand names or aliases, or whether such values should be rejected with a missing parameter exception.The default is false, so by default input like -x=subcommand is rejected if -x is an option that takes a String parameter, and subcommand is a subcommand of this command.

Returns:

true when options can have parameter values that match subcommand names or aliases, false when such values should be rejected with a missing parameter exception

Since:

4.7.8-SNAPSHOT

See Also:

setAllowSubcommandsAsOptionParameters

public CommandLine setAllowSubcommandsAsOptionParameters(boolean newValue)

Sets whether options can have parameter values that match subcommand names or aliases, or whether such values should be rejected with a missing parameter exception.The default is false, so by default input like -x=subcommand is rejected if -x is an option that takes a String parameter, and subcommand is a subcommand of this command.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

newValue - the new setting. When true, options can have parameter values that match subcommand names or aliases, when false, such values are rejected with a missing parameter exception

Returns:

this CommandLine object, to allow method chaining

Since:

4.7.8-SNAPSHOT

See Also:

allowSubcommandsAsOptionParameters

isAllowOptionsAsOptionParameters

public boolean isAllowOptionsAsOptionParameters()

Returns whether options can have parameter values that match the name of an option in this command, or whether such values should be rejected with a missing parameter exception.The default is false, so by default input like -x=--some-option is rejected if -x is an option that takes a String parameter, and --some-option is an option of this command.

This method only considers actual options of this command, as opposed to isUnmatchedOptionsAllowedAsOptionParameters.isUnmatchedOptionsAllowedAsOptionParameters, which considers values that resemble options.

Returns:

true when options can have parameter values that match the name of an option in this command, false when such values should be rejected with a missing parameter exception

Since:

4.7.8-SNAPSHOT

allowOptionsAsOptionParameters

setAllowOptionsAsOptionParameters

public CommandLine setAllowOptionsAsOptionParameters(boolean newValue)

Sets whether options can have parameter values that match the name of an option in this command, or whether such values should be rejected with a missing parameter exception.The default is false, so by default input like -x=--some-option is rejected if -x is an option that takes a String parameter, and --some-option is an option of this command.

This method only considers actual options of this command, as opposed to setUnmatchedOptionsAllowedAsOptionParameters.setUnmatchedOptionsAllowedAsOptionParameters, which considers values that resemble options.

Use with caution! When set to true, any option in the command will consume the maximum number of arguments possible for its arity. This means that an option with arity = "*" will consume all command line arguments following that option. If this is not what you want, consider custom parameter processing.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

newValue - the new setting. When true, options can have parameter values that match the name of an option in this command, when false, such values are rejected with a missing parameter exception

Returns:

this CommandLine object, to allow method chaining

Since:

4.7.8-SNAPSHOT

allowOptionsAsOptionParameters

isUnmatchedOptionsAllowedAsOptionParameters

public boolean isUnmatchedOptionsAllowedAsOptionParameters()

Returns whether options can have parameter values that resemble an option, or whether such values should be rejected as unknown options.The default is true, so by default input like -x=-unknown is accepted if -x is an option that takes a String parameter.

This method only considers values that resemble options, as opposed to isAllowOptionsAsOptionParameters.isAllowOptionsAsOptionParameters, which considers actual options of this command.

Returns:

true when options can have parameter values that resemble an option, false when such values should be rejected as unknown options

Since:

4.4

See Also:

isAllowOptionsAsOptionParameters

unmatchedOptionsAllowedAsOptionParameters

setUnmatchedOptionsAllowedAsOptionParameters

public CommandLine setUnmatchedOptionsAllowedAsOptionParameters(boolean newValue)

Sets whether options can have parameter values that resemble an option, or whether such values should be rejected as unknown options.The default is true, so by default input like -x=-unknown is accepted if -x is an option that takes a String parameter.

This method only considers values that resemble options, as opposed to setAllowOptionsAsOptionParameters.setAllowOptionsAsOptionParameters, which considers actual options of this command.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

newValue - the new setting. When true, options can have parameter values that resemble an option, when false, such values are rejected as unknown options

Returns:

this CommandLine object, to allow method chaining

Since:

4.4

See Also:

setAllowOptionsAsOptionParameters

unmatchedOptionsAllowedAsOptionParameters

isUnmatchedOptionsArePositionalParams

public boolean isUnmatchedOptionsArePositionalParams()

Returns whether arguments on the command line that resemble an option should be treated as positional parameters.The default is false and the parser behaviour depends on isUnmatchedArgumentsAllowed.isUnmatchedArgumentsAllowed.

Returns:

true arguments on the command line that resemble an option should be treated as positional parameters, false otherwise

Since:

3.0

See Also:

setUnmatchedOptionsArePositionalParams

public CommandLine setUnmatchedOptionsArePositionalParams(boolean newValue)

Sets whether arguments on the command line that resemble an option should be treated as positional parameters.The default is false.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

newValue - the new setting. When true, arguments on the command line that resemble an option should be treated as positional parameters.

Returns:

this CommandLine object, to allow method chaining

Since:

3.0

See Also:

isUnmatchedArgumentsAllowed

public boolean isUnmatchedArgumentsAllowed()

Returns whether the end user may specify arguments on the command line that are not matched to any option or parameter fields.The default is false and a UnmatchedArgumentException is thrown if this happens. When true, the last unmatched arguments are available via the getUnmatchedArguments.getUnmatchedArguments method.

Returns:

true if the end use may specify unmatched arguments on the command line, false otherwise

Since:

0.9.7

See Also:

setUnmatchedArgumentsAllowed

public CommandLine setUnmatchedArgumentsAllowed(boolean newValue)

Sets whether the end user may specify unmatched arguments on the command line without a UnmatchedArgumentException being thrown.The default is false.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

newValue - the new setting. When true, the last unmatched arguments are available via the getUnmatchedArguments.getUnmatchedArguments method.

Returns:

this CommandLine object, to allow method chaining

Since:

0.9.7

See Also:

isUnmatchedArgumentsAllowed

public List<String> getUnmatchedArguments()

Returns the list of unmatched command line arguments, if any.

Returns:

the list of unmatched command line arguments or an empty list

Since:

0.9.7

See Also:

getColorScheme

public ColorScheme getColorScheme()

Returns the color scheme to use when printing help.The default value is the default color scheme with Help.Ansi#AUTO.

Since:

4.0

See Also:

setColorScheme

public CommandLine setColorScheme(ColorScheme colorScheme)

Sets the color scheme to use when printing help.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

colorScheme - the new color scheme

Since:

4.0

See Also:

getParameterExceptionHandler

getUsageMessage

getOut

public PrintWriter getOut()

Returns the writer used when printing user-requested usage help or version help during command execute.execute.Defaults to a PrintWriter wrapper around System.out unless setOut.setOut was called with a different writer.

This method is used by execute.execute. Custom IExecutionStrategy implementations should also use this writer.

By convention, when the user requests help with a --help or similar option, the usage help message is printed to the standard output stream so that it can be easily searched and paged.

Since:

4.0

setOut

public CommandLine setOut(PrintWriter out)

Sets the writer to use when printing user-requested usage help or version help during command execute.execute.

This method is used by execute.execute. Custom IExecutionStrategy implementations should also use this writer.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

out - the new PrintWriter to use

Returns:

this CommandLine for method chaining

Since:

4.0

getErr

public PrintWriter getErr()

Returns the writer to use when printing diagnostic (error) messages during command execute.execute.Defaults to a PrintWriter wrapper around System.err, unless setErr.setErr was called with a different writer.

This method is used by execute.execute. IParameterExceptionHandler and IExecutionExceptionHandler implementations should use this writer to print error messages (which may include a usage help message) when an unexpected error occurs.

Since:

4.0

setErr

public CommandLine setErr(PrintWriter err)

Sets the writer to use when printing diagnostic (error) messages during command execute.execute.

This method is used by execute.execute. IParameterExceptionHandler and IExecutionExceptionHandler implementations should use this writer to print error messages (which may include a usage help message) when an unexpected error occurs.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

err - the new PrintWriter to use

Returns:

this CommandLine for method chaining

Since:

4.0

getExitCodeExceptionMapper

public IExitCodeExceptionMapper getExitCodeExceptionMapper()

Returns the mapper that was set by the application to map from exceptions to exit codes, for use by the execute.execute method.

Returns:

the mapper that was setExitCodeExceptionMapper.setExitCodeExceptionMapper, or null if none was set

Since:

4.0

setExitCodeExceptionMapper

public CommandLine setExitCodeExceptionMapper(IExitCodeExceptionMapper exitCodeExceptionMapper)

Sets the mapper used by the execute.execute method to map exceptions to exit codes.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

exitCodeExceptionMapper - the new value

Returns:

this CommandLine for method chaining

Since:

4.0

getExecutionStrategy

public IExecutionStrategy getExecutionStrategy()

Returns the execution strategy used by the execute.execute method to invoke the business logic on the user objects of this command and/or the user-specified subcommand(s).The default value is RunLast.

Returns:

the execution strategy to run the user-specified command

Since:

4.0

setExecutionStrategy

public CommandLine setExecutionStrategy(IExecutionStrategy executionStrategy)

Sets the execution strategy that the execute.execute method should use to invoke the business logic on the user objects of this command and/or the user-specified subcommand(s).

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

executionStrategy - the new execution strategy to run the user-specified command

Returns:

this CommandLine for method chaining

Since:

4.0

getParameterExceptionHandler

public IParameterExceptionHandler getParameterExceptionHandler()

Returns the handler for dealing with invalid user input when the command is execute.execute.

The default implementation prints an error message describing the problem, followed by either suggested alternatives for mistyped options, or the full usage.usage help message of the problematic command; it then delegates to the getExitCodeExceptionMapper.getExitCodeExceptionMapper for an exit code, with CommandSpec#exitCodeOnInvalidInput() as the default exit code.

Alternatively, you can install a "short error message handler" like this:

static class ShortErrorMessageHandler implements IParameterExceptionHandler { public int handleParseException(ParameterException ex, String[] args) { CommandLine cmd = ex.getCommandLine(); PrintWriter writer = cmd.getErr();

    writer.println(ex.getMessage());
    UnmatchedArgumentException.printSuggestions(ex, writer);
    writer.print(cmd.getHelp().fullSynopsis());

    CommandSpec spec = cmd.getCommandSpec();
    writer.printf("Try '%s --help' for more information.%n", spec.qualifiedName());

    return cmd.getExitCodeExceptionMapper() != null
                ? cmd.getExitCodeExceptionMapper().getExitCode(ex)
                : spec.exitCodeOnInvalidInput();
}

}

Install this error handler like this:

new CommandLine(new MyApp()) .setParameterExceptionHandler(new ShortErrorMessageHandler()) .execute(args);

Returns:

the handler for dealing with invalid user input

Since:

4.0

setParameterExceptionHandler

public CommandLine setParameterExceptionHandler(IParameterExceptionHandler parameterExceptionHandler)

Sets the handler for dealing with invalid user input when the command is execute.execute.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

parameterExceptionHandler - the new handler for dealing with invalid user input

Returns:

this CommandLine for method chaining

Since:

4.0

See Also:

getExecutionExceptionHandler

public IExecutionExceptionHandler getExecutionExceptionHandler()

Returns the handler for dealing with exceptions that occurred in the Callable, Runnable or Method user object of a command when the command was execute.execute.

The default implementation rethrows the specified exception.

Returns:

the handler for dealing with exceptions that occurred in the business logic when the execute.execute method was invoked.

Since:

4.0

setExecutionExceptionHandler

public CommandLine setExecutionExceptionHandler(IExecutionExceptionHandler executionExceptionHandler)

Sets a custom handler for dealing with exceptions that occurred in the Callable, Runnable or Method user object of a command when the command was executed via the execute.execute method.

The specified setting will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

Parameters:

executionExceptionHandler - the handler for dealing with exceptions that occurred in the business logic when the execute.execute method was invoked.

Returns:

this CommandLine for method chaining

Since:

4.0

populateCommand

public static T populateCommand(T command, String[] args)

Convenience method that initializes the specified annotated object from the specified command line arguments.

This is equivalent to

new CommandLine(command).parseArgs(args); return command;

All this method does is parse the arguments and populate the annotated fields and methods. The caller is responsible for catching any exceptions, handling requests for usage help or version information, and invoking the business logic. Applications may be interested in using the execute.execute method instead.

Parameters:

command - the object to initialize. This object contains fields annotated with @Option or @Parameters.

args - the command line arguments to parse

Returns:

the specified annotated object

Since:

0.9.7

See Also:

populateSpec

public static T populateSpec(Class spec, String[] args)

Convenience method that derives the command specification from the specified interface class, and returns an instance of the specified interface.The interface is expected to have annotated getter methods. Picocli will instantiate the interface and the getter methods will return the option and positional parameter values matched on the command line.

This is equivalent to

CommandLine cli = new CommandLine(spec); cli.parse(args); return cli.getCommand();

All this method does is parse the arguments and return an instance whose annotated methods return the specified values. The caller is responsible for catching any exceptions, handling requests for usage help or version information, and invoking the business logic. Applications may be interested in using the execute.execute method instead.

Parameters:

spec - the interface that defines the command specification. This object contains getter methods annotated with @Option or @Parameters.

args - the command line arguments to parse

Returns:

an instance of the specified annotated interface

Since:

3.1

See Also:

parse

public List<CommandLine> parse(String[] args)

Expands any CommandLine.isExpandAtFiles in the specified command line arguments, then parses the 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.

If parsing succeeds, the first element in the returned list is always this CommandLine object. The returned list may contain more elements if subcommands were addSubcommand.addSubcommand and these subcommands were initialized by matching command line arguments. If parsing fails, a ParameterException is thrown.

All this method does is parse the arguments and populate the annotated fields and methods. The caller is responsible for catching any exceptions, handling requests for usage help or version information, and invoking the business logic. Applications may be interested in using the execute.execute method instead.

Deprecation

use parseArgs.parseArgs instead

Parameters:

args - the command line arguments to parse

Returns:

a list with the top-level command and any subcommands initialized by this method

parseArgs

public ParseResult parseArgs(String[] args)

Expands any CommandLine.isExpandAtFiles in the specified command line arguments, then parses the arguments and returns a ParseResult with the options, positional parameters, and subcommands (if any) that were recognized and initialized during the parsing process.

If parsing fails, a ParameterException is thrown.

All this method does is parse the arguments and populate the annotated fields and methods. The caller is responsible for catching any exceptions, handling requests for usage help or version information, and invoking the business logic. Applications may be interested in using the execute.execute method instead.

Parameters:

args - the command line arguments to parse

Returns:

a list with the top-level command and any subcommands initialized by this method

See Also:

getParseResult

public ParseResult getParseResult()

getExecutionResult

public T getExecutionResult()

Returns the result of calling the user object Callable or invoking the user object Method after parsing the user input, or null if this command has not been execute.execute or if this CommandLine is for a subcommand that was not specified by the end user on the command line.

Implementation note:

It is the responsibility of the IExecutionStrategy to set this value.

Returns:

the result of the user object Callable or Method (may be null), or null if this (sub)command was not executed

Since:

4.0

setExecutionResult

public void setExecutionResult(Object result)

Sets the result of calling the business logic on the command's user object.

Parameters:

result - the business logic result, may be null

Since:

4.0

See Also:

IHelpCommandInitializable2

IExecutionStrategy

clearExecutionResults

public void clearExecutionResults()

Clears the getExecutionResult.getExecutionResult of a previous invocation from this CommandLine and all subcommands.

Since:

4.0

defaultExceptionHandler

public static io.github.qishr.cascara.common.util.CommandLine.DefaultExceptionHandler<java.util.List<Object> defaultExceptionHandler()

Convenience method that returns new DefaultExceptionHandler<List<Object>>().

printHelpIfRequested

public static boolean printHelpIfRequested(List<CommandLine> parsedCommands, PrintStream out, Ansi ansi)

Deprecation

use printHelpIfRequested.printHelpIfRequested instead

Since:

2.0

printHelpIfRequested

public static boolean printHelpIfRequested(ParseResult parseResult)

Delegates to executeHelpRequest.executeHelpRequest.

Parameters:

parseResult - contains the CommandLine objects found during parsing; check these to see if help was requested

Returns:

true if help was printed, false otherwise

Since:

3.0

printHelpIfRequested

public static boolean printHelpIfRequested(List<CommandLine> parsedCommands, PrintStream out, PrintStream err, Ansi ansi)

Delegates to the implementation of executeHelpRequest.executeHelpRequest.

Deprecation

use executeHelpRequest.executeHelpRequest instead

Parameters:

parsedCommands - the list of CommandLine objects to check if help was requested

out - the PrintStream to print help to if requested

err - the error string to print diagnostic messages to, in addition to the output from the exception handler

ansi - for printing help messages using ANSI styles and colors

Returns:

true if help was printed, false otherwise

Since:

3.0

printHelpIfRequested

public static boolean printHelpIfRequested(List<CommandLine> parsedCommands, PrintStream out, PrintStream err, ColorScheme colorScheme)

Delegates to the implementation of executeHelpRequest.executeHelpRequest.

Deprecation

use executeHelpRequest.executeHelpRequest instead

Parameters:

parsedCommands - the list of CommandLine objects to check if help was requested

out - the PrintStream to print help to if requested

err - the error string to print diagnostic messages to, in addition to the output from the exception handler

colorScheme - for printing help messages using ANSI styles and colors

Returns:

true if help was printed, false otherwise

Since:

3.6

executeHelpRequest

public static Integer executeHelpRequest(ParseResult parseResult)

Helper method that may be useful when processing the ParseResult that results from successfully parseArgs.parseArgs command line arguments.This method prints out usage.usage to the CommandLine.getOut if isUsageHelpRequested.isUsageHelpRequested or printVersionHelp.printVersionHelp to the CommandLine.getOut if isVersionHelpRequested.isVersionHelpRequested and returns CommandSpec#exitCodeOnUsageHelp() or CommandSpec#exitCodeOnVersionHelp(), respectively. If the command is a Command#helpCommand() and runnable or callable, that command is executed and this method returns CommandSpec#exitCodeOnUsageHelp(). Otherwise, if none of the specified CommandLine objects have help requested, this method returns null.

Note that this method only looks at the Option#usageHelp() and Option#versionHelp() attributes. The Option#help() attribute is ignored.

Implementation note:

When an error occurs while processing the help request, it is recommended custom Help commands throw a ParameterException with a reference to the parent command. This will print the error message and the usage for the parent command, and will use the exit code of the exception handler if one was set.

Parameters:

parseResult - contains the CommandLine objects found during parsing; check these to see if help was requested

Returns:

CommandSpec#exitCodeOnUsageHelp() if usage help was requested, CommandSpec#exitCodeOnVersionHelp() if version help was requested, and null otherwise

Since:

4.0

See Also:

execute

public int execute(String[] args)

Convenience method to allow command line application authors to avoid some boilerplate code in their application.To use this method, the annotated object that this CommandLine is constructed with needs to either implement Runnable, Callable, or be a Method object. See getCommandMethods.getCommandMethods for a convenient way to obtain a command Method.

This method replaces the run.run, call.call and invoke.invoke convenience methods that were available with previous versions of picocli.

Exit Code

This method returns an exit code that applications can use to call System.exit. (The return value of the Callable or Method can still be obtained via getExecutionResult.getExecutionResult.) If the user object Callable or Method returns an int or Integer, this will be used as the exit code. Additionally, if the user object implements CommandLine.IExitCodeGenerator, an exit code is obtained by calling its getExitCode() method (after invoking the user object).

In the case of multiple exit codes the highest value will be used (or if all values are negative, the lowest value will be used).

Exception Handling

This method never throws an exception.

If the user specified invalid input, the getParameterExceptionHandler.getParameterExceptionHandler is invoked. By default this prints an error message and the usage help message, and returns an exit code.

If an exception occurred while the user object Runnable, Callable, or Method was invoked, this exception is caught and passed to the getExecutionExceptionHandler.getExecutionExceptionHandler. The default IExecutionExceptionHandler will rethrow this Exception.

Any exception thrown from the IParameterExceptionHandler or IExecutionExceptionHandler is caught, it stacktrace is printed and is mapped to an exit code, using the following logic:

If an CommandLine.IExitCodeExceptionMapper is setExitCodeExceptionMapper.setExitCodeExceptionMapper, this mapper is used to determine the exit code based on the exception.

If an IExitCodeExceptionMapper is not set, by default this method will return the @Command annotation's Command#exitCodeOnInvalidInput() or Command#exitCodeOnExecutionException() value, respectively.

Example Usage:

Command class MyCommand implements CallableInteger { public Integer call() { return 123; } } CommandLine cmd = new CommandLine(new MyCommand()); int exitCode = cmd.execute(args); assert exitCode == 123; System.exit(exitCode);

Since execute is an instance method, not a static method, applications can do configuration before invoking the command. For example: CommandLine cmd = new CommandLine(new MyCallable()) .setCaseInsensitiveEnumValuesAllowed(true) // configure a non-default parser option .setOut(myOutWriter()) // configure an alternative to System.out .setErr(myErrWriter()) // configure an alternative to System.err .setColorScheme(myColorScheme()); // configure a custom color scheme int exitCode = cmd.execute(args); System.exit(exitCode);

If the specified command has subcommands, the RunLast subcommand specified on the command line is executed. This can be configured by setting the setExecutionStrategy.setExecutionStrategy. Built-in alternatives are executing the RunFirst subcommand, or executing RunAll specified subcommands.

Parameters:

args - the command line arguments to parse

Returns:

the exit code

Since:

4.0

See Also:

getParameterExceptionHandler

getExecutionExceptionHandler

getExitCodeExceptionMapper

parseWithHandler

public List<Object> parseWithHandler(IParseResultHandler handler, PrintStream out, String[] args)

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Since:

2.0

parseWithHandler

public R parseWithHandler(IParseResultHandler2 handler, String[] args)

Returns the result of calling parseWithHandlers.parseWithHandlers with a new DefaultExceptionHandler in addition to the specified parse result handler and the specified command line arguments.

This is a convenience method intended to offer the same ease of use as the run.run and call.call methods, but with more flexibility and better support for nested subcommands.

Calling this method roughly expands to: try { ParseResult parseResult = parseArgs(args); return handler.handleParseResult(parseResult); } catch (ParameterException ex) { return new DefaultExceptionHandler<R>().handleParseException(ex, args); }

Picocli provides some default handlers that allow you to accomplish some common tasks with very little code. The following handlers are available:

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. RunFirst handler prints help if requested, and otherwise executes the top-level command as a Runnable or Callable. RunAll handler prints help if requested, and otherwise executes all recognized commands and subcommands as Runnable or Callable tasks. DefaultExceptionHandler prints the error message followed by usage help

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Parameters:

handler - the function that will handle the result of successfully parsing the command line arguments

args - the command line arguments

Returns:

an object resulting from handling the parse result or the exception that occurred while parsing the input

Since:

3.0

See Also:

RunAll

parseWithHandlers

public List<Object> parseWithHandlers(IParseResultHandler handler, PrintStream out, Ansi ansi, IExceptionHandler exceptionHandler, String[] args)

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Since:

2.0

parseWithHandlers

public R parseWithHandlers(IParseResultHandler2 handler, IExceptionHandler2 exceptionHandler, String[] args)

Tries to parseArgs.parseArgs the specified command line arguments, and if successful, delegates the processing of the resulting ParseResult object to the specified IParseResultHandler2.If the command line arguments were invalid, the ParameterException thrown from the parse method is caught and passed to the specified IExceptionHandler2.

This is a convenience method intended to offer the same ease of use as the run.run and call.call methods, but with more flexibility and better support for nested subcommands.

Calling this method roughly expands to:

ParseResult parseResult = null; try { parseResult = parseArgs(args); return handler.handleParseResult(parseResult); } catch (ParameterException ex) { return exceptionHandler.handleParseException(ex, (String[]) args); } catch (ExecutionException ex) { return exceptionHandler.handleExecutionException(ex, parseResult); }

Picocli provides some default handlers that allow you to accomplish some common tasks with very little code. The following handlers are available:

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. RunFirst handler prints help if requested, and otherwise executes the top-level command as a Runnable or Callable. RunAll handler prints help if requested, and otherwise executes all recognized commands and subcommands as Runnable or Callable tasks. DefaultExceptionHandler prints the error message followed by usage help

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Parameters:

handler - the function that will handle the result of successfully parsing the command line arguments

exceptionHandler - the function that can handle the ParameterException thrown when the command line arguments are invalid

args - the command line arguments

Returns:

an object resulting from handling the parse result or the exception that occurred while parsing the input

Since:

3.0

See Also:

RunAll

DefaultExceptionHandler

usage

public static void usage(Object command, PrintStream out)

Equivalent to new CommandLine(command).usage(out).See usage.usage for details.

Parameters:

command - the object annotated with Command, Option and Parameters

out - the print stream to print the help message to

usage

public static void usage(Object command, PrintStream out, Ansi ansi)

Equivalent to new CommandLine(command).usage(out, ansi).See usage.usage for details.

Parameters:

command - the object annotated with Command, Option and Parameters

out - the print stream to print the help message to

ansi - whether the usage message should contain ANSI escape codes or not

usage

public static void usage(Object command, PrintStream out, ColorScheme colorScheme)

Equivalent to new CommandLine(command).usage(out, colorScheme).See usage.usage for details.

Parameters:

command - the object annotated with Command, Option and Parameters

out - the print stream to print the help message to

colorScheme - the ColorScheme defining the styles for options, parameters and commands when ANSI is enabled

usage

public void usage(PrintStream out)

Delegates to usage.usage with the getColorScheme.getColorScheme color scheme.

Parameters:

out - the printStream to print to

See Also:

public void usage(PrintWriter writer)

Delegates to usage.usage with the getColorScheme.getColorScheme color scheme.

Parameters:

writer - the PrintWriter to print to

Since:

3.0

See Also:

public void usage(PrintStream out, Ansi ansi)

Delegates to usage.usage with the default color scheme.

Parameters:

out - the printStream to print to

ansi - whether the usage message should include ANSI escape codes or not

See Also:

public void usage(PrintWriter writer, Ansi ansi)

Similar to usage.usage but with the specified PrintWriter instead of a PrintStream.

Since:

3.0

usage

public void usage(PrintStream out, ColorScheme colorScheme)

Prints a usage help message for the annotated command class to the specified PrintStream.Delegates construction of the usage help message to the Help inner class and is equivalent to:

Help.ColorScheme colorScheme = Help.defaultColorScheme(Help.Ansi.AUTO); Help help = getHelpFactory().create(getCommandSpec(), colorScheme) StringBuilder sb = new StringBuilder(); for (String key : getHelpSectionKeys()) { IHelpSectionRenderer renderer = getHelpSectionMap().get(key); if (renderer != null) { sb.append(renderer.render(help)); } } out.print(sb);

Annotate your class with Command to control many aspects of the usage help message, including the program name, text of section headings and section contents, and some aspects of the auto-generated sections of the usage help message.

To customize the auto-generated sections of the usage help message, like how option details are displayed, instantiate a Help object and use a Help.TextTable with more of fewer columns, a custom layout, and/or a custom option renderer for ultimate control over which aspects of an Option or Field are displayed where.

Parameters:

out - the PrintStream to print the usage help message to

colorScheme - the ColorScheme defining the styles for options, parameters and commands when ANSI is enabled

See Also:

UsageMessageSpec

usage

public void usage(PrintWriter writer, ColorScheme colorScheme)

Similar to usage.usage, but with the specified PrintWriter instead of a PrintStream.

Since:

3.0

getUsageMessage

public String getUsageMessage()

Similar to usage.usage, but returns the usage help message as a String instead of printing it to the PrintStream.

Since:

3.2

getUsageMessage

public String getUsageMessage(Ansi ansi)

Similar to usage.usage, but returns the usage help message as a String instead of printing it to the PrintStream.

Since:

3.2

getUsageMessage

public String getUsageMessage(ColorScheme colorScheme)

Similar to usage.usage, but returns the usage help message as a String instead of printing it to the PrintStream.

Since:

3.2

printVersionHelp

public void printVersionHelp(PrintStream out)

Delegates to printVersionHelp.printVersionHelp with the ANSI setting of the getColorScheme.getColorScheme color scheme.

Parameters:

out - the printStream to print to

Since:

0.9.8

See Also:

printVersionHelp

public void printVersionHelp(PrintStream out, Ansi ansi)

Prints version information from the Command#version() annotation to the specified PrintStream.Each element of the array of version strings is printed on a separate line. Version strings may contain markup for colors and style.

Parameters:

out - the printStream to print to

ansi - whether the usage message should include ANSI escape codes or not

Since:

0.9.8

See Also:

version

versionHelp

isVersionHelpRequested

printVersionHelp

public void printVersionHelp(PrintStream out, Ansi ansi, Object[] params)

Prints version information from the Command#version() annotation to the specified PrintStream.Each element of the array of version strings is formatted with the specified parameters, and printed on a separate line. Both version strings and parameters may contain markup for colors and style.

Parameters:

out - the printStream to print to

ansi - whether the usage message should include ANSI escape codes or not

params - Arguments referenced by the format specifiers in the version strings

Since:

1.0.0

See Also:

version

versionHelp

isVersionHelpRequested

printVersionHelp

public void printVersionHelp(PrintWriter out)

Delegates to printVersionHelp.printVersionHelp with the ANSI setting of the getColorScheme.getColorScheme color scheme.

Parameters:

out - the PrintWriter to print to

Since:

4.0

printVersionHelp

public void printVersionHelp(PrintWriter out, Ansi ansi, Object[] params)

Prints version information from the Command#version() annotation to the specified PrintWriter.Each element of the array of version strings is formatted with the specified parameters, and printed on a separate line. Both version strings and parameters may contain markup for colors and style.

Parameters:

out - the PrintWriter to print to

ansi - whether the usage message should include ANSI escape codes or not

params - Arguments referenced by the format specifiers in the version strings

Since:

4.0

See Also:

version

versionHelp

isVersionHelpRequested

call

public static T call(C callable, String[] args)

Equivalent to new CommandLine(callable).execute(args), except for the return value.

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Parameters:

callable - the command to call when parseArgs.parseArgs succeeds.

args - the command line arguments to parse

Returns:

null if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the Callable

Since:

3.0

See Also:

call

public static T call(C callable, PrintStream out, String[] args)

Delegates to call.call with System.err for diagnostic error messages and Help.Ansi#AUTO.

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Parameters:

callable - the command to call when parseArgs.parseArgs succeeds.

out - the printStream to print the usage help message to when the user requested help

args - the command line arguments to parse

Returns:

null if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the Callable

See Also:

call

public static T call(C callable, PrintStream out, Ansi ansi, String[] args)

Delegates to call.call with System.err for diagnostic error messages.

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Parameters:

callable - the command to call when parseArgs.parseArgs succeeds.

out - the printStream to print the usage help message to when the user requested help

ansi - the ANSI style to use

args - the command line arguments to parse

Returns:

null if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the Callable

See Also:

call

public static T call(C callable, PrintStream out, PrintStream err, Ansi ansi, String[] args)

Convenience method to allow command line application authors to avoid some boilerplate code in their application.The annotated object needs to implement Callable.

Consider using the execute.execute method instead: CommandLine cmd = new CommandLine(callable) .setOut(myOutWriter()) // System.out by default .setErr(myErrWriter()) // System.err by default .setColorScheme(myColorScheme()); // default color scheme, Ansi.AUTO by default int exitCode = cmd.execute(args); //System.exit(exitCode);

If the specified Callable command has subcommands, the RunLast subcommand specified on the command line is executed.

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Parameters:

callable - the command to call when parse.parse succeeds.

out - the printStream to print the usage help message to when the user requested help

err - the printStream to print diagnostic messages to

ansi - including whether the usage message should include ANSI escape codes or not

args - the command line arguments to parse

Returns:

null if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the Callable

Since:

3.0

call

public static T call(Class callableClass, IFactory factory, String[] args)

Equivalent to new CommandLine(callableClass, factory).execute(args), except for the return value.

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Parameters:

callableClass - class of the command to call when parseArgs.parseArgs succeeds.

factory - the factory responsible for instantiating the specified callable class and potentially inject other components

args - the command line arguments to parse

Returns:

null if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the Callable

Since:

3.2

See Also:

call

public static T call(Class callableClass, IFactory factory, PrintStream out, String[] args)

Delegates to call.call with System.err for diagnostic error messages, and Help.Ansi#AUTO.

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Parameters:

callableClass - class of the command to call when parseArgs.parseArgs succeeds.

factory - the factory responsible for instantiating the specified callable class and potentially injecting other components

out - the printStream to print the usage help message to when the user requested help

args - the command line arguments to parse

Returns:

null if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the Callable

Since:

3.2

call

public static T call(Class callableClass, IFactory factory, PrintStream out, Ansi ansi, String[] args)

Delegates to call.call with System.err for diagnostic error messages.

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Parameters:

callableClass - class of the command to call when parseArgs.parseArgs succeeds.

factory - the factory responsible for instantiating the specified callable class and potentially injecting other components

out - the printStream to print the usage help message to when the user requested help

ansi - the ANSI style to use

args - the command line arguments to parse

Returns:

null if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the Callable

Since:

3.2

call

public static T call(Class callableClass, IFactory factory, PrintStream out, PrintStream err, Ansi ansi, String[] args)

Convenience method to allow command line application authors to avoid some boilerplate code in their application.The specified IFactory will create an instance of the specified callableClass; use this method instead of call.call if you want to use a factory that performs Dependency Injection. The annotated class needs to implement Callable.

Consider using the execute.execute method instead: CommandLine cmd = new CommandLine(callableClass, factory) .setOut(myOutWriter()) // System.out by default .setErr(myErrWriter()) // System.err by default .setColorScheme(myColorScheme()); // default color scheme, Ansi.AUTO by default int exitCode = cmd.execute(args); //System.exit(exitCode);

If the specified Callable command has subcommands, the RunLast subcommand specified on the command line is executed.

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Parameters:

callableClass - class of the command to call when parseArgs.parseArgs succeeds.

factory - the factory responsible for instantiating the specified callable class and potentially injecting other components

out - the printStream to print the usage help message to when the user requested help

err - the printStream to print diagnostic messages to

ansi - the ANSI style to use

args - the command line arguments to parse

Returns:

null if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the Callable

Since:

3.2

run

public static void run(R runnable, String[] args)

Equivalent to new CommandLine(runnable).execute(args).

Deprecation

use execute.execute instead

Parameters:

runnable - the command to run when parseArgs.parseArgs succeeds.

args - the command line arguments to parse

Since:

3.0

See Also:

run

public static void run(R runnable, PrintStream out, String[] args)

Delegates to run.run with System.err for diagnostic error messages and Help.Ansi#AUTO.

Deprecation

use execute.execute instead

Parameters:

runnable - the command to run when parseArgs.parseArgs succeeds.

out - the printStream to print the usage help message to when the user requested help

args - the command line arguments to parse

See Also:

run

public static void run(R runnable, PrintStream out, Ansi ansi, String[] args)

Delegates to run.run with System.err for diagnostic error messages.

Deprecation

use execute.execute instead

Parameters:

runnable - the command to run when parseArgs.parseArgs succeeds.

out - the printStream to print the usage help message to when the user requested help

ansi - whether the usage message should include ANSI escape codes or not

args - the command line arguments to parse

See Also:

run

public static void run(R runnable, PrintStream out, PrintStream err, Ansi ansi, String[] args)

Convenience method to allow command line application authors to avoid some boilerplate code in their application.The annotated object needs to implement Runnable.

Consider using the execute.execute method instead: CommandLine cmd = new CommandLine(runnable) .setOut(myOutWriter()) // System.out by default .setErr(myErrWriter()) // System.err by default .setColorScheme(myColorScheme()); // default color scheme, Ansi.AUTO by default int exitCode = cmd.execute(args); //System.exit(exitCode);

If the specified Runnable command has subcommands, the RunLast subcommand specified on the command line is executed.

From picocli v2.0, this method prints usage help or version help if printHelpIfRequested.printHelpIfRequested, and any exceptions thrown by the Runnable are caught and rethrown wrapped in an ExecutionException.

Deprecation

use execute.execute instead

Parameters:

runnable - the command to run when parse.parse succeeds.

out - the printStream to print the usage help message to when the user requested help

err - the printStream to print diagnostic messages to

ansi - whether the usage message should include ANSI escape codes or not

args - the command line arguments to parse

Since:

3.0

run

public static void run(Class runnableClass, IFactory factory, String[] args)

Equivalent to new CommandLine(runnableClass, factory).execute(args).

Deprecation

use execute.execute instead

Parameters:

runnableClass - class of the command to run when parseArgs.parseArgs succeeds.

factory - the factory responsible for instantiating the specified Runnable class and potentially injecting other components

args - the command line arguments to parse

Since:

3.2

See Also:

run

public static void run(Class runnableClass, IFactory factory, PrintStream out, String[] args)

Delegates to run.run with System.err for diagnostic error messages, and Help.Ansi#AUTO.

Deprecation

use execute.execute instead

Parameters:

runnableClass - class of the command to run when parseArgs.parseArgs succeeds.

factory - the factory responsible for instantiating the specified Runnable class and potentially injecting other components

out - the printStream to print the usage help message to when the user requested help

args - the command line arguments to parse

Since:

3.2

See Also:

run

run

public static void run(Class runnableClass, IFactory factory, PrintStream out, Ansi ansi, String[] args)

Delegates to run.run with System.err for diagnostic error messages.

Deprecation

use execute.execute instead

Parameters:

runnableClass - class of the command to run when parseArgs.parseArgs succeeds.

factory - the factory responsible for instantiating the specified Runnable class and potentially injecting other components

out - the printStream to print the usage help message to when the user requested help

ansi - whether the usage message should include ANSI escape codes or not

args - the command line arguments to parse

Since:

3.2

See Also:

run

run

public static void run(Class runnableClass, IFactory factory, PrintStream out, PrintStream err, Ansi ansi, String[] args)

Convenience method to allow command line application authors to avoid some boilerplate code in their application.The specified IFactory will create an instance of the specified runnableClass; use this method instead of run.run if you want to use a factory that performs Dependency Injection. The annotated class needs to implement Runnable.

Consider using the execute.execute method instead: CommandLine cmd = new CommandLine(runnableClass, factory) .setOut(myOutWriter()) // System.out by default .setErr(myErrWriter()) // System.err by default .setColorScheme(myColorScheme()); // default color scheme, Ansi.AUTO by default int exitCode = cmd.execute(args); //System.exit(exitCode);

If the specified Runnable command has subcommands, the RunLast subcommand specified on the command line is executed.

This method prints usage help or version help if printHelpIfRequested.printHelpIfRequested, and any exceptions thrown by the Runnable are caught and rethrown wrapped in an ExecutionException.

Deprecation

use execute.execute instead

Parameters:

runnableClass - class of the command to run when parseArgs.parseArgs succeeds.

factory - the factory responsible for instantiating the specified Runnable class and potentially injecting other components

out - the printStream to print the usage help message to when the user requested help

err - the printStream to print diagnostic messages to

ansi - whether the usage message should include ANSI escape codes or not

args - the command line arguments to parse

Since:

3.2

invoke

public static Object invoke(String methodName, Class<?> cls, String[] args)

Delegates to invoke.invoke with System.out for requested usage help messages, System.err for diagnostic error messages, and Help.Ansi#AUTO.

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Parameters:

methodName - the @Command-annotated method to build a CommandSpec model from, and run when parseArgs.parseArgs succeeds.

cls - the class where the @Command-annotated method is declared, or a subclass

args - the command line arguments to parse

Since:

3.6

See Also:

invoke

public static Object invoke(String methodName, Class<?> cls, PrintStream out, String[] args)

Delegates to invoke.invoke with the specified stream for requested usage help messages, System.err for diagnostic error messages, and Help.Ansi#AUTO.

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Parameters:

methodName - the @Command-annotated method to build a CommandSpec model from, and run when parseArgs.parseArgs succeeds.

cls - the class where the @Command-annotated method is declared, or a subclass

out - the printstream to print requested help message to

args - the command line arguments to parse

Since:

3.6

See Also:

invoke

public static Object invoke(String methodName, Class<?> cls, PrintStream out, Ansi ansi, String[] args)

Delegates to invoke.invoke with the specified stream for requested usage help messages, System.err for diagnostic error messages, and the specified Ansi mode.

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Parameters:

methodName - the @Command-annotated method to build a CommandSpec model from, and run when parseArgs.parseArgs succeeds.

cls - the class where the @Command-annotated method is declared, or a subclass

out - the printstream to print requested help message to

ansi - whether the usage message should include ANSI escape codes or not

args - the command line arguments to parse

Since:

3.6

See Also:

invoke

public static Object invoke(String methodName, Class<?> cls, PrintStream out, PrintStream err, Ansi ansi, String[] args)

Convenience method to allow command line application authors to avoid some boilerplate code in their application.Constructs a CommandSpec model from the @Option and @Parameters-annotated method parameters of the @Command-annotated method, parses the specified command line arguments and invokes the specified method.

Consider using the execute.execute method instead: Method commandMethod = getCommandMethods(cls, methodName).get(0); CommandLine cmd = new CommandLine(commandMethod) .setOut(myOutWriter()) // System.out by default .setErr(myErrWriter()) // System.err by default .setColorScheme(myColorScheme()); // default color scheme, Ansi.AUTO by default int exitCode = cmd.execute(args); //System.exit(exitCode);

Deprecation

use execute.execute and getExecutionResult.getExecutionResult instead

Parameters:

methodName - the @Command-annotated method to build a CommandSpec model from, and run when parseArgs.parseArgs succeeds.

cls - the class where the @Command-annotated method is declared, or a subclass

out - the printStream to print the usage help message to when the user requested help

err - the printStream to print diagnostic messages to

ansi - whether the usage message should include ANSI escape codes or not

args - the command line arguments to parse

Since:

3.6

getCommandMethods

public static List<Method> getCommandMethods(Class<?> cls, String methodName)

Helper to get methods of a class annotated with Command via reflection, optionally filtered by method name (not Command#name()).Methods have to be either public (inherited) members or be declared by cls, that is "inherited" static or protected methods will not be picked up.

Parameters:

cls - the class to search for methods annotated with @Command

methodName - if not null, return only methods whose method name (not Command#name()) equals this string. Ignored if null.

Returns:

the matching command methods, or an empty list

Since:

3.6.0

See Also:

registerConverter

public CommandLine registerConverter(Class cls, ITypeConverter converter)

Registers the specified type converter for the specified class.When initializing fields annotated with Option, the field's type is used as a lookup key to find the associated type converter, and this type converter converts the original command line argument string value to the correct type.

Java 8 lambdas make it easy to register custom type converters:

commandLine.registerConverter(java.nio.file.Path.class, s - java.nio.file.Paths.get(s)); commandLine.registerConverter(java.time.Duration.class, s - java.time.Duration.parse(s));

Built-in type converters are pre-registered for the following java 1.5 types:

all primitive types all primitive wrapper types: Boolean, Byte, Character, Double, Float, Integer, Long, Short any enum java.io.File java.math.BigDecimal java.math.BigInteger java.net.InetAddress java.net.URI java.net.URL java.nio.charset.Charset java.sql.Time java.util.Date java.util.UUID java.util.regex.Pattern StringBuilder CharSequence String

The specified converter will be registered with this CommandLine and the full hierarchy of its subcommands and nested sub-subcommands at the moment the converter is registered. Subcommands added later will not have this converter added automatically. To ensure a custom type converter is available to all subcommands, register the type converter last, after adding subcommands.

Parameters:

cls - the target class to convert parameter string values to

converter - the class capable of converting string values to the specified target type

Returns:

this CommandLine object, to allow method chaining

See Also: