Command line syntax for explicitly passsing the empty collection as a param-value

[nreid260]

It's often useful to be able to explicitly specify a default value, rather than needing to special case to not pass the param at all (e.g. in a bash script). Empty collections are the natural default for most collection-values params, but there's no way to explicitly encode them as a value.

I propose that the empty string should be parsed as the empty collection, to fill this gap. Empty string is the best choice for this empty-collection sentinel because it's the result of string-joining an empty collection, so the transformation is vaguely symmetric.

This proposal does make it impossible to specify a collection containing only the empty string, which is inconsistent in some ways, but that input should be way less common than empty collection. This could be solved by generalizing that trailing separators are ignored by parsing, but that would be a larger change.

[remkop]

I agree that it is currently not possible to specify an empty collection in the annotations.

Workaround

As a workaround, if the option or positional parameter is backed by an annotated field, you can give this field the initial value of an empty collection. That can look something like this:

@Option(names = "-s", description = "workaround: initial value is empty list")
List<String> initiallyEmptyList = new ArrayList<>();

Better solution: support for multi-value defaults

I believe the problem you mention will be properly solved as part of #879 (and #877),
which will provide the ability to specify default values for multi-value options in the annotations.

When #879 is implemented, application developers can write code like this:

@Option(names = "-n", defaultValues = {"1", "2"})
List<Integer> numberList;

@Option(names = "-x", defaultValues = {}, description = "Empty list by default")
List<Integer> otherList;

[nreid260]

The request isn't about the annotations (that I can tell), it's about the command line syntax. I want there to be a way that given:

@Option(names = "--int_list")
List<Integer> numberList;

println("numbers_count: " + numberList.size())

I can do:

$ my_binary --int_list=
number_count: 0

[remkop]

I see what you mean now, thank you for the clarification.

Currently, picocli has the notion of fallbackValue, which is the value that is assigned to options with an optional parameter, when the user specified the option without an option parameter on the command line.

However, currently fallbackValue (like defaultValue) only works for single-value options, not for multi-value options.

The plan is for #879 to address that also.

Your code would look like this:

@Option(names = "--int_list", arity = "0..1", fallbackValues = {})
List<Integer> numberList;

And that would result in an empty list being assigned to numberList when --int_list= is specified on the command line.

[remkop]

@nreid260 You can also accomplish the desired behaviour by specifying a custom IParameterPreprocessor.
This works with the current version of picocli.
For example:

import picocli.CommandLine;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Stack;

public class Issue1987 implements Runnable {
    @CommandLine.Option(names = "--int_list", preprocessor = MyPreProcessor.class)
    List<Integer> numberList;

    static class MyPreProcessor implements CommandLine.IParameterPreprocessor {
        @Override
        public boolean preprocess(Stack<String> args,
                                  CommandLine.Model.CommandSpec commandSpec,
                                  CommandLine.Model.ArgSpec argSpec,
                                  Map<String, Object> info) {
            if (argSpec == commandSpec.findOption("--int_list")) {
                if (args.empty()) {
                    return false; // no parameters at all: let picocli standard parsing handle this case
                }
                if (args.peek().isEmpty()) { // empty option parameter
                    args.pop(); // remove the empty string parameter from the stack
                    if ("=".equals(info.get("separator"))) { // user input was `--int_list=`
                        List<Integer> currentList = argSpec.getValue();
                        if (currentList == null) {
                            argSpec.setValue(new ArrayList<Integer>());
                        } else {
                            // list already has some value from previous args...
                            // your app should decided what (if anything) to do here...
                        }
                    }
                    return true; // tell picocli we handled this option completely
                }
            }
            return false; //let picocli standard parsing do the param handling for this Option
        }
    }


    @Override
    public void run() {
        System.out.println("numbers_count: " + numberList.size());
    }

    public static void main(String[] args) {
        new CommandLine(new Issue1987()).execute(args);
    }
}

[nreid260]

Is there a way to do this generically? Can that preprocessor be added to Picocli?

If 30 lines of code are needed for each flag with needing behavior, I wouldn't call it a solution. Ideally, all collection flags would treat empty input as empty collection.

[remkop]

@nreid260 The generic approach will be available when #879 is implemented in a future release. One of my previous comments has some details on how that will work.

The preprocessor example is a way to accomplish your requirements with the current version of picocli.
Hopefully the example is clear enough for you to get your application to work the way you intend to. You can modify the example to make it generic enough to work for multiple options.

[nreid260]

In my own app, I added a post-processing function to the run() method.

[remkop]

Oh interesting!
When users specify --int_list=, picocli will by default give an error "missing parameter for option --int_list".
The option parameter can be made optional with arity="0..1", but then picocli will still fail trying to convert the empty String to an Integer...

So I thought you needed something to prevent these errors, hence the preprocessor idea.

However, if you have something that works for you, that is great of course.

[nreid260]

Ahh, in my real case it's a list of strings, so the conversion can't fail.