Mike’s Musings

Writing scripts in Groovy is a great way to develop cross-platform utilities. As the complexity of the scripts increase, you will probably find that you need to handle command line options in your script. It can be a lot of work to parse these options or arguments and display usage information when the options are wrong. Groovy bundles the Apache Commons CLI library as part of it’s distribution. However, Groovy also provides a CliBuilder (see references below) to make it much easier to use.

For an introduction, we will create a small test script in Groovy to experiment with the CliBuilder. The script will take several arguments:

• A directory specified with the -d option, which will be required
• An optional -h (help) option
• An optional -n (number) option
• Finally, zero or more script arguments (such as files to process)

First we need to create an instance of CliBuilder as follows. Please excuse the line wrapping.

def cl = new CliBuilder(usage: 'groovy clitest -d "dir" [-h] [-n "number"] [arguments]*')

CliBuilder has a property named usage which is used to display usage information to the user. The value supplied in the constructor above will show the user what options can be specified, but additional detail will also be shown based on the options we tell CliBuilder about. To associate an option to CliBuilder, you invoke a single character method with properties to configure the option (see Option JavaDoc at the Apache web site above). For example, the following line defines the help command line option.

cl.h(longOpt:'help', 'Show usage information and quit')

The longOpt property allows the option to be specified as either -h or --help. The second method argument provides a description of the argument.

The following code as the other two options to our script.

cl.d(argName:'dir', longOpt:'directory', args:1, required:true, 'Directory to Search, REQUIRED')

cl.n(argName:'number', longOpt:'number', args:1, required:false, 'Number of something')

The argName property specifies the name of the argument to the option in the usage information. Both of these options have on argument, which is specified with the args property. The required property is used to tell the command line parser if the option is required or not. Finally, we provide a description for the option for use in display usage information.

That is all we need to do for setup. To actually parse the command line options, use the following command.

def opt = cl.parse(args)

Remember that the command line arguments for a Groovy script are passed to the script as args. If there are parse errors, such as a missing required option, CliBuilder will display information about the parse error/exception and the usage information as well. The return value of parse will be null if there are parse errors.

To test if a non-required option was given on the command line, you would test like this.

if (opt.h)

The directory option above is required and takes one argument. The following code will display the value of that argument.

println "directory: ${opt.d}"

The values for the options will be of type String. Therefore, if we really wanted the number option value to be treated as an Integer, we would need to something like the following.

def int nmbr = 1
...
nmbr = Integer.parseInt(opt.n)

As you can see, adding support for command line arguments in a Groovy script is very straight forward. Below is a complete test script. Try it yourself and experiment with different options and values.

Finally, let me point out that, while I’ve been discussing scripts in this blog, this same technique can be applied to a Groovy class as well.

def cl = new CliBuilder(usage: 'groovy clitest -d "dir" [-h] [-n "number"] [arguments]*')

cl.h(longOpt:'help', 'Show usage information and quit')
cl.d(argName:'dir', longOpt:'directory', args:1, required:true, 'Directory to Search, REQUIRED')
cl.n(argName:'number', longOpt:'number', args:1, required:false, 'Number of something')

def opt = cl.parse(args)
def int nmbr = 1

if (!opt) {
    // because the parse failed, the usage will be shown automatically
    println "\nInvalid command line, exiting..."
} else if (opt.h) {
    cl.usage()
} else {
    println "directory: ${opt.d}"
    if (opt.n) {
	nmbr = Integer.parseInt(opt.n)
	println "nmbr: ${nmbr.class.name} ${nmbr}"
    }
    println "Number of args: ${opt.arguments().size()} : ${opt.arguments()}"
}

CliBuilder Resources
JavaDoc
An article presenting a script using CliBuilder.