CliBuilder (groovy 3.0.19 API)

groovy.cli.picocli.CliBuilder

class CliBuilder
extends Object

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:

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

Properties Summary

Properties
Type	Name and description
`boolean`	`acceptLongOptionsWithSingleHyphen` 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.
`PrintWriter`	`errorWriter` The PrintWriter to write to when invalid user input was provided to the parse(java.lang.String[]) method.
`boolean`	`expandArgumentFiles` Whether arguments of the form '`@`filename' will be expanded into the arguments contained within the file named filename (default true).
`String`	`footer` Optional additional message for usage; displayed after the options.
`String`	`header` Optional additional message for usage; displayed after the usage summary but before the options are displayed.
`String`	`name` This property allows customizing the program name displayed in the synopsis when `cli.usage()` is called.
`CommandLine.Model.ParserSpec`	`parser`
`Boolean`	`posix` To disallow clustered POSIX short options, set this to false.
`Map<String, TypedOption>`	`savedTypeOptions` Internal data structure mapping option names to their associated TypedOption object.
`boolean`	`stopAtNonOption` 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.
`String`	`usage` The command synopsis displayed as the first line in the usage help message, e.g., when `cli.usage()` is called.
`CommandLine.Model.UsageMessageSpec`	`usageMessage`
`int`	`width` Allows customisation of the usage message width.
`PrintWriter`	`writer` The PrintWriter to write the usage help message to when `cli.usage()` is called.

Constructor Summary

Constructors
Constructor and description
`CliBuilder ()`

Methods Summary

Methods
Type Params	Return Type	Name and description
	`Object`	`invokeMethod(String name, Object args)` Internal method: Detect option specification method calls.
`<T>`	`TypedOption<T>`	`option(Map args, Class<T> type, String description)`
	`CommandLine.Model.OptionSpec`	`option(Object shortname, Map details, Object description)` Internal method: How to create an OptionSpec from the specification.
	`OptionAccessor`	`parse(Object args)` Make options accessible from command line args with parser.
