Provides a builder to assist the processing of command line arguments. Two styles are supported: dynamic api style (declarative method calls provide a mini DSL for describing options) and annotation style (annotations on an interface or class describe options).
Dynamic api style
Typical usage (emulate partial arg processing of unix command: ls -alt *.groovy):
 def cli = new CliBuilder(name:'ls')
 cli.a('display all files')
 cli.l('use a long listing format')
 cli.t('sort by modification time')
 def options = cli.parse(args)
 assert options // would be null (false) on failure
 assert options.arguments() == ['*.groovy']
 assert options.a && options.l && options.t
 
 The usage message for this example (obtained using cli.usage()) is shown below:
 Usage: ls [-alt] -a display all files -l use a long listing format -t sort by modification timeAn underlying parser that supports what is called argument 'bursting' is used by default. Bursting would convert '-alt' into '-a -l -t' provided no long option exists with value 'alt' and provided that none of 'a', 'l' or 't' takes an argument (in fact the last one is allowed to take an argument). The bursting behavior can be turned off by configuring the underlying parser. The simplest way to achieve this is by setting the posix property on the CliBuilder to false, i.e. include
posix: false in the constructor call.
 Another example (partial emulation of arg processing for 'ant' command line):
 def cli = new CliBuilder(usage:'ant [options] [targets]',
                          header:'Options:')
 cli.help('print this message')
 cli.logfile(type:File, argName:'file', 'use given file for log')
 cli.D(type:Map, argName:'property=value', 'use value for given property')
 cli.lib(argName:'path', valueSeparator:',', args: '3',
      'comma-separated list of 3 paths to search for jars and classes')
 def options = cli.parse(args)
 ...
 
 Usage message would be:
 
 Usage: ant [options] [targets]
 Options:
   -D= <property=value>   use value for given property
       -help              print this message
       -lib=<path>,<path>,<path>
                          comma-separated list of 3 paths to search for jars and
                            classes
       -logfile=<file>    use given file for log
 
 And if called with the following arguments '-logfile foo -Dbar=baz -lib=/tmp,/usr/lib,~/libs target'
 then the following assertions would be true:
 
 assert options // would be null (false) on failure
 assert options.arguments() == ['target']
 assert options.D == ['bar': 'baz']
 assert options.libs == ['/tmp', '/usr/lib', '~/libs']
 assert options.lib == '/tmp'
 assert options.logfile == new File('foo')
 
 Note the use of some special notation. By adding 's' onto an option
 that may appear multiple times and has an argument or as in this case
 uses a valueSeparator to separate multiple argument values
 causes the list of associated argument values to be returned.
 Another example showing long options (partial emulation of arg processing for 'curl' command line):
 def cli = new CliBuilder(name:'curl')
 cli._(longOpt:'basic', 'Use HTTP Basic Authentication')
 cli.d(longOpt:'data', args:1, argName:'data', 'HTTP POST data')
 cli.G(longOpt:'get', 'Send the -d data with a HTTP GET')
 cli.q('If used as the first parameter disables .curlrc')
 cli._(longOpt:'url', type:URL, argName:'URL', 'Set URL to work with')
 
 Which has the following usage message:
 
 Usage: curl [-Gq] [--basic] [--url=<URL>] [-d=<data>]
       --basic         Use HTTP Basic Authentication
   -d, --data=<data>   HTTP POST data
   -G, --get           Send the -d data with a HTTP GET
   -q                  If used as the first parameter disables .curlrc
       --url=<URL>     Set URL to work with
 
 This example shows a common convention. When mixing short and long names, the
 short names are often one character in size. One character options with
 arguments don't require a space between the option and the argument, e.g.
 -Ddebug=true. The example also shows
 the use of '_' when no short option is applicable.
 Also note that '_' was used multiple times. This is supported but if any other shortOpt or any longOpt is repeated, then the underlying library throws an exception.
 Short option names may not contain a hyphen. If a long option name contains a hyphen, e.g. '--max-wait' then you can either
 use the long hand method call options.hasOption('max-wait') or surround
 the option name in quotes, e.g. options.'max-wait'.
 
