Package picocli

Class CommandLine.Model.CommandSpec

  • Enclosing class:
    CommandLine.Model

    public static class CommandLine.Model.CommandSpec
    extends java.lang.Object
    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 CommandLine.Model.OptionSpec, CommandLine.Model.PositionalParamSpec and subcommands 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.

    Since:
    3.0
    • Field Detail

      • DEFAULT_COMMAND_NAME

        public static final java.lang.String DEFAULT_COMMAND_NAME
        Constant String holding the default program name: "<main class>" .
        Since:
        4.0
        See Also:
        Constant Field Values
    • Method Detail

      • wrapWithoutInspection

        public static CommandLine.Model.CommandSpec wrapWithoutInspection​(java.lang.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 CommandLine.Model.CommandSpec wrapWithoutInspection​(java.lang.Object userObject,
                                                                          CommandLine.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 subcommands, converters, etc., that are registered declaratively with annotation attributes
        Since:
        4.2
      • userObject

        public java.lang.Object userObject()
        Returns the user object associated with this command.
        See Also:
        CommandLine.getCommand()
      • commandLine

        public CommandLine commandLine()
        Returns the CommandLine constructed with this CommandSpec model.
      • subcommandsCaseInsensitive

        public boolean subcommandsCaseInsensitive()
        Returns whether the subcommands are case-insensitive.
        Since:
        4.3
      • subcommandsCaseInsensitive

        public CommandLine.Model.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 CommandLine.Model.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 CommandLine.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 java.lang.String resourceBundleBaseName()
        Returns the resource bundle base name for this command.
        Returns:
        the resource bundle base name from the CommandLine.Model.UsageMessageSpec.messages()
        Since:
        4.0
      • resourceBundle

        public CommandLine.Model.CommandSpec resourceBundle​(java.util.ResourceBundle bundle)
        Initializes the resource bundle for this command: sets the UsageMessageSpec.messages to a Messages object created from this command spec and the specified bundle, and then sets the ArgSpec.messages of all options and positional parameters in this command to the same Messages instance. Subcommands are not modified.
        Parameters:
        bundle - the ResourceBundle to set, may be null
        Returns:
        this commandSpec
        Since:
        3.6
        See Also:
        addSubcommand(String, CommandLine)
      • subcommands

        public java.util.Map<java.lang.String,​CommandLine> subcommands()
        Returns a read-only view of the subcommand map.
      • addSubcommand

        public CommandLine.Model.CommandSpec addSubcommand​(java.lang.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 - 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 alias 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
        Throws:
        CommandLine.InitializationException - if the specified name is null, and no alternative name could be found, or if another subcommand was already registered under the same name, or if one of the aliases of the specified subcommand was already used by another subcommand.
      • addSubcommand

        public CommandLine.Model.CommandSpec addSubcommand​(java.lang.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 alias 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
        Throws:
        CommandLine.InitializationException - if the specified name is null, and no alternative name could be found, or if another subcommand was already registered under the same name, or if one of the aliases of the specified subcommand was already used by another subcommand.
      • removeSubcommand

        public CommandLine removeSubcommand​(java.lang.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 abbreviated or case-insensitive
        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 CommandLine.Model.CommandSpec setAddMethodSubcommands​(java.lang.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 CommandLine.Model.CommandSpec interpolateVariables​(java.lang.Boolean interpolate)
        Sets whether variables should be interpolated in String values. True by default.
        Since:
        4.0
      • 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
      • remove

        public CommandLine.Model.CommandSpec remove​(CommandLine.Model.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
        Throws:
        java.lang.UnsupportedOperationException - if the specified ArgSpec is part of a CommandLine.Model.ArgGroupSpec
        java.util.NoSuchElementException - if the specified ArgSpec is not part of this CommandSpec
        Since:
        4.0
      • addMixin

        public CommandLine.Model.CommandSpec addMixin​(java.lang.String name,
                                                      CommandLine.Model.CommandSpec mixin,
                                                      CommandLine.Model.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:
        mixinAnnotatedElements()
      • addMixin

        public CommandLine.Model.CommandSpec addMixin​(java.lang.String name,
                                                      CommandLine.Model.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 CommandLine.Model.CommandSpec addUnmatchedArgsBinding​(CommandLine.Model.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
      • mixins

        public java.util.Map<java.lang.String,​CommandLine.Model.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.
      • options

        public java.util.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 java.util.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.
      • argGroups

        public java.util.List<CommandLine.Model.ArgGroupSpec> argGroups()
        Returns the argument groups in this command.
        Returns:
        an immutable list of groups of options and positional parameters in this command
        Since:
        4.0
      • optionsMap

        public java.util.Map<java.lang.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.
      • negatedOptionsMap

        public java.util.Map<java.lang.String,​CommandLine.Model.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 java.util.Map<java.lang.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 java.util.List<CommandLine.Model.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 group.
        Returns:
        an immutable list of the required options and positional parameters for this command.
      • specElements

        public java.util.List<CommandLine.Model.IAnnotatedElement> specElements()
        Returns the list of program elements annotated with {@literal @}Spec configured for this command.
        Since:
        4.0
      • parentCommandElements

        public java.util.List<CommandLine.Model.IAnnotatedElement> parentCommandElements()
        Returns the list of program elements annotated with {@literal @}ParentCommand configured for this command.
        Since:
        4.0
      • aliases

        public java.lang.String[] aliases()
        Returns the alias command names of this subcommand.
        Since:
        3.1
      • names

        public java.util.Set<java.lang.String> names()
        Returns all names of this command, including name() and aliases().
        Since:
        3.9
      • args

        public java.util.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 java.lang.String qualifiedName()
        Returns the String to use as the program name in the synopsis line of the help message: this command's name, preceded by the qualified name of the parent command, if any, separated by a space.
        Returns:
        DEFAULT_COMMAND_NAME by default, initialized from CommandLine.Command.name() and the parent command if defined.
        Since:
        3.0.1
      • qualifiedName

        public java.lang.String qualifiedName​(java.lang.String separator)
        Returns this command's fully qualified name, which is its name, preceded by the qualified name of the parent command, if this command has a parent command.
        Parameters:
        separator - the string to put between the names of the commands in the hierarchy
        Returns:
        DEFAULT_COMMAND_NAME by default, initialized from CommandLine.Command.name() and the parent command if any.
        Since:
        3.6
      • version

        public java.lang.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 provider if one is set, otherwise 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:
        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:
        CommandLine.Command.helpCommand()
      • exitCodeOnUsageHelp

        public int exitCodeOnUsageHelp()
        Returns exit code for successful termination after printing usage help on user request. 0 by default, may be set programmatically or via the exitCodeOnVersionHelp annotation.
        Since:
        4.0
        See Also:
        CommandLine.execute(String...)
      • exitCodeOnVersionHelp

        public int exitCodeOnVersionHelp()
        Returns exit code for successful termination after printing version help on user request. 0 by default, may be set programmatically or via the exitCodeOnUsageHelp annotation.
        Since:
        4.0
        See Also:
        CommandLine.execute(String...)
      • exitCodeOnExecutionException

        public int exitCodeOnExecutionException()
        Returns exit code signifying that an exception occurred when invoking the Runnable, Callable or Method user object of a command. 1 by default, may be set programmatically or via the exitCodeOnExecutionException annotation.
        Since:
        4.0
        See Also:
        CommandLine.execute(String...)
      • 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:
        CommandLine.Command.subcommandsRepeatable()
      • toString

        public java.lang.String toString()
        Returns a string representation of this command, used in error messages and trace messages.
        Overrides:
        toString in class java.lang.Object
      • name

        public CommandLine.Model.CommandSpec name​(java.lang.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​(java.lang.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, or null.
        Returns:
        this CommandSpec for method chaining
        Since:
        3.6
      • version

        public CommandLine.Model.CommandSpec version​(java.lang.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 is set.
        Returns:
        this CommandSpec for method chaining
      • exitCodeOnExecutionException

        public CommandLine.Model.CommandSpec exitCodeOnExecutionException​(int newValue)
        Sets exit code signifying that an exception occurred when invoking the Runnable, Callable or Method user object of a command. 1 by default.
        Since:
        4.0
        See Also:
        CommandLine.execute(String...)
      • inherited

        public boolean inherited()
        Returns whether this command is inherited from a parent command.
        Since:
        4.6
        See Also:
        CommandLine.Command.scope()
      • scopeType

        public CommandLine.ScopeType scopeType()
        Returns the scope of this argument; it 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
      • modelTransformer

        public CommandLine.IModelTransformer modelTransformer()
        Returns the model transformer for this CommandSpec instance.
        Since:
        4.6
      • subcommandsRepeatable

        public CommandLine.Model.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:
        CommandLine.Command.subcommandsRepeatable()
      • withToString

        public CommandLine.Model.CommandSpec withToString​(java.lang.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​(CommandLine.Command cmd,
                                            CommandLine.IFactory factory)
        Updates the following attributes from the specified @Command annotation: aliases, parser separator, command name, version, help command, version provider, default provider and usage message spec.
        Parameters:
        cmd - the @Command annotation to get attribute values from
        factory - factory used to instantiate classes
        Since:
        3.7
      • findOption

        public CommandLine.Model.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 CommandLine.Model.OptionSpec findOption​(java.lang.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.