List valid options in error messages

[dduan]

When an option value fails to parse, no custom error message is
provided, and a list of valid candidate values is available, include the
list as part of the error message.

Addresses #344.

Checklist

• I've added at least one test that validates that my change is working, if appropriate
• I've followed the code style of the rest of the project
• I've read the Contribution Guidelines
• I've updated the documentation if necessary

[dduan]

@swift-ci Please test

[dduan]

Not holding any strong opinions about the specific wording. Suggestions welcome.

[natecook1000]

This is great, @dduan!

I want to make sure this doesn't fall apart if allCases is more than a handful of cases. Can we switch to a bulleted list format in that case? Do you think 6 would make a good upper limit on the comma-delimited list?

What do you think of this for the output?

The value 'png' is invalid for '--format <format>'. Please provide one of 'text', 'json', or 'csv'.

The value 'png' is invalid for '--format <format>'. Please provide one of the following:
  - text
  - json
  - csv
  - plist
  - yaml
  - xaml
  - bson
  - xml

[rauhul]

nit: for array arguments with non-empty allValues the help message should read "one or more of"

[dduan]

the help message should read "one or more of"

I've considered this suggestion and found it confusing in context.

1. While it's true that the some parsing strategies allow --format text json, it's also possible that the list is supplied separately like --format text --format json.
2. The beginning of the error message points to a single erroneous value: The value 'png' is invalid for....

IMO it's more accurate to suggest alternatives for a singular value, namely, the attempted value from the user's input.

[dduan]

@swift-ci test

[dduan]

I've implemented @natecook1000's suggestion.

[natecook1000]

Error: duplicate case detected 😜

[natecook1000]

Looks great, thanks @dduan!