org.apache.logging.log4j.core.tools.picocli

Annotation Type CommandLine.Command

@Retention(value=RUNTIME)
 @Target(value={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 and Description
boolean	abbreviateSynopsis Specify true 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 Specify true to show default values in the description column of the options list (except for boolean options).
boolean	sortOptions Specify false 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

public abstract 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

public abstract 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());
 

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

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract boolean abbreviateSynopsis

Specify true 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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.

See Also:

CommandLine.Help.sortOptions

Default:

true

requiredOptionMarker

public abstract 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:

32

showDefaultValues

public abstract boolean showDefaultValues

Specify true 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

public abstract 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

public abstract 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

public abstract 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:

{}