feat: add support for showVersion, similar to showHelp (#1831)

docs/api.md

@@ -1522,6 +1522,33 @@ yargs.showHelp(s => myStream.write(s)); //prints to myStream
 
 Later on, `argv` can be retrieved with `yargs.argv`.
 
+.showVersion([consoleLevel | printCallback])
+---------------------------
+
+Print the version data.
+
+If no argument is provided, version data is printed using `console.error`.
+
+```js
+var yargs = require('yargs/yargs')(process.argv.slice(2));
+yargs.version('1.0.0');
+yargs.showVersion(); //prints to stderr using console.error()
+```
+
+If a string is specified, version data is printed using the [`console`](https://nodejs.org/api/console.html) function `consoleLevel`.
+
+```js
+yargs.showVersion("log"); //prints to stdout using console.log()
+```
+
+If a function is specified, it is called with a single argument - the version data as a string.
+
+```js
+yargs.showVersion(s => myStream.write(s)); //prints to myStream
+```
+
+Later on, `argv` can be retrieved with `yargs.argv`.
+
 .showHelpOnFail(enable, [message])
 ----------------------------------
 

lib/usage.ts

@@ -674,9 +674,11 @@ export function usage(yargs: YargsInstance, y18n: Y18N, shim: PlatformShim) {
     version = ver;
   };
 
-  self.showVersion = () => {
+  self.showVersion = level => {
     const logger = yargs._getLoggerInstance();
-    logger.log(version);
+    if (!level) level = 'error';
+    const emit = typeof level === 'function' ? level : logger[level];
+    emit(version);
   };
 
   self.reset = function reset(localLookup) {
@@ -754,9 +756,9 @@ export interface UsageInstance {
   getUsageDisabled(): boolean;
   help(): string;
   reset(localLookup: Dictionary<boolean>): UsageInstance;
-  showHelp(level: 'error' | 'log' | ((message: string) => void)): void;
+  showHelp(level?: 'error' | 'log' | ((message: string) => void)): void;
   showHelpOnFail(enabled?: boolean | string, message?: string): UsageInstance;
-  showVersion(): void;
+  showVersion(level?: 'error' | 'log' | ((message: string) => void)): void;
   stringifiedValues(values?: any[], separator?: string): string;
   unfreeze(): void;
   usage(msg: string | null, description?: string | false): UsageInstance;

lib/yargs-factory.ts

@@ -1346,6 +1346,12 @@ function Yargs(
     return self;
   };
 
+  self.showVersion = function (level) {
+    argsert('[string|function]', [level], arguments.length);
+    usage.showVersion(level);
+    return self;
+  };
+
   let versionOpt: string | null = null;
   self.version = function version(
     opt?: string | false,
@@ -1759,7 +1765,7 @@ function Yargs(
             if (exitProcess) setBlocking(true);
 
             skipValidation = true;
-            usage.showVersion();
+            usage.showVersion('log');
             self.exit(0);
           }
         });
@@ -2175,6 +2181,9 @@ export interface YargsInstance {
   scriptName(scriptName: string): YargsInstance;
   showCompletionScript($0?: string, cmd?: string): YargsInstance;
   showHelp(level: 'error' | 'log' | ((message: string) => void)): YargsInstance;
+  showVersion(
+    level: 'error' | 'log' | ((message: string) => void)
+  ): YargsInstance;
   showHelpOnFail: {
     (message?: string): YargsInstance;
     (enabled: boolean, message: string): YargsInstance;

test/usage.cjs

@@ -3198,6 +3198,41 @@ describe('usage tests', () => {
     });
   });
 
+  describe('showVersion', () => {
+    // see #143.
+    it('should show version regardless of whether argv has been called', () => {
+      const r = checkUsage(() => {
+        const y = yargs().version('1.0.0').wrap(null);
+
+        y.showVersion();
+      });
+
+      r.errors.join('\n').split(/\n+/).should.deep.equal(['1.0.0']);
+    });
+
+    it('should call the correct console.log method when specified', () => {
+      const r = checkUsage(() => {
+        const y = yargs().version('1.0.0').wrap(null);
+
+        y.showVersion('log');
+      });
+
+      r.errors.length.should.eql(0);
+      r.logs.join('\n').split(/\n+/).should.deep.equal(['1.0.0']);
+    });
+
+    it('should call the callback to print when specified', done => {
+      const y = yargs().version('1.0.0').wrap(null);
+
+      y.showVersion(printCallback);
+
+      function printCallback(msg) {
+        msg.split(/\n+/).should.deep.equal(['1.0.0']);
+        return done();
+      }
+    });
+  });
+
   describe('$0', () => {
     function mockProcessArgv(argv, cb) {
       const argvOld = process.argv;