Contention between optional option and required parameter

[mohdpasha]

The example I am using has three options followed by one required parameter. The options could be used in any order. One of the options is a String with arity="0..1". This is an optional string. When this option is used as the last of the options (with the option used but a value not specified) followed by the required String parameter, the value which should go to the REQUIRED parameter is going to the OPTIONAL option instead. MissingParameterException is being thrown. This is not expected behavior. I would consider this a bug. I can provide additional details if the scenario is unclear. Thank you.

[remkop]

Hi, yes, this is how picocli currently handles options with an optional parameter.

The picocli parser is “greedy” when it handles optional parameters: it looks at the value following the option name, and if that value is likely to be a parameter (not another option or subcommand) then picocli will process the value as a parameter for that option.

(See also a similar discussion on #979.)

(Update: I raised Investigate feasibility of parser backtracking for ambiguous options (#980) for this.)

We could try to improve the logic for determining if a value is “likely to be a parameter”, but this is not straightforward. It requires looking forward at all remaining arguments to see if all required positional parameters (there may be more than one) will get a value. This means parsing all the way to the end before deciding on how to treat the value following an optional option: so we would need to implement a backtracking parser, and while this is on the TODO list, it may take a while before I can get to it.

Possible Solutions/Workarounds

One way to deal with this is to point out this ambiguity in the documentation of your application. End users can disambiguate the input by specifying either the -- end-of-options delimiter or another option between the optional option and the required parameter. It is after all quite possible that the end user intended the value to be a parameter for the option and actually did forget to specify the required positional parameter.

An alternative you could consider is removing the ambiguity from your application. For example, an optional option could be replaced by a boolean option plus an option that requires a parameter.

[mohdpasha]

So, the optional option has three possibilities:

1. Not used (-x was not used)
2. Used without a value (-x)
3. Used with a value (-x value)

These are all valid for arity 0..1.

In throwing a MissingParameterException, your logic is throwing out #2 as a valid possibility. To me, that translates as a bug because it goes against the specification.

[remkop]

I will update the documentation to clarify what picocli's behaviour is in this scenario. I don't think it is mentioned anywhere at the moment.

[remkop]

Until #980 is implemented, the best I can do is clarify the current behaviour.

I added section Options with an Optional Parameter to the user manual.

[remkop]

Closing this issue.
This is a known and (thanks to your feedback) documented drawback of defining commands that have both an option with an optional parameter and a positional parameter.

However, picocli now offers parser plugins for custom parameter processing.
The documentation for the IParameterPreprocessor plugin has an example showing a solution for this exact use case.

Hopefully that offers sufficient flexibility for people to build applications meeting their requirements.