Class CommandLine.Model.CommandSpec
- java.lang.Object
-
- picocli.CommandLine.Model.CommandSpec
-
- Enclosing class:
- CommandLine.Model
public static class CommandLine.Model.CommandSpec extends Object
TheCommandSpecclass 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
mainmethod) 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
CommandSpecobjects, each with a set ofCommandLine.Model.OptionSpec,CommandLine.Model.PositionalParamSpecand subcommands associated with it. This object model is used by the picocli command line interpreter and help message generator.Picocli can construct a
CommandSpecautomatically from classes with@Command,@Optionand@Parametersannotations. Alternatively aCommandSpeccan be constructed programmatically.- Since:
- 3.0
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description CommandLine.Model.CommandSpecadd(CommandLine.Model.ArgSpec arg)Adds the specified option spec or positional parameter spec to the list of configured arguments to expect.CommandLine.Model.CommandSpecaddMethodSubcommands()Reflects on the class of the user object and registers any command methods (class methods annotated with@Command) as subcommands.CommandLine.Model.CommandSpecaddMethodSubcommands(CommandLine.IFactory factory)Reflects on the class of the user object and registers any command methods (class methods annotated with@Command) as subcommands.CommandLine.Model.CommandSpecaddMixin(String name, CommandLine.Model.CommandSpec mixin)Adds the specified mixinCommandSpecobject to the map of mixins for this command.CommandLine.Model.CommandSpecaddOption(CommandLine.Model.OptionSpec option)Adds the specified option spec to the list of configured arguments to expect.CommandLine.Model.CommandSpecaddPositional(CommandLine.Model.PositionalParamSpec positional)Adds the specified positional parameter spec to the list of configured arguments to expect.CommandLine.Model.CommandSpecaddSubcommand(String name, CommandLine subCommandLine)Adds the specified subcommand with the specified name.CommandLine.Model.CommandSpecaddSubcommand(String name, CommandLine.Model.CommandSpec subcommand)Adds the specified subcommand with the specified name.CommandLine.Model.CommandSpecaddUnmatchedArgsBinding(CommandLine.Model.UnmatchedArgsBinding spec)Adds the specifiedUnmatchedArgsBindingto the list of model objects to capture unmatched arguments for this command.String[]aliases()Returns the alias command names of this subcommand.CommandLine.Model.CommandSpecaliases(String... aliases)Sets the alternative names by which this subcommand is recognized on the command line.List<CommandLine.Model.ArgSpec>args()Returns the list of all options and positional parameters configured for this command.CommandLinecommandLine()Returns the CommandLine constructed with thisCommandSpecmodel.protected CommandLine.Model.CommandSpeccommandLine(CommandLine commandLine)Sets the CommandLine constructed with thisCommandSpecmodel.static CommandLine.Model.CommandSpeccreate()Creates and returns a newCommandSpecwithout any associated user object.CommandLine.IDefaultValueProviderdefaultValueProvider()Returns the default value provider for this command.CommandLine.Model.CommandSpecdefaultValueProvider(CommandLine.IDefaultValueProvider defaultValueProvider)Sets default value provider for this command.CommandLine.Model.OptionSpecfindOption(char shortName)Returns the option with the specified short name, ornullif no option with that name is defined for this command.CommandLine.Model.OptionSpecfindOption(String name)Returns the option with the specified name, ornullif no option with that name is defined for this command.static CommandLine.Model.CommandSpecforAnnotatedObject(Object userObject)Creates and returns a newCommandSpecinitialized from the specified associated user object.static CommandLine.Model.CommandSpecforAnnotatedObject(Object userObject, CommandLine.IFactory factory)Creates and returns a newCommandSpecinitialized from the specified associated user object.static CommandLine.Model.CommandSpecforAnnotatedObjectLenient(Object userObject)Creates and returns a newCommandSpecinitialized from the specified associated user object.static CommandLine.Model.CommandSpecforAnnotatedObjectLenient(Object userObject, CommandLine.IFactory factory)Creates and returns a newCommandSpecinitialized from the specified associated user object.booleanhelpCommand()Returns whether this subcommand is a help command, and required options and positional parameters of the parent command should not be validated.CommandLine.Model.CommandSpechelpCommand(boolean newValue)Sets whether this is a help command and required parameter checking should be suspended.Map<String,CommandLine.Model.CommandSpec>mixins()Returns a map of the mixin names to mixinCommandSpecobjects configured for this command.booleanmixinStandardHelpOptions()Returnstrueif the standard help options have been mixed in with this command,falseotherwise.CommandLine.Model.CommandSpecmixinStandardHelpOptions(boolean newValue)Sets whether the standard help options should be mixed in with this command.Stringname()Returns name of this command.CommandLine.Model.CommandSpecname(String name)Sets the String to use as the program name in the synopsis line of the help message.Set<String>names()List<CommandLine.Model.OptionSpec>options()Returns the list of options configured for this command.Map<String,CommandLine.Model.OptionSpec>optionsMap()Returns a map of the option names to option spec objects configured for this command.CommandLine.Model.CommandSpecparent()Returns the parent command of this subcommand, ornullif this is a top-level command.CommandLine.Model.CommandSpecparent(CommandLine.Model.CommandSpec parent)Sets the parent command of this subcommand.CommandLine.Model.ParserSpecparser()Returns the parser specification for this command.CommandLine.Model.CommandSpecparser(CommandLine.Model.ParserSpec settings)Initializes the parser specification for this command from the specified settings and returns this commandSpec.List<CommandLine.Model.PositionalParamSpec>positionalParameters()Returns the list of positional parameters configured for this command.Map<Character,CommandLine.Model.OptionSpec>posixOptionsMap()Returns a map of the short (single character) option names to option spec objects configured for this command.StringqualifiedName()Returns the String to use as the program name in the synopsis line of the help message: this command'sname, preceded by the qualified name of the parent command, if any, separated by a space.StringqualifiedName(String separator)Returns this command's fully qualified name, which is itsname, preceded by the qualified name of the parent command, if this command has a parent command.List<CommandLine.Model.ArgSpec>requiredArgs()Returns the list of required options and positional parameters configured for this command.ResourceBundleresourceBundle()Returns the resource bundle for this command.CommandLine.Model.CommandSpecresourceBundle(ResourceBundle bundle)Initializes the resource bundle for this command: sets theUsageMessageSpec.messagesto aMessagesobject created from this command spec and the specified bundle, and then sets theArgSpec.messagesof all options and positional parameters in this command to the sameMessagesinstance.Map<String,CommandLine>subcommands()Returns a read-only view of the subcommand map.StringtoString()Returns a string representation of this command, used in error messages and trace messages.List<CommandLine.Model.UnmatchedArgsBinding>unmatchedArgsBindings()Returns the list ofUnmatchedArgumentsBindingsconfigured for this command; eachUnmatchedArgsBindingcaptures the arguments that could not be matched to any options or positional parameters.CommandLine.Model.UsageMessageSpecusageMessage()Returns the usage help message specification for this command.CommandLine.Model.CommandSpecusageMessage(CommandLine.Model.UsageMessageSpec settings)Initializes the usageMessage specification for this command from the specified settings and returns this commandSpec.ObjectuserObject()Returns the user object associated with this command.String[]version()Returns version information for this command, to print to the console when the user specifies an option to request version help.CommandLine.Model.CommandSpecversion(String... version)Sets version information literals for this command, to print to the console when the user specifies an option to request version help.CommandLine.IVersionProviderversionProvider()Returns the version provider for this command, to generate theversion()strings.CommandLine.Model.CommandSpecversionProvider(CommandLine.IVersionProvider versionProvider)Sets version provider for this command, to generate theversion()strings.CommandLine.Model.CommandSpecwithToString(String newValue)Sets the string representation of this command, used in error messages and trace messages.static CommandLine.Model.CommandSpecwrapWithoutInspection(Object userObject)Creates and returns a newCommandSpecwith the specified associated user object.
-
-
-
Method Detail
-
create
public static CommandLine.Model.CommandSpec create()
Creates and returns a newCommandSpecwithout any associated user object.
-
wrapWithoutInspection
public static CommandLine.Model.CommandSpec wrapWithoutInspection(Object userObject)
Creates and returns a newCommandSpecwith 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 benull.
-
forAnnotatedObject
public static CommandLine.Model.CommandSpec forAnnotatedObject(Object userObject)
Creates and returns a newCommandSpecinitialized from the specified associated user object. The specified user object must have at least oneCommandLine.Command,CommandLine.OptionorCommandLine.Parametersannotation.- Parameters:
userObject- the user object annotated withCommandLine.Command,CommandLine.Optionand/orCommandLine.Parametersannotations.- Throws:
CommandLine.InitializationException- if the specified object has no picocli annotations or has invalid annotations
-
forAnnotatedObject
public static CommandLine.Model.CommandSpec forAnnotatedObject(Object userObject, CommandLine.IFactory factory)
Creates and returns a newCommandSpecinitialized from the specified associated user object. The specified user object must have at least oneCommandLine.Command,CommandLine.OptionorCommandLine.Parametersannotation.- Parameters:
userObject- the user object annotated withCommandLine.Command,CommandLine.Optionand/orCommandLine.Parametersannotations.factory- the factory used to create instances of subcommands, converters, etc., that are registered declaratively with annotation attributes- Throws:
CommandLine.InitializationException- if the specified object has no picocli annotations or has invalid annotations
-
forAnnotatedObjectLenient
public static CommandLine.Model.CommandSpec forAnnotatedObjectLenient(Object userObject)
Creates and returns a newCommandSpecinitialized from the specified associated user object. If the specified user object has noCommandLine.Command,CommandLine.OptionorCommandLine.Parametersannotations, an emptyCommandSpecis returned.- Parameters:
userObject- the user object annotated withCommandLine.Command,CommandLine.Optionand/orCommandLine.Parametersannotations.- Throws:
CommandLine.InitializationException- if the specified object has invalid annotations
-
forAnnotatedObjectLenient
public static CommandLine.Model.CommandSpec forAnnotatedObjectLenient(Object userObject, CommandLine.IFactory factory)
Creates and returns a newCommandSpecinitialized from the specified associated user object. If the specified user object has noCommandLine.Command,CommandLine.OptionorCommandLine.Parametersannotations, an emptyCommandSpecis returned.- Parameters:
userObject- the user object annotated withCommandLine.Command,CommandLine.Optionand/orCommandLine.Parametersannotations.factory- the factory used to create instances of subcommands, converters, etc., that are registered declaratively with annotation attributes- Throws:
CommandLine.InitializationException- if the specified object has invalid annotations
-
userObject
public Object userObject()
Returns the user object associated with this command.- See Also:
CommandLine.getCommand()
-
commandLine
public CommandLine commandLine()
Returns the CommandLine constructed with thisCommandSpecmodel.
-
commandLine
protected CommandLine.Model.CommandSpec commandLine(CommandLine commandLine)
Sets the CommandLine constructed with thisCommandSpecmodel.
-
parser
public CommandLine.Model.ParserSpec parser()
Returns the parser specification for this command.
-
parser
public CommandLine.Model.CommandSpec parser(CommandLine.Model.ParserSpec settings)
Initializes the parser specification for this command from the specified settings and returns this commandSpec.
-
usageMessage
public CommandLine.Model.UsageMessageSpec usageMessage()
Returns the usage help message specification for this command.
-
usageMessage
public CommandLine.Model.CommandSpec usageMessage(CommandLine.Model.UsageMessageSpec settings)
Initializes the usageMessage specification for this command from the specified settings and returns this commandSpec.
-
resourceBundle
public ResourceBundle resourceBundle()
Returns the resource bundle for this command.- Returns:
- the resource bundle from the CommandLine.Model.UsageMessageSpec.messages()
- Since:
- 3.6
-
resourceBundle
public CommandLine.Model.CommandSpec resourceBundle(ResourceBundle bundle)
Initializes the resource bundle for this command: sets theUsageMessageSpec.messagesto aMessagesobject created from this command spec and the specified bundle, and then sets theArgSpec.messagesof all options and positional parameters in this command to the sameMessagesinstance. Subcommands are not modified.- Parameters:
bundle- the ResourceBundle to set, may benull- Returns:
- this commandSpec
- Since:
- 3.6
- See Also:
addSubcommand(String, CommandLine)
-
subcommands
public Map<String,CommandLine> subcommands()
Returns a read-only view of the subcommand map.
-
addSubcommand
public CommandLine.Model.CommandSpec addSubcommand(String name, CommandLine.Model.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 - when this String is encountered in the command line arguments the subcommand is invokedsubcommand- describes the subcommand to envoke when the name is encountered on the command line- Returns:
- this
CommandSpecobject for method chaining
-
addSubcommand
public CommandLine.Model.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 - when this String is encountered in the command line arguments the subcommand is invokedsubCommandLine- the subcommand to envoke when the name is encountered on the command line- Returns:
- this
CommandSpecobject for method chaining
-
addMethodSubcommands
public CommandLine.Model.CommandSpec addMethodSubcommands()
Reflects on the class of the user object and registers any command methods (class methods annotated with@Command) as subcommands.- Returns:
- this
CommandLine.Model.CommandSpecobject for method chaining - Since:
- 3.6.0
- See Also:
addMethodSubcommands(IFactory),addSubcommand(String, CommandLine)
-
addMethodSubcommands
public CommandLine.Model.CommandSpec addMethodSubcommands(CommandLine.IFactory factory)
Reflects on the class of the user object 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
CommandLine.Model.CommandSpecobject for method chaining - Since:
- 3.7.0
- See Also:
addSubcommand(String, CommandLine)
-
parent
public CommandLine.Model.CommandSpec parent()
Returns the parent command of this subcommand, ornullif this is a top-level command.
-
parent
public CommandLine.Model.CommandSpec parent(CommandLine.Model.CommandSpec parent)
Sets the parent command of this subcommand.- Returns:
- this CommandSpec for method chaining
-
add
public CommandLine.Model.CommandSpec add(CommandLine.Model.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 CommandLine.Model.CommandSpec addOption(CommandLine.Model.OptionSpec option)
Adds the specified option spec to the list of configured arguments to expect. The option's CommandLine.Model.OptionSpec.description() may now return Strings from this CommandSpec's messages. The option parameter's CommandLine.Model.ArgSpec.defaultValueString() may now return Strings from this CommandSpec'sdefaultValueProvider()IDefaultValueProvider}.- Parameters:
option- the option spec to add- Returns:
- this CommandSpec for method chaining
- Throws:
CommandLine.DuplicateOptionAnnotationsException- if any of the names of the specified option is the same as the name of another option
-
addPositional
public CommandLine.Model.CommandSpec addPositional(CommandLine.Model.PositionalParamSpec positional)
Adds the specified positional parameter spec to the list of configured arguments to expect. The positional parameter's CommandLine.Model.PositionalParamSpec.description() may now return Strings from this CommandSpec's messages. The positional parameter's CommandLine.Model.ArgSpec.defaultValueString() may now return Strings from this CommandSpec'sdefaultValueProvider()IDefaultValueProvider}.- Parameters:
positional- the positional parameter spec to add- Returns:
- this CommandSpec for method chaining
-
addMixin
public CommandLine.Model.CommandSpec addMixin(String name, CommandLine.Model.CommandSpec mixin)
Adds the specified mixinCommandSpecobject to the map of mixins for this command.- Parameters:
name- the name that can be used to later retrieve the mixinmixin- the mixin whose options and positional parameters and other attributes to add to this command- Returns:
- this CommandSpec for method chaining
-
addUnmatchedArgsBinding
public CommandLine.Model.CommandSpec addUnmatchedArgsBinding(CommandLine.Model.UnmatchedArgsBinding spec)
Adds the specifiedUnmatchedArgsBindingto 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
-
mixins
public Map<String,CommandLine.Model.CommandSpec> mixins()
Returns a map of the mixin names to mixinCommandSpecobjects configured for this command.- Returns:
- an immutable map of mixins added to this command.
-
options
public List<CommandLine.Model.OptionSpec> options()
Returns the list of options configured for this command.- Returns:
- an immutable list of options that this command recognizes.
-
positionalParameters
public List<CommandLine.Model.PositionalParamSpec> positionalParameters()
Returns the list of positional parameters configured for this command.- Returns:
- an immutable list of positional parameters that this command recognizes.
-
optionsMap
public Map<String,CommandLine.Model.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.
-
posixOptionsMap
public Map<Character,CommandLine.Model.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<CommandLine.Model.ArgSpec> requiredArgs()
Returns the list of required options and positional parameters configured for this command.- Returns:
- an immutable list of the required options and positional parameters for this command.
-
unmatchedArgsBindings
public List<CommandLine.Model.UnmatchedArgsBinding> unmatchedArgsBindings()
Returns the list ofUnmatchedArgumentsBindingsconfigured for this command; eachUnmatchedArgsBindingcaptures the arguments that could not be matched to any options or positional parameters.
-
name
public String name()
Returns name of this command. Used in the synopsis line of the help message.DEFAULT_COMMAND_NAMEby default, initialized fromCommandLine.Command.name()if defined.- See Also:
qualifiedName()
-
aliases
public String[] aliases()
Returns the alias command names of this subcommand.- Since:
- 3.1
-
args
public List<CommandLine.Model.ArgSpec> 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'sname, preceded by the qualified name of the parent command, if any, separated by a space.- Returns:
DEFAULT_COMMAND_NAMEby default, initialized fromCommandLine.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 itsname, 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_NAMEby default, initialized fromCommandLine.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
version providerif one is set, otherwise the version literals
-
versionProvider
public CommandLine.IVersionProvider versionProvider()
Returns the version provider for this command, to generate theversion()strings.- Returns:
- the version provider or
nullif the version strings should be returned from the version literals.
-
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:
trueif this subcommand is a help command and picocli should not check for missing required options and positional parameters on the parent command- See Also:
CommandLine.Command.helpCommand()
-
mixinStandardHelpOptions
public boolean mixinStandardHelpOptions()
Returnstrueif the standard help options have been mixed in with this command,falseotherwise.
-
toString
public String toString()
Returns a string representation of this command, used in error messages and trace messages.
-
name
public CommandLine.Model.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 CommandLine.Model.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 CommandLine.IDefaultValueProvider defaultValueProvider()
Returns the default value provider for this command.- Returns:
- the default value provider or
null - Since:
- 3.6
-
defaultValueProvider
public CommandLine.Model.CommandSpec defaultValueProvider(CommandLine.IDefaultValueProvider defaultValueProvider)
Sets default value provider for this command.- Parameters:
defaultValueProvider- the default value provider to use, ornull.- Returns:
- this CommandSpec for method chaining
- Since:
- 3.6
-
version
public CommandLine.Model.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 noversionProvideris set.- Returns:
- this CommandSpec for method chaining
-
versionProvider
public CommandLine.Model.CommandSpec versionProvider(CommandLine.IVersionProvider versionProvider)
Sets version provider for this command, to generate theversion()strings.- Parameters:
versionProvider- the version provider to use to generate the version strings, ornullif the version literals should be used.- Returns:
- this CommandSpec for method chaining
-
helpCommand
public CommandLine.Model.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:
CommandLine.Command.helpCommand()
-
mixinStandardHelpOptions
public CommandLine.Model.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:
CommandLine.Command.mixinStandardHelpOptions()
-
withToString
public CommandLine.Model.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
-
findOption
public CommandLine.Model.OptionSpec findOption(char shortName)
Returns the option with the specified short name, ornullif no option with that name is defined for this command.
-
findOption
public CommandLine.Model.OptionSpec findOption(String name)
Returns the option with the specified name, ornullif 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.
-
-