[Groovy] Class CliBuilder

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 time
 

An 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	args indicates 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 the optionalArg setting. args can often be omitted if a type is specified.
optionalArg	boolean	arity	If optionalArg=true, then args=3 is the equivalent of arity="0..3" in picocli. When optionalArg=true, args='+' is equivalent to arity="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 convert property.
convert	Closure	converter	A closure that takes a single String parameter and returns an object converted to the type of this option. The picocli equivalent is the ITypeConverter interface.
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 valueSeparator and converted to the option type before it is set.

See groovy.cli.picocli.CliBuilderTest for further examples.

@-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 paramC
 

Then calling the command line with:

 someCommand

temp.args:

-arg2 paramD Is the same as calling this:

 someCommand -arg1 paramA paramB paramC -arg2 paramD
 

This 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 {

@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 = 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