Skip to content

Commit

Permalink
Merge pull request #1142 from tj/develop
Browse files Browse the repository at this point in the history 
Release 4.1
  • Loading branch information
@abetomo
abetomo authored Jan 6, 2020
2 parents b25cc3a + 1c66935 commit 8e1cdf5
Show file tree
Hide file tree
Showing 21 changed files with 1,083 additions and 407 deletions.
2 changes: 2 additions & 0 deletions .eslintignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# We have not configured eslint for TypeScript so avoid bogus error messages in the test file and typings file.
**/*.ts
3 changes: 2 additions & 1 deletion .eslintrc.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
"rules": {
"one-var": "off",
"semi": ["error", "always"],
"space-before-function-paren": ["error", "never"]
"space-before-function-paren": ["error", "never"],
"no-else-return": ["error", { "allowElseIf": false }]
}
}
171 changes: 30 additions & 141 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,32 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.

<!-- markdownlint-disable MD024 -->

## [4.1.0] (2020-01-06)

### Added

- two routines to change how option values are handled, and eliminate name clashes with command properties ([#933] [#1102])
- see storeOptionsAsProperties and passCommandToAction in README
- `.parseAsync` to use instead of `.parse` if supply async action handlers ([#806] [#1118])

### Fixed

- Remove trailing blanks from wrapped help text ([#1096])

### Changed

- update dependencies
- extend security coverage for Commander 2.x to 2020-02-03
- improvements to README
- improvements to TypeScript definition documentation
- move old versions out of main CHANGELOG
- removed explicit use of `ts-node` in tests

## [4.0.1] (2019-11-12)

### Fixed

* display help when requested, even if there are missing required options [(#1091)]
* display help when requested, even if there are missing required options ([#1091])

## [4.0.0] (2019-11-02)

Expand Down Expand Up @@ -355,152 +376,16 @@ program

* remove input methods (.prompt, .confirm, etc)

## 1.3.2 / 2013-07-18

* add support for sub-commands to co-exist with the original command

## 1.3.1 / 2013-07-18

* add quick .runningCommand hack so you can opt-out of other logic when running a sub command

## 1.3.0 / 2013-07-09

* add EACCES error handling
* fix sub-command --help

## 1.2.0 / 2013-06-13

* allow "-" hyphen as an option argument
* support for RegExp coercion

## 1.1.1 / 2012-11-20

* add more sub-command padding
* fix .usage() when args are present. Closes #106

## 1.1.0 / 2012-11-16

* add git-style executable subcommand support. Closes #94

## 1.0.5 / 2012-10-09

* fix `--name` clobbering. Closes #92
* fix examples/help. Closes #89

## 1.0.4 / 2012-09-03

* add `outputHelp()` method.

## 1.0.3 / 2012-08-30

* remove invalid .version() defaulting

## 1.0.2 / 2012-08-24

* add `--foo=bar` support [arv]
* fix password on node 0.8.8. Make backward compatible with 0.6 [focusaurus]

## 1.0.1 / 2012-08-03

* fix issue #56
* fix tty.setRawMode(mode) was moved to tty.ReadStream#setRawMode() (i.e. process.stdin.setRawMode())

## 1.0.0 / 2012-07-05

* add support for optional option descriptions
* add defaulting of `.version()` to package.json's version

## 0.6.1 / 2012-06-01

* Added: append (yes or no) on confirmation
* Added: allow node.js v0.7.x

## 0.6.0 / 2012-04-10

* Added `.prompt(obj, callback)` support. Closes #49
* Added default support to .choose(). Closes #41
* Fixed the choice example

## 0.5.1 / 2011-12-20

* Fixed `password()` for recent nodes. Closes #36

## 0.5.0 / 2011-12-04

* Added sub-command option support [itay]

## 0.4.3 / 2011-12-04

* Fixed custom help ordering. Closes #32

## 0.4.2 / 2011-11-24

* Added travis support
* Fixed: line-buffered input automatically trimmed. Closes #31

## 0.4.1 / 2011-11-18

* Removed listening for "close" on --help

## 0.4.0 / 2011-11-15

* Added support for `--`. Closes #24

## 0.3.3 / 2011-11-14

* Fixed: wait for close event when writing help info [Jerry Hamlet]

## 0.3.2 / 2011-11-01

* Fixed long flag definitions with values [felixge]

## 0.3.1 / 2011-10-31

* Changed `--version` short flag to `-V` from `-v`
* Changed `.version()` so it's configurable [felixge]

## 0.3.0 / 2011-10-31

* Added support for long flags only. Closes #18

## 0.2.1 / 2011-10-24

* "node": ">= 0.4.x < 0.7.0". Closes #20

## 0.2.0 / 2011-09-26

* Allow for defaults that are not just boolean. Default peassignment only occurs for --no-*, optional, and required arguments. [Jim Isaacs]

## 0.1.0 / 2011-08-24

* Added support for custom `--help` output

## 0.0.5 / 2011-08-18

* Changed: when the user enters nothing prompt for password again
* Fixed issue with passwords beginning with numbers [NuckChorris]

## 0.0.4 / 2011-08-15

* Fixed `Commander#args`

## 0.0.3 / 2011-08-15

* Added default option value support

## 0.0.2 / 2011-08-15

* Added mask support to `Command#password(str[, mask], fn)`
* Added `Command#password(str, fn)`

## 0.0.1 / 2010-01-03
## Older versions

* Initial release
* [1.x](./changelogs/CHANGELOG-1.md)
* [0.x](./changelogs/CHANGELOG-0.md)

[#599]: https://github.com/tj/commander.js/issues/599
[#611]: https://github.com/tj/commander.js/issues/611
[#697]: https://github.com/tj/commander.js/issues/697
[#795]: https://github.com/tj/commander.js/issues/795
[#806]: https://github.com/tj/commander.js/issues/806
[#915]: https://github.com/tj/commander.js/issues/915
[#938]: https://github.com/tj/commander.js/issues/938
[#963]: https://github.com/tj/commander.js/issues/963
Expand All @@ -509,6 +394,7 @@ program
[#987]: https://github.com/tj/commander.js/issues/987
[#990]: https://github.com/tj/commander.js/issues/990
[#991]: https://github.com/tj/commander.js/issues/991
[#993]: https://github.com/tj/commander.js/issues/993
[#999]: https://github.com/tj/commander.js/issues/999
[#1010]: https://github.com/tj/commander.js/pull/1010
[#1018]: https://github.com/tj/commander.js/pull/1018
Expand All @@ -526,6 +412,9 @@ program
[#1071]: https://github.com/tj/commander.js/pull/1071
[#1081]: https://github.com/tj/commander.js/pull/1081
[#1091]: https://github.com/tj/commander.js/pull/1091
[#1096]: https://github.com/tj/commander.js/pull/1096
[#1102]: https://github.com/tj/commander.js/pull/1102
[#1118]: https://github.com/tj/commander.js/pull/1118

[Unreleased]: https://github.com/tj/commander.js/compare/master...develop
[4.0.1]: https://github.com/tj/commander.js/compare/v4.0.0..v4.0.1
Expand Down
60 changes: 57 additions & 3 deletions Readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)

- [Commander.js](#commanderjs)
- [Installation](#installation)
- [Declaring _program_ variable](#declaring-program-variable)
- [Declaring program variable](#declaring-program-variable)
- [Options](#options)
- [Common option types, boolean and value](#common-option-types-boolean-and-value)
- [Default option value](#default-option-value)
Expand All @@ -31,8 +31,9 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
- [.help(cb)](#helpcb)
- [Custom event listeners](#custom-event-listeners)
- [Bits and pieces](#bits-and-pieces)
- [Avoiding option name clashes](#avoiding-option-name-clashes)
- [TypeScript](#typescript)
- [Node options such as `--harmony`](#node-options-such-as---harmony)
- [Node options such as --harmony](#node-options-such-as---harmony)
- [Node debugging](#node-debugging)
- [Override exit handling](#override-exit-handling)
- [Examples](#examples)
Expand Down Expand Up @@ -70,6 +71,8 @@ Options are defined with the `.option()` method, also serving as documentation f

The options can be accessed as properties on the Command object. Multi-word options such as "--template-engine" are camel-cased, becoming `program.templateEngine` etc. Multiple short flags may be combined as a single arg, for example `-abc` is equivalent to `-a -b -c`.

See also optional new behaviour to [avoid name clashes](#avoiding-option-name-clashes).

### Common option types, boolean and value

The two most used option types are a boolean flag, and an option which takes a value (declared using angle brackets). Both are `undefined` unless specified on command line.
Expand Down Expand Up @@ -374,6 +377,19 @@ program
program.parse(process.argv)
```

You may supply an `async` action handler, in which case you call `.parseAsync` rather than `.parse`.

```js
async function run() { /* code goes here */ }

