Throw for unsupported option setup#2270
Conversation
|
Released in Commander v13.0.0 |
|
Hi @shadowspawn! We noticed some of our commands break with v13 because they are configured with more than one long flag. The idea is to provide a shorter version without using a one-letter option, e.g. Now that multi-letter options are also throwing an error, this feels quite limiting. I get the point of considering POSIX-compatibility with multi-letter options (I am always confused by those e.g. in Gnu’s |
|
No, I had not considered multiple long options. Like multi-character short options, they just happened to work. There is an issue open about multiple-character short options, and I'll add a reference to multiple longs: #2307 Hyrum's Law: https://www.hyrumslaw.com
|
|
This PR was released in Commander 13.0 Support for dual long options to allow a short-ish flag was added in Commander 13.1: #2312 |
This PR contains the following updates: | Package | Type | Update | Change | |---|---|---|---| | [commander](https://github.com/tj/commander.js) | devDependencies | major | [`12.1.0` -> `13.0.0`](https://renovatebot.com/diffs/npm/commander/12.1.0/13.0.0) | --- ### Release Notes <details> <summary>tj/commander.js (commander)</summary> ### [`v13.0.0`](https://github.com/tj/commander.js/blob/HEAD/CHANGELOG.md#1300-2024-12-30) [Compare Source](tj/commander.js@v12.1.0...v13.0.0) ##### Added - support multiple calls to `.parse()` with default settings (\[[#​2299](tj/commander.js#2299)]) - add `.saveStateBeforeParse()` and `.restoreStateBeforeParse()` for use by subclasses (\[[#​2299](tj/commander.js#2299)]) - style routines like `styleTitle()` to add color to help using `.configureHelp()` or Help subclass (\[[#​2251](tj/commander.js#2251)]) - color related support in `.configureOutput()` for `getOutHasColors()`, `getErrHasColors()`, and `stripColor()` (\[[#​2251](tj/commander.js#2251)]) - Help property for `minWidthToWrap` (\[[#​2251](tj/commander.js#2251)]) - Help methods for `displayWidth()`, `boxWrap()`, `preformatted()` et al (\[[#​2251](tj/commander.js#2251)]) ##### Changed - *Breaking*: excess command-arguments cause an error by default, see migration tips (\[[#​2223](tj/commander.js#2223)]) - *Breaking*: throw during Option construction for unsupported option flags, like multiple characters after single `-` (\[[#​2270](tj/commander.js#2270)]) - *Breaking*: throw on multiple calls to `.parse()` if `storeOptionsAsProperties: true` (\[[#​2299](tj/commander.js#2299)]) - TypeScript: include implicit `this` in parameters for action handler callback (\[[#​2197](tj/commander.js#2197)]) ##### Deleted - *Breaking*: `Help.wrap()` refactored into `formatItem()` and `boxWrap()` (\[[#​2251](tj/commander.js#2251)]) ##### Migration Tips **Excess command-arguments** It is now an error for the user to specify more command-arguments than are expected. (`allowExcessArguments` is now false by default.) Old code: ```js program.option('-p, --port <number>', 'port number'); program.action((options) => { console.log(program.args); }); ``` Now shows an error: ```console $ node example.js a b c error: too many arguments. Expected 0 arguments but got 3. ``` You can declare the expected arguments. The help will then be more accurate too. Note that declaring new arguments will change what is passed to the action handler. ```js program.option('-p, --port <number>', 'port number'); program.argument('[args...]', 'remote command and arguments'); // expecting zero or more arguments program.action((args, options) => { console.log(args); }); ``` Or you could suppress the error, useful for minimising changes in legacy code. ```js program.option('-p, --port', 'port number'); program.allowExcessArguments(); program.action((options) => { console.log(program.args); }); ``` </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzOS44NC4wIiwidXBkYXRlZEluVmVyIjoiMzkuODQuMCIsInRhcmdldEJyYW5jaCI6Im1haW4iLCJsYWJlbHMiOltdfQ==--> Reviewed-on: https://git.justinelmore.dev/jelmore1674/build-changelog/pulls/38 Reviewed-by: Justin Elmore <jelmore1674@noreply.justinelmore.dev> Co-authored-by: Renovate Bot <renovate-bot@forgejo.justinelmore.dev> Co-committed-by: Renovate Bot <renovate-bot@forgejo.justinelmore.dev>
Pull Request
Problem
People who try and use unsupported Option flags do not get an error, and have to discover themselves that there are problems at runtime.
Placeholder issue: #2235
See: #430 #479 #908 #1718 #1862 #2211 #2222 #2227
Solution
Throw for unsupported Option flags, especially for known issues — too many flags, and short flag with more than one character.
This will break some existing programs that had undetected problems. (It broke one of our tests!)
ChangeLog