# Picocli 2.0: Groovy Scripts on Steroids

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

Invoking 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, `@Field` variables annotated with `@Option` or `@Parameters` are 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.3

For 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!