async function main() {
program
.command('run')
.action(run);
await program.parseAsync(process.argv);
}
```

A command's options on the command line are validated when the command is used. Any unknown options will be reported as an error. However, if an action-based command does not define an action, then the options are not validated.

Configuration options can be passed with the call to `.command()`. Specifying `true` for `opts.noHelp` will remove the command from the generated help output.
Expand Down Expand Up @@ -550,6 +566,43 @@ program.on('command:*', function () {

## Bits and pieces

### Avoiding option name clashes

The original and default behaviour is that the option values are stored
as properties on the program, and the action handler is passed a
command object with the options values stored as properties.
This is very convenient to code, but the downside is possible clashes with
existing properties of Command.

There are two new routines to change the behaviour, and the default behaviour may change in the future:

- `storeOptionsAsProperties`: whether to store option values as properties on command object, or store separately (specify false) and access using `.opts()`
- `passCommandToAction`: whether to pass command to action handler,
or just the options (specify false)

```js
// file: ./examples/storeOptionsAsProperties.action.js
program
.storeOptionsAsProperties(false)
.passCommandToAction(false);

program
.name('my-program-name')
.option('-n,--name <name>');

program
.command('show')
.option('-a,--action <action>')
.action((options) => {
console.log(options.action);
});

program.parse(process.argv);

const programOptions = program.opts();
console.log(programOptions.name);
```

### TypeScript

The Commander package includes its TypeScript Definition file, but also requires the node types which you need to install yourself. e.g.
Expand Down Expand Up @@ -648,7 +701,8 @@ More Demos can be found in the [examples](https://github.com/tj/commander.js/tre

## Support

Commander is supported on Node 8 and above. (Commander is likely to still work on older versions of Node, but is not tested below Node 8.)
Commander 4.x is supported on Node 8 and above, and is likely to work with Node 6 but not tested.
(For versions of Node below Node 6, use Commander 3.x or 2.x.)

The main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.

Expand Down
Loading

0 comments on commit 8e1cdf5

Please sign in to comment.