Add support for IDefaultValueProvider

[remkop]

Add support for IDefaultValueProvider on @Command and potentially on individual @Option and @Parameters.

See discussion under #261.

Proposed API:

interface IDefaultValueProvider {
    /** Returns the default value for an option or positional parameter or {@code null}.
     * The returned value is converted to the type of the option/positional parameter
     * via the same type converter used when populating this option/positional
     * parameter from a command line argument.
     * @param argSpec the option or positional parameter, never {@code null}
     * @return the default value for the option or positional parameter, or {@code null} if
     *       this provider has no default value for the specified option or positional parameter
     */
    String defaultValue(ArgSpec argSpec);
}

[remkop]

Note to self: this ticket can/should be implemented before #322. Given the discussion on #280, there are some trade-offs with a defaulValue annotation attribute, while the benefits of this ticket are more clear.

[remkop]

API-wise, I think the below is sufficient for the first cut:

public @interface Command {
  Class<? extends IDefaultValueProvider> defaultValueProvider() default NoDefaultProvider.class;
  // ...
}
private static class NoDefaultProvider implements IDefaultValueProvider {
    public String defaultValue(ArgSpec argSpec) { throw new UnsupportedOperationException(); }
}

public static class CommandSpec {
  public IDefaultValueProvider defaultValueProvider() { return defaultValueProvider; }
  public CommandSpec defaultValueProvider(IDefaultValueProvider  defaultValueProvider) {
    this.defaultValueProvider = defaultValueProvider;
    return this; 
  }
  // ...
}

No need to have an defaultValueProvider annotation attribute on @option and @parameters.

[NicolasMassart]

If you can help me, I have difficulties to see how to retrieve the CommandSpec (to get my default value provider) from within the ArgSpec defaultValue() method

[remkop]

I was thinking to leave ArgSpec.default() untouched, and only add logic to the method in Interpreter where the default values are set before parsing the user input. Away from PC, from memory I think it was setDefaultValue(ArgSpec). I was thinking to also pass the IDefaultProvider to that method.

[NicolasMassart]

Ok, something like that ?

        private void applyDefault(IDefaultValueProvider defaultValueProvider,
            ArgSpec arg, List<ArgSpec> required) throws Exception {

            String defaultValue = defaultValueProvider == null ? arg.defaultValue() : defaultValueProvider.defaultValue(arg) ;

            if (defaultValue == null) { return; }
            if (tracer.isDebug()) {tracer.debug("Applying defaultValue (%s) to %s%n", defaultValue, arg);}
            Range arity = arg.arity().min(Math.max(1, arg.arity().min));

            applyOption(arg, LookBehind.SEPARATE, arity, stack(defaultValue), new HashSet<ArgSpec>(), arg.toString);
            required.remove(arg);
        }

[remkop]

Yes exactly!

[NicolasMassart]

Also do you have an idea about where to put the test ? I was thinking about something around

picocli/src/test/java/picocli/CommandLineModelTest.java

Line 1014 in c5f3acc

public void testOptionSpec_setsDefaultValue_ifNotMatched() {

[NicolasMassart]

I'm going to propose my PR without test for now for you to see if it's ok, but of course I'm going to add these test. Anyway you wont merge it if there's no tests ;)

[remkop]

That was quick! Thanks!
I’ll review as soon as I can.
As for where to put the tests, it may be easier to add a new test class for testing IDefaultProvider.

[NicolasMassart]

Agree fort the new test class.

[NicolasMassart]

@remkop let me know what you think of the PR #458. For me it seems over but...

[remkop]

Thanks for the contribution!
I’ll take a look as soon as I can get to my PC.

I guess the last thing is a mention of this new mechanism in the Default Values section of the user manual. I can take care of that unless you get to it first.

[NicolasMassart]

Will try.

[remkop]

Ok, then I'll wait for you on the docs.
Would you mind rebasing your branch on master?

[remkop]

I merged the PR. Many thanks! There are some other tickets I'm already working on so it may take me a bit before I will get to the user manual. If you feel like doing another PR for the user manual, go for it! :-)

[NicolasMassart]

I will have a look at the doc part, I promise. Meanwhile I'm going to use the system to be sure it works well ;)

[NicolasMassart]

I would need to add something to the PR I did, a boolean to indicate if the defaultprovider should override default values or not. I will propose another PR for that and the doc of course.

[remkop]

What is the use case for this boolean? If someone wants a default value in the code to “win”, they can simply omit it from the config file, no?

I would prefer to keep it simple. We can always enhance later if really necessary.

[remkop]

Alternatively, IDefaultProvider implementors can inspect the specified ArgSpec and return its default value if one exists. Again, there should be no need for a boolean in the picocli API.

[NicolasMassart]

Yes sometimes, when you are head down in the code you don't see obvious things...

[remkop]

No worries. :-)

[NicolasMassart]

Looking deeper, it seems that it however requires a fix in my previous PR. Because if I have a default or initial value, the default provider value can't apply. So that's why I wanted to go in this twisted addition I guess. But the right way to do is to fix it instead of adding more logic...
So I will provide a PR and fixed tests.

[remkop]

I went ahead and added some text to the user manual and release notes. Feel free to suggest further improvements.

Again thanks for the contribution!

[NicolasMassart]

Sorry for the delay for doc. I will review what you wrote but next time I will do more. Just that work always comes first...

[remkop]

No worries!
Grateful for what you did!

[remkop]

I just realized we forgot about ${DEFAULT-VALUE} replacement in the usage help description.
That is tricky because the ArgSpec does not have a reference to the default value provider...
I guess we need to add that, or a reference to the CommandSpec, when an ArgSpec is added to the CommandSpec.

[remkop]

I've given it some thought and I am leaning towards changing ArgSpec.defaultValueString() to return the value from the default provider (if one exists).

That meets the first goal (description text containing ${DEFAULT-VALUE} should be rendered with the default value), and at the same time allows application authors to distinguish between the default value that was programmatically set on an option (can be obtained with ArgSpec.defaultValue()) and the default value from the provider (can be obtained with IDefaultProvider.defaultValue(ArgSpec)).

(Also need to update the Javadoc for these ArgSpec methods to clarify where the values come from.)