Class CommandLine
- java.lang.Object
-
- org.apache.logging.log4j.core.tools.picocli.CommandLine
-
public class CommandLine extends Object
CommandLine interpreter that uses reflection to initialize an annotated domain object with values obtained from the command line arguments.
Example
import static picocli.CommandLine.*; @Command(header = "Encrypt FILE(s), or standard input, to standard output or to the output file.", version = "v1.2.3") public class Encrypt { @Parameters(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; @Option(names = { "-v", "--verbose"}, description = "Verbosely list files processed") private boolean verbose; @Option(names = { "-h", "--help", "-?", "-help"}, usageHelp = true, description = "Display this help and exit") private boolean help; @Option(names = { "-V", "--version"}, versionHelp = true, description = "Display version info and exit") private boolean versionHelp; }
Use
CommandLine
to initialize a domain object as follows:public static void main(String... args) { Encrypt encrypt = new Encrypt(); try { List<CommandLine> parsedCommands = new CommandLine(encrypt).parse(args); if (!CommandLine.printHelpIfRequested(parsedCommands, System.err, Help.Ansi.AUTO)) { runProgram(encrypt); } } catch (ParameterException ex) { // command line arguments could not be parsed System.err.println(ex.getMessage()); ex.getCommandLine().usage(System.err); } }
Invoke the above program with some command line arguments. The below are all equivalent:
--verbose --out=outfile in1 in2 --verbose --out outfile in1 in2 -v --out=outfile in1 in2 -v -o outfile in1 in2 -v -o=outfile in1 in2 -vo outfile in1 in2 -vo=outfile in1 in2 -v -ooutfile in1 in2 -vooutfile in1 in2
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
CommandLine.Command
Annotate your class with@Command
when you want more control over the format of the generated help message.static class
CommandLine.DefaultExceptionHandler
Default exception handler that prints the exception message to the specifiedPrintStream
, followed by the usage message for the command or subcommand whose input was invalid.static class
CommandLine.DuplicateOptionAnnotationsException
Exception indicating that multiple fields have been annotated with the same Option name.static class
CommandLine.ExecutionException
Exception indicating a problem while invoking a command or subcommand.static class
CommandLine.Help
A collection of methods and inner classes that provide fine-grained control over the contents and layout of the usage help message to display to end users when help is requested or invalid input values were specified.static interface
CommandLine.IExceptionHandler
Represents a function that can handle aParameterException
that occurred while parsing the command line arguments.static class
CommandLine.InitializationException
Exception indicating a problem duringCommandLine
initialization.static interface
CommandLine.IParseResultHandler
Represents a function that can process a List ofCommandLine
objects resulting from successfully parsing the command line arguments.static interface
CommandLine.ITypeConverter<K>
When parsing command line arguments and initializing fields annotated with@Option
or@Parameters
, String values can be converted to any type for which aITypeConverter
is registered.static class
CommandLine.MaxValuesforFieldExceededException
Exception indicating that more values were specified for an option or parameter than itsarity
allows.static class
CommandLine.MissingParameterException
Exception indicating that a required parameter was not specified.static class
CommandLine.MissingTypeConverterException
Exception indicating that an annotated field had a type for which noCommandLine.ITypeConverter
was registered.static interface
CommandLine.Option
Annotate fields in your class with@Option
and picocli will initialize these fields when matching arguments are specified on the command line.static class
CommandLine.OverwrittenOptionException
Exception indicating that an option for a single-value option field has been specified multiple times on the command line.static class
CommandLine.ParameterException
Exception indicating something went wrong while parsing command line options.static class
CommandLine.ParameterIndexGapException
Exception indicating that there was a gap in the indices of the fields annotated withCommandLine.Parameters
.static interface
CommandLine.Parameters
Fields annotated with@Parameters
will be initialized with positional parameters.static class
CommandLine.PicocliException
Base class of all exceptions thrown bypicocli.CommandLine
.static class
CommandLine.Range
Describes the number of parameters required and accepted by an option or a positional parameter.static class
CommandLine.RunAll
Command line parse result handler that prints help if requested, and otherwise executes the top-level command and all subcommands asRunnable
orCallable
.static class
CommandLine.RunFirst
Command line parse result handler that prints help if requested, and otherwise executes the top-levelRunnable
orCallable
command.static class
CommandLine.RunLast
Command line parse result handler that prints help if requested, and otherwise executes the most specificRunnable
orCallable
subcommand.static class
CommandLine.TypeConversionException
Exception thrown byCommandLine.ITypeConverter
implementations to indicate a String could not be converted.static class
CommandLine.UnmatchedArgumentException
Exception indicating that a command line argument could not be mapped to any of the fields annotated withCommandLine.Option
orCommandLine.Parameters
.
-
Constructor Summary
Constructors Constructor Description CommandLine(Object command)
Constructs a newCommandLine
interpreter with the specified annotated object.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description CommandLine
addSubcommand(String name, Object command)
Registers a subcommand with the specified name.static <C extends Callable<T>,T>
Tcall(C callable, PrintStream out, String... args)
Delegates tocall(Callable, PrintStream, Help.Ansi, String...)
withCommandLine.Help.Ansi.AUTO
.static <C extends Callable<T>,T>
Tcall(C callable, PrintStream out, CommandLine.Help.Ansi ansi, String... args)
Convenience method to allow command line application authors to avoid some boilerplate code in their application.<T> T
getCommand()
Returns the annotated object that thisCommandLine
instance was constructed with.String
getCommandName()
Returns the command name (also called program name) displayed in the usage help synopsis.CommandLine
getParent()
Returns the command that this is a subcommand of, ornull
if this is a top-level command.String
getSeparator()
Returns the String that separates option names from option values when parsing command line options.Map<String,CommandLine>
getSubcommands()
Returns a map with the subcommands registered on this instance.List<String>
getUnmatchedArguments()
Returns the list of unmatched command line arguments, if any.boolean
isOverwrittenOptionsAllowed()
Returns whether options for single-value fields can be specified multiple times on the command line.boolean
isUnmatchedArgumentsAllowed()
Returns whether the end user may specify arguments on the command line that are not matched to any option or parameter fields.boolean
isUsageHelpRequested()
Returnstrue
if an option annotated withCommandLine.Option.usageHelp()
was specified on the command line.boolean
isVersionHelpRequested()
Returnstrue
if an option annotated withCommandLine.Option.versionHelp()
was specified on the command line.List<CommandLine>
parse(String... args)
Parses the specified command line arguments and returns a list ofCommandLine
objects representing the top-level command and any subcommands (if any) that were recognized and initialized during the parsing process.List<Object>
parseWithHandler(CommandLine.IParseResultHandler handler, PrintStream out, String... args)
Returns the result of callingparseWithHandlers(IParseResultHandler, PrintStream, Help.Ansi, IExceptionHandler, String...)
withHelp.Ansi.AUTO
and a newCommandLine.DefaultExceptionHandler
in addition to the specified parse result handler,PrintStream
, and the specified command line arguments.List<Object>
parseWithHandlers(CommandLine.IParseResultHandler handler, PrintStream out, CommandLine.Help.Ansi ansi, CommandLine.IExceptionHandler exceptionHandler, String... args)
static <T> T
populateCommand(T command, String... args)
Convenience method that initializes the specified annotated object from the specified command line arguments.static boolean
printHelpIfRequested(List<CommandLine> parsedCommands, PrintStream out, CommandLine.Help.Ansi ansi)
Helper method that may be useful when processing the list ofCommandLine
objects that result from successfully parsing command line arguments.void
printVersionHelp(PrintStream out)
Delegates toprintVersionHelp(PrintStream, Help.Ansi)
with the platform default.void
printVersionHelp(PrintStream out, CommandLine.Help.Ansi ansi)
Prints version information from theCommandLine.Command.version()
annotation to the specifiedPrintStream
.void
printVersionHelp(PrintStream out, CommandLine.Help.Ansi ansi, Object... params)
Prints version information from theCommandLine.Command.version()
annotation to the specifiedPrintStream
.<K> CommandLine
registerConverter(Class<K> cls, CommandLine.ITypeConverter<K> converter)
Registers the specified type converter for the specified class.static <R extends Runnable>
voidrun(R runnable, PrintStream out, String... args)
Delegates torun(Runnable, PrintStream, Help.Ansi, String...)
withCommandLine.Help.Ansi.AUTO
.static <R extends Runnable>
voidrun(R runnable, PrintStream out, CommandLine.Help.Ansi ansi, String... args)
Convenience method to allow command line application authors to avoid some boilerplate code in their application.CommandLine
setCommandName(String commandName)
Sets the command name (also called program name) displayed in the usage help synopsis to the specified value.CommandLine
setOverwrittenOptionsAllowed(boolean newValue)
Sets whether options for single-value fields can be specified multiple times on the command line without aCommandLine.OverwrittenOptionException
being thrown.CommandLine
setSeparator(String separator)
Sets the String the parser uses to separate option names from option values to the specified value.CommandLine
setUnmatchedArgumentsAllowed(boolean newValue)
Sets whether the end user may specify unmatched arguments on the command line without aCommandLine.UnmatchedArgumentException
being thrown.void
usage(PrintStream out)
Delegates tousage(PrintStream, Help.Ansi)
with the platform default.void
usage(PrintStream out, CommandLine.Help.Ansi ansi)
Delegates tousage(PrintStream, Help.ColorScheme)
with the default color scheme.void
usage(PrintStream out, CommandLine.Help.ColorScheme colorScheme)
Prints a usage help message for the annotated command class to the specifiedPrintStream
.static void
usage(Object command, PrintStream out)
Equivalent tonew CommandLine(command).usage(out)
.static void
usage(Object command, PrintStream out, CommandLine.Help.Ansi ansi)
Equivalent tonew CommandLine(command).usage(out, ansi)
.static void
usage(Object command, PrintStream out, CommandLine.Help.ColorScheme colorScheme)
Equivalent tonew CommandLine(command).usage(out, colorScheme)
.
-
-
-
Field Detail
-
VERSION
public static final String VERSION
This is picocli version "2.0.3".- See Also:
- Constant Field Values
-
-
Constructor Detail
-
CommandLine
public CommandLine(Object command)
Constructs a newCommandLine
interpreter with the specified annotated object. When theparse(String...)
method is called, fields of the specified object that are annotated with@Option
or@Parameters
will be initialized based on command line arguments.- Parameters:
command
- the object to initialize from the command line arguments- Throws:
CommandLine.InitializationException
- if the specified command object does not have aCommandLine.Command
,CommandLine.Option
orCommandLine.Parameters
annotation
-
-
Method Detail
-
addSubcommand
public CommandLine addSubcommand(String name, Object command)
Registers a subcommand with the specified name. For example:CommandLine commandLine = new CommandLine(new Git()) .addSubcommand("status", new GitStatus()) .addSubcommand("commit", new GitCommit(); .addSubcommand("add", new GitAdd()) .addSubcommand("branch", new GitBranch()) .addSubcommand("checkout", new GitCheckout()) //... ;
The specified object can be an annotated object or a
CommandLine
instance with its own nested subcommands. For example:CommandLine commandLine = new CommandLine(new MainCommand()) .addSubcommand("cmd1", new ChildCommand1()) // subcommand .addSubcommand("cmd2", new ChildCommand2()) .addSubcommand("cmd3", new CommandLine(new ChildCommand3()) // subcommand with nested sub-subcommands .addSubcommand("cmd3sub1", new GrandChild3Command1()) .addSubcommand("cmd3sub2", new GrandChild3Command2()) .addSubcommand("cmd3sub3", new CommandLine(new GrandChild3Command3()) // deeper nesting .addSubcommand("cmd3sub3sub1", new GreatGrandChild3Command3_1()) .addSubcommand("cmd3sub3sub2", new GreatGrandChild3Command3_2()) ) );
The default type converters are available on all subcommands and nested sub-subcommands, but custom type converters are registered only with the subcommand hierarchy as it existed when the custom type was registered. To ensure a custom type converter is available to all subcommands, register the type converter last, after adding subcommands.
See also the
CommandLine.Command.subcommands()
annotation to register subcommands declaratively.- Parameters:
name
- the string to recognize on the command line as a subcommandcommand
- the object to initialize with command line arguments following the subcommand name. This may be aCommandLine
instance with its own (nested) subcommands- Returns:
- this CommandLine object, to allow method chaining
- Since:
- 0.9.7
- See Also:
registerConverter(Class, ITypeConverter)
,CommandLine.Command.subcommands()
-
getSubcommands
public Map<String,CommandLine> getSubcommands()
Returns a map with the subcommands registered on this instance.- Returns:
- a map with the registered subcommands
- Since:
- 0.9.7
-
getParent
public CommandLine getParent()
Returns the command that this is a subcommand of, ornull
if this is a top-level command.- Returns:
- the command that this is a subcommand of, or
null
if this is a top-level command - Since:
- 0.9.8
- See Also:
addSubcommand(String, Object)
,CommandLine.Command.subcommands()
-
getCommand
public <T> T getCommand()
Returns the annotated object that thisCommandLine
instance was constructed with.- Type Parameters:
T
- the type of the variable that the return value is being assigned to- Returns:
- the annotated object that this
CommandLine
instance was constructed with - Since:
- 0.9.7
-
isUsageHelpRequested
public boolean isUsageHelpRequested()
Returnstrue
if an option annotated withCommandLine.Option.usageHelp()
was specified on the command line.- Returns:
- whether the parser encountered an option annotated with
CommandLine.Option.usageHelp()
. - Since:
- 0.9.8
-
isVersionHelpRequested
public boolean isVersionHelpRequested()
Returnstrue
if an option annotated withCommandLine.Option.versionHelp()
was specified on the command line.- Returns:
- whether the parser encountered an option annotated with
CommandLine.Option.versionHelp()
. - Since:
- 0.9.8
-
isOverwrittenOptionsAllowed
public boolean isOverwrittenOptionsAllowed()
Returns whether options for single-value fields can be specified multiple times on the command line. The default isfalse
and aCommandLine.OverwrittenOptionException
is thrown if this happens. Whentrue
, the last specified value is retained.- Returns:
true
if options for single-value fields can be specified multiple times on the command line,false
otherwise- Since:
- 0.9.7
-
setOverwrittenOptionsAllowed
public CommandLine setOverwrittenOptionsAllowed(boolean newValue)
Sets whether options for single-value fields can be specified multiple times on the command line without aCommandLine.OverwrittenOptionException
being thrown.The specified setting will be registered with this
CommandLine
and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.- Parameters:
newValue
- the new setting- Returns:
- this
CommandLine
object, to allow method chaining - Since:
- 0.9.7
-
isUnmatchedArgumentsAllowed
public boolean isUnmatchedArgumentsAllowed()
Returns whether the end user may specify arguments on the command line that are not matched to any option or parameter fields. The default isfalse
and aCommandLine.UnmatchedArgumentException
is thrown if this happens. Whentrue
, the last unmatched arguments are available via thegetUnmatchedArguments()
method.- Returns:
true
if the end use may specify unmatched arguments on the command line,false
otherwise- Since:
- 0.9.7
- See Also:
getUnmatchedArguments()
-
setUnmatchedArgumentsAllowed
public CommandLine setUnmatchedArgumentsAllowed(boolean newValue)
Sets whether the end user may specify unmatched arguments on the command line without aCommandLine.UnmatchedArgumentException
being thrown.The specified setting will be registered with this
CommandLine
and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.- Parameters:
newValue
- the new setting. Whentrue
, the last unmatched arguments are available via thegetUnmatchedArguments()
method.- Returns:
- this
CommandLine
object, to allow method chaining - Since:
- 0.9.7
- See Also:
getUnmatchedArguments()
-
getUnmatchedArguments
public List<String> getUnmatchedArguments()
Returns the list of unmatched command line arguments, if any.- Returns:
- the list of unmatched command line arguments or an empty list
- Since:
- 0.9.7
- See Also:
isUnmatchedArgumentsAllowed()
-
populateCommand
public static <T> T populateCommand(T command, String... args)
Convenience method that initializes the specified annotated object from the specified command line arguments.
This is equivalent to
CommandLine cli = new CommandLine(command); cli.parse(args); return command;
- Type Parameters:
T
- the type of the annotated object- Parameters:
command
- the object to initialize. This object contains fields annotated with@Option
or@Parameters
.args
- the command line arguments to parse- Returns:
- the specified annotated object
- Throws:
CommandLine.InitializationException
- if the specified command object does not have aCommandLine.Command
,CommandLine.Option
orCommandLine.Parameters
annotationCommandLine.ParameterException
- if the specified command line arguments are invalid- Since:
- 0.9.7
-
parse
public List<CommandLine> parse(String... args)
Parses the specified command line arguments and returns a list ofCommandLine
objects representing the top-level command and any subcommands (if any) that were recognized and initialized during the parsing process.If parsing succeeds, the first element in the returned list is always
this CommandLine
object. The returned list may contain more elements if subcommands were registered and these subcommands were initialized by matching command line arguments. If parsing fails, aCommandLine.ParameterException
is thrown.- Parameters:
args
- the command line arguments to parse- Returns:
- a list with the top-level command and any subcommands initialized by this method
- Throws:
CommandLine.ParameterException
- if the specified command line arguments are invalid; useCommandLine.ParameterException.getCommandLine()
to get the command or subcommand whose user input was invalid
-
printHelpIfRequested
public static boolean printHelpIfRequested(List<CommandLine> parsedCommands, PrintStream out, CommandLine.Help.Ansi ansi)
Helper method that may be useful when processing the list ofCommandLine
objects that result from successfully parsing command line arguments. This method prints out usage help if requested or version help if requested and returnstrue
. Otherwise, if none of the specifiedCommandLine
objects have help requested, this method returnsfalse
.Note that this method only looks at the
usageHelp
andversionHelp
attributes. Thehelp
attribute is ignored.- Parameters:
parsedCommands
- the list ofCommandLine
objects to check if help was requestedout
- thePrintStream
to print help to if requestedansi
- for printing help messages using ANSI styles and colors- Returns:
true
if help was printed,false
otherwise- Since:
- 2.0
-
parseWithHandler
public List<Object> parseWithHandler(CommandLine.IParseResultHandler handler, PrintStream out, String... args)
Returns the result of callingparseWithHandlers(IParseResultHandler, PrintStream, Help.Ansi, IExceptionHandler, String...)
withHelp.Ansi.AUTO
and a newCommandLine.DefaultExceptionHandler
in addition to the specified parse result handler,PrintStream
, and the specified command line arguments.This is a convenience method intended to offer the same ease of use as the
run
andcall
methods, but with more flexibility and better support for nested subcommands.Calling this method roughly expands to:
try { List<CommandLine> parsedCommands = parse(args); return parseResultsHandler.handleParseResult(parsedCommands, out, Help.Ansi.AUTO); } catch (ParameterException ex) { return new DefaultExceptionHandler().handleException(ex, out, ansi, args); }
Picocli provides some default handlers that allow you to accomplish some common tasks with very little code. The following handlers are available:
CommandLine.RunLast
handler prints help if requested, and otherwise gets the last specified command or subcommand and tries to execute it as aRunnable
orCallable
.CommandLine.RunFirst
handler prints help if requested, and otherwise executes the top-level command as aRunnable
orCallable
.CommandLine.RunAll
handler prints help if requested, and otherwise executes all recognized commands and subcommands asRunnable
orCallable
tasks.CommandLine.DefaultExceptionHandler
prints the error message followed by usage help
- Parameters:
handler
- the function that will process the result of successfully parsing the command line argumentsout
- thePrintStream
to print help to if requestedargs
- the command line arguments- Returns:
- a list of results, or an empty list if there are no results
- Throws:
CommandLine.ExecutionException
- if the command line arguments were parsed successfully but a problem occurred while processing the parse results; useCommandLine.ExecutionException.getCommandLine()
to get the command or subcommand where processing failed- Since:
- 2.0
- See Also:
CommandLine.RunLast
,CommandLine.RunAll
-
parseWithHandlers
public List<Object> parseWithHandlers(CommandLine.IParseResultHandler handler, PrintStream out, CommandLine.Help.Ansi ansi, CommandLine.IExceptionHandler exceptionHandler, String... args)
Tries to parse the specified command line arguments, and if successful, delegates the processing of the resulting list ofCommandLine
objects to the specified handler. If the command line arguments were invalid, theParameterException
thrown from theparse
method is caught and passed to the specifiedCommandLine.IExceptionHandler
.This is a convenience method intended to offer the same ease of use as the
run
andcall
methods, but with more flexibility and better support for nested subcommands.Calling this method roughly expands to:
try { List<CommandLine> parsedCommands = parse(args); return parseResultsHandler.handleParseResult(parsedCommands, out, ansi); } catch (ParameterException ex) { return new exceptionHandler.handleException(ex, out, ansi, args); }
Picocli provides some default handlers that allow you to accomplish some common tasks with very little code. The following handlers are available:
CommandLine.RunLast
handler prints help if requested, and otherwise gets the last specified command or subcommand and tries to execute it as aRunnable
orCallable
.CommandLine.RunFirst
handler prints help if requested, and otherwise executes the top-level command as aRunnable
orCallable
.CommandLine.RunAll
handler prints help if requested, and otherwise executes all recognized commands and subcommands asRunnable
orCallable
tasks.CommandLine.DefaultExceptionHandler
prints the error message followed by usage help
- Parameters:
handler
- the function that will process the result of successfully parsing the command line argumentsout
- thePrintStream
to print help to if requestedansi
- for printing help messages using ANSI styles and colorsexceptionHandler
- the function that can handle theParameterException
thrown when the command line arguments are invalidargs
- the command line arguments- Returns:
- a list of results produced by the
IParseResultHandler
or theIExceptionHandler
, or an empty list if there are no results - Throws:
CommandLine.ExecutionException
- if the command line arguments were parsed successfully but a problem occurred while processing the parse resultCommandLine
objects; useCommandLine.ExecutionException.getCommandLine()
to get the command or subcommand where processing failed- Since:
- 2.0
- See Also:
CommandLine.RunLast
,CommandLine.RunAll
,CommandLine.DefaultExceptionHandler
-
usage
public static void usage(Object command, PrintStream out)
Equivalent tonew CommandLine(command).usage(out)
. Seeusage(PrintStream)
for details.- Parameters:
command
- the object annotated withCommandLine.Command
,CommandLine.Option
andCommandLine.Parameters
out
- the print stream to print the help message to- Throws:
IllegalArgumentException
- if the specified command object does not have aCommandLine.Command
,CommandLine.Option
orCommandLine.Parameters
annotation
-
usage
public static void usage(Object command, PrintStream out, CommandLine.Help.Ansi ansi)
Equivalent tonew CommandLine(command).usage(out, ansi)
. Seeusage(PrintStream, Help.Ansi)
for details.- Parameters:
command
- the object annotated withCommandLine.Command
,CommandLine.Option
andCommandLine.Parameters
out
- the print stream to print the help message toansi
- whether the usage message should contain ANSI escape codes or not- Throws:
IllegalArgumentException
- if the specified command object does not have aCommandLine.Command
,CommandLine.Option
orCommandLine.Parameters
annotation
-
usage
public static void usage(Object command, PrintStream out, CommandLine.Help.ColorScheme colorScheme)
Equivalent tonew CommandLine(command).usage(out, colorScheme)
. Seeusage(PrintStream, Help.ColorScheme)
for details.- Parameters:
command
- the object annotated withCommandLine.Command
,CommandLine.Option
andCommandLine.Parameters
out
- the print stream to print the help message tocolorScheme
- theColorScheme
defining the styles for options, parameters and commands when ANSI is enabled- Throws:
IllegalArgumentException
- if the specified command object does not have aCommandLine.Command
,CommandLine.Option
orCommandLine.Parameters
annotation
-
usage
public void usage(PrintStream out)
Delegates tousage(PrintStream, Help.Ansi)
with the platform default.- Parameters:
out
- the printStream to print to- See Also:
usage(PrintStream, Help.ColorScheme)
-
usage
public void usage(PrintStream out, CommandLine.Help.Ansi ansi)
Delegates tousage(PrintStream, Help.ColorScheme)
with the default color scheme.- Parameters:
out
- the printStream to print toansi
- whether the usage message should include ANSI escape codes or not- See Also:
usage(PrintStream, Help.ColorScheme)
-
usage
public void usage(PrintStream out, CommandLine.Help.ColorScheme colorScheme)
Prints a usage help message for the annotated command class to the specifiedPrintStream
. Delegates construction of the usage help message to theCommandLine.Help
inner class and is equivalent to:Help help = new Help(command).addAllSubcommands(getSubcommands()); StringBuilder sb = new StringBuilder() .append(help.headerHeading()) .append(help.header()) .append(help.synopsisHeading()) //e.g. Usage: .append(help.synopsis()) //e.g. <main class> [OPTIONS] <command> [COMMAND-OPTIONS] [ARGUMENTS] .append(help.descriptionHeading()) //e.g. %nDescription:%n%n .append(help.description()) //e.g. {"Converts foos to bars.", "Use options to control conversion mode."} .append(help.parameterListHeading()) //e.g. %nPositional parameters:%n%n .append(help.parameterList()) //e.g. [FILE...] the files to convert .append(help.optionListHeading()) //e.g. %nOptions:%n%n .append(help.optionList()) //e.g. -h, --help displays this help and exits .append(help.commandListHeading()) //e.g. %nCommands:%n%n .append(help.commandList()) //e.g. add adds the frup to the frooble .append(help.footerHeading()) .append(help.footer()); out.print(sb);
Annotate your class with
CommandLine.Command
to control many aspects of the usage help message, including the program name, text of section headings and section contents, and some aspects of the auto-generated sections of the usage help message.To customize the auto-generated sections of the usage help message, like how option details are displayed, instantiate a
CommandLine.Help
object and use aCommandLine.Help.TextTable
with more of fewer columns, a custom layout, and/or a custom option renderer for ultimate control over which aspects of an Option or Field are displayed where.- Parameters:
out
- thePrintStream
to print the usage help message tocolorScheme
- theColorScheme
defining the styles for options, parameters and commands when ANSI is enabled
-
printVersionHelp
public void printVersionHelp(PrintStream out)
Delegates toprintVersionHelp(PrintStream, Help.Ansi)
with the platform default.- Parameters:
out
- the printStream to print to- Since:
- 0.9.8
- See Also:
printVersionHelp(PrintStream, Help.Ansi)
-
printVersionHelp
public void printVersionHelp(PrintStream out, CommandLine.Help.Ansi ansi)
Prints version information from theCommandLine.Command.version()
annotation to the specifiedPrintStream
. Each element of the array of version strings is printed on a separate line. Version strings may contain markup for colors and style.- Parameters:
out
- the printStream to print toansi
- whether the usage message should include ANSI escape codes or not- Since:
- 0.9.8
- See Also:
CommandLine.Command.version()
,CommandLine.Option.versionHelp()
,isVersionHelpRequested()
-
printVersionHelp
public void printVersionHelp(PrintStream out, CommandLine.Help.Ansi ansi, Object... params)
Prints version information from theCommandLine.Command.version()
annotation to the specifiedPrintStream
. Each element of the array of version strings is formatted with the specified parameters, and printed on a separate line. Both version strings and parameters may contain markup for colors and style.- Parameters:
out
- the printStream to print toansi
- whether the usage message should include ANSI escape codes or notparams
- Arguments referenced by the format specifiers in the version strings- Since:
- 1.0.0
- See Also:
CommandLine.Command.version()
,CommandLine.Option.versionHelp()
,isVersionHelpRequested()
-
call
public static <C extends Callable<T>,T> T call(C callable, PrintStream out, String... args)
Delegates tocall(Callable, PrintStream, Help.Ansi, String...)
withCommandLine.Help.Ansi.AUTO
.From picocli v2.0, this method prints usage help or version help if requested, and any exceptions thrown by the
Callable
are caught and rethrown wrapped in anExecutionException
.- Type Parameters:
C
- the annotated object must implement CallableT
- the return type of the most specific command (must implementCallable
)- Parameters:
callable
- the command to call when parsing succeeds.out
- the printStream to print toargs
- the command line arguments to parse- Returns:
null
if an error occurred while parsing the command line options, otherwise returns the result of calling the Callable- Throws:
CommandLine.InitializationException
- if the specified command object does not have aCommandLine.Command
,CommandLine.Option
orCommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Callable throws an exception- See Also:
call(Callable, PrintStream, Help.Ansi, String...)
,parseWithHandlers(IParseResultHandler, PrintStream, Help.Ansi, IExceptionHandler, String...)
,CommandLine.RunFirst
-
call
public static <C extends Callable<T>,T> T call(C callable, PrintStream out, CommandLine.Help.Ansi ansi, String... args)
Convenience method to allow command line application authors to avoid some boilerplate code in their application. The annotated object needs to implementCallable
. Calling this method is equivalent to:CommandLine cmd = new CommandLine(callable); List<CommandLine> parsedCommands; try { parsedCommands = cmd.parse(args); } catch (ParameterException ex) { out.println(ex.getMessage()); cmd.usage(out, ansi); return null; } if (CommandLine.printHelpIfRequested(parsedCommands, out, ansi)) { return null; } CommandLine last = parsedCommands.get(parsedCommands.size() - 1); try { Callable<Object> subcommand = last.getCommand(); return subcommand.call(); } catch (Exception ex) { throw new ExecutionException(last, "Error calling " + last.getCommand(), ex); }
If the specified Callable command has subcommands, the last subcommand specified on the command line is executed. Commands with subcommands may be interested in calling the
parseWithHandler
method with aCommandLine.RunAll
handler or a custom handler.From picocli v2.0, this method prints usage help or version help if requested, and any exceptions thrown by the
Callable
are caught and rethrown wrapped in anExecutionException
.- Type Parameters:
C
- the annotated object must implement CallableT
- the return type of the specifiedCallable
- Parameters:
callable
- the command to call when parsing succeeds.out
- the printStream to print toansi
- whether the usage message should include ANSI escape codes or notargs
- the command line arguments to parse- Returns:
null
if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the Callable- Throws:
CommandLine.InitializationException
- if the specified command object does not have aCommandLine.Command
,CommandLine.Option
orCommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Callable throws an exception- See Also:
parseWithHandlers(IParseResultHandler, PrintStream, Help.Ansi, IExceptionHandler, String...)
,CommandLine.RunLast
-
run
public static <R extends Runnable> void run(R runnable, PrintStream out, String... args)
Delegates torun(Runnable, PrintStream, Help.Ansi, String...)
withCommandLine.Help.Ansi.AUTO
.From picocli v2.0, this method prints usage help or version help if requested, and any exceptions thrown by the
Runnable
are caught and rethrown wrapped in anExecutionException
.- Type Parameters:
R
- the annotated object must implement Runnable- Parameters:
runnable
- the command to run when parsing succeeds.out
- the printStream to print toargs
- the command line arguments to parse- Throws:
CommandLine.InitializationException
- if the specified command object does not have aCommandLine.Command
,CommandLine.Option
orCommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Runnable throws an exception- See Also:
run(Runnable, PrintStream, Help.Ansi, String...)
,parseWithHandlers(IParseResultHandler, PrintStream, Help.Ansi, IExceptionHandler, String...)
,CommandLine.RunFirst
-
run
public static <R extends Runnable> void run(R runnable, PrintStream out, CommandLine.Help.Ansi ansi, String... args)
Convenience method to allow command line application authors to avoid some boilerplate code in their application. The annotated object needs to implementRunnable
. Calling this method is equivalent to:CommandLine cmd = new CommandLine(runnable); List<CommandLine> parsedCommands; try { parsedCommands = cmd.parse(args); } catch (ParameterException ex) { out.println(ex.getMessage()); cmd.usage(out, ansi); return null; } if (CommandLine.printHelpIfRequested(parsedCommands, out, ansi)) { return null; } CommandLine last = parsedCommands.get(parsedCommands.size() - 1); try { Runnable subcommand = last.getCommand(); subcommand.run(); } catch (Exception ex) { throw new ExecutionException(last, "Error running " + last.getCommand(), ex); }
If the specified Runnable command has subcommands, the last subcommand specified on the command line is executed. Commands with subcommands may be interested in calling the
parseWithHandler
method with aCommandLine.RunAll
handler or a custom handler.From picocli v2.0, this method prints usage help or version help if requested, and any exceptions thrown by the
Runnable
are caught and rethrown wrapped in anExecutionException
.- Type Parameters:
R
- the annotated object must implement Runnable- Parameters:
runnable
- the command to run when parsing succeeds.out
- the printStream to print toansi
- whether the usage message should include ANSI escape codes or notargs
- the command line arguments to parse- Throws:
CommandLine.InitializationException
- if the specified command object does not have aCommandLine.Command
,CommandLine.Option
orCommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Runnable throws an exception- See Also:
parseWithHandlers(IParseResultHandler, PrintStream, Help.Ansi, IExceptionHandler, String...)
,CommandLine.RunLast
-
registerConverter
public <K> CommandLine registerConverter(Class<K> cls, CommandLine.ITypeConverter<K> converter)
Registers the specified type converter for the specified class. When initializing fields annotated withCommandLine.Option
, the field's type is used as a lookup key to find the associated type converter, and this type converter converts the original command line argument string value to the correct type.Java 8 lambdas make it easy to register custom type converters:
commandLine.registerConverter(java.nio.file.Path.class, s -> java.nio.file.Paths.get(s)); commandLine.registerConverter(java.time.Duration.class, s -> java.time.Duration.parse(s));
Built-in type converters are pre-registered for the following java 1.5 types:
- all primitive types
- all primitive wrapper types: Boolean, Byte, Character, Double, Float, Integer, Long, Short
- any enum
- java.io.File
- java.math.BigDecimal
- java.math.BigInteger
- java.net.InetAddress
- java.net.URI
- java.net.URL
- java.nio.charset.Charset
- java.sql.Time
- java.util.Date
- java.util.UUID
- java.util.regex.Pattern
- StringBuilder
- CharSequence
- String
The specified converter will be registered with this
CommandLine
and the full hierarchy of its subcommands and nested sub-subcommands at the moment the converter is registered. Subcommands added later will not have this converter added automatically. To ensure a custom type converter is available to all subcommands, register the type converter last, after adding subcommands.- Type Parameters:
K
- the target type- Parameters:
cls
- the target class to convert parameter string values toconverter
- the class capable of converting string values to the specified target type- Returns:
- this CommandLine object, to allow method chaining
- See Also:
addSubcommand(String, Object)
-
getSeparator
public String getSeparator()
Returns the String that separates option names from option values when parsing command line options. "=" by default.- Returns:
- the String the parser uses to separate option names from option values
-
setSeparator
public CommandLine setSeparator(String separator)
Sets the String the parser uses to separate option names from option values to the specified value. The separator may also be set declaratively with theCommandLine.Command.separator()
annotation attribute.- Parameters:
separator
- the String that separates option names from option values- Returns:
- this
CommandLine
object, to allow method chaining
-
getCommandName
public String getCommandName()
Returns the command name (also called program name) displayed in the usage help synopsis. "<main class>" by default.- Returns:
- the command name (also called program name) displayed in the usage
-
setCommandName
public CommandLine setCommandName(String commandName)
Sets the command name (also called program name) displayed in the usage help synopsis to the specified value. Note that this method only modifies the usage help message, it does not impact parsing behaviour. The command name may also be set declaratively with theCommandLine.Command.name()
annotation attribute.- Parameters:
commandName
- command name (also called program name) displayed in the usage help synopsis- Returns:
- this
CommandLine
object, to allow method chaining
-
-