Although CliBuilder on the whole hides away the underlying library used for processing the arguments, it does provide some hooks which let you make use of the underlying library directly should the need arise. For example, the last two lines of the 'curl' example above could be replaced with the following:
 import picocli.CommandLine.Model.*
 ... as before ...
 cli << OptionSpec.builder('-q').
                      description('If used as the first parameter disables .curlrc').build()
 cli << OptionSpec.builder('--url').type(URL.class).paramLabel('<URL>').
                      description('Set URL to work with').build()
 ...
 
 As another example, the usageMessage property gives
 fine-grained control over the usage help message (see the
 picocli user manual
 for details):
 
 def cli = new CliBuilder()
 cli.name = "myapp"
 cli.usageMessage.with {
     headerHeading("@|bold,underline Header heading:|@%n")
     header("Header 1", "Header 2")                     // before the synopsis
     synopsisHeading("%n@|bold,underline Usage:|@ ")
     descriptionHeading("%n@|bold,underline Description heading:|@%n")
     description("Description 1", "Description 2")      // after the synopsis
     optionListHeading("%n@|bold,underline Options heading:|@%n")
     footerHeading("%n@|bold,underline Footer heading:|@%n")
     footer("Footer 1", "Footer 2")
 }
 Supported Option Properties:
| Property | Type | Picocli equivalent | Description | 
|---|---|---|---|
| argName | String | names | Short name for the option, will be prefixed with a single hyphen. | 
| longOpt | String | names | Long name for the option, will be prefixed with two hyphens
       unless acceptLongOptionsWithSingleHyphen
       is true.
       An option must have either a long name or a short name (or both). | 
| args | int or String | arity | argsindicates the number of parameters for this option.
       A String value of '+' indicates at least one up to any number of parameters.
       The minimum number of parameters depends on the type (booleans require no parameters)
       and theoptionalArgsetting.argscan often be omitted if atypeis specified. | 
| optionalArg | boolean | arity | If optionalArg=true, thenargs=3is the equivalent ofarity="0..3"in picocli.
       WhenoptionalArg=true,args='+'is equivalent toarity="0..*". | 
| required | boolean | required | If true, this option must be specified on the command line, or an exception is thrown. | 
| type | Class | type | Option parameters are converted to this type. The underlying library has built-in converters for
     many types.
       A custom converter can be specified with the convertproperty. | 
| convert | Closure | converter | A closure that takes a single String parameter and returns an object converted to the typeof this option.
       The picocli equivalent is theITypeConverterinterface. | 
| valueSeparator | char | splitRegex | The character used to split a single command line argument into parts. | 
| defaultValue | String | defaultValue | The value the option should have if it did not appear on the command line.
       The specified String value will be split into parts with the valueSeparatorand
       converted to the optiontypebefore it is set. | 
