Create empty Map for Map @Option in command methods

[bobtiernay-okta]

Currently the following will result in a null Map being passed to the method:

public Status exec(@Option(names = "-e", description = "Environmental variables in key=value format") Map<String, String> vars) {
// ...
}

From the docs:

If the field is null, picocli will instantiate it when the option or positional parameter is matched. If the type is not a concrete class, picocli will instantiate a LinkedHashMap to preserve the input ordering.

However this is isn't a field so the expectation is unclear. Ideally this would be initialized to an empty Map. Updating the documentation to account for command methods would also be useful.

[remkop]

The convention in picocli is to not modify annotated fields (or parameters) that weren’t matched on the command line, unless a default value was specified.

For object fields this means that if they’re declared without an initial value, they stay null. For parameters the behavior is similar.

Do you feel like providing a pull request to improve the documentation? (No need to change the HTML file, it is generated from the index.adoc file.)

[remkop]

@bobtiernay-okta Does this answer your question?

[bobtiernay-okta]

Yes it does thanks. Sorry, I planned to say I would help add a note to the docs. Might be able to get to it later in the week. Thanks!

[remkop]

That would be great, thanks!

[bobtiernay-okta]

So I'm trying to update the documentation but I'm struggling to square the existing docs:

If the field is null, picocli will instantiate it when the option or positional parameter is matched

with your comment above:

The convention in picocli is to not modify annotated fields (or parameters) that weren’t matched on the command line, unless a default value was specified.

In the case of an @Option that is on a command method parameter without a defaultValue specified, should't the behavior be to create it per the first sentence above?

[remkop]

I created a test to demonstrate the current behaviour and actually found a bug. :-) The test is in the issue I created: #538

The test shows the expected behaviour:

• if no options are matched, method parameters without a default will have a null value, while method parameters with a default will have the default value
• if options are matched, the matched value is passed to the method

In the case of fields, it's similar, but slightly more complex because fields can have an initial value in their declaration, for example:

@Option(names = "-x")
Integer x = 123;

• if the option is not matched, annotated fields without a default will be set to their initial value, and annotated fields with a default will be set to the default value. Instead of "are not modified" it's more accurate to say "are reset to the initial value".
• if the option is matched, annotated fields are set to the matched value.

Also, when the option is matched, for Collection fields picocli will instantiate the Collection unless the field already has a non-null value (similar for Maps):

@Option(names = "-y")
List<String> y = null; // picocli creates an ArrayList instance if -y is matched

@Option(names = "-z")
List<String> z = new ArrayList<>(); // picocli adds to this existing instance if -z is matched

[remkop]

Did my last comment answer your question?

[remkop]

Early warning: I’m planning to do a release in a week or so. If you can provide any doc improvements this week they will be included in the upcoming release. Of course there will be other releases if that’s too soon.

[bobtiernay-okta]

Will try to get to this tomorrow or Monday.

[remkop]

Great, thanks!

[remkop]

Hi @bobtiernay-okta, I saw the PR on #545, thank you! Is this ready to be merged and are you happy to close this ticket when #545 is merged or are there more changes in the pipeline?

[bobtiernay-okta]

I think its good enough for now. I was going to add more detail but it really didn't fit in that section. I'll try to contribute a more substantial piece next time!

[remkop]

Understood. I merged to PR. Do you want to keep this ticket open?