Picocli: ParameterException: add reference to offending ArgSpec

[rpanak]

I really like your library so far, thanks for the good work.

You could make it more useful by adding support for parameters with limited set of acceptable values. This typically maps to using enums as the java type for the parameter. I've tried to find other CLI parsers for Java that support this and I've only found argparse4j.
This can be viewed as a special case of parameter validation, but in my opinion it's common enough so that implementing this would help a lot of people (since there is no proper validation). Of course, you can solve the problem in the client code but having this in the library could prove so much better (possibility to print the acceptable values in help text). The values could be specified in the annotation or determined automatically in case of an enum.

[remkop]

Your timing is impeccable, sir!
Please take a look at the release notes file in master.

One the items for the upcoming 3.2 release is that the description for an option or positional parameter can include a ${COMPLETION-CANDIDATES} variable.

For enums, this expands to a list of the enum values. Enums already validate values during type conversation.

For options and positional parameters that are not enums, from 3.2 you can specify a class that generates completion candidates. This is intended to be used for command line completion, especially for jline2 integration. (Also used to generate bash completion scripts.)

However, picocli will not do validation against completion candidates. It considers completion candidates to be nothing more than suggestions for the user. For example, an option with type File can show all files in the current directory as completion candidates, but the option may accept a file path outside that directory.

Generally, I haven’t added a Validator interface for options because I cannot see how this would add much to the application doing the validation. Also, such an interface would only be a partial solution since many applications need to validate _combinations_ of options. I’m open to be convinced otherwise but for now I’m not focusing on validation.

[rpanak]

Great news indeed!

The thing for validation is you often need just a set of values. The set need not be unnecessarily small (e.g. enum), but can be a (larger) subset of a primitive type (let's say integers from 0 to 100; impractical for enums). You're right that you won't solve complicated validation use cases and you probably even shouldn't. Keeping it simple has its own appeal. When I think about it, my example could be probably solved even now by having a custom converter.

The use case I had in mind for validating enums is something more (end)user friendly. Trying a value not in the given enum type as a parameter gives the user a not really nice java exception. Good for a java dev, bad for the user. I was thinking the user could get more useful error message like

Invalid 'algorithm' specification: 'AES-129'. Valid values are: 'AES-128', 'AES-256'

Maybe giving the exceptions more structure like adding reference to problematic parameter and a non-string cause-of-the-parsing-error specification would allow me to implement it myself in my client code. Or maybe there's another way that I'm missing.

Anyway, the 3.2 release goes a long way (especially with the completions).

[remkop]

About error handling: picocli throws a ParameterException if the user specified invalid input (e.g. value could not be converted, missing mandatory parameters etc).

If you use CommandLine.run(new YourRunnable(), args) in your main method, the default exception handler will catch the ParameterException, print the message of that exception and show the usage help message. No stack trace is shown.

However, if picocli called run or call on a command and the run or call method threw an exception, picocli will throw an ExecutionException wrapping the original exception. I believe this is a reasonable compromise.

So, the error message is very important since that will be shown to the user if they specified an invalid crypto algorithm, for example.

[remkop]

Sorry, I did not read your comment carefully.

You want the ParameterException class to supply a reference to the offending ArgSpec. That is a good idea. I need to take a look at what is involved.

Would you mind changing the title of this issue to reflect the feature request?

[dhait]

Please consider my pull request #406 to address this feature request.

[remkop]

@dhait Thanks for the PR! It has been merged into master. I may make some changes to combine some constructors.

[remkop]

I combined some of the constructors and updated the release notes. Thanks again for the PR!

[rpanak]

LOL, I haven't been at a computer for a couple of days. What a progress - commit, PR, merge. I applaud you, gentlemen. Seems like chosing picocli has been a good idea.

Anyway, I've renamed the issue.

[remkop]

I’ve released picocli 3.2 which includes this change.

[remkop]

If you like the project, please star it on GitHub and tell your friends! :-)