commander - npm Package Compare versions

Comparing version 7.0.0-0 to 7.0.0-1

CHANGELOG.md

@@ -11,2 +11,17 @@ # Changelog
 
+## [7.0.0-1] (2020-11-21)
+
+### Added
+
+- `.createOption()` to support subclassing of automatically created options (like `.createCommand()`) ([#1380])
+- `.configureOutput()` to modify use of stdout and stderr or customise display of errors ([#1387])
+
+### Breaking changes relative to 7.0.0-0
+
+- rework new `Help.wrap()` for simpler usage pattern (#1395)
+- rename new "columns" properties (#1396)
+  - `Help.columns` -> `helpWidth`
+  - `getOutColumns()` -> `getOutHelpWidth()`
+  - `getErrColumns()` -> `getErrHelpWidth()`
+
 ## [7.0.0-0] (2020-10-25)
@@ -205,86 +220,5 @@
 
-## [4.1.1] (2020-02-02)
-
-### Fixed
-
-* TypeScript definition for `.action()` should include Promise for async ([#1157])
-
-## [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])
-
-## [4.0.0] (2019-11-02)
-
-### Added
-
-* automatically wrap and indent help descriptions for options and commands ([#1051])
-* `.exitOverride()` allows override of calls to `process.exit` for additional error handling and to keep program running ([#1040])
-* support for declaring required options with `.requiredOptions()` ([#1071])
-* GitHub Actions support ([#1027])
-* translation links in README
-
-### Changed
-
-* dev: switch tests from Sinon+Should to Jest with major rewrite of tests ([#1035])
-* call default subcommand even when there are unknown options ([#1047])
-* *Breaking* Commander is only officially supported on Node 8 and above, and requires Node 6 ([#1053])
-
-### Fixed
-
-* *Breaking* keep command object out of program.args when action handler called ([#1048])
-  * also, action handler now passed array of unknown arguments
-* complain about unknown options when program argument supplied and action handler ([#1049])
-  * this changes parameters to `command:*` event to include unknown arguments
-* removed deprecated `customFds` option from call to `child_process.spawn` ([#1052])
-* rework TypeScript declarations to bring all types into imported namespace ([#1081])
-
-### Migration Tips
-
-#### Testing for no arguments
-
-If you were previously using code like:
-
-```js
-if (!program.args.length) ...
-```
-
-a partial replacement is:
-
-```js
-if (program.rawArgs.length < 3) ...
-```
-
-## [4.0.0-1] Prerelease (2019-10-08)
-
-(Released in 4.0.0)
-
-## [4.0.0-0] Prerelease (2019-10-01)
-
-(Released in 4.0.0)
-
 ## Older versions
 
+* [4.x](./changelogs/CHANGELOG-4.md)
 * [3.x](./changelogs/CHANGELOG-3.md)
@@ -304,3 +238,2 @@ * [2.x](./changelogs/CHANGELOG-2.md)
 [#802]: https://github.com/tj/commander.js/issues/802
-[#806]: https://github.com/tj/commander.js/issues/806
 [#809]: https://github.com/tj/commander.js/issues/809
@@ -310,20 +243,5 @@ [#948]: https://github.com/tj/commander.js/issues/948
 [#995]: https://github.com/tj/commander.js/issues/995
-[#1027]: https://github.com/tj/commander.js/pull/1027
 [#1032]: https://github.com/tj/commander.js/issues/1032
-[#1035]: https://github.com/tj/commander.js/pull/1035
-[#1040]: https://github.com/tj/commander.js/pull/1040
-[#1047]: https://github.com/tj/commander.js/pull/1047
-[#1048]: https://github.com/tj/commander.js/pull/1048
-[#1049]: https://github.com/tj/commander.js/pull/1049
-[#1051]: https://github.com/tj/commander.js/pull/1051
-[#1052]: https://github.com/tj/commander.js/pull/1052
-[#1053]: https://github.com/tj/commander.js/pull/1053
 [#1062]: https://github.com/tj/commander.js/pull/1062
-[#1071]: https://github.com/tj/commander.js/pull/1071
-[#1081]: https://github.com/tj/commander.js/pull/1081
 [#1088]: https://github.com/tj/commander.js/issues/1088
-[#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
 [#1119]: https://github.com/tj/commander.js/pull/1119
@@ -336,3 +254,2 @@ [#1133]: https://github.com/tj/commander.js/pull/1133
 [#1153]: https://github.com/tj/commander.js/issues/1153
-[#1157]: https://github.com/tj/commander.js/pull/1157
 [#1159]: https://github.com/tj/commander.js/pull/1159
@@ -373,4 +290,7 @@ [#1165]: https://github.com/tj/commander.js/pull/1165
 [#1375]: https://github.com/tj/commander.js/pull/1375
+[#1380]: https://github.com/tj/commander.js/pull/1380
+[#1387]: https://github.com/tj/commander.js/pull/1387
 
 [Unreleased]: https://github.com/tj/commander.js/compare/master...develop
+[7.0.0-1]: https://github.com/tj/commander.js/compare/v7.0.0-0...v7.0.0-1
 [7.0.0-0]: https://github.com/tj/commander.js/compare/v6.2.0...v7.0.0-0
@@ -388,7 +308,1 @@ [6.2.0]: https://github.com/tj/commander.js/compare/v6.1.0..v6.2.0
 [5.0.0-0]: https://github.com/tj/commander.js/compare/v4.1.1..v5.0.0-0
-[4.1.1]: https://github.com/tj/commander.js/compare/v4.1.0..v4.1.1
-[4.1.0]: https://github.com/tj/commander.js/compare/v4.0.1..v4.1.0
-[4.0.1]: https://github.com/tj/commander.js/compare/v4.0.0..v4.0.1
-[4.0.0]: https://github.com/tj/commander.js/compare/v3.0.2..v4.0.0
-[4.0.0-1]: https://github.com/tj/commander.js/compare/v4.0.0-0..v4.0.0-1
-[4.0.0-0]: https://github.com/tj/commander.js/compare/v3.0.2...v4.0.0-0

package.json

 {
   "name": "commander",
-  "version": "7.0.0-0",
+  "version": "7.0.0-1",
   "description": "the complete solution for node.js command-line programs",
@@ -5,0 +5,0 @@ "keywords": [

Readme.md

 # Commander.js
 
-[![Build Status](https://api.travis-ci.org/tj/commander.js.svg?branch=master)](http://travis-ci.org/tj/commander.js)
+[![Build Status](https://github.com/tj/commander.js/workflows/build/badge.svg)](https://github.com/tj/commander.js/actions?query=workflow%3A%22build%22)
 [![NPM Version](http://img.shields.io/npm/v/commander.svg?style=flat)](https://www.npmjs.org/package/commander)
@@ -44,3 +44,3 @@ [![NPM Downloads](https://img.shields.io/npm/dm/commander.svg?style=flat)](https://npmcharts.com/compare/commander?minimal=true)
     - [Debugging stand-alone executable subcommands](#debugging-stand-alone-executable-subcommands)
-    - [Override exit handling](#override-exit-handling)
+    - [Override exit and output handling](#override-exit-and-output-handling)
     - [Additional documentation](#additional-documentation)
@@ -636,3 +636,3 @@ - [Examples](#examples)
 
-- `columns`: specify the wrap width, useful for unit tests
+- `helpWidth`: specify the wrap width, useful for unit tests
 - `sortSubcommands`: sort the subcommands alphabetically
@@ -777,3 +777,3 @@ - `sortOptions`: sort the options alphabetically
 
-### Override exit handling
+### Override exit and output handling
 
@@ -796,2 +796,24 @@ By default Commander calls `process.exit` when it detects errors, or after displaying the help or version. You can override
 
+By default Commander is configured for a command-line application and writes to stdout and stderr.
+You can modify this behaviour for custom applications. In addition, you can modify the display of error messages.
+
+Example file: [configure-output.js](./examples/configure-output.js)
+
+
+```js
+function errorColor(str) {
+  // Add ANSI escape codes to display text in red.
+  return `\x1b[31m${str}\x1b[0m`;
+}
+
+program
+  .configureOutput({
+    // Visibly override write routines as example!
+    writeOut: (str) => process.stdout.write(`[OUT] ${str}`),
+    writeErr: (str) => process.stdout.write(`[ERR] ${str}`),
+    // Highlight errors in color.
+    outputError: (str, write) => write(errorColor(str))
+  });
+```
+
 ### Additional documentation
@@ -798,0 +820,0 @@

typings/index.d.ts

@@ -53,3 +53,3 @@ // Type definitions for commander
      */
-    makeOptionMandatory(value?: boolean): this;
+    makeOptionMandatory(mandatory?: boolean): this;
 
@@ -59,3 +59,3 @@ /**
      */
-    hideHelp(value?: boolean): this;
+    hideHelp(hide?: boolean): this;
 
@@ -81,4 +81,4 @@ /**
   interface Help {
-    /** output columns, long lines are wrapped to fit */
-    columns: number;
+    /** output helpWidth, long lines are wrapped to fit */
+    helpWidth?: number;
     sortSubcommands: boolean;
@@ -118,5 +118,4 @@ sortOptions: boolean;
     /**
-     * Optionally wrap the given str to a max width of width characters per line
-     * while indenting with indent spaces. Do not wrap if insufficient width or
-     * string is manually formatted.
+     * Wrap the given string to width characters per line, with lines after the first indented.
+     * Do not wrap if insufficient room for wrapping, or string is manually formatted.
      */
@@ -141,3 +140,11 @@ wrap(str: string, width: number, indent: number): string;
   }
+  interface OutputConfiguration {
+    writeOut?(str: string): void;
+    writeErr?(str: string): void;
+    getOutHelpWidth?(): number;
+    getErrHelpWidth?(): number;
+    outputError?(str: string, write: (str: string) => void): void;
 
+  }
+
   type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
@@ -258,2 +265,21 @@
     /**
+     * The default output goes to stdout and stderr. You can customise this for special
+     * applications. You can also customise the display of errors by overriding outputError.
+     *
+     * The configuration properties are all functions:
+     *
+     *    // functions to change where being written, stdout and stderr
+     *    writeOut(str)
+     *    writeErr(str)
+     *    // matching functions to specify width for wrapping help
+     *    getOutHelpWidth()
+     *    getErrHelpWidth()
+     *    // functions based on what is being written out
+     *    outputError(str, write) // used for displaying errors, and not used for displaying help
+     */
+    configureOutput(configuration: OutputConfiguration): this;
+    /** Get configuration */
+    configureOutput(): OutputConfiguration;
+
+    /**
      * Register callback `fn` for the command.
@@ -332,2 +358,11 @@ *
     /**
+     * Factory routine to create a new unattached option.
+     *
+     * See .option() for creating an attached option, which uses this routine to
+     * create the option. You can override createOption to return a custom option.
+     */
+
+    createOption(flags: string, description?: string): Option;
+
+    /**
      * Add a prepared Option.
@@ -345,3 +380,3 @@ *
      */
-    storeOptionsAsProperties(value?: boolean): this;
+    storeOptionsAsProperties(storeAsProperties?: boolean): this;
 
@@ -354,3 +389,3 @@ /**
      */
-    passCommandToAction(value?: boolean): this;
+    passCommandToAction(passCommand?: boolean): this;
 
@@ -367,3 +402,3 @@ /**
      */
-    combineFlagAndOptionalValue(arg?: boolean): this;
+    combineFlagAndOptionalValue(combine?: boolean): this;
 
@@ -373,6 +408,5 @@ /**
      *
-     * @param [arg] if `true` or omitted, no error will be thrown for unknown options.
      * @returns `this` command for chaining
      */
-    allowUnknownOption(arg?: boolean): this;
+    allowUnknownOption(allowUnknown?: boolean): this;
 
@@ -503,3 +537,3 @@ /**
      */
-    helpInformation(): string;
+    helpInformation(context?: HelpContext): string;
 
@@ -506,0 +540,0 @@ /**

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

131978

increased by1.28%

Lines of code

2437

increased by3.53%

Number of lines in readme file

875

increased by2.58%

No dependency changes