Picocli 2.0 adds improved support for other JVM languages, especially Groovy. Why use picocli when the Groovy language has built-in CLI support with the CliBuilder class?
You may like picocli’s usage help, which shows ANSI colors and styles by default. Another feature you may fancy is the command line TAB autocompletion. Finally, there is a slew of smaller features, like the fact that your script needs zero lines of command line parsing code, picocli’s subcommand support, type conversion for both options and positional parameters, and parser tracing, to name a few.
Example
Let’s take a look at an example. The checksum.groovy script below takes one or more file parameters,
and for each file prints out a checksum and the file name. The "checksum" algorithm is MD5 by default,
but users may specify a different MessageDigest algorithm. Users can request usage help with the
-h or --help option.
@Grab('info.picocli:picocli:2.0.3')
@picocli.groovy.PicocliScript
import groovy.transform.Field
import java.security.MessageDigest
import static picocli.CommandLine.*
@Parameters(arity="1", paramLabel="FILE", description="The file(s) whose checksum to calculate.")
@Field File[] files
@Option(names = ["-a", "--algorithm"], description = [
"MD2, MD5, SHA-1, SHA-256, SHA-384, SHA-512,",
" or any other MessageDigest algorithm."])
@Field String algorithm = "MD5"
@Option(names= ["-h", "--help"], usageHelp= true, description= "Show this help message and exit.")
@Field boolean helpRequested
files.each {
println MessageDigest.getInstance(algorithm).digest(it.bytes).encodeHex().toString() + "\t" + it
}When run in the $picocli-home/examples/src/main/groovy/picocli/examples directory,
this example script gives the following results:
$ groovy checksum.groovy *.*
4995d24bbb3adf67e2120c36dd3027b7 checksum.groovy
a03c852de017f9303fcc373c7adafac6 checksum-with-banner.groovy
1ee567193bf41cc835ce76b6ca29ed30 checksum-without-base.groovyInvoking the script with the -h or --help option shows the usage help message
with ANSI colors and styles below:
Where’s the Code?
You may have noticed that the above script does not contain any logic for parsing the command line arguments or for handling requests for usage help.
Without the @picocli.groovy.PicocliScript annotation, the script code would look something like this:
class Checksum {
@Parameters(arity = "1", paramLabel = "FILE", description = "...")
File[] files
@Option(names = ["-a", "--algorithm"], description = ["..."])
String algorithm = "MD5"
@Option(names = ["-h", "--help"], usageHelp = true, description = "...")
boolean helpRequested
}
Checksum checksum = new Checksum()
CommandLine commandLine = new CommandLine(checksum)
try {
commandLine.parse(args)
if (commandLine.usageHelpRequested) {
commandLine.usage(System.out)
} else {
checksum.files.each {
byte[] digest = MessageDigest.getInstance(checksum.algorithm).digest(it.bytes)
println digest.encodeHex().toString() + "\t" + it
}
}
} catch (ParameterException ex) {
println ex.message
commandLine.usage(System.out)
}The above example has explicit code to parse the command line, deal with invalid user input, and check for usage help requests. The first version of the script did not have any of this boilerplate code.
Let’s take a look at how this works.
Basescript
Scripts annotated with @picocli.groovy.PicocliScript are automatically transformed to use
picocli.groovy.PicocliBaseScript as their base class.
This turns a Groovy script into a picocli-based command line application.
When the script is run, Groovy calls the script’s run method.
The PicocliBaseScript::run method takes care of parsing the command line and populating the script
fields with the results. The run method does the following:
-
First,
@Fieldvariables annotated with@Optionor@Parametersare initialized from the command line arguments. -
If the user input was invalid, an error message is printed followed by the usage help message.
-
If the user requested usage help or version information, this is printed to the console and the script exits.
-
Otherwise, the script body is executed.
This behavior can be customized, see the PicocliBaseScript javadoc for more details.
In addition to changing the script base class, the @PicocliScript annotation also allows Groovy
scripts to use the @Command annotation directly, without introducing a helper class.
The picocli parser will look for this annotation on the
class containing the @Option and @Parameters-annotated fields. The same custom
AST transformation
that changes the script’s base class also moves any @Command annotation in the script to this
transformed class so the picocli parser can pick it up.
Usage Help With Colors
The @Command annotation lets you customize parts of the usage help message like command name, description, headers, footers etc.
Let’s add some bells and whistles to the example script. (Credit to http://patorjk.com/software/taag/ for the ASCII Art Generator.)
@Grab('info.picocli:picocli:2.0.3')
@Command(header = [
$/@|bold,green ___ ___ _ _ |@/$,
$/@|bold,green / __|_ _ ___ _____ ___ _ / __| |_ ___ __| |__ ____ _ _ __ |@/$,
$/@|bold,green | (_ | '_/ _ \/ _ \ V / || | | (__| ' \/ -_) _| / /(_-< || | ' \ |@/$,
$/@|bold,green \___|_| \___/\___/\_/ \_, | \___|_||_\___\__|_\_\/__/\_,_|_|_|_||@/$,
$/@|bold,green |__/ |@/$
],
description = "Print a checksum of each specified FILE.",
version = 'checksum v1.2.3', showDefaultValues = true,
footerHeading = "%nFor more details, see:%n",
footer = ["[1] https://docs.oracle.com/javase/9/docs/specs/security/standard-names.html",
"ASCII Art thanks to http://patorjk.com/software/taag/"]
)
@picocli.groovy.PicocliScript
import groovy.transform.Field
import java.security.MessageDigest
import static picocli.CommandLine.*
@Parameters(arity="1", paramLabel="FILE", description="The file(s) whose checksum to calculate.")
@Field private File[] files
@Option(names = ["-a", "--algorithm"], description = [
"MD2, MD5, SHA-1, SHA-256, SHA-384, SHA-512, or",
" any other MessageDigest algorithm. See [1] for more details."])
@Field private String algorithm = "MD5"
@Option(names= ["-h", "--help"], usageHelp=true, description="Show this help message and exit.")
@Field private boolean helpRequested
@Option(names= ["-V", "--version"], versionHelp=true, description="Show version info and exit.")
@Field private boolean versionInfoRequested
files.each {
println MessageDigest.getInstance(algorithm).digest(it.bytes).encodeHex().toString() + "\t" + it
}The new version of the script adds a header and footer, and the ability to print version information.
All text displayed in the usage help message and version information may contain format specifiers
like the %n line separator.
The usage help message can also display ANSI colors and styles.
Picocli supports a simple markup syntax where @| starts an ANSI styled section and |@ ends it.
Immediately following the @| is a comma-separated list of colors and styles,
like @|STYLE1[,STYLE2]… text|@.
See the picocli user manual for details on what colors and styles are available.
The usage help message for the new script looks like this:
The @Command annotation also has a version = "checksum v1.2.3" attribute.
This version string is printed when the user specifies --version on the command line because
we declared an @Option with that name with attribute versionHelp = true.
$ groovy checksum-with-banner.groovy --version
checksum v1.2.3For more details, see the Version Help section of the user manual.
Conclusion
The @PicocliScript annotation allows Groovy scripts to omit boilerplate code and while adding powerful common command line application functionality.
In the final version of our example script, most of the code is actually description text for the usage help message.
There is a lot more to picocli, give it a try!
Please star the project on GitHub if you like it and tell your friends!