public class CommandLine
extends java.lang.Object
CommandLine interpreter that uses reflection to initialize an annotated domain object with values obtained from the command line arguments.
import static picocli.CommandLine.*; @Command(mixinStandardHelpOptions = true, version = "v3.0.0", header = "Encrypt FILE(s), or standard input, to standard output or to the output file.") 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 = "Verbose mode. Helpful for troubleshooting. Multiple -v options increase the verbosity.") private boolean[] verbose; }
Use CommandLine
to initialize a domain object as follows:
public static void main(String... args) { Encrypt encrypt = new Encrypt(); try { ParseResult parseResult = new CommandLine(encrypt).parseArgs(args); if (!CommandLine.printHelpIfRequested(parseResult)) { 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
Another example that implements Callable
and uses the CommandLine.call
convenience API to run in a single line of code:
@Command(description = "Prints the checksum (MD5 by default) of a file to STDOUT.", name = "checksum", mixinStandardHelpOptions = true, version = "checksum 3.0") class CheckSum implements Callable<Void> { @Parameters(index = "0", description = "The file whose checksum to calculate.") private File file; @Option(names = {"-a", "--algorithm"}, description = "MD5, SHA-1, SHA-256, ...") private String algorithm = "MD5"; public static void main(String[] args) { // CheckSum implements Callable, so parsing, error handling and handling user // requests for usage help or version help can be done with one line of code. CommandLine.call(new CheckSum(), args); } @Override public Void call() throws Exception { // your business logic goes here... byte[] fileContents = Files.readAllBytes(file.toPath()); byte[] digest = MessageDigest.getInstance(algorithm).digest(fileContents); System.out.println(javax.xml.bind.DatatypeConverter.printHexBinary(digest)); return null; } }
Modifier and Type | Class and Description |
---|---|
static class |
CommandLine.AbstractHandler<R,T extends CommandLine.AbstractHandler<R,T>>
Abstract superclass for
CommandLine.IParseResultHandler2 and CommandLine.IExceptionHandler2 implementations. |
static class |
CommandLine.AbstractParseResultHandler<R>
Command line parse result handler that returns a value.
|
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<R>
Default exception handler that handles invalid user input by printing the exception message, 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 class |
CommandLine.HelpCommand
Help command that can be installed as a subcommand on all application commands.
|
static interface |
CommandLine.IDefaultValueProvider
Provides default value for a command.
|
static interface |
CommandLine.IExceptionHandler
Deprecated.
Use
CommandLine.IExceptionHandler2 instead. |
static interface |
CommandLine.IExceptionHandler2<R>
Classes implementing this interface know how to handle
ParameterExceptions (usually from invalid user input)
and ExecutionExceptions that occurred while executing the Runnable or Callable command. |
static interface |
CommandLine.IFactory
Factory for instantiating classes that are registered declaratively with annotation attributes, like
CommandLine.Command.subcommands() , CommandLine.Option.converter() , CommandLine.Parameters.converter() and CommandLine.Command.versionProvider() . |
static interface |
CommandLine.IHelpCommandInitializable
Help commands that provide usage help for other commands can implement this interface to be initialized with the information they need.
|
static interface |
CommandLine.IHelpFactory
Creates the
CommandLine.Help instance used to render the usage help message. |
static interface |
CommandLine.IHelpSectionRenderer
Renders a section of the usage help message.
|
static class |
CommandLine.InitializationException
Exception indicating a problem during
CommandLine initialization. |
static interface |
CommandLine.IParseResultHandler
Deprecated.
Use
CommandLine.IParseResultHandler2 instead. |
static interface |
CommandLine.IParseResultHandler2<R>
Represents a function that can process the
ParseResult object 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 a ITypeConverter is registered. |
static interface |
CommandLine.IVersionProvider
Provides version information for a command.
|
static class |
CommandLine.MaxValuesExceededException
Exception indicating that more values were specified for an option or parameter than its
arity 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 no
CommandLine.ITypeConverter was
registered. |
static interface |
CommandLine.Mixin
Fields annotated with
@Mixin are "expanded" into the current command: @Option and
@Parameters in the mixin class are added to the options and positional parameters of this command. |
static class |
CommandLine.Model
This class provides a namespace for classes and interfaces that model concepts and attributes of command line interfaces in picocli.
|
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 with
CommandLine.Parameters . |
static interface |
CommandLine.Parameters
Fields annotated with
@Parameters will be initialized with positional parameters. |
static interface |
CommandLine.ParentCommand
Fields annotated with
@ParentCommand will be initialized with the parent command of the current subcommand. |
static class |
CommandLine.ParseResult
Encapsulates the result of parsing an array of command line arguments.
|
static class |
CommandLine.PicocliException
Base class of all exceptions thrown by
picocli.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 as
Runnable or Callable . |
static class |
CommandLine.RunFirst
Command line parse result handler that prints help if requested, and otherwise executes the top-level
Runnable or Callable command. |
static class |
CommandLine.RunLast
Command line parse result handler that prints help if requested, and otherwise executes the most specific
Runnable or Callable subcommand. |
static interface |
CommandLine.Spec
Fields annotated with
@Spec will be initialized with the CommandSpec for the command the field is part of. |
static class |
CommandLine.TypeConversionException
Exception thrown by
CommandLine.ITypeConverter implementations to indicate a String could not be converted. |
static interface |
CommandLine.Unmatched
Fields annotated with
@Unmatched will be initialized with the list of unmatched command line arguments, if any. |
static class |
CommandLine.UnmatchedArgumentException
Exception indicating that a command line argument could not be mapped to any of the fields annotated with
CommandLine.Option or CommandLine.Parameters . |
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
VERSION
This is picocli version "3.9.6".
|
Constructor and Description |
---|
CommandLine(java.lang.Object command)
Constructs a new
CommandLine interpreter with the specified object (which may be an annotated user object or a CommandSpec ) and a default subcommand factory. |
CommandLine(java.lang.Object command,
CommandLine.IFactory factory)
Constructs a new
CommandLine interpreter with the specified object (which may be an annotated user object or a CommandSpec ) and object factory. |
Modifier and Type | Method and Description |
---|---|
CommandLine |
addMixin(java.lang.String name,
java.lang.Object mixin)
Adds the options and positional parameters in the specified mixin to this command.
|
CommandLine |
addSubcommand(java.lang.String name,
java.lang.Object command)
Registers a subcommand with the specified name.
|
CommandLine |
addSubcommand(java.lang.String name,
java.lang.Object command,
java.lang.String... aliases)
Registers a subcommand with the specified name and all specified aliases.
|
static <C extends java.util.concurrent.Callable<T>,T> |
call(java.lang.Class<C> callableClass,
CommandLine.IFactory factory,
java.io.PrintStream out,
CommandLine.Help.Ansi ansi,
java.lang.String... args)
Delegates to
call(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...) with
System.err for diagnostic error messages. |
static <C extends java.util.concurrent.Callable<T>,T> |
call(java.lang.Class<C> callableClass,
CommandLine.IFactory factory,
java.io.PrintStream out,
java.io.PrintStream err,
CommandLine.Help.Ansi ansi,
java.lang.String... args)
Convenience method to allow command line application authors to avoid some boilerplate code in their application.
|
static <C extends java.util.concurrent.Callable<T>,T> |
call(java.lang.Class<C> callableClass,
CommandLine.IFactory factory,
java.io.PrintStream out,
java.lang.String... args)
Delegates to
call(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...) with
System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO . |
static <C extends java.util.concurrent.Callable<T>,T> |
call(java.lang.Class<C> callableClass,
CommandLine.IFactory factory,
java.lang.String... args)
Delegates to
call(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...) with System.out for
requested usage help messages, System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO . |
static <C extends java.util.concurrent.Callable<T>,T> |
call(C callable,
java.io.PrintStream out,
CommandLine.Help.Ansi ansi,
java.lang.String... args)
Delegates to
call(Callable, PrintStream, PrintStream, Help.Ansi, String...) with System.err for diagnostic error messages. |
static <C extends java.util.concurrent.Callable<T>,T> |
call(C callable,
java.io.PrintStream out,
java.io.PrintStream err,
CommandLine.Help.Ansi ansi,
java.lang.String... args)
Convenience method to allow command line application authors to avoid some boilerplate code in their application.
|
static <C extends java.util.concurrent.Callable<T>,T> |
call(C callable,
java.io.PrintStream out,
java.lang.String... args)
Delegates to
call(Callable, PrintStream, PrintStream, Help.Ansi, String...) with System.err for
diagnostic error messages and CommandLine.Help.Ansi.AUTO . |
static <C extends java.util.concurrent.Callable<T>,T> |
call(C callable,
java.lang.String... args)
Delegates to
call(Callable, PrintStream, PrintStream, Help.Ansi, String...) with System.out for
requested usage help messages, System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO . |
static CommandLine.DefaultExceptionHandler<java.util.List<java.lang.Object>> |
defaultExceptionHandler()
Convenience method that returns
new DefaultExceptionHandler<List<Object>>() . |
java.lang.Character |
getAtFileCommentChar()
Returns the character that starts a single-line comment or
null if all content of argument files should
be interpreted as arguments (without comments). |
<T> T |
getCommand()
Returns the annotated user object that this
CommandLine instance was constructed with. |
static java.util.List<java.lang.reflect.Method> |
getCommandMethods(java.lang.Class<?> cls,
java.lang.String methodName)
Helper to get methods of a class annotated with
@Command via reflection, optionally filtered by method name (not @Command.name ). |
java.lang.String |
getCommandName()
Returns the command name (also called program name) displayed in the usage help synopsis.
|
CommandLine.Model.CommandSpec |
getCommandSpec()
Returns the
CommandSpec model that this CommandLine was constructed with. |
CommandLine.IDefaultValueProvider |
getDefaultValueProvider()
Returns the default value provider for the command, or
null if none has been set. |
java.lang.String |
getEndOfOptionsDelimiter()
Returns the end-of-options delimiter that signals that the remaining command line arguments should be treated as positional parameters.
|
CommandLine.IHelpFactory |
getHelpFactory()
Returns the
IHelpFactory that is used to construct the usage help message. |
java.util.List<java.lang.String> |
getHelpSectionKeys()
Returns the section keys in the order that the usage help message should render the sections.
|
java.util.Map<java.lang.String,CommandLine.IHelpSectionRenderer> |
getHelpSectionMap()
Returns the map of section keys and renderers used to construct the usage help message.
|
java.util.Map<java.lang.String,java.lang.Object> |
getMixins()
Returns a map of user objects whose options and positional parameters were added to ("mixed in" with) this command.
|
CommandLine |
getParent()
Returns the command that this is a subcommand of, or
null if this is a top-level command. |
CommandLine.ParseResult |
getParseResult() |
java.util.ResourceBundle |
getResourceBundle()
Returns the ResourceBundle of this command or
null if no resource bundle is set. |
java.lang.String |
getSeparator()
Returns the String that separates option names from option values when parsing command line options.
|
java.util.Map<java.lang.String,CommandLine> |
getSubcommands()
Returns a map with the subcommands registered on this instance.
|
java.util.List<java.lang.String> |
getUnmatchedArguments()
Returns the list of unmatched command line arguments, if any.
|
int |
getUsageHelpWidth()
Returns the maximum width of the usage help message.
|
java.lang.String |
getUsageMessage()
Similar to
usage(PrintStream) , but returns the usage help message as a String instead of printing it to the PrintStream . |
java.lang.String |
getUsageMessage(CommandLine.Help.Ansi ansi)
Similar to
usage(PrintStream, Help.Ansi) , but returns the usage help message as a String instead of printing it to the PrintStream . |
java.lang.String |
getUsageMessage(CommandLine.Help.ColorScheme colorScheme)
Similar to
usage(PrintStream, Help.ColorScheme) , but returns the usage help message as a String instead of printing it to the PrintStream . |
static java.lang.Object |
invoke(java.lang.String methodName,
java.lang.Class<?> cls,
java.io.PrintStream out,
CommandLine.Help.Ansi ansi,
java.lang.String... args)
Delegates to
invoke(String, Class, PrintStream, PrintStream, Help.Ansi, String...) with the specified stream for
requested usage help messages, System.err for diagnostic error messages, and the specified Ansi mode. |
static java.lang.Object |
invoke(java.lang.String methodName,
java.lang.Class<?> cls,
java.io.PrintStream out,
java.io.PrintStream err,
CommandLine.Help.Ansi ansi,
java.lang.String... args)
Convenience method to allow command line application authors to avoid some boilerplate code in their application.
|
static java.lang.Object |
invoke(java.lang.String methodName,
java.lang.Class<?> cls,
java.io.PrintStream out,
java.lang.String... args)
Delegates to
invoke(String, Class, PrintStream, PrintStream, Help.Ansi, String...) with the specified stream for
requested usage help messages, System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO . |
static java.lang.Object |
invoke(java.lang.String methodName,
java.lang.Class<?> cls,
java.lang.String... args)
Delegates to
invoke(String, Class, PrintStream, PrintStream, Help.Ansi, String...) with System.out for
requested usage help messages, System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO . |
boolean |
isCaseInsensitiveEnumValuesAllowed()
Returns whether the parser should ignore case when converting arguments to
enum values. |
boolean |
isExpandAtFiles()
Returns whether arguments starting with
'@' should be treated as the path to an argument file and its
contents should be expanded into separate arguments for each line in the specified file. |
boolean |
isOverwrittenOptionsAllowed()
Returns whether options for single-value fields can be specified multiple times on the command line.
|
boolean |
isPosixClusteredShortOptionsAllowed()
Returns whether the parser accepts clustered short options.
|
boolean |
isSplitQuotedStrings()
Returns whether the parser is allowed to split quoted Strings or not.
|
boolean |
isStopAtPositional()
Returns whether the parser interprets the first positional parameter as "end of options" so the remaining
arguments are all treated as positional parameters.
|
boolean |
isStopAtUnmatched()
Returns whether the parser should stop interpreting options and positional parameters as soon as it encounters an
unmatched option.
|
boolean |
isToggleBooleanFlags()
Returns whether the value of boolean flag options should be "toggled" when the option is matched.
|
boolean |
isTrimQuotes()
Returns whether the parser should trim quotes from command line arguments before processing them.
|
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 |
isUnmatchedOptionsArePositionalParams()
Returns whether arguments on the command line that resemble an option should be treated as positional parameters.
|
boolean |
isUsageHelpRequested()
Returns
true if an option annotated with CommandLine.Option.usageHelp() was specified on the command line. |
boolean |
isUseSimplifiedAtFiles()
Returns whether to use a simplified argument file format that is compatible with JCommander.
|
boolean |
isVersionHelpRequested()
Returns
true if an option annotated with CommandLine.Option.versionHelp() was specified on the command line. |
java.util.List<CommandLine> |
parse(java.lang.String... args)
Parses the specified command line arguments and returns a list of
CommandLine objects representing the
top-level command and any subcommands (if any) that were recognized and initialized during the parsing process. |
CommandLine.ParseResult |
parseArgs(java.lang.String... args)
Parses the specified command line arguments and returns a list of
ParseResult with the options, positional
parameters, and subcommands (if any) that were recognized and initialized during the parsing process. |
<R> R |
parseWithHandler(CommandLine.IParseResultHandler2<R> handler,
java.lang.String[] args)
Returns the result of calling
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...) with
a new CommandLine.DefaultExceptionHandler in addition to the specified parse result handler and the specified command line arguments. |
java.util.List<java.lang.Object> |
parseWithHandler(CommandLine.IParseResultHandler handler,
java.io.PrintStream out,
java.lang.String... args)
Deprecated.
use
parseWithHandler(IParseResultHandler2, String[]) instead |
<R> R |
parseWithHandlers(CommandLine.IParseResultHandler2<R> handler,
CommandLine.IExceptionHandler2<R> exceptionHandler,
java.lang.String... args)
|
java.util.List<java.lang.Object> |
parseWithHandlers(CommandLine.IParseResultHandler handler,
java.io.PrintStream out,
CommandLine.Help.Ansi ansi,
CommandLine.IExceptionHandler exceptionHandler,
java.lang.String... args)
Deprecated.
|
static <T> T |
populateCommand(T command,
java.lang.String... args)
Convenience method that initializes the specified annotated object from the specified command line arguments.
|
static <T> T |
populateSpec(java.lang.Class<T> spec,
java.lang.String... args)
Convenience method that derives the command specification from the specified interface class, and returns an
instance of the specified interface.
|
static boolean |
printHelpIfRequested(CommandLine.ParseResult parseResult)
Delegates to
printHelpIfRequested(List, PrintStream, PrintStream, Help.Ansi) with
parseResult.asCommandLineList(), System.out, System.err, Help.Ansi.AUTO . |
static boolean |
printHelpIfRequested(java.util.List<CommandLine> parsedCommands,
java.io.PrintStream out,
CommandLine.Help.Ansi ansi)
Deprecated.
|
static boolean |
printHelpIfRequested(java.util.List<CommandLine> parsedCommands,
java.io.PrintStream out,
java.io.PrintStream err,
CommandLine.Help.Ansi ansi)
Helper method that may be useful when processing the list of
CommandLine objects that result from successfully
parsing command line arguments. |
static boolean |
printHelpIfRequested(java.util.List<CommandLine> parsedCommands,
java.io.PrintStream out,
java.io.PrintStream err,
CommandLine.Help.ColorScheme colorScheme)
Helper method that may be useful when processing the list of
CommandLine objects that result from successfully
parsing command line arguments. |
void |
printVersionHelp(java.io.PrintStream out)
Delegates to
printVersionHelp(PrintStream, Help.Ansi) with the platform default. |
void |
printVersionHelp(java.io.PrintStream out,
CommandLine.Help.Ansi ansi)
Prints version information from the
CommandLine.Command.version() annotation to the specified PrintStream . |
void |
printVersionHelp(java.io.PrintStream out,
CommandLine.Help.Ansi ansi,
java.lang.Object... params)
Prints version information from the
CommandLine.Command.version() annotation to the specified PrintStream . |
<K> CommandLine |
registerConverter(java.lang.Class<K> cls,
CommandLine.ITypeConverter<K> converter)
Registers the specified type converter for the specified class.
|
static <R extends java.lang.Runnable> |
run(java.lang.Class<R> runnableClass,
CommandLine.IFactory factory,
java.io.PrintStream out,
CommandLine.Help.Ansi ansi,
java.lang.String... args)
Delegates to
run(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...) with
System.err for diagnostic error messages. |
static <R extends java.lang.Runnable> |
run(java.lang.Class<R> runnableClass,
CommandLine.IFactory factory,
java.io.PrintStream out,
java.io.PrintStream err,
CommandLine.Help.Ansi ansi,
java.lang.String... args)
Convenience method to allow command line application authors to avoid some boilerplate code in their application.
|
static <R extends java.lang.Runnable> |
run(java.lang.Class<R> runnableClass,
CommandLine.IFactory factory,
java.io.PrintStream out,
java.lang.String... args)
Delegates to
run(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...) with
System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO . |
static <R extends java.lang.Runnable> |
run(java.lang.Class<R> runnableClass,
CommandLine.IFactory factory,
java.lang.String... args)
Delegates to
run(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...) with System.out for
requested usage help messages, System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO . |
static <R extends java.lang.Runnable> |
run(R runnable,
java.io.PrintStream out,
CommandLine.Help.Ansi ansi,
java.lang.String... args)
Delegates to
run(Runnable, PrintStream, PrintStream, Help.Ansi, String...) with System.err for diagnostic error messages. |
static <R extends java.lang.Runnable> |
run(R runnable,
java.io.PrintStream out,
java.io.PrintStream err,
CommandLine.Help.Ansi ansi,
java.lang.String... args)
Convenience method to allow command line application authors to avoid some boilerplate code in their application.
|
static <R extends java.lang.Runnable> |
run(R runnable,
java.io.PrintStream out,
java.lang.String... args)
Delegates to
run(Runnable, PrintStream, PrintStream, Help.Ansi, String...) with System.err for diagnostic error messages and CommandLine.Help.Ansi.AUTO . |
static <R extends java.lang.Runnable> |
run(R runnable,
java.lang.String... args)
Delegates to
run(Runnable, PrintStream, PrintStream, Help.Ansi, String...) with System.out for
requested usage help messages, System.err for diagnostic error messages, and CommandLine.Help.Ansi.AUTO . |
CommandLine |
setAtFileCommentChar(java.lang.Character atFileCommentChar)
Sets the character that starts a single-line comment or
null if all content of argument files should
be interpreted as arguments (without comments). |
CommandLine |
setCaseInsensitiveEnumValuesAllowed(boolean newValue)
Sets whether the parser should ignore case when converting arguments to
enum values. |
CommandLine |
setCommandName(java.lang.String commandName)
Sets the command name (also called program name) displayed in the usage help synopsis to the specified value.
|
CommandLine |
setDefaultValueProvider(CommandLine.IDefaultValueProvider newValue)
Sets a default value provider for the command and sub-commands
|
CommandLine |
setEndOfOptionsDelimiter(java.lang.String delimiter)
Sets the end-of-options delimiter that signals that the remaining command line arguments should be treated as positional parameters.
|
CommandLine |
setExpandAtFiles(boolean expandAtFiles)
Sets whether arguments starting with
'@' should be treated as the path to an argument file and its
contents should be expanded into separate arguments for each line in the specified file. |
CommandLine |
setHelpFactory(CommandLine.IHelpFactory helpFactory)
Sets a new
IHelpFactory to customize the usage help message. |
CommandLine |
setHelpSectionKeys(java.util.List<java.lang.String> keys)
Sets the section keys in the order that the usage help message should render the sections.
|
CommandLine |
setHelpSectionMap(java.util.Map<java.lang.String,CommandLine.IHelpSectionRenderer> map)
Sets the map of section keys and renderers used to construct the usage help message.
|
CommandLine |
setOverwrittenOptionsAllowed(boolean newValue)
Sets whether options for single-value fields can be specified multiple times on the command line without a
CommandLine.OverwrittenOptionException being thrown. |
CommandLine |
setPosixClusteredShortOptionsAllowed(boolean newValue)
Sets whether short options like
-x -v -f SomeFile can be clustered together like -xvfSomeFile . |
CommandLine |
setResourceBundle(java.util.ResourceBundle bundle)
Sets the ResourceBundle containing usage help message strings.
|
CommandLine |
setSeparator(java.lang.String separator)
Sets the String the parser uses to separate option names from option values to the specified value.
|
CommandLine |
setSplitQuotedStrings(boolean newValue)
Sets whether the parser is allowed to split quoted Strings.
|
CommandLine |
setStopAtPositional(boolean newValue)
Sets whether the parser interprets the first positional parameter as "end of options" so the remaining
arguments are all treated as positional parameters.
|
CommandLine |
setStopAtUnmatched(boolean newValue)
Sets whether the parser should stop interpreting options and positional parameters as soon as it encounters an
unmatched option.
|
CommandLine |
setToggleBooleanFlags(boolean newValue)
Sets whether the value of boolean flag options should be "toggled" when the option is matched.
|
CommandLine |
setTrimQuotes(boolean newValue)
Sets whether the parser should trim quotes from command line arguments before processing them.
|
CommandLine |
setUnmatchedArgumentsAllowed(boolean newValue)
Sets whether the end user may specify unmatched arguments on the command line without a
CommandLine.UnmatchedArgumentException being thrown. |
CommandLine |
setUnmatchedOptionsArePositionalParams(boolean newValue)
Sets whether arguments on the command line that resemble an option should be treated as positional parameters.
|
CommandLine |
setUsageHelpWidth(int width)
Sets the maximum width of the usage help message.
|
CommandLine |
setUseSimplifiedAtFiles(boolean simplifiedAtFiles)
Sets whether to use a simplified argument file format that is compatible with JCommander.
|
static void |
usage(java.lang.Object command,
java.io.PrintStream out)
Equivalent to
new CommandLine(command).usage(out) . |
static void |
usage(java.lang.Object command,
java.io.PrintStream out,
CommandLine.Help.Ansi ansi)
Equivalent to
new CommandLine(command).usage(out, ansi) . |
static void |
usage(java.lang.Object command,
java.io.PrintStream out,
CommandLine.Help.ColorScheme colorScheme)
Equivalent to
new CommandLine(command).usage(out, colorScheme) . |
void |
usage(java.io.PrintStream out)
Delegates to
usage(PrintStream, Help.Ansi) with the platform default. |
void |
usage(java.io.PrintStream out,
CommandLine.Help.Ansi ansi)
Delegates to
usage(PrintStream, Help.ColorScheme) with the default color scheme. |
void |
usage(java.io.PrintStream out,
CommandLine.Help.ColorScheme colorScheme)
Prints a usage help message for the annotated command class to the specified
PrintStream . |
void |
usage(java.io.PrintWriter writer)
Delegates to
usage(PrintWriter, Help.Ansi) with the platform default. |
void |
usage(java.io.PrintWriter writer,
CommandLine.Help.Ansi ansi)
Similar to
usage(PrintStream, Help.Ansi) but with the specified PrintWriter instead of a PrintStream . |
void |
usage(java.io.PrintWriter writer,
CommandLine.Help.ColorScheme colorScheme)
Similar to
usage(PrintStream, Help.ColorScheme) , but with the specified PrintWriter instead of a PrintStream . |
public static final java.lang.String VERSION
public CommandLine(java.lang.Object command)
CommandLine
interpreter with the specified object (which may be an annotated user object or a CommandSpec
) and a default subcommand factory.
The specified object may be a CommandSpec
object, or it may be a @Command
-annotated
user object with @Option
and @Parameters
-annotated fields, in which case picocli automatically
constructs a CommandSpec
from this user object.
When the parse(String...)
method is called, the CommandSpec
object will be
initialized based on command line arguments. If the commandSpec is created from an annotated user object, this
user object will be initialized based on the command line arguments.
command
- an annotated user object or a CommandSpec
object to initialize from the command line argumentsCommandLine.InitializationException
- if the specified command object does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationpublic CommandLine(java.lang.Object command, CommandLine.IFactory factory)
CommandLine
interpreter with the specified object (which may be an annotated user object or a CommandSpec
) and object factory.
The specified object may be a CommandSpec
object, or it may be a @Command
-annotated
user object with @Option
and @Parameters
-annotated fields, in which case picocli automatically
constructs a CommandSpec
from this user object.
If the specified command object is an interface Class
with @Option
and @Parameters
-annotated methods,
picocli creates a Proxy
whose methods return the matched command line values.
If the specified command object is a concrete Class
, picocli delegates to the factory to get an instance.
When the parse(String...)
method is called, the CommandSpec
object will be
initialized based on command line arguments. If the commandSpec is created from an annotated user object, this
user object will be initialized based on the command line arguments.
command
- an annotated user object or a CommandSpec
object to initialize from the command line argumentsfactory
- the factory used to create instances of subcommands, converters, etc., that are registered declaratively with annotation attributesCommandLine.InitializationException
- if the specified command object does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationpublic CommandLine.Model.CommandSpec getCommandSpec()
CommandSpec
model that this CommandLine
was constructed with.CommandSpec
modelpublic CommandLine addMixin(java.lang.String name, java.lang.Object mixin)
The specified object may be a CommandSpec
object, or it may be a user object with
@Option
and @Parameters
-annotated fields, in which case picocli automatically
constructs a CommandSpec
from this user object.
name
- the name by which the mixin object may later be retrievedmixin
- an annotated user object or a CommandSpec
object whose options and positional parameters to add to this commandpublic java.util.Map<java.lang.String,java.lang.Object> getMixins()
CommandSpec
objects without
user objects were programmatically added, use the underlying model
directly.public CommandLine addSubcommand(java.lang.String name, java.lang.Object command)
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.
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 a CommandLine
instance with its own (nested) subcommandsregisterConverter(Class, ITypeConverter)
,
CommandLine.Command.subcommands()
public CommandLine addSubcommand(java.lang.String name, java.lang.Object command, java.lang.String... aliases)
addSubcommand(String, Object)
.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 a CommandLine
instance with its own (nested) subcommandsaliases
- zero or more alias names that are also recognized on the command line as this subcommandaddSubcommand(String, Object)
public java.util.Map<java.lang.String,CommandLine> getSubcommands()
public CommandLine getParent()
null
if this is a top-level command.null
if this is a top-level commandaddSubcommand(String, Object)
,
CommandLine.Command.subcommands()
public <T> T getCommand()
CommandLine
instance was constructed with.T
- the type of the variable that the return value is being assigned toCommandLine
instance was constructed withpublic boolean isUsageHelpRequested()
true
if an option annotated with CommandLine.Option.usageHelp()
was specified on the command line.CommandLine.Option.usageHelp()
.public boolean isVersionHelpRequested()
true
if an option annotated with CommandLine.Option.versionHelp()
was specified on the command line.CommandLine.Option.versionHelp()
.public CommandLine.IHelpFactory getHelpFactory()
IHelpFactory
that is used to construct the usage help message.setHelpFactory(IHelpFactory)
public CommandLine setHelpFactory(CommandLine.IHelpFactory helpFactory)
IHelpFactory
to customize the usage help message.helpFactory
- the new help factory. Must be non-null
.
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.
CommandLine
object, to allow method chainingpublic java.util.List<java.lang.String> getHelpSectionKeys()
setSectionKeys
. The default keys are (in order):
SECTION_KEY_HEADER_HEADING
SECTION_KEY_HEADER
SECTION_KEY_SYNOPSIS_HEADING
SECTION_KEY_SYNOPSIS
SECTION_KEY_DESCRIPTION_HEADING
SECTION_KEY_DESCRIPTION
SECTION_KEY_PARAMETER_LIST_HEADING
SECTION_KEY_PARAMETER_LIST
SECTION_KEY_OPTION_LIST_HEADING
SECTION_KEY_OPTION_LIST
SECTION_KEY_COMMAND_LIST_HEADING
SECTION_KEY_COMMAND_LIST
SECTION_KEY_FOOTER_HEADING
SECTION_KEY_FOOTER
public CommandLine setHelpSectionKeys(java.util.List<java.lang.String> keys)
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.
Use CommandLine.Model.UsageMessageSpec.sectionKeys(List)
to customize a command without affecting its subcommands.
getHelpSectionKeys()
public java.util.Map<java.lang.String,CommandLine.IHelpSectionRenderer> getHelpSectionMap()
setSectionKeys
.
Sections that are either not in this map or not in the list returned by getSectionKeys
are omitted.
NOTE: By modifying the returned Map
, only the usage help message of this command is affected.
Use setHelpSectionMap(Map)
to customize the usage help message for this command and all subcommands.
public CommandLine setHelpSectionMap(java.util.Map<java.lang.String,CommandLine.IHelpSectionRenderer> map)
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.
Use CommandLine.Model.UsageMessageSpec.sectionMap(Map)
to customize a command without affecting its subcommands.
getHelpSectionMap()
public boolean isToggleBooleanFlags()
true
it is set to false
, and when the value is
false
it is set to true
. If toggling is off, flags are simply set to true
.true
the value of boolean flag options should be "toggled" when the option is matched, false
otherwisepublic CommandLine setToggleBooleanFlags(boolean newValue)
true
.
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.
newValue
- the new settingCommandLine
object, to allow method chainingpublic boolean isOverwrittenOptionsAllowed()
false
and a CommandLine.OverwrittenOptionException
is thrown if this happens.
When true
, the last specified value is retained.true
if options for single-value fields can be specified multiple times on the command line, false
otherwisepublic CommandLine setOverwrittenOptionsAllowed(boolean newValue)
CommandLine.OverwrittenOptionException
being thrown.
The default is false
.
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.
newValue
- the new settingCommandLine
object, to allow method chainingpublic boolean isPosixClusteredShortOptionsAllowed()
true
.true
if short options like -x -v -f SomeFile
can be clustered together like -xvfSomeFile
, false
otherwisepublic CommandLine setPosixClusteredShortOptionsAllowed(boolean newValue)
-x -v -f SomeFile
can be clustered together like -xvfSomeFile
. The default is true
.
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.
newValue
- the new settingCommandLine
object, to allow method chainingpublic boolean isCaseInsensitiveEnumValuesAllowed()
enum
values. The default is false
.true
if enum values can be specified that don't match the toString()
value of the enum constant, false
otherwise;
e.g., for an option of type java.time.DayOfWeek,
values MonDaY
, monday
and MONDAY
are all recognized if true
.public CommandLine setCaseInsensitiveEnumValuesAllowed(boolean newValue)
enum
values. The default is false
.
When set to true, for example, for an option of type java.time.DayOfWeek,
values MonDaY
, monday
and MONDAY
are all recognized if true
.
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.
newValue
- the new settingCommandLine
object, to allow method chainingpublic boolean isTrimQuotes()
true
if the property is present and empty,
or if its value is "true".true
if the parser should trim quotes from command line arguments before processing them, false
otherwise;public CommandLine setTrimQuotes(boolean newValue)
true
if the property is set and empty, or
if its value is "true".
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.
Calling this method will cause the "picocli.trimQuotes" property to have no effect.
newValue
- the new settingCommandLine
object, to allow method chainingpublic boolean isSplitQuotedStrings()
false
,
so quoted strings are treated as a single value that cannot be split.true
if the parser is allowed to split quoted Strings, false
otherwise;CommandLine.Model.ArgSpec.splitRegex()
public CommandLine setSplitQuotedStrings(boolean newValue)
false
.
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.
newValue
- the new settingCommandLine
object, to allow method chainingCommandLine.Model.ArgSpec.splitRegex()
public java.lang.String getEndOfOptionsDelimiter()
"--"
.public CommandLine setEndOfOptionsDelimiter(java.lang.String delimiter)
delimiter
- the end-of-options delimiter; must not be null
. The default is "--"
.CommandLine
object, to allow method chainingpublic CommandLine.IDefaultValueProvider getDefaultValueProvider()
null
if none has been set.null
CommandLine.Command.defaultValueProvider()
,
CommandLine.Model.CommandSpec.defaultValueProvider()
,
CommandLine.Model.ArgSpec.defaultValueString()
public CommandLine setDefaultValueProvider(CommandLine.IDefaultValueProvider newValue)
The specified setting will be registered with this CommandLine
and the full hierarchy of its
sub-commands and nested sub-subcommands at the moment this method is called. Sub-commands added
later will have the default setting. To ensure a setting is applied to all
sub-commands, call the setter last, after adding sub-commands.
newValue
- the default value provider to useCommandLine
object, to allow method chainingpublic boolean isStopAtPositional()
false
.true
if all values following the first positional parameter should be treated as positional parameters, false
otherwisepublic CommandLine setStopAtPositional(boolean newValue)
false
.
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.
newValue
- true
if all values following the first positional parameter should be treated as positional parameters, false
otherwiseCommandLine
object, to allow method chainingpublic boolean isStopAtUnmatched()
false
.
Setting this flag to true
automatically sets the unmatchedArgumentsAllowed flag to true
also.
true
when an unmatched option should result in the remaining command line arguments to be added to the
unmatchedArguments listpublic CommandLine setStopAtUnmatched(boolean newValue)
false
.
Setting this flag to true
automatically sets the unmatchedArgumentsAllowed flag to true
also.
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.
newValue
- true
when an unmatched option should result in the remaining command line arguments to be added to the
unmatchedArguments listCommandLine
object, to allow method chainingpublic boolean isUnmatchedOptionsArePositionalParams()
false
and the parser behaviour depends on isUnmatchedArgumentsAllowed()
.true
arguments on the command line that resemble an option should be treated as positional parameters, false
otherwisegetUnmatchedArguments()
public CommandLine setUnmatchedOptionsArePositionalParams(boolean newValue)
false
.
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.
newValue
- the new setting. When true
, arguments on the command line that resemble an option should be treated as positional parameters.CommandLine
object, to allow method chaininggetUnmatchedArguments()
,
isUnmatchedArgumentsAllowed()
public boolean isUnmatchedArgumentsAllowed()
false
and a CommandLine.UnmatchedArgumentException
is thrown if this happens.
When true
, the last unmatched arguments are available via the getUnmatchedArguments()
method.true
if the end use may specify unmatched arguments on the command line, false
otherwisegetUnmatchedArguments()
public CommandLine setUnmatchedArgumentsAllowed(boolean newValue)
CommandLine.UnmatchedArgumentException
being thrown.
The default is false
.
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.
newValue
- the new setting. When true
, the last unmatched arguments are available via the getUnmatchedArguments()
method.CommandLine
object, to allow method chaininggetUnmatchedArguments()
public java.util.List<java.lang.String> getUnmatchedArguments()
isUnmatchedArgumentsAllowed()
public static <T> T populateCommand(T command, java.lang.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;
T
- the type of the annotated objectcommand
- the object to initialize. This object contains fields annotated with
@Option
or @Parameters
.args
- the command line arguments to parseCommandLine.InitializationException
- if the specified command object does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ParameterException
- if the specified command line arguments are invalidpublic static <T> T populateSpec(java.lang.Class<T> spec, java.lang.String... args)
Convenience method that derives the command specification from the specified interface class, and returns an instance of the specified interface. The interface is expected to have annotated getter methods. Picocli will instantiate the interface and the getter methods will return the option and positional parameter values matched on the command line.
This is equivalent to
CommandLine cli = new CommandLine(spec); cli.parse(args); return cli.getCommand();
T
- the type of the annotated objectspec
- the interface that defines the command specification. This object contains getter methods annotated with
@Option
or @Parameters
.args
- the command line arguments to parseCommandLine.InitializationException
- if the specified command object does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ParameterException
- if the specified command line arguments are invalidpublic java.util.List<CommandLine> parse(java.lang.String... args)
CommandLine
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, a
CommandLine.ParameterException
is thrown.
args
- the command line arguments to parseCommandLine.ParameterException
- if the specified command line arguments are invalid; use
CommandLine.ParameterException.getCommandLine()
to get the command or subcommand whose user input was invalidpublic CommandLine.ParseResult parseArgs(java.lang.String... args)
ParseResult
with the options, positional
parameters, and subcommands (if any) that were recognized and initialized during the parsing process.
If parsing fails, a CommandLine.ParameterException
is thrown.
args
- the command line arguments to parseCommandLine.ParameterException
- if the specified command line arguments are invalid; use
CommandLine.ParameterException.getCommandLine()
to get the command or subcommand whose user input was invalidpublic CommandLine.ParseResult getParseResult()
public static CommandLine.DefaultExceptionHandler<java.util.List<java.lang.Object>> defaultExceptionHandler()
new DefaultExceptionHandler<List<Object>>()
.@Deprecated public static boolean printHelpIfRequested(java.util.List<CommandLine> parsedCommands, java.io.PrintStream out, CommandLine.Help.Ansi ansi)
printHelpIfRequested(List, PrintStream, PrintStream, Help.Ansi)
insteadpublic static boolean printHelpIfRequested(CommandLine.ParseResult parseResult)
printHelpIfRequested(List, PrintStream, PrintStream, Help.Ansi)
with
parseResult.asCommandLineList(), System.out, System.err, Help.Ansi.AUTO
.public static boolean printHelpIfRequested(java.util.List<CommandLine> parsedCommands, java.io.PrintStream out, java.io.PrintStream err, CommandLine.Help.Ansi ansi)
CommandLine
objects that result from successfully
parsing command line arguments. This method prints out
usage help if requested
or version help if requested
and returns true
. If the command is a CommandLine.Command.helpCommand()
and runnable
or callable
,
that command is executed and this method returns true
.
Otherwise, if none of the specified CommandLine
objects have help requested,
this method returns false
.
Note that this method only looks at the usageHelp
and
versionHelp
attributes. The help
attribute is ignored.
Implementation note:
When an error occurs while processing the help request, it is recommended custom Help commands throw a
CommandLine.ParameterException
with a reference to the parent command. This will print the error message and the
usage for the parent command, and will use the exit code of the exception handler if one was set.
parsedCommands
- the list of CommandLine
objects to check if help was requestedout
- the PrintStream
to print help to if requestederr
- the error string to print diagnostic messages to, in addition to the output from the exception handleransi
- for printing help messages using ANSI styles and colorstrue
if help was printed, false
otherwiseCommandLine.IHelpCommandInitializable
public static boolean printHelpIfRequested(java.util.List<CommandLine> parsedCommands, java.io.PrintStream out, java.io.PrintStream err, CommandLine.Help.ColorScheme colorScheme)
CommandLine
objects that result from successfully
parsing command line arguments. This method prints out
usage help if requested
or version help if requested
and returns true
. If the command is a CommandLine.Command.helpCommand()
and runnable
or callable
,
that command is executed and this method returns true
.
Otherwise, if none of the specified CommandLine
objects have help requested,
this method returns false
.
Note that this method only looks at the usageHelp
and
versionHelp
attributes. The help
attribute is ignored.
Implementation note:
When an error occurs while processing the help request, it is recommended custom Help commands throw a
CommandLine.ParameterException
with a reference to the parent command. This will print the error message and the
usage for the parent command, and will use the exit code of the exception handler if one was set.
parsedCommands
- the list of CommandLine
objects to check if help was requestedout
- the PrintStream
to print help to if requestederr
- the error string to print diagnostic messages to, in addition to the output from the exception handlercolorScheme
- for printing help messages using ANSI styles and colorstrue
if help was printed, false
otherwiseCommandLine.IHelpCommandInitializable
@Deprecated public java.util.List<java.lang.Object> parseWithHandler(CommandLine.IParseResultHandler handler, java.io.PrintStream out, java.lang.String... args)
parseWithHandler(IParseResultHandler2, String[])
insteadpublic <R> R parseWithHandler(CommandLine.IParseResultHandler2<R> handler, java.lang.String[] args)
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
with
a new CommandLine.DefaultExceptionHandler
in addition to the specified parse result handler and the specified command line arguments.
This is a convenience method intended to offer the same ease of use as the run
and call
methods, but with more flexibility and better
support for nested subcommands.
Calling this method roughly expands to:
try {
ParseResult parseResult = parseArgs(args);
return handler.handleParseResult(parseResult);
} catch (ParameterException ex) {
return new DefaultExceptionHandler<R>().handleParseException(ex, 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 a Runnable
or Callable
.CommandLine.RunFirst
handler prints help if requested, and otherwise executes the top-level command as a Runnable
or Callable
.CommandLine.RunAll
handler prints help if requested, and otherwise executes all recognized commands and subcommands as Runnable
or Callable
tasks.CommandLine.DefaultExceptionHandler
prints the error message followed by usage helpR
- the return type of this handlerhandler
- the function that will handle the result of successfully parsing the command line argumentsargs
- the command line argumentsCommandLine.ExecutionException
- if the command line arguments were parsed successfully but a problem occurred while processing the
parse results; use CommandLine.ExecutionException.getCommandLine()
to get the command or subcommand where processing failedCommandLine.RunLast
,
CommandLine.RunAll
@Deprecated public java.util.List<java.lang.Object> parseWithHandlers(CommandLine.IParseResultHandler handler, java.io.PrintStream out, CommandLine.Help.Ansi ansi, CommandLine.IExceptionHandler exceptionHandler, java.lang.String... args)
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
insteadpublic <R> R parseWithHandlers(CommandLine.IParseResultHandler2<R> handler, CommandLine.IExceptionHandler2<R> exceptionHandler, java.lang.String... args)
ParseResult
object to the specified handler.
If the command line arguments were invalid, the ParameterException
thrown from the parse
method
is caught and passed to the specified CommandLine.IExceptionHandler2
.
This is a convenience method intended to offer the same ease of use as the run
and call
methods, but with more flexibility and better
support for nested subcommands.
Calling this method roughly expands to:
ParseResult parseResult = null; try { parseResult = parseArgs(args); return handler.handleParseResult(parseResult); } catch (ParameterException ex) { return exceptionHandler.handleParseException(ex, (String[]) args); } catch (ExecutionException ex) { return exceptionHandler.handleExecutionException(ex, parseResult); }
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 a Runnable
or Callable
.CommandLine.RunFirst
handler prints help if requested, and otherwise executes the top-level command as a Runnable
or Callable
.CommandLine.RunAll
handler prints help if requested, and otherwise executes all recognized commands and subcommands as Runnable
or Callable
tasks.CommandLine.DefaultExceptionHandler
prints the error message followed by usage helpR
- the return type of the result handler and exception handlerhandler
- the function that will handle the result of successfully parsing the command line argumentsexceptionHandler
- the function that can handle the ParameterException
thrown when the command line arguments are invalidargs
- the command line argumentsCommandLine.ExecutionException
- if the command line arguments were parsed successfully but a problem occurred while processing the parse
result ParseResult
object; use CommandLine.ExecutionException.getCommandLine()
to get the command or subcommand where processing failedCommandLine.RunLast
,
CommandLine.RunAll
,
CommandLine.DefaultExceptionHandler
public static void usage(java.lang.Object command, java.io.PrintStream out)
new CommandLine(command).usage(out)
. See usage(PrintStream)
for details.command
- the object annotated with CommandLine.Command
, CommandLine.Option
and CommandLine.Parameters
out
- the print stream to print the help message tojava.lang.IllegalArgumentException
- if the specified command object does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationpublic static void usage(java.lang.Object command, java.io.PrintStream out, CommandLine.Help.Ansi ansi)
new CommandLine(command).usage(out, ansi)
.
See usage(PrintStream, Help.Ansi)
for details.command
- the object annotated with CommandLine.Command
, CommandLine.Option
and CommandLine.Parameters
out
- the print stream to print the help message toansi
- whether the usage message should contain ANSI escape codes or notjava.lang.IllegalArgumentException
- if the specified command object does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationpublic static void usage(java.lang.Object command, java.io.PrintStream out, CommandLine.Help.ColorScheme colorScheme)
new CommandLine(command).usage(out, colorScheme)
.
See usage(PrintStream, Help.ColorScheme)
for details.command
- the object annotated with CommandLine.Command
, CommandLine.Option
and CommandLine.Parameters
out
- the print stream to print the help message tocolorScheme
- the ColorScheme
defining the styles for options, parameters and commands when ANSI is enabledjava.lang.IllegalArgumentException
- if the specified command object does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationpublic void usage(java.io.PrintStream out)
usage(PrintStream, Help.Ansi)
with the platform default.out
- the printStream to print tousage(PrintStream, Help.ColorScheme)
public void usage(java.io.PrintWriter writer)
usage(PrintWriter, Help.Ansi)
with the platform default.writer
- the PrintWriter to print tousage(PrintWriter, Help.ColorScheme)
public void usage(java.io.PrintStream out, CommandLine.Help.Ansi ansi)
usage(PrintStream, Help.ColorScheme)
with the default color scheme.out
- the printStream to print toansi
- whether the usage message should include ANSI escape codes or notusage(PrintStream, Help.ColorScheme)
public void usage(java.io.PrintWriter writer, CommandLine.Help.Ansi ansi)
usage(PrintStream, Help.Ansi)
but with the specified PrintWriter
instead of a PrintStream
.public void usage(java.io.PrintStream out, CommandLine.Help.ColorScheme colorScheme)
PrintStream
.
Delegates construction of the usage help message to the CommandLine.Help
inner class and is equivalent to:
Help.ColorScheme colorScheme = Help.defaultColorScheme(Help.Ansi.AUTO); Help help = getHelpFactory().create(getCommandSpec(), colorScheme) StringBuilder sb = new StringBuilder(); for (String key : getHelpSectionKeys()) { IHelpSectionRenderer renderer = getHelpSectionMap().get(key); if (renderer != null) { sb.append(renderer.render(help)); } } 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 a CommandLine.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.
out
- the PrintStream
to print the usage help message tocolorScheme
- the ColorScheme
defining the styles for options, parameters and commands when ANSI is enabledCommandLine.Model.UsageMessageSpec
public void usage(java.io.PrintWriter writer, CommandLine.Help.ColorScheme colorScheme)
usage(PrintStream, Help.ColorScheme)
, but with the specified PrintWriter
instead of a PrintStream
.public java.lang.String getUsageMessage()
usage(PrintStream)
, but returns the usage help message as a String instead of printing it to the PrintStream
.public java.lang.String getUsageMessage(CommandLine.Help.Ansi ansi)
usage(PrintStream, Help.Ansi)
, but returns the usage help message as a String instead of printing it to the PrintStream
.public java.lang.String getUsageMessage(CommandLine.Help.ColorScheme colorScheme)
usage(PrintStream, Help.ColorScheme)
, but returns the usage help message as a String instead of printing it to the PrintStream
.public void printVersionHelp(java.io.PrintStream out)
printVersionHelp(PrintStream, Help.Ansi)
with the platform default.out
- the printStream to print toprintVersionHelp(PrintStream, Help.Ansi)
public void printVersionHelp(java.io.PrintStream out, CommandLine.Help.Ansi ansi)
CommandLine.Command.version()
annotation to the specified PrintStream
.
Each element of the array of version strings is printed on a separate line. Version strings may contain
markup for colors and style.out
- the printStream to print toansi
- whether the usage message should include ANSI escape codes or notCommandLine.Command.version()
,
CommandLine.Option.versionHelp()
,
isVersionHelpRequested()
public void printVersionHelp(java.io.PrintStream out, CommandLine.Help.Ansi ansi, java.lang.Object... params)
CommandLine.Command.version()
annotation to the specified PrintStream
.
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.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 stringsCommandLine.Command.version()
,
CommandLine.Option.versionHelp()
,
isVersionHelpRequested()
public static <C extends java.util.concurrent.Callable<T>,T> T call(C callable, java.lang.String... args)
call(Callable, PrintStream, PrintStream, Help.Ansi, String...)
with System.out
for
requested usage help messages, System.err
for diagnostic error messages, and CommandLine.Help.Ansi.AUTO
.C
- the annotated object must implement CallableT
- the return type of the most specific command (must implement Callable
)callable
- the command to call when parsing succeeds.args
- the command line arguments to parsenull
if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the CallableCommandLine.InitializationException
- if the specified command object does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Callable throws an exceptioncall(Callable, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
public static <C extends java.util.concurrent.Callable<T>,T> T call(C callable, java.io.PrintStream out, java.lang.String... args)
call(Callable, PrintStream, PrintStream, Help.Ansi, String...)
with System.err
for
diagnostic error messages and CommandLine.Help.Ansi.AUTO
.C
- the annotated object must implement CallableT
- the return type of the most specific command (must implement Callable
)callable
- the command to call when parsing succeeds.out
- the printStream to print the usage help message to when the user requested helpargs
- the command line arguments to parsenull
if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the CallableCommandLine.InitializationException
- if the specified command object does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Callable throws an exceptioncall(Callable, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
,
CommandLine.RunLast
public static <C extends java.util.concurrent.Callable<T>,T> T call(C callable, java.io.PrintStream out, CommandLine.Help.Ansi ansi, java.lang.String... args)
call(Callable, PrintStream, PrintStream, Help.Ansi, String...)
with System.err
for diagnostic error messages.C
- the annotated object must implement CallableT
- the return type of the most specific command (must implement Callable
)callable
- the command to call when parsing succeeds.out
- the printStream to print the usage help message to when the user requested helpansi
- the ANSI style to useargs
- the command line arguments to parsenull
if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the CallableCommandLine.InitializationException
- if the specified command object does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Callable throws an exceptioncall(Callable, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
,
CommandLine.RunLast
public static <C extends java.util.concurrent.Callable<T>,T> T call(C callable, java.io.PrintStream out, java.io.PrintStream err, CommandLine.Help.Ansi ansi, java.lang.String... args)
Callable
. Calling this method is equivalent to:
CommandLine cmd = new CommandLine(callable);
List<Object> results = cmd.parseWithHandlers(new RunLast().useOut(out).useAnsi(ansi),
new DefaultExceptionHandler().useErr(err).useAnsi(ansi),
args);
T result = results == null || results.isEmpty() ? null : (T) results.get(0);
return result;
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 the CommandLine.RunAll
handler or a custom handler.
Use call(Class, IFactory, ...)
instead of this method
if you want to use a factory that performs Dependency Injection.
C
- the annotated object must implement CallableT
- the return type of the specified Callable
callable
- the command to call when parsing succeeds.out
- the printStream to print the usage help message to when the user requested helperr
- the printStream to print diagnostic messages toansi
- whether the usage message should include ANSI escape codes or notargs
- the command line arguments to parsenull
if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the CallableCommandLine.InitializationException
- if the specified command object does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Callable throws an exceptioncall(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
,
CommandLine.RunLast
public static <C extends java.util.concurrent.Callable<T>,T> T call(java.lang.Class<C> callableClass, CommandLine.IFactory factory, java.lang.String... args)
call(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
with System.out
for
requested usage help messages, System.err
for diagnostic error messages, and CommandLine.Help.Ansi.AUTO
.C
- the annotated class must implement CallableT
- the return type of the most specific command (must implement Callable
)callableClass
- class of the command to call when parsing succeeds.factory
- the factory responsible for instantiating the specified callable class and potentially inject other componentsargs
- the command line arguments to parsenull
if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the CallableCommandLine.InitializationException
- if the specified class cannot be instantiated by the factory, or does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Callable throws an exceptioncall(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
public static <C extends java.util.concurrent.Callable<T>,T> T call(java.lang.Class<C> callableClass, CommandLine.IFactory factory, java.io.PrintStream out, java.lang.String... args)
call(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
with
System.err
for diagnostic error messages, and CommandLine.Help.Ansi.AUTO
.C
- the annotated class must implement CallableT
- the return type of the most specific command (must implement Callable
)callableClass
- class of the command to call when parsing succeeds.factory
- the factory responsible for instantiating the specified callable class and potentially injecting other componentsout
- the printStream to print the usage help message to when the user requested helpargs
- the command line arguments to parsenull
if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the CallableCommandLine.InitializationException
- if the specified class cannot be instantiated by the factory, or does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Callable throws an exceptioncall(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
public static <C extends java.util.concurrent.Callable<T>,T> T call(java.lang.Class<C> callableClass, CommandLine.IFactory factory, java.io.PrintStream out, CommandLine.Help.Ansi ansi, java.lang.String... args)
call(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
with
System.err
for diagnostic error messages.C
- the annotated class must implement CallableT
- the return type of the most specific command (must implement Callable
)callableClass
- class of the command to call when parsing succeeds.factory
- the factory responsible for instantiating the specified callable class and potentially injecting other componentsout
- the printStream to print the usage help message to when the user requested helpansi
- the ANSI style to useargs
- the command line arguments to parsenull
if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the CallableCommandLine.InitializationException
- if the specified class cannot be instantiated by the factory, or does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Callable throws an exceptioncall(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
public static <C extends java.util.concurrent.Callable<T>,T> T call(java.lang.Class<C> callableClass, CommandLine.IFactory factory, java.io.PrintStream out, java.io.PrintStream err, CommandLine.Help.Ansi ansi, java.lang.String... args)
callableClass
;
use this method instead of call(Callable, ...)
if you want to use a factory that performs Dependency Injection.
The annotated class needs to implement Callable
. Calling this method is equivalent to:
CommandLine cmd = new CommandLine(callableClass, factory);
List<Object> results = cmd.parseWithHandlers(new RunLast().useOut(out).useAnsi(ansi),
new DefaultExceptionHandler().useErr(err).useAnsi(ansi),
args);
T result = results == null || results.isEmpty() ? null : (T) results.get(0);
return result;
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 the CommandLine.RunAll
handler or a custom handler.
C
- the annotated class must implement CallableT
- the return type of the most specific command (must implement Callable
)callableClass
- class of the command to call when parsing succeeds.factory
- the factory responsible for instantiating the specified callable class and potentially injecting other componentsout
- the printStream to print the usage help message to when the user requested helperr
- the printStream to print diagnostic messages toansi
- the ANSI style to useargs
- the command line arguments to parsenull
if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the CallableCommandLine.InitializationException
- if the specified class cannot be instantiated by the factory, or does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Callable throws an exceptioncall(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
,
call(Callable, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
public static <R extends java.lang.Runnable> void run(R runnable, java.lang.String... args)
run(Runnable, PrintStream, PrintStream, Help.Ansi, String...)
with System.out
for
requested usage help messages, System.err
for diagnostic error messages, and CommandLine.Help.Ansi.AUTO
.R
- the annotated object must implement Runnablerunnable
- the command to run when parsing succeeds.args
- the command line arguments to parseCommandLine.InitializationException
- if the specified command object does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Runnable throws an exceptionrun(Runnable, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
,
CommandLine.RunLast
public static <R extends java.lang.Runnable> void run(R runnable, java.io.PrintStream out, java.lang.String... args)
run(Runnable, PrintStream, PrintStream, Help.Ansi, String...)
with System.err
for diagnostic error messages and CommandLine.Help.Ansi.AUTO
.R
- the annotated object must implement Runnablerunnable
- the command to run when parsing succeeds.out
- the printStream to print the usage help message to when the user requested helpargs
- the command line arguments to parseCommandLine.InitializationException
- if the specified command object does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Runnable throws an exceptionrun(Runnable, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandler(IParseResultHandler2, String[])
,
CommandLine.RunLast
public static <R extends java.lang.Runnable> void run(R runnable, java.io.PrintStream out, CommandLine.Help.Ansi ansi, java.lang.String... args)
run(Runnable, PrintStream, PrintStream, Help.Ansi, String...)
with System.err
for diagnostic error messages.R
- the annotated object must implement Runnablerunnable
- the command to run when parsing succeeds.out
- the printStream to print the usage help message to when the user requested helpansi
- whether the usage message should include ANSI escape codes or notargs
- the command line arguments to parseCommandLine.InitializationException
- if the specified command object does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Runnable throws an exceptionrun(Runnable, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
,
CommandLine.RunLast
public static <R extends java.lang.Runnable> void run(R runnable, java.io.PrintStream out, java.io.PrintStream err, CommandLine.Help.Ansi ansi, java.lang.String... args)
Runnable
. Calling this method is equivalent to:
CommandLine cmd = new CommandLine(runnable);
cmd.parseWithHandlers(new RunLast().useOut(out).useAnsi(ansi),
new DefaultExceptionHandler().useErr(err).useAnsi(ansi),
args);
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 the CommandLine.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 an ExecutionException
.
Use run(Class, IFactory, ...)
instead of this method
if you want to use a factory that performs Dependency Injection.
R
- the annotated object must implement Runnablerunnable
- the command to run when parsing succeeds.out
- the printStream to print the usage help message to when the user requested helperr
- the printStream to print diagnostic messages toansi
- whether the usage message should include ANSI escape codes or notargs
- the command line arguments to parseCommandLine.InitializationException
- if the specified command object does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Runnable throws an exceptionparseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
,
CommandLine.RunLast
,
run(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
public static <R extends java.lang.Runnable> void run(java.lang.Class<R> runnableClass, CommandLine.IFactory factory, java.lang.String... args)
run(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
with System.out
for
requested usage help messages, System.err
for diagnostic error messages, and CommandLine.Help.Ansi.AUTO
.R
- the annotated class must implement RunnablerunnableClass
- class of the command to run when parsing succeeds.factory
- the factory responsible for instantiating the specified Runnable class and potentially injecting other componentsargs
- the command line arguments to parseCommandLine.InitializationException
- if the specified class cannot be instantiated by the factory, or does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Runnable throws an exceptionrun(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
,
CommandLine.RunLast
public static <R extends java.lang.Runnable> void run(java.lang.Class<R> runnableClass, CommandLine.IFactory factory, java.io.PrintStream out, java.lang.String... args)
run(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
with
System.err
for diagnostic error messages, and CommandLine.Help.Ansi.AUTO
.R
- the annotated class must implement RunnablerunnableClass
- class of the command to run when parsing succeeds.factory
- the factory responsible for instantiating the specified Runnable class and potentially injecting other componentsout
- the printStream to print the usage help message to when the user requested helpargs
- the command line arguments to parseCommandLine.InitializationException
- if the specified class cannot be instantiated by the factory, or does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Runnable throws an exceptionrun(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
,
CommandLine.RunLast
public static <R extends java.lang.Runnable> void run(java.lang.Class<R> runnableClass, CommandLine.IFactory factory, java.io.PrintStream out, CommandLine.Help.Ansi ansi, java.lang.String... args)
run(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
with
System.err
for diagnostic error messages.R
- the annotated class must implement RunnablerunnableClass
- class of the command to run when parsing succeeds.factory
- the factory responsible for instantiating the specified Runnable class and potentially injecting other componentsout
- the printStream to print the usage help message to when the user requested helpansi
- whether the usage message should include ANSI escape codes or notargs
- the command line arguments to parseCommandLine.InitializationException
- if the specified class cannot be instantiated by the factory, or does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Runnable throws an exceptionrun(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
,
CommandLine.RunLast
public static <R extends java.lang.Runnable> void run(java.lang.Class<R> runnableClass, CommandLine.IFactory factory, java.io.PrintStream out, java.io.PrintStream err, CommandLine.Help.Ansi ansi, java.lang.String... args)
runnableClass
;
use this method instead of run(Runnable, ...)
if you want to use a factory that performs Dependency Injection.
The annotated class needs to implement Runnable
. Calling this method is equivalent to:
CommandLine cmd = new CommandLine(runnableClass, factory);
cmd.parseWithHandlers(new RunLast().useOut(out).useAnsi(ansi),
new DefaultExceptionHandler().useErr(err).useAnsi(ansi),
args);
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 the CommandLine.RunAll
handler or a custom handler.
This method prints usage help or version help if requested,
and any exceptions thrown by the Runnable
are caught and rethrown wrapped in an ExecutionException
.
R
- the annotated class must implement RunnablerunnableClass
- class of the command to run when parsing succeeds.factory
- the factory responsible for instantiating the specified Runnable class and potentially injecting other componentsout
- the printStream to print the usage help message to when the user requested helperr
- the printStream to print diagnostic messages toansi
- whether the usage message should include ANSI escape codes or notargs
- the command line arguments to parseCommandLine.InitializationException
- if the specified class cannot be instantiated by the factory, or does not have a CommandLine.Command
, CommandLine.Option
or CommandLine.Parameters
annotationCommandLine.ExecutionException
- if the Runnable throws an exceptionrun(Class, IFactory, PrintStream, PrintStream, Help.Ansi, String...)
,
run(Runnable, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
,
CommandLine.RunLast
public static java.lang.Object invoke(java.lang.String methodName, java.lang.Class<?> cls, java.lang.String... args)
invoke(String, Class, PrintStream, PrintStream, Help.Ansi, String...)
with System.out
for
requested usage help messages, System.err
for diagnostic error messages, and CommandLine.Help.Ansi.AUTO
.methodName
- the @Command
-annotated method to build a CommandLine.Model.CommandSpec
model from,
and run when parsing succeeds.cls
- the class where the @Command
-annotated method is declared, or a subclassargs
- the command line arguments to parseCommandLine.InitializationException
- if the specified method does not have a CommandLine.Command
annotation,
or if the specified class contains multiple @Command
-annotated methods with the specified nameCommandLine.ExecutionException
- if the Runnable throws an exceptioninvoke(String, Class, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
public static java.lang.Object invoke(java.lang.String methodName, java.lang.Class<?> cls, java.io.PrintStream out, java.lang.String... args)
invoke(String, Class, PrintStream, PrintStream, Help.Ansi, String...)
with the specified stream for
requested usage help messages, System.err
for diagnostic error messages, and CommandLine.Help.Ansi.AUTO
.methodName
- the @Command
-annotated method to build a CommandLine.Model.CommandSpec
model from,
and run when parsing succeeds.cls
- the class where the @Command
-annotated method is declared, or a subclassout
- the printstream to print requested help message toargs
- the command line arguments to parseCommandLine.InitializationException
- if the specified method does not have a CommandLine.Command
annotation,
or if the specified class contains multiple @Command
-annotated methods with the specified nameCommandLine.ExecutionException
- if the Runnable throws an exceptioninvoke(String, Class, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
public static java.lang.Object invoke(java.lang.String methodName, java.lang.Class<?> cls, java.io.PrintStream out, CommandLine.Help.Ansi ansi, java.lang.String... args)
invoke(String, Class, PrintStream, PrintStream, Help.Ansi, String...)
with the specified stream for
requested usage help messages, System.err
for diagnostic error messages, and the specified Ansi mode.methodName
- the @Command
-annotated method to build a CommandLine.Model.CommandSpec
model from,
and run when parsing succeeds.cls
- the class where the @Command
-annotated method is declared, or a subclassout
- the printstream to print requested help message toansi
- whether the usage message should include ANSI escape codes or notargs
- the command line arguments to parseCommandLine.InitializationException
- if the specified method does not have a CommandLine.Command
annotation,
or if the specified class contains multiple @Command
-annotated methods with the specified nameCommandLine.ExecutionException
- if the Runnable throws an exceptioninvoke(String, Class, PrintStream, PrintStream, Help.Ansi, String...)
,
parseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
public static java.lang.Object invoke(java.lang.String methodName, java.lang.Class<?> cls, java.io.PrintStream out, java.io.PrintStream err, CommandLine.Help.Ansi ansi, java.lang.String... args)
CommandLine.Model.CommandSpec
model from the @Option
and @Parameters
-annotated method parameters
of the @Command
-annotated method, parses the specified command line arguments and invokes the specified method.
Calling this method is equivalent to:
Method commandMethod = getCommandMethods(cls, methodName).get(0);
CommandLine cmd = new CommandLine(commandMethod);
List<Object> list = cmd.parseWithHandlers(new RunLast().useOut(out).useAnsi(ansi),
new DefaultExceptionHandler().useErr(err).useAnsi(ansi),
args);
return list == null ? null : list.get(0);
methodName
- the @Command
-annotated method to build a CommandLine.Model.CommandSpec
model from,
and run when parsing succeeds.cls
- the class where the @Command
-annotated method is declared, or a subclassout
- the printStream to print the usage help message to when the user requested helperr
- the printStream to print diagnostic messages toansi
- whether the usage message should include ANSI escape codes or notargs
- the command line arguments to parseCommandLine.InitializationException
- if the specified method does not have a CommandLine.Command
annotation,
or if the specified class contains multiple @Command
-annotated methods with the specified nameCommandLine.ExecutionException
- if the method throws an exceptionparseWithHandlers(IParseResultHandler2, IExceptionHandler2, String...)
public static java.util.List<java.lang.reflect.Method> getCommandMethods(java.lang.Class<?> cls, java.lang.String methodName)
@Command
via reflection, optionally filtered by method name (not @Command.name
).
Methods have to be either public (inherited) members or be declared by cls
, that is "inherited" static or protected methods will not be picked up.cls
- the class to search for methods annotated with @Command
methodName
- if not null
, return only methods whose method name (not @Command.name
) equals this string. Ignored if null
.invoke(String, Class, String...)
public <K> CommandLine registerConverter(java.lang.Class<K> cls, CommandLine.ITypeConverter<K> converter)
CommandLine.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:
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.
K
- the target typecls
- the target class to convert parameter string values toconverter
- the class capable of converting string values to the specified target typeaddSubcommand(String, Object)
public java.lang.String getSeparator()
CommandLine.Model.ParserSpec.separator()
public CommandLine setSeparator(java.lang.String separator)
CommandLine.Command.separator()
annotation attribute.
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.
separator
- the String that separates option names from option valuesCommandLine
object, to allow method chainingCommandLine.Model.ParserSpec.separator(String)
public java.util.ResourceBundle getResourceBundle()
null
if no resource bundle is set.CommandLine.Command.resourceBundle()
,
CommandLine.Model.CommandSpec.resourceBundle()
public CommandLine setResourceBundle(java.util.ResourceBundle bundle)
The specified bundle 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 not be impacted. To ensure a setting is applied to all
subcommands, call the setter last, after adding subcommands.
bundle
- the ResourceBundle containing usage help message stringsCommandLine
object, to allow method chainingCommandLine.Command.resourceBundle()
,
CommandLine.Model.CommandSpec.resourceBundle(ResourceBundle)
public int getUsageHelpWidth()
public CommandLine setUsageHelpWidth(int width)
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.
width
- the maximum width of the usage help messageCommandLine
object, to allow method chainingCommandLine.Model.UsageMessageSpec.width(int)
public java.lang.String getCommandName()
CommandLine.Model.CommandSpec.name()
public CommandLine setCommandName(java.lang.String commandName)
CommandLine.Command.name()
annotation attribute.commandName
- command name (also called program name) displayed in the usage help synopsisCommandLine
object, to allow method chainingCommandLine.Model.CommandSpec.name(String)
public boolean isExpandAtFiles()
'@'
should be treated as the path to an argument file and its
contents should be expanded into separate arguments for each line in the specified file.
This property is true
by default.@files
should be expanded into their contentpublic CommandLine setExpandAtFiles(boolean expandAtFiles)
'@'
should be treated as the path to an argument file and its
contents should be expanded into separate arguments for each line in the specified file. (true
by default.)expandAtFiles
- whether "argument files" or @files
should be expanded into their contentCommandLine
object, to allow method chainingpublic java.lang.Character getAtFileCommentChar()
null
if all content of argument files should
be interpreted as arguments (without comments).
If specified, all characters from the comment character to the end of the line are ignored.null
. The default is '#'
.public CommandLine setAtFileCommentChar(java.lang.Character atFileCommentChar)
null
if all content of argument files should
be interpreted as arguments (without comments).
If specified, all characters from the comment character to the end of the line are ignored.atFileCommentChar
- the character that starts a single-line comment or null
. The default is '#'
.CommandLine
object, to allow method chainingpublic boolean isUseSimplifiedAtFiles()
"picocli.useSimplifiedAtFiles"
is defined, the system property value overrides the programmatically set value.false
.public CommandLine setUseSimplifiedAtFiles(boolean simplifiedAtFiles)
"picocli.useSimplifiedAtFiles"
is defined, the system property value overrides the programmatically set value.simplifiedAtFiles
- whether to use a simplified argument file format. The default is false
.CommandLine
object, to allow method chaining