search

pkgjs / parseargs

Polyfill of `util.parseArgs()`
Apache License 2.0
121 stars 9 forks source link

Make positionals opt-in when strict:true #116

Closed bakkot closed 2 years ago

bakkot commented 2 years ago

Fixes https://github.com/pkgjs/parseargs/issues/85.

In the second commit I've updated the message for unknown options to suggest using --. I'm not sure if this is worth doing, but I figured I'd implement it for discussion; happy to revert if it seems unhelpful.

shadowspawn commented 2 years ago

From https://github.com/pkgjs/parseargs/issues/85#issuecomment-1094143617

That is, I think that making positionals opt-in is in keeping with the "you will need to provide config for each option that you want to accept" design. I regard positionals as being a kind of option that you want to accept.

I think giving authors insight into the design helps smooth the experience, so more likely the API works the way they expect it to work because we guided their expectations (https://github.com/pkgjs/parseargs/issues/85#issuecomment-1098832809).

I am interested in seeing a sentence or two in the docs to spin the config-what-you-accept story or similar. I was thinking outside the documentation of the properties themselves and tying in the options.

bakkot commented 2 years ago

I am interested in seeing a sentence or two in the docs to spin the config-what-you-accept story or similar. I was thinking outside the documentation of the properties themselves and tying in the options.

Makes sense. I've added the following sentence as a start, though I'm happy to try to expand this section:

Takes a specification for the expected options and returns a structured object corresponding to passed arguments.

shadowspawn commented 2 years ago

Optional: there could be a single check for ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL after parsing, rather than two checks inside the loop.

bakkot commented 2 years ago

Optional: there could be a single check for ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL after parsing, rather than two checks inside the loop.

Doing the check after parsing means any other errors will happen first, even errors which are later in the input. I prefer getting errors in the order in which the corresponding problematic things appear.

shadowspawn commented 2 years ago

In the second commit I've updated the message for unknown options to suggest using --. I'm not sure if this is worth doing, but I figured I'd implement it for discussion; happy to revert if it seems unhelpful.

Something for future, not urgent.

We didn't really have time to discuss this. I expect most errors for unknown options will be for typos in the option name, so the suggestion is not going to be relevant. Not harmful, but not helpful. We are going the extra mile with error messages since they may be the UX, so could perhaps have two suggestions, with a "check the spelling" type suggestion first?