@-files
CliBuilder also supports Argument File processing. If an argument starts with an '@' character followed by a filename, then the contents of the file with name filename are placed into the command line. The feature can be turned off by setting expandArgumentFiles to false. If turned on, you can still pass a real parameter with an initial '@' character by escaping it with an additional '@' symbol, e.g. '@@foo' will become '@foo' and not be subject to expansion. As an example, if the file temp.args contains the content:
-arg1 paramA paramB paramCThen calling the command line with:
someCommand
someCommand -arg1 paramA paramB paramC -arg2 paramDThis feature is particularly useful on operating systems which place limitations on the size of the command line (e.g. Windows). The feature is similar to the 'Command Line Argument File' processing supported by javadoc and javac. Consult the corresponding documentation for those tools if you wish to see further examples.
Annotation style with an interface
With this style an interface is defined containing an annotated method for each option. It might look like this (following roughly the earlier 'ls' example):
 import groovy.cli.Option
 import groovy.cli.Unparsed
 interface OptionInterface {def args = '-alt *.groovy'.split() // normally from commandline itself def cli = new CliBuilder(usage:'ls') def options = cli.parseFromSpec(OptionInterface, args) assert options.remaining() == ['*.groovy'] assert options.all() && options.longFormat() && options.time()
Annotation style with a class
With this style a user-supplied instance is used. Annotations on that instance's class members (properties and setter methods) indicate how to set options and provide the option details using annotation attributes. It might look like this (again using the earlier 'ls' example):
 import groovy.cli.Option
 import groovy.cli.Unparsed
 class OptionClass {
     @Option(shortName='a', description='display all files') boolean all
     @Option(shortName='l', description='use a long listing format') boolean longFormat
     @Option(shortName='t', description='sort by modification time') boolean time
     @Unparsed List remaining
 }
 
 Then this description is supplied to CliBuilder during parsing, e.g.:
 def args = '-alt *.groovy'.split() // normally from commandline itself def cli = new CliBuilder(usage:'ls') def options = new OptionClass() cli.parseFromInstance(options, args) assert options.remaining == ['*.groovy'] assert options.all && options.longFormat && options.time
| Type | Name and description | 
|---|---|
| boolean | acceptLongOptionsWithSingleHyphenFor backwards compatibility with Apache Commons CLI, set this property to trueif the parser should recognize long options with both
 a single hyphen and a double hyphen prefix. | 
| PrintWriter | errorWriterThe PrintWriter to write to when invalid user input was provided to the parse(java.lang.String[]) method. | 
| boolean | expandArgumentFilesWhether arguments of the form ' @filename' will be expanded into the arguments contained within the file named filename (default true). | 
| String | footerOptional additional message for usage; displayed after the options. | 
| String | headerOptional additional message for usage; displayed after the usage summary but before the options are displayed. | 
| String | nameThis property allows customizing the program name displayed in the synopsis when cli.usage()is called. | 
| ParserSpec | parserNot normally accessed directly but allows fine-grained control over the parser behaviour via the API of the underlying library if needed. | 
| Boolean | posixTo disallow clustered POSIX short options, set this to false. | 
| Map<String, TypedOption> | savedTypeOptionsInternal data structure mapping option names to their associated TypedOption object. | 
| boolean | stopAtNonOptionConfigures what the parser should do when arguments not recognized as options are encountered: when true(the default), the
 remaining arguments are all treated as positional parameters. | 
| String | usageThe command synopsis displayed as the first line in the usage help message, e.g., when cli.usage()is called. | 
| UsageMessageSpec | usageMessageNot normally accessed directly but allows fine-grained control over the usage help message via the API of the underlying library if needed. | 
| int | widthAllows customisation of the usage message width. | 
| PrintWriter | writerThe PrintWriter to write the usage help message to when cli.usage()is called. | 
| Type Params | Return Type | Name and description | 
|---|---|---|
|  | def | invokeMethod(String name, Object args)Internal method: Detect option specification method calls. | 
| <T> | TypedOption<T> | option(Map args, Class<T> type, String description) | 
|  | OptionSpec | option(def shortname, Map details, def description)Internal method: How to create an OptionSpec from the specification. | 
|  | OptionAccessor | parse(def args)Make options accessible from command line args with parser. | 
| <T> | T | parseFromInstance(T optionInstance, def args)Given an instance containing members with annotations, derive the options specification. | 
| <T> | T | parseFromSpec(Class<T> optionsClass, String[] args)Given an interface containing members with annotations, derive the options specification. | 
|  | void | setExpandArgumentFiles(boolean expand)Sets the expandArgumentFiles property on this CliBuilderand on the parser used by the underlying library. | 
|  | void | setFooter(String footer)Sets the footer property on this CliBuilderand on the usageMessage used by the underlying library. | 
|  | void | setHeader(String header)Sets the header property on this CliBuilderand thedescriptionon the usageMessage used by the underlying library. | 
|  | void | setPosix(Boolean posix)Sets the posix property on this CliBuilderand theposixClusteredShortOptionsAllowedproperty on the parser
 used by the underlying library. | 
|  | void | setStopAtNonOption(boolean stopAtNonOption)Sets the stopAtNonOption property on this CliBuilderand thestopAtPositionalproperty on the parser
 used by the underlying library. | 
|  | void | setUsage(String usage)Sets the usage property on this CliBuilderand thecustomSynopsison the usageMessage used by the underlying library. | 
|  | void | setWidth(int width)Sets the width property on this CliBuilderand on the usageMessage used by the underlying library. | 
|  | void | setWriter(PrintWriter writer)For backwards compatibility reasons, if a custom writeris set, this sets
 both the writer and the errorWriter to the specified writer. | 
|  | void | usage()Prints the usage message with the specified header, footer and width to the specified writer (default: System.out). | 
 For backwards compatibility with Apache Commons CLI, set this property to
 true if the parser should recognize long options with both
 a single hyphen and a double hyphen prefix. The default is false,
 so only long options with a double hypen prefix (--option) are recognized.
     
The PrintWriter to write to when invalid user input was provided to the parse(java.lang.String[]) method. Defaults to stderr but you can provide your own PrintWriter if desired.
 Whether arguments of the form '@filename' will be expanded into the arguments contained within the file named filename (default true).
     
Optional additional message for usage; displayed after the options.
Optional additional message for usage; displayed after the usage summary but before the options are displayed.
 This property allows customizing the program name displayed in the synopsis when cli.usage() is called.
 Ignored if the usage property is set.
     
Not normally accessed directly but allows fine-grained control over the parser behaviour via the API of the underlying library if needed.
To disallow clustered POSIX short options, set this to false.
Internal data structure mapping option names to their associated TypedOption object.
 Configures what the parser should do when arguments not recognized
 as options are encountered: when true (the default), the
 remaining arguments are all treated as positional parameters.
 When false, the parser will continue to look for options, and
 only the unrecognized arguments are treated as positional parameters.
     
 The command synopsis displayed as the first line in the usage help message, e.g., when cli.usage() is called.
 When not set, a default synopsis is generated that shows the supported options and parameters.
     
Not normally accessed directly but allows fine-grained control over the usage help message via the API of the underlying library if needed.
Allows customisation of the usage message width.
 The PrintWriter to write the usage help message to
 when cli.usage() is called.
 Defaults to stdout but you can provide your own PrintWriter if desired.
     
Internal method: Detect option specification method calls.
Internal method: How to create an OptionSpec from the specification.
Make options accessible from command line args with parser. Returns null on bad command lines after displaying usage message.
Given an instance containing members with annotations, derive the options specification.
Given an interface containing members with annotations, derive the options specification.
 Sets the expandArgumentFiles property on this CliBuilder
 and on the parser used by the underlying library. @-files
     
expand -  whether to expand argument Sets the footer property on this CliBuilder
 and on the usageMessage used by the underlying library.
     
footer -  the footer of the usage help message Sets the header property on this CliBuilder and the
 description on the usageMessage used by the underlying library.
     
header -  the description text of the usage help message Sets the posix property on this CliBuilder and the
 posixClusteredShortOptionsAllowed property on the parser
 used by the underlying library.
     
posix -  whether to allow clustered short options Sets the stopAtNonOption property on this CliBuilder and the
 stopAtPositional property on the parser
 used by the underlying library.
     
stopAtNonOption -  when true (the default), the
          remaining arguments are all treated as positional parameters.
          When false, the parser will continue to look for options, and
          only the unrecognized arguments are treated as positional parameters. Sets the usage property on this CliBuilder and the
 customSynopsis on the usageMessage used by the underlying library.
     
usage -  the custom synopsis of the usage help message Sets the width property on this CliBuilder
 and on the usageMessage used by the underlying library.
     
width -  the width of the usage help message For backwards compatibility reasons, if a custom writer is set, this sets
 both the writer and the errorWriter to the specified writer.
     
writer -  the writer to initialize both the writer and the errorWriter to