CommandLine (picocli 2.3.0 API)
Date: 2018-02-13

picocli

## Class CommandLine

- java.lang.Object
- - picocli.CommandLine

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

  ## Example

      import static picocli.CommandLine.*;

       @Command(header = "Encrypt FILE(s), or standard input, to standard output or to the output file.",
                version = "v1.2.3")
       public class Encrypt {

           @Parameters(type = File.class, description = "Any number of input files")
           private List<File> files = new ArrayList<File>();

           @Option(names = { "-o", "--out" }, description = "Output file (default: print to console)")
           private File outputFile;

           @Option(names = { "-v", "--verbose"}, description = "Verbosely list files processed")
           private boolean verbose;

           @Option(names = { "-h", "--help", "-?", "-help"}, usageHelp = true, description = "Display this help and exit")
           private boolean help;

           @Option(names = { "-V", "--version"}, versionHelp = true, description = "Display version info and exit")
           private boolean versionHelp;
       }

  Use `CommandLine` to initialize a domain object as follows:

       public static void main(String... args) {
           Encrypt encrypt = new Encrypt();
           try {
               List<CommandLine> parsedCommands = new CommandLine(encrypt).parse(args);
               if (!CommandLine.printHelpIfRequested(parsedCommands, System.err, Help.Ansi.AUTO)) {
                   runProgram(encrypt);
               }
           } catch (ParameterException ex) { // command line arguments could not be parsed
               System.err.println(ex.getMessage());
               ex.getCommandLine().usage(System.err);
           }
       }

  Invoke the above program with some command line arguments. The below are all equivalent:

       --verbose --out=outfile in1 in2
       --verbose --out outfile in1 in2
       -v --out=outfile in1 in2
       -v -o outfile in1 in2
       -v -o=outfile in1 in2
       -vo outfile in1 in2
       -vo=outfile in1 in2
       -v -ooutfile in1 in2
       -vooutfile in1 in2

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `CommandLine.Command` Annotate your class with `@Command` when you want more control over the format of the generated help message.
    `static class` | `CommandLine.DefaultExceptionHandler` Default exception handler that prints the exception message to the specified `PrintStream`, followed by the usage message for the command or subcommand whose input was invalid.
    `static class` | `CommandLine.DuplicateOptionAnnotationsException` Exception indicating that multiple fields have been annotated with the same Option name.
    `static class` | `CommandLine.ExecutionException` Exception indicating a problem while invoking a command or subcommand.
    `static class` | `CommandLine.Help` A collection of methods and inner classes that provide fine-grained control over the contents and layout of the usage help message to display to end users when help is requested or invalid input values were specified.
    `static interface` | `CommandLine.IExceptionHandler` Represents a function that can handle a `ParameterException` that occurred while parsing the command line arguments.
    `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 class` | `CommandLine.InitializationException` Exception indicating a problem during `CommandLine` initialization.
    `static interface` | `CommandLine.IParseResultHandler` Represents a function that can process a List of `CommandLine` objects resulting from successfully parsing the command line arguments.
    `static interface` | `CommandLine.ITypeConverter<K>` When parsing command line arguments and initializing fields annotated with `@Option` or `@Parameters`, String values can be converted to any type for which a `ITypeConverter` is registered.
    `static interface` | `CommandLine.IVersionProvider` Provides version information for a command.
    `static class` | `CommandLine.MaxValuesforFieldExceededException` 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.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.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 class` | `CommandLine.TypeConversionException` Exception thrown by `CommandLine.ITypeConverter` implementations to indicate a String could not be converted.
    `static class` | `CommandLine.UnmatchedArgumentException` Exception indicating that a command line argument could not be mapped to any of the fields annotated with `CommandLine.Option` or `CommandLine.Parameters`.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `VERSION` This is picocli version "2.3.0".

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CommandLine(java.lang.Object command)` Constructs a new `CommandLine` interpreter with the specified annotated object and a default subcommand factory.
    `CommandLine(java.lang.Object command, CommandLine.IFactory factory)` Constructs a new `CommandLine` interpreter with the specified annotated object and object factory.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `CommandLine` | `addSubcommand(java.lang.String name, java.lang.Object command)` Registers a subcommand with the specified name.
    `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)` 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> T` | `call(C callable, java.io.PrintStream out, java.lang.String... args)` Delegates to `call(Callable, PrintStream, Help.Ansi, String...)` with `CommandLine.Help.Ansi.AUTO`.
    `<T> T` | `getCommand()` Returns the annotated object that this `CommandLine` instance was constructed with.
    `java.lang.String` | `getCommandName()` Returns the command name (also called program name) displayed in the usage help synopsis.
    `CommandLine` | `getParent()` Returns the command that this is a subcommand of, or `null` if this is a top-level command.
    `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.
    `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` | `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` | `isUnmatchedArgumentsAllowed()` Returns whether the end user may specify arguments on the command line that are not matched to any option or parameter fields.
    `boolean` | `isUsageHelpRequested()` Returns `true` if an option annotated with `CommandLine.Option.usageHelp()` was specified on the command line.
    `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.
    `java.util.List<java.lang.Object>` | `parseWithHandler(CommandLine.IParseResultHandler handler, java.io.PrintStream out, java.lang.String... args)` Returns the result of calling `parseWithHandlers(IParseResultHandler, PrintStream, Help.Ansi, IExceptionHandler, String...)` with `Help.Ansi.AUTO` and a new `CommandLine.DefaultExceptionHandler` in addition to the specified parse result handler, `PrintStream`, and the specified command line arguments.
    `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)` Tries to parse the specified command line arguments, and if successful, delegates the processing of the resulting list of `CommandLine` objects to the specified handler.
    `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 boolean` | `printHelpIfRequested(java.util.List<CommandLine> parsedCommands, java.io.PrintStream out, 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.
    `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> void` | `run(R runnable, java.io.PrintStream out, 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> void` | `run(R runnable, java.io.PrintStream out, java.lang.String... args)` Delegates to `run(Runnable, PrintStream, Help.Ansi, String...)` with `CommandLine.Help.Ansi.AUTO`.
    `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` | `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` | `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` | `setSeparator(java.lang.String separator)` Sets the String the parser uses to separate option names from option values to the specified value.
    `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` | `setUnmatchedArgumentsAllowed(boolean newValue)` Sets whether the end user may specify unmatched arguments on the command line without a `CommandLine.UnmatchedArgumentException` being thrown.
    `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`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### VERSION

          public static final java.lang.String VERSION

      This is picocli version "2.3.0".
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### CommandLine

          public CommandLine(java.lang.Object command)

      Constructs a new `CommandLine` interpreter with the specified annotated object and a default subcommand factory. When the `parse(String...)` method is called, fields of the specified object that are annotated with `@Option` or `@Parameters` will be initialized based on command line arguments.
      Parameters:
        `command` - the object to initialize from the command line arguments
      Throws:
        `CommandLine.InitializationException` - if the specified command object does not have a `CommandLine.Command`, `CommandLine.Option` or `CommandLine.Parameters` annotation

    - #### CommandLine

          public CommandLine(java.lang.Object command,
                     CommandLine.IFactory factory)

      Constructs a new `CommandLine` interpreter with the specified annotated object and object factory. When the `parse(String...)` method is called, fields of the specified object that are annotated with `@Option` or `@Parameters` will be initialized based on command line arguments.
      Parameters:
        `command` - the object to initialize from the command line arguments
        `factory` - the factory used to create instances of subcommands that are registered declaratively with annotation attributes
      Throws:
        `CommandLine.InitializationException` - if the specified command object does not have a `CommandLine.Command`, `CommandLine.Option` or `CommandLine.Parameters` annotation

  - ### Method Detail

    - #### addSubcommand

          public CommandLine addSubcommand(java.lang.String name,
                                  java.lang.Object command)

      Registers a subcommand with the specified name. For example:

           CommandLine commandLine = new CommandLine(new Git())
                   .addSubcommand("status",   new GitStatus())
                   .addSubcommand("commit",   new GitCommit();
                   .addSubcommand("add",      new GitAdd())
                   .addSubcommand("branch",   new GitBranch())
                   .addSubcommand("checkout", new GitCheckout())
                   //...
                   ;

      The specified object can be an annotated object or a `CommandLine` instance with its own nested subcommands. For example:

           CommandLine commandLine = new CommandLine(new MainCommand())
                   .addSubcommand("cmd1",                 new ChildCommand1()) // subcommand
                   .addSubcommand("cmd2",                 new ChildCommand2())
                   .addSubcommand("cmd3", new CommandLine(new ChildCommand3()) // subcommand with nested sub-subcommands
                           .addSubcommand("cmd3sub1",                 new GrandChild3Command1())
                           .addSubcommand("cmd3sub2",                 new GrandChild3Command2())
                           .addSubcommand("cmd3sub3", new CommandLine(new GrandChild3Command3()) // deeper nesting
                                   .addSubcommand("cmd3sub3sub1", new GreatGrandChild3Command3_1())
                                   .addSubcommand("cmd3sub3sub2", new GreatGrandChild3Command3_2())
                           )
                   );

      The default type converters are available on all subcommands and nested sub-subcommands, but custom type converters are registered only with the subcommand hierarchy as it existed when the custom type was registered. To ensure a custom type converter is available to all subcommands, register the type converter last, after adding subcommands.

      See also the `CommandLine.Command.subcommands()` annotation to register subcommands declaratively.

      Parameters:
        `name` - the string to recognize on the command line as a subcommand
        `command` - the object to initialize with command line arguments following the subcommand name. This may be a `CommandLine` instance with its own (nested) subcommands
      Returns:
        this CommandLine object, to allow method chaining
      Since:
        0.9.7
      See Also:
        `registerConverter(Class, ITypeConverter)`, `CommandLine.Command.subcommands()`

    - #### getSubcommands

          public java.util.Map<java.lang.String,CommandLine> getSubcommands()

      Returns a map with the subcommands registered on this instance.
      Returns:
        a map with the registered subcommands
      Since:
        0.9.7

    - #### getParent

          public CommandLine getParent()

      Returns the command that this is a subcommand of, or `null` if this is a top-level command.
      Returns:
        the command that this is a subcommand of, or `null` if this is a top-level command
      Since:
        0.9.8
      See Also:
        `addSubcommand(String, Object)`, `CommandLine.Command.subcommands()`

    - #### getCommand

          public <T> T getCommand()

      Returns the annotated object that this `CommandLine` instance was constructed with.
      Type Parameters:
        `T` - the type of the variable that the return value is being assigned to
      Returns:
        the annotated object that this `CommandLine` instance was constructed with
      Since:
        0.9.7

    - #### isUsageHelpRequested

          public boolean isUsageHelpRequested()

      Returns `true` if an option annotated with `CommandLine.Option.usageHelp()` was specified on the command line.
      Returns:
        whether the parser encountered an option annotated with `CommandLine.Option.usageHelp()`.
      Since:
        0.9.8

    - #### isVersionHelpRequested

          public boolean isVersionHelpRequested()

      Returns `true` if an option annotated with `CommandLine.Option.versionHelp()` was specified on the command line.
      Returns:
        whether the parser encountered an option annotated with `CommandLine.Option.versionHelp()`.
      Since:
        0.9.8

    - #### isOverwrittenOptionsAllowed

          public boolean isOverwrittenOptionsAllowed()

      Returns whether options for single-value fields can be specified multiple times on the command line. The default is `false` and a `CommandLine.OverwrittenOptionException` is thrown if this happens. When `true`, the last specified value is retained.
      Returns:
        `true` if options for single-value fields can be specified multiple times on the command line, `false` otherwise
      Since:
        0.9.7

    - #### setOverwrittenOptionsAllowed

          public CommandLine setOverwrittenOptionsAllowed(boolean newValue)

      Sets whether options for single-value fields can be specified multiple times on the command line without a `CommandLine.OverwrittenOptionException` being thrown.

      The specified setting will be registered with this `CommandLine` and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

      Parameters:
        `newValue` - the new setting
      Returns:
        this `CommandLine` object, to allow method chaining
      Since:
        0.9.7

    - #### isStopAtPositional

          public 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. The default is `false`.
      Returns:
        `true` if all values following the first positional parameter should be treated as positional parameters, `false` otherwise
      Since:
        2.3

    - #### setStopAtPositional

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

      Parameters:
        `newValue` - `true` if all values following the first positional parameter should be treated as positional parameters, `false` otherwise
      Returns:
        this `CommandLine` object, to allow method chaining
      Since:
        2.3

    - #### isStopAtUnmatched

          public boolean isStopAtUnmatched()

      Returns whether the parser should stop interpreting options and positional parameters as soon as it encounters an unmatched option. Unmatched options are arguments that look like an option but are not one of the known options, or positional arguments for which there is no available slots (the command has no positional parameters or their size is limited). The default is `false`.

      Setting this flag to `true` automatically sets the unmatchedArgumentsAllowed flag to `true` also.

      Returns:
        `true` when an unmatched option should result in the remaining command line arguments to be added to the unmatchedArguments list
      Since:
        2.3

    - #### setStopAtUnmatched

          public CommandLine setStopAtUnmatched(boolean newValue)

      Sets whether the parser should stop interpreting options and positional parameters as soon as it encounters an unmatched option. Unmatched options are arguments that look like an option but are not one of the known options, or positional arguments for which there is no available slots (the command has no positional parameters or their size is limited). The default is `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.

      Parameters:
        `newValue` - `true` when an unmatched option should result in the remaining command line arguments to be added to the unmatchedArguments list
      Returns:
        this `CommandLine` object, to allow method chaining
      Since:
        2.3

    - #### isUnmatchedArgumentsAllowed

          public boolean isUnmatchedArgumentsAllowed()

      Returns whether the end user may specify arguments on the command line that are not matched to any option or parameter fields. The default is `false` and a `CommandLine.UnmatchedArgumentException` is thrown if this happens. When `true`, the last unmatched arguments are available via the `getUnmatchedArguments()` method.
      Returns:
        `true` if the end use may specify unmatched arguments on the command line, `false` otherwise
      Since:
        0.9.7
      See Also:
        `getUnmatchedArguments()`

    - #### setUnmatchedArgumentsAllowed

          public CommandLine setUnmatchedArgumentsAllowed(boolean newValue)

      Sets whether the end user may specify unmatched arguments on the command line without a `CommandLine.UnmatchedArgumentException` being thrown.

      The specified setting will be registered with this `CommandLine` and the full hierarchy of its subcommands and nested sub-subcommands at the moment this method is called. Subcommands added later will have the default setting. To ensure a setting is applied to all subcommands, call the setter last, after adding subcommands.

      Parameters:
        `newValue` - the new setting. When `true`, the last unmatched arguments are available via the `getUnmatchedArguments()` method.
      Returns:
        this `CommandLine` object, to allow method chaining
      Since:
        0.9.7
      See Also:
        `getUnmatchedArguments()`

    - #### getUnmatchedArguments

          public java.util.List<java.lang.String> getUnmatchedArguments()

      Returns the list of unmatched command line arguments, if any.
      Returns:
        the list of unmatched command line arguments or an empty list
      Since:
        0.9.7
      See Also:
        `isUnmatchedArgumentsAllowed()`

    - #### populateCommand

          public static <T> T populateCommand(T command,
                              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;

      Type Parameters:
        `T` - the type of the annotated object
      Parameters:
        `command` - the object to initialize. This object contains fields annotated with `@Option` or `@Parameters`.
        `args` - the command line arguments to parse
      Returns:
        the specified annotated object
      Throws:
        `CommandLine.InitializationException` - if the specified command object does not have a `CommandLine.Command`, `CommandLine.Option` or `CommandLine.Parameters` annotation
        `CommandLine.ParameterException` - if the specified command line arguments are invalid
      Since:
        0.9.7

    - #### parse

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

      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.

      Parameters:
        `args` - the command line arguments to parse
      Returns:
        a list with the top-level command and any subcommands initialized by this method
      Throws:
        `CommandLine.ParameterException` - if the specified command line arguments are invalid; use `CommandLine.ParameterException.getCommandLine()` to get the command or subcommand whose user input was invalid

    - #### printHelpIfRequested

          public static boolean printHelpIfRequested(java.util.List<CommandLine> parsedCommands,
                                     java.io.PrintStream out,
                                     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. This method prints out usage help if requested or version help if requested and 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.

      Parameters:
        `parsedCommands` - the list of `CommandLine` objects to check if help was requested
        `out` - the `PrintStream` to print help to if requested
        `ansi` - for printing help messages using ANSI styles and colors
      Returns:
        `true` if help was printed, `false` otherwise
      Since:
        2.0

    - #### parseWithHandler

          public java.util.List<java.lang.Object> parseWithHandler(CommandLine.IParseResultHandler handler,
                                                          java.io.PrintStream out,
                                                          java.lang.String... args)

      Returns the result of calling `parseWithHandlers(IParseResultHandler, PrintStream, Help.Ansi, IExceptionHandler, String...)` with `Help.Ansi.AUTO` and a new `CommandLine.DefaultExceptionHandler` in addition to the specified parse result handler, `PrintStream`, and the specified command line arguments.

      This is a convenience method intended to offer the same ease of use as the `run` and `call` methods, but with more flexibility and better support for nested subcommands.

      Calling this method roughly expands to:

           try {
               List<CommandLine> parsedCommands = parse(args);
               return parseResultsHandler.handleParseResult(parsedCommands, out, Help.Ansi.AUTO);
           } catch (ParameterException ex) {
               return new DefaultExceptionHandler().handleException(ex, out, ansi, args);
           }

      Picocli provides some default handlers that allow you to accomplish some common tasks with very little code. The following handlers are available:

      - `CommandLine.RunLast` handler prints help if requested, and otherwise gets the last specified command or subcommand and tries to execute it as 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 help
      Parameters:
        `handler` - the function that will process the result of successfully parsing the command line arguments
        `out` - the `PrintStream` to print help to if requested
        `args` - the command line arguments
      Returns:
        a list of results, or an empty list if there are no results
      Throws:
        `CommandLine.ExecutionException` - if the command line arguments were parsed successfully but a problem occurred while processing the parse results; use `CommandLine.ExecutionException.getCommandLine()` to get the command or subcommand where processing failed
      Since:
        2.0
      See Also:
        `CommandLine.RunLast`, `CommandLine.RunAll`

    - #### parseWithHandlers

          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)

      Tries to parse the specified command line arguments, and if successful, delegates the processing of the resulting list of `CommandLine` objects 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.IExceptionHandler`.

      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 {
               List<CommandLine> parsedCommands = parse(args);
               return parseResultsHandler.handleParseResult(parsedCommands, out, ansi);
           } catch (ParameterException ex) {
               return new exceptionHandler.handleException(ex, out, ansi, args);
           }

      Picocli provides some default handlers that allow you to accomplish some common tasks with very little code. The following handlers are available:

      - `CommandLine.RunLast` handler prints help if requested, and otherwise gets the last specified command or subcommand and tries to execute it as 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 help
      Parameters:
        `handler` - the function that will process the result of successfully parsing the command line arguments
        `out` - the `PrintStream` to print help to if requested
        `ansi` - for printing help messages using ANSI styles and colors
        `exceptionHandler` - the function that can handle the `ParameterException` thrown when the command line arguments are invalid
        `args` - the command line arguments
      Returns:
        a list of results produced by the `IParseResultHandler` or the `IExceptionHandler`, or an empty list if there are no results
      Throws:
        `CommandLine.ExecutionException` - if the command line arguments were parsed successfully but a problem occurred while processing the parse result `CommandLine` objects; use `CommandLine.ExecutionException.getCommandLine()` to get the command or subcommand where processing failed
      Since:
        2.0
      See Also:
        `CommandLine.RunLast`, `CommandLine.RunAll`, `CommandLine.DefaultExceptionHandler`

    - #### usage

          public static void usage(java.lang.Object command,
                   java.io.PrintStream out)

      Equivalent to `new CommandLine(command).usage(out)`. See `usage(PrintStream)` for details.
      Parameters:
        `command` - the object annotated with `CommandLine.Command`, `CommandLine.Option` and `CommandLine.Parameters`
        `out` - the print stream to print the help message to
      Throws:
        `java.lang.IllegalArgumentException` - if the specified command object does not have a `CommandLine.Command`, `CommandLine.Option` or `CommandLine.Parameters` annotation

    - #### usage

          public static void usage(java.lang.Object command,
                   java.io.PrintStream out,
                   CommandLine.Help.Ansi ansi)

      Equivalent to `new CommandLine(command).usage(out, ansi)`. See `usage(PrintStream, Help.Ansi)` for details.
      Parameters:
        `command` - the object annotated with `CommandLine.Command`, `CommandLine.Option` and `CommandLine.Parameters`
        `out` - the print stream to print the help message to
        `ansi` - whether the usage message should contain ANSI escape codes or not
      Throws:
        `java.lang.IllegalArgumentException` - if the specified command object does not have a `CommandLine.Command`, `CommandLine.Option` or `CommandLine.Parameters` annotation

    - #### usage

          public static void usage(java.lang.Object command,
                   java.io.PrintStream out,
                   CommandLine.Help.ColorScheme colorScheme)

      Equivalent to `new CommandLine(command).usage(out, colorScheme)`. See `usage(PrintStream, Help.ColorScheme)` for details.
      Parameters:
        `command` - the object annotated with `CommandLine.Command`, `CommandLine.Option` and `CommandLine.Parameters`
        `out` - the print stream to print the help message to
        `colorScheme` - the `ColorScheme` defining the styles for options, parameters and commands when ANSI is enabled
      Throws:
        `java.lang.IllegalArgumentException` - if the specified command object does not have a `CommandLine.Command`, `CommandLine.Option` or `CommandLine.Parameters` annotation

    - #### usage

          public void usage(java.io.PrintStream out)

      Delegates to `usage(PrintStream, Help.Ansi)` with the platform default.
      Parameters:
        `out` - the printStream to print to
      See Also:
        `usage(PrintStream, Help.ColorScheme)`

    - #### usage

          public void usage(java.io.PrintStream out,
                   CommandLine.Help.Ansi ansi)

      Delegates to `usage(PrintStream, Help.ColorScheme)` with the default color scheme.
      Parameters:
        `out` - the printStream to print to
        `ansi` - whether the usage message should include ANSI escape codes or not
      See Also:
        `usage(PrintStream, Help.ColorScheme)`

    - #### usage

          public void usage(java.io.PrintStream out,
                   CommandLine.Help.ColorScheme colorScheme)

      Prints a usage help message for the annotated command class to the specified `PrintStream`. Delegates construction of the usage help message to the `CommandLine.Help` inner class and is equivalent to:

           Help help = new Help(command).addAllSubcommands(getSubcommands());
           StringBuilder sb = new StringBuilder()
                   .append(help.headerHeading())
                   .append(help.header())
                   .append(help.synopsisHeading())      //e.g. Usage:
                   .append(help.synopsis())             //e.g. <main class> [OPTIONS] <command> [COMMAND-OPTIONS] [ARGUMENTS]
                   .append(help.descriptionHeading())   //e.g. %nDescription:%n%n
                   .append(help.description())          //e.g. {"Converts foos to bars.", "Use options to control conversion mode."}
                   .append(help.parameterListHeading()) //e.g. %nPositional parameters:%n%n
                   .append(help.parameterList())        //e.g. [FILE...] the files to convert
                   .append(help.optionListHeading())    //e.g. %nOptions:%n%n
                   .append(help.optionList())           //e.g. -h, --help   displays this help and exits
                   .append(help.commandListHeading())   //e.g. %nCommands:%n%n
                   .append(help.commandList())          //e.g.    add       adds the frup to the frooble
                   .append(help.footerHeading())
                   .append(help.footer());
           out.print(sb);

      Annotate your class with `CommandLine.Command` to control many aspects of the usage help message, including the program name, text of section headings and section contents, and some aspects of the auto-generated sections of the usage help message.

      To customize the auto-generated sections of the usage help message, like how option details are displayed, instantiate a `CommandLine.Help` object and use 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.

      Parameters:
        `out` - the `PrintStream` to print the usage help message to
        `colorScheme` - the `ColorScheme` defining the styles for options, parameters and commands when ANSI is enabled

    - #### printVersionHelp

          public void printVersionHelp(java.io.PrintStream out)

      Delegates to `printVersionHelp(PrintStream, Help.Ansi)` with the platform default.
      Parameters:
        `out` - the printStream to print to
      Since:
        0.9.8
      See Also:
        `printVersionHelp(PrintStream, Help.Ansi)`

    - #### printVersionHelp

          public void printVersionHelp(java.io.PrintStream out,
                              CommandLine.Help.Ansi ansi)

      Prints version information from the `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.
      Parameters:
        `out` - the printStream to print to
        `ansi` - whether the usage message should include ANSI escape codes or not
      Since:
        0.9.8
      See Also:
        `CommandLine.Command.version()`, `CommandLine.Option.versionHelp()`, `isVersionHelpRequested()`

    - #### printVersionHelp

          public void printVersionHelp(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`. Each element of the array of version strings is formatted with the specified parameters, and printed on a separate line. Both version strings and parameters may contain markup for colors and style.
      Parameters:
        `out` - the printStream to print to
        `ansi` - whether the usage message should include ANSI escape codes or not
        `params` - Arguments referenced by the format specifiers in the version strings
      Since:
        1.0.0
      See Also:
        `CommandLine.Command.version()`, `CommandLine.Option.versionHelp()`, `isVersionHelpRequested()`

    - #### call

          public static <C extends java.util.concurrent.Callable<T>,T> T call(C callable,
                                                              java.io.PrintStream out,
                                                              java.lang.String... args)

      Delegates to `call(Callable, PrintStream, Help.Ansi, String...)` with `CommandLine.Help.Ansi.AUTO`.

      From picocli v2.0, this method prints usage help or version help if requested, and any exceptions thrown by the `Callable` are caught and rethrown wrapped in an `ExecutionException`.

      Type Parameters:
        `C` - the annotated object must implement Callable
        `T` - the return type of the most specific command (must implement `Callable`)
      Parameters:
        `callable` - the command to call when parsing succeeds.
        `out` - the printStream to print to
        `args` - the command line arguments to parse
      Returns:
        `null` if an error occurred while parsing the command line options, otherwise returns the result of calling the Callable
      Throws:
        `CommandLine.InitializationException` - if the specified command object does not have a `CommandLine.Command`, `CommandLine.Option` or `CommandLine.Parameters` annotation
        `CommandLine.ExecutionException` - if the Callable throws an exception
      See Also:
        `call(Callable, PrintStream, Help.Ansi, String...)`, `parseWithHandlers(IParseResultHandler, PrintStream, Help.Ansi, IExceptionHandler, String...)`, `CommandLine.RunFirst`

    - #### call

          public static <C extends java.util.concurrent.Callable<T>,T> T call(C callable,
                                                              java.io.PrintStream out,
                                                              CommandLine.Help.Ansi ansi,
                                                              java.lang.String... args)

      Convenience method to allow command line application authors to avoid some boilerplate code in their application. The annotated object needs to implement `Callable`. Calling this method is equivalent to:

           CommandLine cmd = new CommandLine(callable);
           List<CommandLine> parsedCommands;
           try {
               parsedCommands = cmd.parse(args);
           } catch (ParameterException ex) {
               out.println(ex.getMessage());
               cmd.usage(out, ansi);
               return null;
           }
           if (CommandLine.printHelpIfRequested(parsedCommands, out, ansi)) {
               return null;
           }
           CommandLine last = parsedCommands.get(parsedCommands.size() - 1);
           try {
               Callable<Object> subcommand = last.getCommand();
               return subcommand.call();
           } catch (Exception ex) {
               throw new ExecutionException(last, "Error calling " + last.getCommand(), ex);
           }

      If the specified Callable command has subcommands, the last subcommand specified on the command line is executed. Commands with subcommands may be interested in calling the `parseWithHandler` method with a `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 `Callable` are caught and rethrown wrapped in an `ExecutionException`.

      Type Parameters:
        `C` - the annotated object must implement Callable
        `T` - the return type of the specified `Callable`
      Parameters:
        `callable` - the command to call when parsing succeeds.
        `out` - the printStream to print to
        `ansi` - whether the usage message should include ANSI escape codes or not
        `args` - the command line arguments to parse
      Returns:
        `null` if an error occurred while parsing the command line options, or if help was requested and printed. Otherwise returns the result of calling the Callable
      Throws:
        `CommandLine.InitializationException` - if the specified command object does not have a `CommandLine.Command`, `CommandLine.Option` or `CommandLine.Parameters` annotation
        `CommandLine.ExecutionException` - if the Callable throws an exception
      See Also:
        `parseWithHandlers(IParseResultHandler, PrintStream, Help.Ansi, IExceptionHandler, String...)`, `CommandLine.RunLast`

    - #### run

          public static <R extends java.lang.Runnable> void run(R runnable,
                                                java.io.PrintStream out,
                                                java.lang.String... args)

      Delegates to `run(Runnable, PrintStream, Help.Ansi, String...)` with `CommandLine.Help.Ansi.AUTO`.

      From picocli v2.0, this method prints usage help or version help if requested, and any exceptions thrown by the `Runnable` are caught and rethrown wrapped in an `ExecutionException`.

      Type Parameters:
        `R` - the annotated object must implement Runnable
      Parameters:
        `runnable` - the command to run when parsing succeeds.
        `out` - the printStream to print to
        `args` - the command line arguments to parse
      Throws:
        `CommandLine.InitializationException` - if the specified command object does not have a `CommandLine.Command`, `CommandLine.Option` or `CommandLine.Parameters` annotation
        `CommandLine.ExecutionException` - if the Runnable throws an exception
      See Also:
        `run(Runnable, PrintStream, Help.Ansi, String...)`, `parseWithHandlers(IParseResultHandler, PrintStream, Help.Ansi, IExceptionHandler, String...)`, `CommandLine.RunFirst`

    - #### run

          public static <R extends java.lang.Runnable> void run(R runnable,
                                                java.io.PrintStream out,
                                                CommandLine.Help.Ansi ansi,
                                                java.lang.String... args)

      Convenience method to allow command line application authors to avoid some boilerplate code in their application. The annotated object needs to implement `Runnable`. Calling this method is equivalent to:

           CommandLine cmd = new CommandLine(runnable);
           List<CommandLine> parsedCommands;
           try {
               parsedCommands = cmd.parse(args);
           } catch (ParameterException ex) {
               out.println(ex.getMessage());
               cmd.usage(out, ansi);
               return null;
           }
           if (CommandLine.printHelpIfRequested(parsedCommands, out, ansi)) {
               return null;
           }
           CommandLine last = parsedCommands.get(parsedCommands.size() - 1);
           try {
               Runnable subcommand = last.getCommand();
               subcommand.run();
           } catch (Exception ex) {
               throw new ExecutionException(last, "Error running " + last.getCommand(), ex);
           }

      If the specified Runnable command has subcommands, the last subcommand specified on the command line is executed. Commands with subcommands may be interested in calling the `parseWithHandler` method with a `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`.

      Type Parameters:
        `R` - the annotated object must implement Runnable
      Parameters:
        `runnable` - the command to run when parsing succeeds.
        `out` - the printStream to print to
        `ansi` - whether the usage message should include ANSI escape codes or not
        `args` - the command line arguments to parse
      Throws:
        `CommandLine.InitializationException` - if the specified command object does not have a `CommandLine.Command`, `CommandLine.Option` or `CommandLine.Parameters` annotation
        `CommandLine.ExecutionException` - if the Runnable throws an exception
      See Also:
        `parseWithHandlers(IParseResultHandler, PrintStream, Help.Ansi, IExceptionHandler, String...)`, `CommandLine.RunLast`

    - #### registerConverter

          public <K> CommandLine registerConverter(java.lang.Class<K> cls,
                                          CommandLine.ITypeConverter<K> converter)

      Registers the specified type converter for the specified class. When initializing fields annotated with `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:

      - all primitive types
      - all primitive wrapper types: Boolean, Byte, Character, Double, Float, Integer, Long, Short
      - any enum
      - java.io.File
      - java.math.BigDecimal
      - java.math.BigInteger
      - java.net.InetAddress
      - java.net.URI
      - java.net.URL
      - java.nio.charset.Charset
      - java.sql.Time
      - java.util.Date
      - java.util.UUID
      - java.util.regex.Pattern
      - StringBuilder
      - CharSequence
      - String

      The specified converter will be registered with this `CommandLine` and the full hierarchy of its subcommands and nested sub-subcommands at the moment the converter is registered. Subcommands added later will not have this converter added automatically. To ensure a custom type converter is available to all subcommands, register the type converter last, after adding subcommands.

      Type Parameters:
        `K` - the target type
      Parameters:
        `cls` - the target class to convert parameter string values to
        `converter` - the class capable of converting string values to the specified target type
      Returns:
        this CommandLine object, to allow method chaining
      See Also:
        `addSubcommand(String, Object)`

    - #### getSeparator

          public java.lang.String getSeparator()

      Returns the String that separates option names from option values when parsing command line options. by default.
      Returns:
        the String the parser uses to separate option names from option values

    - #### setSeparator

          public CommandLine setSeparator(java.lang.String separator)

      Sets the String the parser uses to separate option names from option values to the specified value. The separator may also be set declaratively with the `CommandLine.Command.separator()` annotation attribute.
      Parameters:
        `separator` - the String that separates option names from option values
      Returns:
        this `CommandLine` object, to allow method chaining

    - #### getCommandName

          public java.lang.String getCommandName()

      Returns the command name (also called program name) displayed in the usage help synopsis. by default.
      Returns:
        the command name (also called program name) displayed in the usage
      Since:
        2.0

    - #### setCommandName

          public CommandLine setCommandName(java.lang.String commandName)

      Sets the command name (also called program name) displayed in the usage help synopsis to the specified value. Note that this method only modifies the usage help message, it does not impact parsing behaviour. The command name may also be set declaratively with the `CommandLine.Command.name()` annotation attribute.
      Parameters:
        `commandName` - command name (also called program name) displayed in the usage help synopsis
      Returns:
        this `CommandLine` object, to allow method chaining
      Since:
        2.0

    - #### isExpandAtFiles

          public 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. This property is `true` by default.
      Returns:
        whether "argument files" or `@files` should be expanded into their content
      Since:
        2.1

    - #### setExpandAtFiles

          public 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. (`true` by default.)
      Parameters:
        `expandAtFiles` - whether "argument files" or `@files` should be expanded into their content
      Returns:
        this `CommandLine` object, to allow method chaining
      Since:
        2.1