`<T>`	`T`	`parseFromInstance(T optionInstance, Object 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 `CliBuilder` and on the parser used by the underlying library.
	`void`	`setFooter(String footer)` Sets the footer property on this `CliBuilder` and on the usageMessage used by the underlying library.
	`void`	`setHeader(String header)` Sets the header property on this `CliBuilder` and the `description` on the usageMessage used by the underlying library.
	`void`	`setPosix(Boolean posix)` Sets the posix property on this `CliBuilder` and the `posixClusteredShortOptionsAllowed` property on the parser used by the underlying library.
	`void`	`setStopAtNonOption(boolean stopAtNonOption)` Sets the stopAtNonOption property on this `CliBuilder` and the `stopAtPositional` property on the parser used by the underlying library.
	`void`	`setUsage(String usage)` Sets the usage property on this `CliBuilder` and the `customSynopsis` on the usageMessage used by the underlying library.
	`void`	`setWidth(int width)` Sets the width property on this `CliBuilder` and on the usageMessage used by the underlying library.
	`void`	`setWriter(PrintWriter writer)` For backwards compatibility reasons, if a custom `writer` is 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).

Inherited Methods Summary

Inherited Methods
Methods inherited from class	Name
`class Object`	`wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`

- Property Detail
  - boolean acceptLongOptionsWithSingleHyphen
    
    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.
    Since:
    2.5
  - PrintWriter errorWriter
    
    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.
    Since:
    2.5
  - boolean expandArgumentFiles
    
    Whether arguments of the form '@filename' will be expanded into the arguments contained within the file named filename (default true).
  - String footer
    
    Optional additional message for usage; displayed after the options.
  - String header
    
    Optional additional message for usage; displayed after the usage summary but before the options are displayed.
  - String name
    
    This property allows customizing the program name displayed in the synopsis when cli.usage() is called. Ignored if the usage property is set.
    Since:
    2.5
  - final CommandLine.Model.ParserSpec parser
  - Boolean posix
    
    To disallow clustered POSIX short options, set this to false.
  - Map<String, TypedOption> savedTypeOptions
    
    Internal data structure mapping option names to their associated TypedOption object.
  - boolean stopAtNonOption
    
    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.
  - String usage
    
    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.
    See Also:
    name
  - final CommandLine.Model.UsageMessageSpec usageMessage
  - int width
    
    Allows customisation of the usage message width.
  - PrintWriter writer
    
    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.
- Constructor Detail
  - CliBuilder()
- Method Detail
  - Object invokeMethod(String name, Object args)
    
    Internal method: Detect option specification method calls.
  - <T> TypedOption<T> option(Map args, Class<T> type, String description)
  - CommandLine.Model.OptionSpec option(Object shortname, Map details, Object description)
    
    Internal method: How to create an OptionSpec from the specification.
  - OptionAccessor parse(Object args)
    
    Make options accessible from command line args with parser. Returns null on bad command lines after displaying usage message.
  - <T> T parseFromInstance(T optionInstance, Object args)
    
    Given an instance containing members with annotations, derive the options specification.
    Parameters:
    optionInstance
    args
    Returns:
    the options instance populated with the processed options
  - <T> T parseFromSpec(Class<T> optionsClass, String[] args)
    
    Given an interface containing members with annotations, derive the options specification.
    Parameters:
    optionsClass
    args
    Returns:
    an instance containing the processed options
  - void setExpandArgumentFiles(boolean expand)
    
    Sets the expandArgumentFiles property on this CliBuilder and on the parser used by the underlying library. @-files
    Parameters:
    expand - whether to expand argument
  - void setFooter(String footer)
    
    Sets the footer property on this CliBuilder and on the usageMessage used by the underlying library.
    Parameters:
    footer - the footer of the usage help message
  - void setHeader(String header)
    
    Sets the header property on this CliBuilder and the description on the usageMessage used by the underlying library.
    Parameters:
    header - the description text of the usage help message
  - void setPosix(Boolean posix)
    
    Sets the posix property on this CliBuilder and the posixClusteredShortOptionsAllowed property on the parser used by the underlying library.
    Parameters:
    posix - whether to allow clustered short options
  - void setStopAtNonOption(boolean stopAtNonOption)
    
    Sets the stopAtNonOption property on this CliBuilder and the stopAtPositional property on the parser used by the underlying library.
    Parameters:
    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.
  - void setUsage(String usage)
    
    Sets the usage property on this CliBuilder and the customSynopsis on the usageMessage used by the underlying library.
    Parameters:
    usage - the custom synopsis of the usage help message
  - void setWidth(int width)
    
    Sets the width property on this CliBuilder and on the usageMessage used by the underlying library.
    Parameters:
    width - the width of the usage help message
  - void setWriter(PrintWriter writer)
    
    For backwards compatibility reasons, if a custom writer is set, this sets both the writer and the errorWriter to the specified writer.
    Parameters:
    writer - the writer to initialize both the writer and the errorWriter to
  - void usage()
    
    Prints the usage message with the specified header, footer and width to the specified writer (default: System.out).

Summary:
Property
Constructor
Method

| Detail:
Property
Constructor
Method

[Groovy] Class CliBuilder

Properties Summary

Constructor Summary

Methods Summary

Inherited Methods Summary

Property Detail

boolean acceptLongOptionsWithSingleHyphen

PrintWriter errorWriter

boolean expandArgumentFiles

String footer

String header

String name

final CommandLine.Model.ParserSpec parser

Boolean posix

Map<String, TypedOption> savedTypeOptions

boolean stopAtNonOption

String usage

final CommandLine.Model.UsageMessageSpec usageMessage

int width

PrintWriter writer

Constructor Detail

CliBuilder()

Method Detail

Object invokeMethod(String name, Object args)

<T> TypedOption<T> option(Map args, Class<T> type, String description)

CommandLine.Model.OptionSpec option(Object shortname, Map details, Object description)

OptionAccessor parse(Object args)

<T> T parseFromInstance(T optionInstance, Object args)

<T> T parseFromSpec(Class<T> optionsClass, String[] args)

void setExpandArgumentFiles(boolean expand)

void setFooter(String footer)

void setHeader(String header)

void setPosix(Boolean posix)

void setStopAtNonOption(boolean stopAtNonOption)

void setUsage(String usage)

void setWidth(int width)

void setWriter(PrintWriter writer)

void usage()