diff --git a/docs/api.md b/docs/api.md index 2440dd318..72231584e 100644 --- a/docs/api.md +++ b/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]) ---------------------------------- diff --git a/lib/usage.ts b/lib/usage.ts index 93f982fa0..5b4989674 100644 --- a/lib/usage.ts +++ b/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): 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; diff --git a/lib/yargs-factory.ts b/lib/yargs-factory.ts index 7a9185928..1c12740a8 100644 --- a/lib/yargs-factory.ts +++ b/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; diff --git a/test/usage.cjs b/test/usage.cjs index d914bb7c1..d0345f255 100644 --- a/test/usage.cjs +++ b/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;