Package io.github.qishr.cascara.common.util
Class CommandSpec
java.lang.Object
        io.github.qishr.cascara.common.util.CommandLine.Model.CommandSpec
Enclosing Class:
    io.github.qishr.cascara.common.util.CommandLine.Model
public static class CommandSpec
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.
Picocli views a command line application as a hierarchy of commands: there is a top-level command (usually the Java
class with the main method) with optionally a set of command line options, positional parameters and subcommands.
Subcommands themselves can have options, positional parameters and nested sub-subcommands to any level of depth.
The object model has a corresponding hierarchy of CommandSpec objects, each with a set of OptionSpec,
PositionalParamSpec and CommandLine associated with it.
This object model is used by the picocli command line interpreter and help message generator.
Picocli can construct a CommandSpec automatically from classes with Command, Option and
Parameters annotations. Alternatively a CommandSpec can be constructed programmatically.
Field Summary
| Modifier and Type | Field | Description |
|---|---|---|
| public static final String | DEFAULT_COMMAND_NAME | Constant String holding the default program name: "<main class>". |
Method Summary
| Modifier and Type | Method | Description |
|---|---|---|
| public static CommandSpec | create() | Creates and returns a new CommandSpec without any associated user object. |
| public static CommandSpec | wrapWithoutInspection(Object userObject) | Creates and returns a new CommandSpec with the specified associated user object. |
| public static CommandSpec | wrapWithoutInspection(Object userObject, IFactory factory) | Creates and returns a new CommandSpec with the specified associated user object. |
| public static CommandSpec | forAnnotatedObject(Object userObject) | Creates and returns a new CommandSpec initialized from the specified associated user object. |
| public static CommandSpec | forAnnotatedObject(Object userObject, IFactory factory) | Creates and returns a new CommandSpec initialized from the specified associated user object. |
| public static CommandSpec | forAnnotatedObjectLenient(Object userObject) | Creates and returns a new CommandSpec initialized from the specified associated user object. |
| public static CommandSpec | forAnnotatedObjectLenient(Object userObject, IFactory factory) | Creates and returns a new CommandSpec initialized from the specified associated user object. |
| public Object | userObject() | Returns the user object associated with this command. |
| public CommandLine | commandLine() | Returns the CommandLine constructed with this CommandSpec model. |
| protected CommandSpec | commandLine(CommandLine commandLine) | Sets the CommandLine constructed with this CommandSpec model. |
| public ParserSpec | parser() | Returns the parser specification for this command. |
| public CommandSpec | parser(ParserSpec settings) | Initializes the parser specification for this command from the specified settings and returns this commandSpec. |
| public UsageMessageSpec | usageMessage() | Returns the usage help message specification for this command. |
| public CommandSpec | usageMessage(UsageMessageSpec settings) | Initializes the usageMessage specification for this command from the specified settings and returns this commandSpec. |
| public boolean | subcommandsCaseInsensitive() | Returns whether the subcommands are case-insensitive. |
| public CommandSpec | subcommandsCaseInsensitive(boolean caseInsensitiveSubcommands) | Sets the case-insensitivity of subcommands. |
| public boolean | optionsCaseInsensitive() | Returns whether the options are case-insensitive. |
| public CommandSpec | optionsCaseInsensitive(boolean caseInsensitiveOptions) | Sets the case-insensitivity of options. |
| public String | resourceBundleBaseName() | Returns the resource bundle base name for this command. |
| public CommandSpec | resourceBundleBaseName(String resourceBundleBaseName) | Initializes the resource bundle for this command: sets the UsageMessageSpec#messages(CommandLine.Model.Messages) to a Messages object created from this command spec and the specified bundle, and then sets the ArgSpec#messages(CommandLine.Model.Messages) of all options and positional parameters in this command to the same Messages instance. |
| public ResourceBundle | resourceBundle() | Returns the resource bundle for this command. |
| public CommandSpec | resourceBundle(ResourceBundle bundle) | Initializes the resource bundle for this command: sets the UsageMessageSpec#messages(CommandLine.Model.Messages) to a Messages object created from this command spec and the specified bundle, and then sets the ArgSpec#messages(CommandLine.Model.Messages) of all options and positional parameters in this command to the same Messages instance. |
| public Map<String, CommandLine> | subcommands() | Returns a read-only view of the subcommand map. |
| public CommandSpec | addSubcommand(String name, CommandSpec subcommand) | Adds the specified subcommand with the specified name. |
| public CommandSpec | addSubcommand(String name, CommandLine subCommandLine) | Adds the specified subcommand with the specified name. |
| public CommandLine | removeSubcommand(String name) | Removes the subcommand with the specified name or alias from this CommandSpec and returns the CommandLine instance that was associated with the specified name, or null of the specified name was not associated with a subcommand. |
| public boolean | isAddMethodSubcommands() | Returns whether method commands should be added as subcommands. |
| public CommandSpec | setAddMethodSubcommands(Boolean addMethodSubcommands) | Sets whether method commands should be added as subcommands. |
| public boolean | interpolateVariables() | Returns whether variables should be interpolated in String values. |
| public CommandSpec | interpolateVariables(Boolean interpolate) | Sets whether variables should be interpolated in String values. |
| public CommandSpec | addMethodSubcommands() | Reflects on the class of the userObject.userObject and registers any command methods (class methods annotated with @Command) as subcommands. |
| public CommandSpec | addMethodSubcommands(IFactory factory) | Reflects on the class of the userObject.userObject and registers any command methods (class methods annotated with @Command) as subcommands. |
| public CommandSpec | parent() | Returns the parent command of this subcommand, or null if this is a top-level command. |
| public CommandSpec | root() | Returns the root command: the top-level command of the hierarchy, never null. |
| public CommandSpec | parent(CommandSpec parent) | Sets the parent command of this subcommand. |
| public CommandSpec | add(ArgSpec arg) | Adds the specified option spec or positional parameter spec to the list of configured arguments to expect. |
| public CommandSpec | addOption(OptionSpec option) | Adds the specified option spec to the list of configured arguments to expect. |
| public CommandSpec | addPositional(PositionalParamSpec positional) | Adds the specified positional parameter spec to the list of configured arguments to expect. |
| public CommandSpec | remove(ArgSpec arg) | (INCUBATING) Removes the specified option spec or positional parameter spec from the list of configured arguments to expect. |
| public CommandSpec | addArgGroup(ArgGroupSpec group) | Adds the specified ArgGroupSpec to the groups in this command. |
| public CommandSpec | addMixin(String name, CommandSpec mixin, IAnnotatedElement annotatedElement) | Adds the specified mixin CommandSpec object to the map of mixins for this command. |
| public CommandSpec | addMixin(String name, CommandSpec mixin) | Adds the specified mixin CommandSpec object to the map of mixins for this command. |
| public CommandSpec | addUnmatchedArgsBinding(UnmatchedArgsBinding spec) | Adds the specified UnmatchedArgsBinding to the list of model objects to capture unmatched arguments for this command. |
| public CommandSpec | addSpecElement(IAnnotatedElement spec) | Adds the specified {@literal @}Spec-annotated program element to the list of elements for this command. |
| public CommandSpec | addParentCommandElement(IAnnotatedElement spec) | Adds the specified {@literal @}ParentCommand-annotated program element to the list of elements for this command. |
| public Map<String, CommandSpec> | mixins() | Returns a map of the mixin names to mixin CommandSpec objects configured for this command. |
| public Map<String, IAnnotatedElement> | mixinAnnotatedElements() | Returns a map of the mixin names to mixin IAnnotatedElement objects for this command. |
| public List<OptionSpec> | options() | Returns the list of options configured for this command. |
| public List<PositionalParamSpec> | positionalParameters() | Returns the list of positional parameters configured for this command. |
| public List<ArgGroupSpec> | argGroups() | Returns the ArgGroupSpec in this command. |
| public Map<String, OptionSpec> | optionsMap() | Returns a map of the option names to option spec objects configured for this command. |
| public Map<String, OptionSpec> | negatedOptionsMap() | Returns a map of the negated option names to option spec objects configured for this command. |
| public Map<Character, OptionSpec> | posixOptionsMap() | Returns a map of the short (single character) option names to option spec objects configured for this command. |
| public List<ArgSpec> | requiredArgs() | Returns the list of required options and positional parameters configured for this command. |
| public List<UnmatchedArgsBinding> | unmatchedArgsBindings() | Returns the list of UnmatchedArgsBinding configured for this command; each UnmatchedArgsBinding captures the arguments that could not be matched to any options or positional parameters. |
| public List<IAnnotatedElement> | specElements() | Returns the list of program elements annotated with {@literal @}Spec configured for this command. |
| public List<IAnnotatedElement> | parentCommandElements() | Returns the list of program elements annotated with {@literal @}ParentCommand configured for this command. |
| public String | name() | Returns name of this command. |
| public String[] | aliases() | Returns the alias command names of this subcommand. |
| public Set<String> | names() | Returns all names of this command, including name.name and aliases.aliases. |
| public List<ArgSpec> | args() | Returns the list of all options and positional parameters configured for this command. |
| public String | qualifiedName() | Returns the String to use as the program name in the synopsis line of the help message: this command's name.name, preceded by the qualified name of the parent command, if any, separated by a space. |
| public String | qualifiedName(String separator) | Returns this command's fully qualified name, which is its name.name, preceded by the qualified name of the parent command, if this command has a parent command. |
| public String[] | version() | Returns version information for this command, to print to the console when the user specifies an option to request version help. |
| public IVersionProvider | versionProvider() | Returns the version provider for this command, to generate the version.version strings. |
| public boolean | helpCommand() | Returns whether this subcommand is a help command, and required options and positional parameters of the parent command should not be validated. |
| public int | exitCodeOnSuccess() | Returns exit code for successful termination. |
| public int | exitCodeOnUsageHelp() | Returns exit code for successful termination after printing usage help on user request. |
| public int | exitCodeOnVersionHelp() | Returns exit code for successful termination after printing version help on user request. |
| public int | exitCodeOnInvalidInput() | Returns exit code for command line usage error. |
| public int | exitCodeOnExecutionException() | Returns exit code signifying that an exception occurred when invoking the Runnable, Callable or Method user object of a command. |
| public INegatableOptionTransformer | negatableOptionTransformer() | Returns the INegatableOptionTransformer used to create the negative form of negatable options. |
| public boolean | mixinStandardHelpOptions() | Returns true if the standard help options have been mixed in with this command, false otherwise. |
| public boolean | subcommandsRepeatable() | Returns whether the subcommands of this command are repeatable, that is, whether such subcommands can occur multiple times and may be followed by sibling commands instead of just child commands. |
| public String | toString() | Returns a string representation of this command, used in error messages and trace messages. |
| public CommandSpec | name(String name) | Sets the String to use as the program name in the synopsis line of the help message. |
| public CommandSpec | aliases(String[] aliases) | Sets the alternative names by which this subcommand is recognized on the command line. |
| public IDefaultValueProvider | defaultValueProvider() | Returns the default value provider for this command. |
| public CommandSpec | defaultValueProvider(IDefaultValueProvider defaultValueProvider) | Sets default value provider for this command. |
| public CommandSpec | version(String[] version) | Sets version information literals for this command, to print to the console when the user specifies an option to request version help. |
| public CommandSpec | versionProvider(IVersionProvider versionProvider) | Sets version provider for this command, to generate the version.version strings. |
| public CommandSpec | helpCommand(boolean newValue) | Sets whether this is a help command and required parameter checking should be suspended. |
| public CommandSpec | exitCodeOnSuccess(int newValue) | Sets exit code for successful termination. |
| public CommandSpec | exitCodeOnUsageHelp(int newValue) | Sets exit code for successful termination after printing usage help on user request. |
| public CommandSpec | exitCodeOnVersionHelp(int newValue) | Sets exit code for successful termination after printing version help on user request. |
| public CommandSpec | exitCodeOnInvalidInput(int newValue) | Sets exit code for command line usage error. |
| public CommandSpec | exitCodeOnExecutionException(int newValue) | Sets exit code signifying that an exception occurred when invoking the Runnable, Callable or Method user object of a command. |
| public boolean | inherited() | Returns whether this command is inherited from a parent command. |
| public ScopeType | scopeType() | Returns the scope of this argument; is it local, or inherited (it applies to this command as well as all sub- and sub-subcommands). |
| public CommandSpec | scopeType(ScopeType scopeType) | Sets the scope of where this argument applies: only this command, or also all sub (and sub-sub) commands, and returns this builder. |
| public IModelTransformer | modelTransformer() | Returns the model transformer for this CommandSpec instance. |
| public CommandSpec | modelTransformer(IModelTransformer modelTransformer) | Sets the model transformer for this CommandSpec instance. |
| public IParameterPreprocessor | preprocessor() | Returns the preprocessor for this CommandSpec instance. |
| public CommandSpec | preprocessor(IParameterPreprocessor preprocessor) | Sets the preprocessor for this CommandSpec instance. |
| public CommandSpec | negatableOptionTransformer(INegatableOptionTransformer newValue) | Sets the INegatableOptionTransformer used to create the negative form of negatable options. |
| public CommandSpec | mixinStandardHelpOptions(boolean newValue) | Sets whether the standard help options should be mixed in with this command. |
| public CommandSpec | subcommandsRepeatable(boolean subcommandsRepeatable) | Sets whether the subcommands of this command are repeatable, that is, whether such subcommands can occur multiple times and may be followed by sibling commands instead of just child commands. |
| public CommandSpec | withToString(String newValue) | Sets the string representation of this command, used in error messages and trace messages. |
| public void | updateCommandAttributes(Command cmd, IFactory factory) | Updates the following attributes from the specified @Command annotation: aliases, ParserSpec#separator(), command name, version, help command, version provider, default provider and UsageMessageSpec. |
| public OptionSpec | findOption(char shortName) | Returns the option with the specified short name, or null if no option with that name is defined for this command. |
| public OptionSpec | findOption(String name) | Returns the option with the specified name, or null if no option with that name is defined for this command. |
Field Details
DEFAULT_COMMAND_NAME
public static final String DEFAULT_COMMAND_NAME
Constant String holding the default program name: "<main class>".
Method Details
create
public static CommandSpec create()
Creates and returns a new CommandSpec without any associated user object.
wrapWithoutInspection
public static CommandSpec wrapWithoutInspection(Object userObject)
Creates and returns a new CommandSpec with the specified associated user object.The specified user object is not inspected for annotations.
Parameters:
userObject - the associated user object. May be any object, may be null.
wrapWithoutInspection
public static CommandSpec wrapWithoutInspection(Object userObject, IFactory factory)
Creates and returns a new CommandSpec with the specified associated user object.The specified user object is not inspected for annotations.
Parameters:
userObject - the associated user object. May be any object, may be null.
factory - the factory used to create instances of Command.subcommands, converters, etc., that are registered declaratively with annotation attributes
Since:
4.2
forAnnotatedObject
public static CommandSpec forAnnotatedObject(Object userObject)
Creates and returns a new CommandSpec initialized from the specified associated user object.The specified
user object must have at least one Command, Option or Parameters annotation.
Parameters:
userObject - the user object annotated with Command, Option and/or Parameters annotations.
forAnnotatedObject
public static CommandSpec forAnnotatedObject(Object userObject, IFactory factory)
Creates and returns a new CommandSpec initialized from the specified associated user object.The specified
user object must have at least one Command, Option or Parameters annotation.
Parameters:
userObject - the user object annotated with Command, Option and/or Parameters annotations.
factory - the factory used to create instances of Command.subcommands, converters, etc., that are registered declaratively with annotation attributes
forAnnotatedObjectLenient
public static CommandSpec forAnnotatedObjectLenient(Object userObject)
Creates and returns a new CommandSpec initialized from the specified associated user object.If the specified
user object has no Command, Option or Parameters annotations, an empty CommandSpec is returned.
Parameters:
userObject - the user object annotated with Command, Option and/or Parameters annotations.
forAnnotatedObjectLenient
public static CommandSpec forAnnotatedObjectLenient(Object userObject, IFactory factory)
Creates and returns a new CommandSpec initialized from the specified associated user object.If the specified
user object has no Command, Option or Parameters annotations, an empty CommandSpec is returned.
Parameters:
userObject - the user object annotated with Command, Option and/or Parameters annotations.
factory - the factory used to create instances of Command.subcommands, converters, etc., that are registered declaratively with annotation attributes
userObject
public Object userObject()
Returns the user object associated with this command.
See Also:
commandLine
public CommandLine commandLine()
Returns the CommandLine constructed with this CommandSpec model.
commandLine
protected CommandSpec commandLine(CommandLine commandLine)
Sets the CommandLine constructed with this CommandSpec model.
parser
public ParserSpec parser()
Returns the parser specification for this command.
parser
public CommandSpec parser(ParserSpec settings)
Initializes the parser specification for this command from the specified settings and returns this commandSpec.
usageMessage
public UsageMessageSpec usageMessage()
Returns the usage help message specification for this command.
usageMessage
public CommandSpec usageMessage(UsageMessageSpec settings)
Initializes the usageMessage specification for this command from the specified settings and returns this commandSpec.
subcommandsCaseInsensitive
public boolean subcommandsCaseInsensitive()
Returns whether the subcommands are case-insensitive.
Since:
4.3
subcommandsCaseInsensitive
public CommandSpec subcommandsCaseInsensitive(boolean caseInsensitiveSubcommands)
Sets the case-insensitivity of subcommands.
Since:
4.3
optionsCaseInsensitive
public boolean optionsCaseInsensitive()
Returns whether the options are case-insensitive.
Since:
4.3
optionsCaseInsensitive
public CommandSpec optionsCaseInsensitive(boolean caseInsensitiveOptions)
Sets the case-insensitivity of options.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.
Since:
4.3
resourceBundleBaseName
public String resourceBundleBaseName()
Returns the resource bundle base name for this command.
Returns:
the resource bundle base name from the
Since:
4.0
resourceBundleBaseName
public CommandSpec resourceBundleBaseName(String resourceBundleBaseName)
Initializes the resource bundle for this command: sets the UsageMessageSpec#messages(CommandLine.Model.Messages) to
a Messages object created from this command spec and the specified bundle, and then sets the
ArgSpec#messages(CommandLine.Model.Messages) of all options and positional parameters in this command
to the same Messages instance.Subcommands are not modified.
This method is preferable to resourceBundle.resourceBundle for pre-Java 8
Parameters:
resourceBundleBaseName - the base name of the ResourceBundle to set, may be null
Returns:
this commandSpec
Since:
4.0
See Also:
resourceBundle
public ResourceBundle resourceBundle()
Returns the resource bundle for this command.
Returns:
the resource bundle from the
Since:
3.6
resourceBundle
public CommandSpec resourceBundle(ResourceBundle bundle)
Initializes the resource bundle for this command: sets the UsageMessageSpec#messages(CommandLine.Model.Messages) to
a Messages object created from this command spec and the specified bundle, and then sets the
ArgSpec#messages(CommandLine.Model.Messages) of all options and positional parameters in this command
to the same Messages instance.Subcommands are not modified.
Parameters:
bundle - the ResourceBundle to set, may be null
Returns:
this commandSpec
Since:
3.6
See Also:
subcommands
public Map<String, CommandLine> subcommands()
Returns a read-only view of the subcommand map.
addSubcommand
public CommandSpec addSubcommand(String name, CommandSpec subcommand)
Adds the specified subcommand with the specified name.If the specified subcommand does not have a ResourceBundle set, it is initialized to the ResourceBundle of this command spec.
Parameters:
name - subcommand name - the preferred subcommand name to register the subcommand under.
If null, the CommandSpec.name of the specified subcommand is used;
if this is also null, the first CommandSpec.aliases is used.
When this String is encountered in the command line arguments, the subcommand is invoked.
subcommand - describes the subcommand to envoke when the name is encountered on the command line
Returns:
this CommandSpec object for method chaining
addSubcommand
public CommandSpec addSubcommand(String name, CommandLine subCommandLine)
Adds the specified subcommand with the specified name.If the specified subcommand does not have a ResourceBundle set, it is initialized to the ResourceBundle of this command spec.
Parameters:
name - subcommand name - the preferred subcommand name to register the subcommand under.
If null, the name of the specified subcommand is used;
if this is also null, the first CommandSpec.aliases is used.
When this String is encountered in the command line arguments, the subcommand is invoked.
subCommandLine - the subcommand to envoke when the name is encountered on the command line
Returns:
this CommandSpec object for method chaining
removeSubcommand
public CommandLine removeSubcommand(String name)
Removes the subcommand with the specified name or alias from this CommandSpec and
returns the CommandLine instance that was associated with the specified name,
or null of the specified name was not associated with a subcommand.
Parameters:
name - name or alias of the subcommand to remove; may be
#isAbbreviatedSubcommandsAllowed() or #isSubcommandsCaseInsensitive()
Returns:
the removed CommandLine instance or null
Since:
4.6
isAddMethodSubcommands
public boolean isAddMethodSubcommands()
Returns whether method commands should be added as subcommands.True by default. Used by the annotation processor.
Since:
4.0
setAddMethodSubcommands
public CommandSpec setAddMethodSubcommands(Boolean addMethodSubcommands)
Sets whether method commands should be added as subcommands.True by default. Used by the annotation processor.
Since:
4.0
interpolateVariables
public boolean interpolateVariables()
Returns whether variables should be interpolated in String values.True by default.
Since:
4.0
interpolateVariables
public CommandSpec interpolateVariables(Boolean interpolate)
Sets whether variables should be interpolated in String values.True by default.
Since:
4.0
addMethodSubcommands
public CommandSpec addMethodSubcommands()
Reflects on the class of the userObject.userObject and registers any command methods
(class methods annotated with @Command) as subcommands.
Returns:
this CommandSpec object for method chaining
Since:
3.6.0
See Also:
addMethodSubcommands
public CommandSpec addMethodSubcommands(IFactory factory)
Reflects on the class of the userObject.userObject and registers any command methods
(class methods annotated with @Command) as subcommands.
Parameters:
factory - the factory used to create instances of subcommands, converters, etc., that are registered declaratively with annotation attributes
Returns:
this CommandSpec object for method chaining
Since:
3.7.0
See Also:
parent
public CommandSpec parent()
Returns the parent command of this subcommand, or null if this is a top-level command.
root
public CommandSpec root()
Returns the root command: the top-level command of the hierarchy, never null.
Since:
4.3
parent
public CommandSpec parent(CommandSpec parent)
Sets the parent command of this subcommand.
Returns:
this CommandSpec for method chaining
add
public CommandSpec add(ArgSpec arg)
Adds the specified option spec or positional parameter spec to the list of configured arguments to expect.
Parameters:
arg - the option spec or positional parameter spec to add
Returns:
this CommandSpec for method chaining
addOption
public CommandSpec addOption(OptionSpec option)
Adds the specified option spec to the list of configured arguments to expect.The option's may now return Strings from this CommandSpec's messages. The option parameter's may now return Strings from this CommandSpec's CommandSpec.defaultValueProvider IDefaultValueProvider}.
Parameters:
option - the option spec to add
Returns:
this CommandSpec for method chaining
addPositional
public CommandSpec addPositional(PositionalParamSpec positional)
Adds the specified positional parameter spec to the list of configured arguments to expect.The positional parameter's may now return Strings from this CommandSpec's messages. The positional parameter's may now return Strings from this CommandSpec's CommandSpec.defaultValueProvider IDefaultValueProvider}.
Parameters:
positional - the positional parameter spec to add
Returns:
this CommandSpec for method chaining
remove
public CommandSpec remove(ArgSpec arg)
(INCUBATING) Removes the specified option spec or positional parameter spec from the list of configured arguments to expect.
Parameters:
arg - the option spec or positional parameter spec to remove
Returns:
this CommandSpec for method chaining
Since:
4.0
addArgGroup
public CommandSpec addArgGroup(ArgGroupSpec group)
Adds the specified ArgGroupSpec to the groups in this command.
Parameters:
group - the group spec to add
Returns:
this CommandSpec for method chaining
Since:
4.0
addMixin
public CommandSpec addMixin(String name, CommandSpec mixin, IAnnotatedElement annotatedElement)
Adds the specified mixin CommandSpec object to the map of mixins for this command.
Parameters:
name - the name that can be used to later retrieve the mixin
mixin - the mixin whose options and positional parameters and other attributes to add to this command
annotatedElement - the Mixin-annotated program element
Returns:
this CommandSpec for method chaining
Since:
4.1
See Also:
addMixin
public CommandSpec addMixin(String name, CommandSpec mixin)
Adds the specified mixin CommandSpec object to the map of mixins for this command.
Parameters:
name - the name that can be used to later retrieve the mixin
mixin - the mixin whose options and positional parameters and other attributes to add to this command
Returns:
this CommandSpec for method chaining
addUnmatchedArgsBinding
public CommandSpec addUnmatchedArgsBinding(UnmatchedArgsBinding spec)
Adds the specified UnmatchedArgsBinding to the list of model objects to capture unmatched arguments for this command.
Parameters:
spec - the unmatched arguments binding to capture unmatched arguments
Returns:
this CommandSpec for method chaining
addSpecElement
public CommandSpec addSpecElement(IAnnotatedElement spec)
Adds the specified {@literal @}Spec-annotated program element to the list of elements for this command.
Returns:
this CommandSpec for method chaining
Since:
4.0
addParentCommandElement
public CommandSpec addParentCommandElement(IAnnotatedElement spec)
Adds the specified {@literal @}ParentCommand-annotated program element to the list of elements for this command.
Returns:
this CommandSpec for method chaining
Since:
4.0
mixins
public Map<String, CommandSpec> mixins()
Returns a map of the mixin names to mixin CommandSpec objects configured for this command.
Returns:
an immutable map of mixins added to this command.
mixinAnnotatedElements
public Map<String, IAnnotatedElement> mixinAnnotatedElements()
Returns a map of the mixin names to mixin IAnnotatedElement objects for this command.
Returns:
an immutable map of Mixin-annotated elements added to this command.
Since:
4.1
See Also:
options
public List<OptionSpec> options()
Returns the list of options configured for this command.
Returns:
an immutable list of options that this command recognizes.
positionalParameters
public List<PositionalParamSpec> positionalParameters()
Returns the list of positional parameters configured for this command.
Returns:
an immutable list of positional parameters that this command recognizes.
argGroups
public List<ArgGroupSpec> argGroups()
Returns the ArgGroupSpec in this command.
Returns:
an immutable list of groups of options and positional parameters in this command
Since:
4.0
optionsMap
public Map<String, OptionSpec> optionsMap()
Returns a map of the option names to option spec objects configured for this command.
Returns:
an immutable map of options that this command recognizes.
negatedOptionsMap
public Map<String, OptionSpec> negatedOptionsMap()
Returns a map of the negated option names to option spec objects configured for this command.
Returns:
an immutable map of negatable options that this command recognizes.
Since:
4.0
posixOptionsMap
public Map<Character, OptionSpec> posixOptionsMap()
Returns a map of the short (single character) option names to option spec objects configured for this command.
Returns:
an immutable map of options that this command recognizes.
requiredArgs
public List<ArgSpec> requiredArgs()
Returns the list of required options and positional parameters configured for this command.This does not include options and positional parameters that are part of a ArgGroupSpec.
Returns:
an immutable list of the required options and positional parameters for this command.
unmatchedArgsBindings
public List<UnmatchedArgsBinding> unmatchedArgsBindings()
Returns the list of UnmatchedArgsBinding configured for this command;
each UnmatchedArgsBinding captures the arguments that could not be matched to any options or positional parameters.
specElements
public List<IAnnotatedElement> specElements()
Returns the list of program elements annotated with {@literal @}Spec configured for this command.
Since:
4.0
parentCommandElements
public List<IAnnotatedElement> parentCommandElements()
Returns the list of program elements annotated with {@literal @}ParentCommand configured for this command.
Since:
4.0
name
public String name()
Returns name of this command.Used in the synopsis line of the help message. #DEFAULT_COMMAND_NAME by default, initialized from Command.name if defined.
See Also:
aliases
public String[] aliases()
Returns the alias command names of this subcommand.
Since:
3.1
names
Returns all names of this command, including name.name and aliases.aliases.
Since:
3.9
args
Returns the list of all options and positional parameters configured for this command.
Returns:
an immutable list of all options and positional parameters for this command.
qualifiedName
public String qualifiedName()
Returns the String to use as the program name in the synopsis line of the help message: this command's name.name, preceded by the qualified name of the parent command, if any, separated by a space.
Returns:
DEFAULT_COMMAND_NAME by default, initialized from Command.name and the parent command if defined.
Since:
3.0.1
qualifiedName
public String qualifiedName(String separator)
Returns this command's fully qualified name, which is its name.name, preceded by the qualified name of the parent command, if this command has a parent command.
Parameters:
separator - the string to put between the names of the commands in the hierarchy
Returns:
DEFAULT_COMMAND_NAME by default, initialized from Command.name and the parent command if any.
Since:
3.6
version
public String[] version()
Returns version information for this command, to print to the console when the user specifies an option to request version help.This is not part of the usage help message.
Returns:
the version strings generated by the versionProvider.versionProvider if one is set, otherwise the version.version
versionProvider
public IVersionProvider versionProvider()
Returns the version provider for this command, to generate the version.version strings.
Returns:
the version provider or null if the version strings should be returned from the version.version.
helpCommand
public boolean helpCommand()
Returns whether this subcommand is a help command, and required options and positional parameters of the parent command should not be validated.
Returns:
true if this subcommand is a help command and picocli should not check for missing required
options and positional parameters on the parent command
See Also:
exitCodeOnSuccess
public int exitCodeOnSuccess()
Returns exit code for successful termination. by default, may be set programmatically or via the Command.exitCodeOnSuccess annotation.
Since:
4.0
See Also:
exitCodeOnUsageHelp
public int exitCodeOnUsageHelp()
Returns exit code for successful termination after printing usage help on user request. by default, may be set programmatically or via the Command.exitCodeOnVersionHelp annotation.
Since:
4.0
See Also:
exitCodeOnVersionHelp
public int exitCodeOnVersionHelp()
Returns exit code for successful termination after printing version help on user request. by default, may be set programmatically or via the Command.exitCodeOnUsageHelp annotation.
Since:
4.0
See Also:
exitCodeOnInvalidInput
public int exitCodeOnInvalidInput()
Returns exit code for command line usage error. by default, may be set programmatically or via the Command.exitCodeOnInvalidInput annotation.
Since:
4.0
See Also:
exitCodeOnExecutionException
public int exitCodeOnExecutionException()
Returns exit code signifying that an exception occurred when invoking the Runnable, Callable or Method user object of a command. by default, may be set programmatically or via the Command.exitCodeOnExecutionException annotation.
Since:
4.0
See Also:
negatableOptionTransformer
public INegatableOptionTransformer negatableOptionTransformer()
Returns the INegatableOptionTransformer used to create the negative form of negatable options.
Since:
4.0
See Also:
mixinStandardHelpOptions
public boolean mixinStandardHelpOptions()
Returns true if the standard help options have been mixed in with this command, false otherwise.
subcommandsRepeatable
public boolean subcommandsRepeatable()
Returns whether the subcommands of this command are repeatable, that is, whether such subcommands can occur multiple times and may be followed by sibling commands instead of just child commands.
Since:
4.2
See Also:
toString
public String toString()
Returns a string representation of this command, used in error messages and trace messages.
name
public CommandSpec name(String name)
Sets the String to use as the program name in the synopsis line of the help message.
Returns:
this CommandSpec for method chaining
aliases
public CommandSpec aliases(String[] aliases)
Sets the alternative names by which this subcommand is recognized on the command line.
Returns:
this CommandSpec for method chaining
Since:
3.1
defaultValueProvider
public IDefaultValueProvider defaultValueProvider()
Returns the default value provider for this command.
Returns:
the default value provider or null
Since:
3.6
defaultValueProvider
public CommandSpec defaultValueProvider(IDefaultValueProvider defaultValueProvider)
Sets default value provider for this command.
Parameters:
defaultValueProvider - the default value provider to use, or null.
Returns:
this CommandSpec for method chaining
Since:
3.6
version
public CommandSpec version(String[] version)
Sets version information literals for this command, to print to the console when the user specifies an option to request version help.Only used if no versionProvider.versionProvider is set.
Returns:
this CommandSpec for method chaining
versionProvider
public CommandSpec versionProvider(IVersionProvider versionProvider)
Sets version provider for this command, to generate the version.version strings.
Parameters:
versionProvider - the version provider to use to generate the version strings, or null if the version.version should be used.
Returns:
this CommandSpec for method chaining
helpCommand
public CommandSpec helpCommand(boolean newValue)
Sets whether this is a help command and required parameter checking should be suspended.
Returns:
this CommandSpec for method chaining
See Also:
exitCodeOnSuccess
public CommandSpec exitCodeOnSuccess(int newValue)
Sets exit code for successful termination. by default.
Since:
4.0
See Also:
exitCodeOnUsageHelp
public CommandSpec exitCodeOnUsageHelp(int newValue)
Sets exit code for successful termination after printing usage help on user request. by default.
Since:
4.0
See Also:
exitCodeOnVersionHelp
public CommandSpec exitCodeOnVersionHelp(int newValue)
Sets exit code for successful termination after printing version help on user request. by default.
Since:
4.0
See Also:
exitCodeOnInvalidInput
public CommandSpec exitCodeOnInvalidInput(int newValue)
Sets exit code for command line usage error. by default.
Since:
4.0
See Also:
exitCodeOnExecutionException
public CommandSpec exitCodeOnExecutionException(int newValue)
Sets exit code signifying that an exception occurred when invoking the Runnable, Callable or Method user object of a command. by default.
Since:
4.0
See Also:
inherited
public boolean inherited()
Returns whether this command is inherited from a parent command.
Since:
4.6
See Also:
scopeType
public ScopeType scopeType()
Returns the scope of this argument; is it local, or inherited (it applies to this command as well as all sub- and sub-subcommands).
Returns:
whether this argument applies to all descendent subcommands of the command where it is defined
Since:
4.6
scopeType
public CommandSpec scopeType(ScopeType scopeType)
Sets the scope of where this argument applies: only this command, or also all sub (and sub-sub) commands, and returns this builder.
Since:
4.6
modelTransformer
public IModelTransformer modelTransformer()
Returns the model transformer for this CommandSpec instance.
Since:
4.6
modelTransformer
public CommandSpec modelTransformer(IModelTransformer modelTransformer)
Sets the model transformer for this CommandSpec instance.
Since:
4.6
preprocessor
public IParameterPreprocessor preprocessor()
Returns the preprocessor for this CommandSpec instance.
Since:
4.6
preprocessor
public CommandSpec preprocessor(IParameterPreprocessor preprocessor)
Sets the preprocessor for this CommandSpec instance.
Since:
4.6
negatableOptionTransformer
public CommandSpec negatableOptionTransformer(INegatableOptionTransformer newValue)
Sets the INegatableOptionTransformer used to create the negative form of negatable options.Note that CommandSpec.optionsCaseInsensitive 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.
Since:
4.0
See Also:
mixinStandardHelpOptions
public CommandSpec mixinStandardHelpOptions(boolean newValue)
Sets whether the standard help options should be mixed in with this command.
Returns:
this CommandSpec for method chaining
See Also:
subcommandsRepeatable
public CommandSpec subcommandsRepeatable(boolean subcommandsRepeatable)
Sets whether the subcommands of this command are repeatable, that is, whether such subcommands can occur multiple times and may be followed by sibling commands instead of just child commands.
Since:
4.2
See Also:
withToString
public CommandSpec withToString(String newValue)
Sets the string representation of this command, used in error messages and trace messages.
Parameters:
newValue - the string representation
Returns:
this CommandSpec for method chaining
updateCommandAttributes
public void updateCommandAttributes(Command cmd, IFactory factory)
Updates the following attributes from the specified @Command annotation:
aliases, ParserSpec#separator(), command name, version, help command,
version provider, default provider and UsageMessageSpec.
Parameters:
cmd - the @Command annotation to get attribute values from
factory - factory used to instantiate classes
Since:
3.7
findOption
public OptionSpec findOption(char shortName)
Returns the option with the specified short name, or null if no option with that name is defined for this command.
findOption
public OptionSpec findOption(String name)
Returns the option with the specified name, or null if no option with that name is defined for this command.
Parameters:
name - used to search the options. May include option name prefix characters or not.