Annotation Type CommandLine.Command
-
@Retention(RUNTIME) @Target({TYPE,LOCAL_VARIABLE,PACKAGE}) public static @interface CommandLine.Command
Annotate your class with
@Command
when you want more control over the format of the generated help message.@Command(name = "Encrypt", description = "Encrypt FILE(s), or standard input, to standard output or to the output file.", footer = "Copyright (c) 2017") public class Encrypt { @Parameters(paramLabel = "FILE", type = File.class, description = "Any number of input files") private List<File> files = new ArrayList<File>(); @Option(names = { "-o", "--out" }, description = "Output file (default: print to console)") private File outputFile; }
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
- [footer]
-
-
Optional Element Summary
Optional Elements Modifier and Type Optional Element Description boolean
abbreviateSynopsis
Specifytrue
to generate an abbreviated synopsis like"<main> [OPTIONS] [PARAMETERS...]"
.String
commandListHeading
Set the heading preceding the subcommands list.String[]
customSynopsis
Specify one or more custom synopsis lines to display instead of an auto-generated synopsis.String[]
description
Optional text to display between the synopsis line(s) and the list of options.String
descriptionHeading
Set the heading preceding the description section.String[]
footer
Optional text to display after the list of options.String
footerHeading
Set the heading preceding the footer section.String[]
header
Optional summary description of the command, shown before the synopsis.String
headerHeading
Set the heading preceding the header section.String
name
Program name to show in the synopsis.String
optionListHeading
Set the heading preceding the options list.String
parameterListHeading
Set the heading preceding the parameters list.char
requiredOptionMarker
Prefix required options with this character in the options list.String
separator
String that separates options from option parameters.boolean
showDefaultValues
Specifytrue
to show default values in the description column of the options list (except for boolean options).boolean
sortOptions
Specifyfalse
to show Options in declaration order.Class<?>[]
subcommands
A list of classes to instantiate and register as subcommands.String
synopsisHeading
Set the heading preceding the synopsis text.String[]
version
Version information for this command, to print to the console when the user specifies an option to request version help.
-
-
-
Element Detail
-
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:
CommandLine.Help.commandName
- Default:
- "<main class>"
-
-
-
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 theCommandLine.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());
- Returns:
- the declaratively registered subcommands of this command, or an empty array if none
- Since:
- 0.9.8
- See Also:
CommandLine.addSubcommand(String, Object)
- Default:
- {}
-
-
-
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:
CommandLine.Help.separator
,CommandLine.setSeparator(String)
- Default:
- "="
-
-
-
version
String[] version
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:
- a string or an array of strings with version information about this command.
- Since:
- 0.9.8
- See Also:
CommandLine.printVersionHelp(PrintStream)
- Default:
- {}
-
-
-
headerHeading
String headerHeading
Set the heading preceding the header section. May contain embedded format specifiers.- Returns:
- the heading preceding the header section
- See Also:
CommandLine.Help.headerHeading(Object...)
- Default:
- ""
-
-
-
header
String[] header
Optional summary description of the command, shown before the synopsis.- Returns:
- summary description of the command
- See Also:
CommandLine.Help.header
,CommandLine.Help.header(Object...)
- Default:
- {}
-
-
-
synopsisHeading
String synopsisHeading
Set the heading preceding the synopsis text. May contain embedded format specifiers. The default heading is"Usage: "
(without a line break between the heading and the synopsis text).- Returns:
- the heading preceding the synopsis text
- See Also:
CommandLine.Help.synopsisHeading(Object...)
- Default:
- "Usage: "
-
-
-
abbreviateSynopsis
boolean abbreviateSynopsis
Specifytrue
to generate an abbreviated synopsis like"<main> [OPTIONS] [PARAMETERS...]"
. By default, a detailed synopsis with individual option names and parameters is generated.- Returns:
- whether the synopsis should be abbreviated
- See Also:
CommandLine.Help.abbreviateSynopsis
,CommandLine.Help.abbreviatedSynopsis()
,CommandLine.Help.detailedSynopsis(Comparator, boolean)
- Default:
- false
-
-
-
customSynopsis
String[] customSynopsis
Specify one or more custom synopsis lines to display instead of an auto-generated synopsis.- Returns:
- custom synopsis text to replace the auto-generated synopsis
- See Also:
CommandLine.Help.customSynopsis
,CommandLine.Help.customSynopsis(Object...)
- Default:
- {}
-
-
-
descriptionHeading
String descriptionHeading
Set the heading preceding the description section. May contain embedded format specifiers.- Returns:
- the heading preceding the description section
- See Also:
CommandLine.Help.descriptionHeading(Object...)
- Default:
- ""
-
-
-
description
String[] description
Optional text to display between the synopsis line(s) and the list of options.- Returns:
- description of this command
- See Also:
CommandLine.Help.description
,CommandLine.Help.description(Object...)
- Default:
- {}
-
-
-
parameterListHeading
String parameterListHeading
Set the heading preceding the parameters list. May contain embedded format specifiers.- Returns:
- the heading preceding the parameters list
- See Also:
CommandLine.Help.parameterListHeading(Object...)
- Default:
- ""
-
-
-
optionListHeading
String optionListHeading
Set the heading preceding the options list. May contain embedded format specifiers.- Returns:
- the heading preceding the options list
- See Also:
CommandLine.Help.optionListHeading(Object...)
- Default:
- ""
-
-
-
sortOptions
boolean sortOptions
Specifyfalse
to show Options in declaration order. The default is to sort alphabetically.- Returns:
- whether options should be shown in alphabetic order.
- See Also:
CommandLine.Help.sortOptions
- 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
- See Also:
CommandLine.Help.requiredOptionMarker
- Default:
- ' '
-
-
-
showDefaultValues
boolean showDefaultValues
Specifytrue
to show default values in the description column of the options list (except for boolean options). False by default.- Returns:
- whether the default values for options and parameters should be shown in the description column
- See Also:
CommandLine.Help.showDefaultValues
- Default:
- false
-
-
-
commandListHeading
String commandListHeading
Set the heading preceding the subcommands list. May contain embedded format specifiers. The default heading is"Commands:%n"
(with a line break at the end).- Returns:
- the heading preceding the subcommands list
- See Also:
CommandLine.Help.commandListHeading(Object...)
- Default:
- "Commands:%n"
-
-
-
footerHeading
String footerHeading
Set the heading preceding the footer section. May contain embedded format specifiers.- Returns:
- the heading preceding the footer section
- See Also:
CommandLine.Help.footerHeading(Object...)
- Default:
- ""
-
-
-
footer
String[] footer
Optional text to display after the list of options.- Returns:
- text to display after the list of options
- See Also:
CommandLine.Help.footer
,CommandLine.Help.footer(Object...)
- Default:
- {}
-
-