javapicocli

PicoCLI "defaultValue" and option values for primitive arrays

How are default values and option values for primitive arrays properly specified in PicoCli?

A primitive value can be annotated with a defaultValue string value:

@Option(
    names        = {"--one-value"},
    defaultValue = "1.25",
    description  = "one value (default: ${DEFAULT-VALUE})")
private double oneValue;

or set with on the field:

@Option(
    names        = {"--one-value"},
    description  = "one value (default: ${DEFAULT-VALUE})")
private double oneValue = 1.25;

In both cases oneValue=1.25; the description correctly reads as one value (default: 1.25); and, the values can be overridden on the command line with:

--one-value=1.23

An array of primitive values, however:

@Option(
    names        = {"--multiple-values"},
    defaultValue = "[0.00, 0.25, 0.50, 1.25]",
    paramLabels  = "values",
    description  = "multiple values (default: ${DEFAULT-VALUE})")
private double[] values;

fails with:

Invalid value for option '--multiple-values' (<values>): '[0.00, 0.25, 0.50, 1.25]' is not a double

even though the ${DEFAULT-VALUE} help says:

--multiple-values=<values>  multiple values (default: "[0.00, 0.25, 0.50, 1.25]")

The default values can be set on the field:

@Option(
    names        = {"--multiple-values"},
    defaultValue = "[0.00, 0.25, 0.50, 1.25]",
    paramLabels  = "values",
    description  = "one value (default: ${DEFAULT-VALUE})")
private double[] values; = new double[] {0.00, 0.25, 0.50, 1.25};

but in both cases these command line options fail:

--multiple-values="[0.10, 0.20]"
--multiple-values="0.10, 0.20"
--multiple-values=0.10,0.20

with:

'...' is not a double

So, what the right way to set the defaultValues and command line option for a primitive array?

Solution

  • Status as of picocli 4.7.1

    As of version 4.7.1, picocli does not have direct support for setting default values for multi-value options or positional parameters. ("Multi-value" meaning: options/positional parameters that can be specified multiple times and have an array, a Collection or a Map as the underlying data type.)

    Roadmap

    There is a feature request for this on the picocli issue tracker: https://github.com/remkop/picocli/issues/879 The proposal is to add new API, that will allow option definitions like this:

    @Option(names = "-x", defaultValues = { "1.1", "2.2", "3.3" })
double[] values;

    When implemented, that will also cover primitive arrays: default values are specified as Strings (just like command line values are) and are converted to the target data type by the type converter for that data type.

    Pull requests are always welcome! 😅

    Workaround

    With the current version of picocli you may be able to work around this by defining the option with a split regex to allow users to specify multiple comma-separated values after the option name. For example:

    @Option(
    names        = {"-m", "--multiple-values"},
    defaultValue = "0.00,0.25,0.50,1.25",
    split        = ",",
    paramLabels  = "values",
    description  = "multiple values (default: ${DEFAULT-VALUE})")
private double[] values;

    That has a multi-value default, but will also allow users to specify command lines like this:

    mycommand -m 1.1,2.2,3,3 -m 4.4 -m 5.5,6.6

    This may not be exactly what you want, but may be the closest we can get with the current version of picocli.