Package nz.org.riskscape.picocli

Annotation Interface CommandLine.Command

Enclosing class:
CommandLine
@Retention(RUNTIME) @Target({TYPE,LOCAL_VARIABLE,FIELD,PACKAGE,METHOD}) public static @interface CommandLine.Command

Annotate your class with @Command when you want more control over the format of the generated help message. From 3.6, methods can also be annotated with @Command, where the method parameters define the command options and positional parameters. 

  @Command(name              = "Encrypt", mixinStandardHelpOptions = true,
         description         = "Encrypt FILE(s), or standard input, to standard output or to the output file.",
         version             = "Encrypt version 1.0",
         footer              = "Copyright (c) 2017",
         exitCodeListHeading = "Exit Codes:%n",
         exitCodeList        = { " 0:Successful program execution.",
                                 "64:Invalid input: an unknown option or invalid parameter was specified.",
                                 "70:Execution exception: an exception occurred while executing the business logic."}
         )
  public class Encrypt {
      @Parameters(paramLabel = "FILE", description = "Any number of input files")
      private List<File> files = new ArrayList<File>();

 
 
 &#064;Option(names = { "-o", "--out" }, description = "Output file (default: print to console)")
  private File outputFile;
 
  &#064;Option(names = { "-v", "--verbose"}, description = "Verbose mode. Helpful for troubleshooting. Multiple -v options increase the verbosity.")
  private boolean[] verbose;
 

 
 
}

