feat(): add examples

docs/api.md

@@ -766,12 +766,23 @@ var argv = require('yargs')
 
 .example(cmd, desc)
 -------------------
+.example(exampleArray)
+-------------------
 
 Give some example invocations of your program. Inside `cmd`, the string
 `$0` will get interpolated to the current script name or node command for the
 present script similar to how `$0` works in bash or perl.
 Examples will be printed out as part of the help message.
 
+If you want to add multiple examples at once, just pass an array of examples, e.g
+```js
+require('yargs')
+  .example([
+    ['$0 --config "~/config.json"', 'Use custom config'],
+    ['$0 --safe', 'Start in safe mode']
+  ]);
+```
+
 <a name="exitprocess"></a>.exitProcess(enable)
 ----------------------------------
 

lib/yargs.ts

@@ -451,9 +451,15 @@ export function Yargs (processArgs: string | string[] = [], cwd = process.cwd(),
     return self
   }
 
-  self.example = function (cmd, description) {
-    argsert('<string> [string]', [cmd, description], arguments.length)
-    usage.example(cmd, description)
+  self.example = function (cmd: string | [string, string?][], description?: string) {
+    argsert('<string|array> [string]', [cmd, description], arguments.length)
+
+    if (Array.isArray(cmd)) {
+      cmd.forEach((exampleParams) => self.example(...exampleParams))
+    } else {
+      usage.example(cmd, description)
+    }
+
     return self
   }
 
@@ -1490,7 +1496,7 @@ export interface YargsInstance {
   env (prefix?: string | false): YargsInstance
   epilog: YargsInstance['epilogue']
   epilogue (msg: string): YargsInstance
-  example (cmd: string, description?: string): YargsInstance
+  example (cmd: string | [string, string?][], description?: string): YargsInstance
   exit (code: number, err?: YError | string): void
   exitProcess (enabled: boolean): YargsInstance
   fail (f: FailureFunction): YargsInstance

test/usage.js

@@ -1084,6 +1084,33 @@ describe('usage tests', () => {
     ])
   })
 
+  it('should display examples on fail when passing multiple examples at once', () => {
+    const r = checkUsage(() => yargs('')
+      .example([
+        ['$0 something', 'description'],
+        ['$0 something else', 'other description']
+      ])
+      .demand(['y'])
+      .wrap(null)
+      .parse()
+    )
+    r.should.have.property('result')
+    r.result.should.have.property('_').with.length(0)
+    r.should.have.property('errors')
+    r.should.have.property('logs').with.length(0)
+    r.should.have.property('exit').and.equal(true)
+    r.errors.join('\n').split(/\n+/).should.deep.equal([
+      'Options:',
+      '  --help     Show help  [boolean]',
+      '  --version  Show version number  [boolean]',
+      '  -y  [required]',
+      'Examples:',
+      '  usage something       description',
+      '  usage something else  other description',
+      'Missing required argument: y'
+    ])
+  })
+
   describe('demand option with boolean flag', () => {
     describe('with demand option', () => {
       it('should report missing required arguments', () => {