The structure of a help message looks like this:

  • [header]
  • [synopsis]: Usage: <commandName> [OPTIONS] [FILE...]
  • [description]
  • [parameter list]: [FILE...] Any number of input files
  • [option list]: -h, --help prints this help message and exits
  • [exit code list]
  • [footer]

  • Element Details

    • name

      String name
      Program name to show in the synopsis. If omitted, "<main class>" is used. For declaratively added subcommands, this attribute is also used by the parser to recognize subcommands in the command line arguments.
      Returns:
      the program name to show in the synopsis
      See Also:
      Default:
      "<main class>"

    • aliases

      String[] aliases
      Alternative command names by which this subcommand is recognized on the command line.
      Returns:
      one or more alternative command names
      Since:
      3.1
      Default:
      {}

    • subcommands

      Class<?>[] subcommands
      A list of classes to instantiate and register as subcommands. When registering subcommands declaratively like this, you don't need to call the CommandLine.addSubcommand(String, Object) method. For example, this: 
       @Command(subcommands = {
         GitStatus.class,
         GitCommit.class,
         GitBranch.class })
 public class Git { ... }

 CommandLine commandLine = new CommandLine(new Git());
      is equivalent to this: 
       // alternative: programmatically add subcommands.
 // NOTE: in this case there should be no `subcommands` attribute on the @Command annotation.
 @Command public class Git { ... }

 CommandLine commandLine = new CommandLine(new Git())
         .addSubcommand("status",   new GitStatus())
         .addSubcommand("commit",   new GitCommit())
         .addSubcommand("branch",   new GitBranch());
      Applications may be interested in the following built-in commands in picocli that can be used as subcommands:
      • CommandLine.HelpCommand - a help subcommand that prints help on the following or preceding command
      • AutoComplete.GenerateCompletion - a generate-completion subcommand that prints a Bash/ZSH completion script for its parent command, so that clients can install autocompletion in one line by running source <(parent-command generate-completion) in the shell
      Returns:
      the declaratively registered subcommands of this command, or an empty array if none
      Since:
      0.9.8
      See Also:
      Default:
      {}

    • addMethodSubcommands

      boolean addMethodSubcommands
      Specify whether methods annotated with @Command should be registered as subcommands of their enclosing @Command class. The default is true. For example: 
       @Command
 public class Git {
     @Command
     void status() { ... }
 }

 CommandLine git = new CommandLine(new Git());
      is equivalent to this: 
       // don't add command methods as subcommands automatically
 @Command(addMethodSubcommands = false)
 public class Git {
     @Command
     void status() { ... }
 }

 // add command methods as subcommands programmatically
 CommandLine git = new CommandLine(new Git());
 CommandLine status = new CommandLine(CommandLine.getCommandMethods(Git.class, "status").get(0));
 git.addSubcommand("status", status);
      Returns:
      whether methods annotated with @Command should be registered as subcommands
      Since:
      3.6.0
      See Also:
      Default:
      true

    • separator

      String separator
      String that separates options from option parameters. Default is "=". Spaces are also accepted.
      Returns:
      the string that separates options from option parameters, used both when parsing and when generating usage help
      See Also:
      Default:
      "="

    • version

      String[] version
      Version information for this command, to print to the console when the user specifies an option to request version help. Each element of the array is rendered on a separate line.

      May contain embedded format specifiers like %n line separators. Literal percent '%' characters must be escaped with another %.

      This is not part of the usage help message.

      Returns:
      a string or an array of strings with version information about this command (each string in the array is displayed on a separate line).
      Since:
      0.9.8
      See Also:
      Default:
      {}

    • versionProvider

      Class<? extends CommandLine.IVersionProvider> versionProvider
      Class that can provide version information dynamically at runtime. An implementation may return version information obtained from the JAR manifest, a properties file or some other source.
      Returns:
      a Class that can provide version information dynamically at runtime
      Since:
      2.2
      Default:
      nz.org.riskscape.picocli.CommandLine.NoVersionProvider.class

    • mixinStandardHelpOptions

      boolean mixinStandardHelpOptions

      Adds the standard -h and --help usageHelp options and -V and --version versionHelp options to the options of this command.

      Note that if no version() or versionProvider() is specified, the --version option will not print anything.

      For internationalization: the help option has descriptionKey = &quot;mixinStandardHelpOptions.help&quot;, and the version option has descriptionKey = &quot;mixinStandardHelpOptions.version&quot;.

      Returns:
      whether the auto-help mixin should be added to this command
      Default:
      false

    • helpCommand

      boolean helpCommand
      Set this attribute to true if this subcommand is a help command, and required options and positional parameters of the parent command should not be validated. If a subcommand marked as helpCommand is specified on the command line, picocli will not validate the parent arguments (so no "missing required option" errors) and the CommandLine.printHelpIfRequested(List, PrintStream, PrintStream, Help.Ansi) method will return true.
      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
      Since:
      3.0
      Default:
      false

    • headerHeading

      String headerHeading
      Set the heading preceding the header section.

      May contain embedded format specifiers like %n line separators. Literal percent '%' characters must be escaped with another %.

      Returns:
      the heading preceding the header section
      See Also:
      Default:
      ""

    • header

      String[] header
      Optional summary description of the command, shown before the synopsis. Each element of the array is rendered on a separate line.

      May contain embedded format specifiers like %n line separators. Literal percent '%' characters must be escaped with another %.

      Returns:
      summary description of the command
      See Also:
      Default:
      {}

    • synopsisHeading

      String synopsisHeading
      Set the heading preceding the synopsis text. The default heading is "Usage: " (without a line break between the heading and the synopsis text).

      May contain embedded format specifiers like %n line separators. Literal percent '%' characters must be escaped with another %.

      Returns:
      the heading preceding the synopsis text
      See Also:
      Default:
      "Usage: "

    • abbreviateSynopsis

      boolean abbreviateSynopsis
      Specify true to generate an abbreviated synopsis like "<main> [OPTIONS] [PARAMETERS...] [COMMAND]". By default, a detailed synopsis with individual option names and parameters is generated.
      Returns:
      whether the synopsis should be abbreviated
      See Also:
      Default:
      false

    • customSynopsis

      String[] customSynopsis
      Specify one or more custom synopsis lines to display instead of an auto-generated synopsis. Each element of the array is rendered on a separate line.

      May contain embedded format specifiers like %n line separators. Literal percent '%' characters must be escaped with another %.

      Returns:
      custom synopsis text to replace the auto-generated synopsis
      See Also:
      Default:
      {}

    • synopsisSubcommandLabel

      String synopsisSubcommandLabel

      Specify the String to show in the synopsis for the subcommands of this command. The default is &quot;[COMMAND]&quot;. Ignored if this command has no subcommands.

      Since:
      4.0
      Default:
      "[COMMAND]"

    • descriptionHeading

      String descriptionHeading
      Set the heading preceding the description section.

      May contain embedded format specifiers like %n line separators. Literal percent '%' characters must be escaped with another %.

      Returns:
      the heading preceding the description section
      See Also:
      Default:
      ""

    • description

      String[] description
      Optional text to display between the synopsis line(s) and the list of options. Each element of the array is rendered on a separate line.

      May contain embedded format specifiers like %n line separators. Literal percent '%' characters must be escaped with another %.

      Returns:
      description of this command
      See Also:
      Default:
      {}

    • parameterListHeading

      String parameterListHeading
      Set the heading preceding the parameters list.

      May contain embedded format specifiers like %n line separators. Literal percent '%' characters must be escaped with another %.

      Returns:
      the heading preceding the parameters list
      See Also:
      Default:
      ""

    • optionListHeading

      String optionListHeading
      Set the heading preceding the options list.

      May contain embedded format specifiers like %n line separators. Literal percent '%' characters must be escaped with another %.

      Returns:
      the heading preceding the options list
      See Also:
      Default:
      ""

    • sortOptions

      boolean sortOptions
      Specify false to show Options in declaration order. The default is to sort alphabetically.
      Returns:
      whether options should be shown in alphabetic order.
      Default:
      true

    • requiredOptionMarker

      char requiredOptionMarker
      Prefix required options with this character in the options list. The default is no marker: the synopsis indicates which options and parameters are required.
      Returns:
      the character to show in the options list to mark required options
      Default:
      ' '

    • defaultValueProvider

      Class<? extends CommandLine.IDefaultValueProvider> defaultValueProvider
      Class that can provide default values dynamically at runtime. An implementation may return default value obtained from a configuration file like a properties file or some other source.

      Applications may be interested in the CommandLine.PropertiesDefaultProvider built-in default provider that allows end users to maintain their own default values for options and positional parameters, which may override the defaults that are hard-coded in the application.

      Returns:
      a Class that can provide default values dynamically at runtime
      Since:
      3.6
      Default:
      nz.org.riskscape.picocli.CommandLine.NoDefaultProvider.class

    • showDefaultValues

      boolean showDefaultValues
      Specify true to show default values in the description column of the options list (except for boolean options). False by default.

      Note that picocli 3.2 allows embedding default values anywhere in the option or positional parameter description that ignores this setting.

      Returns:
      whether the default values for options and parameters should be shown in the description column
      Default:
      false

    • commandListHeading

      String commandListHeading
      Set the heading preceding the subcommands list. The default heading is "Commands:%n" (with a line break at the end).

      May contain embedded format specifiers like %n line separators. Literal percent '%' characters must be escaped with another %.

      Returns:
      the heading preceding the subcommands list
      See Also:
      Default:
      "Commands:%n"

    • footerHeading

      String footerHeading
      Set the heading preceding the footer section.

      May contain embedded format specifiers like %n line separators. Literal percent '%' characters must be escaped with another %.

      Returns:
      the heading preceding the footer section
      See Also:
      Default:
      ""

    • footer

      String[] footer
      Optional text to display after the list of options. Each element of the array is rendered on a separate line.

      May contain embedded format specifiers like %n line separators. Literal percent '%' characters must be escaped with another %.

      Returns:
      text to display after the list of options
      See Also:
      Default:
      {}

    • hidden

      boolean hidden

      Set hidden=true if this command should not be included in the list of commands in the usage help of the parent command.

      Returns:
      whether this command should be excluded from the usage message
      Since:
      3.0
      Default:
      false

    • resourceBundle

      String resourceBundle
      Set the base name of the ResourceBundle to find option and positional parameters descriptions, as well as usage help message sections and section headings.

      See CommandLine.Model.Messages for more details and an example.

      Returns:
      the base name of the ResourceBundle for usage help strings
      Since:
      3.6
      See Also:
      Default:
      ""

    • usageHelpWidth

      int usageHelpWidth
      Set the usage help message width. The default is 80.
      Since:
      3.7
      See Also:
      Default:
      80

    • usageHelpAutoWidth

      boolean usageHelpAutoWidth
      If true, picocli will attempt to detect the terminal width and adjust the usage help message accordingly. End users may enable this by setting system property "picocli.usage.width" to AUTO, and may disable this by setting this system property to a numeric value. This feature requires Java 7 or greater. The default is false
      Since:
      4.0
      See Also:
      Default:
      false

    • exitCodeOnSuccess

      int exitCodeOnSuccess
      Exit code for successful termination. by default.
      Since:
      4.0
      See Also:
      Default:
      0

    • exitCodeOnUsageHelp

      int exitCodeOnUsageHelp
      Exit code for successful termination after printing usage help on user request. by default.
      Since:
      4.0
      See Also:
      Default:
      0

    • exitCodeOnVersionHelp

      int exitCodeOnVersionHelp
      Exit code for successful termination after printing version help on user request. by default.
      Since:
      4.0
      See Also:
      Default:
      0

    • exitCodeOnInvalidInput

      int exitCodeOnInvalidInput
      Exit code for command line usage error. by default.
      Since:
      4.0
      See Also:
      Default:
      2

    • exitCodeOnExecutionException

      int exitCodeOnExecutionException
      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:
      Default:
      1

    • exitCodeListHeading

      String exitCodeListHeading
      Set the heading preceding the exit codes section, may contain "%n" line separators. "" (empty string) by default.
      Since:
      4.0
      See Also:
      Default:
      ""

    • exitCodeList

      String[] exitCodeList
      Set the values to be displayed in the exit codes section as a list of "key:value" pairs: keys are exit codes, values are descriptions. Descriptions may contain "%n" line separators.

      For example:

       @Command(exitCodeListHeading = "Exit Codes:%n",
          exitCodeList = { " 0:Successful program execution.",
                           "64:Invalid input: an unknown option or invalid parameter was specified.",
                           "70:Execution exception: an exception occurred while executing the business logic."})
      Since:
      4.0
      Default:
      {}