Repository: yargs/yargs
Pull request #958 (2017-09-18 15:39:51)

feat: multiple usage calls are now collected, not replaced
Feature request #888 

bcoe: @Morishiri thanks for this contribution at first glance this looks really solid.

Patch:
diff --git a/lib/usage.js b/lib/usage.js
index 47cbf75..16c4b19 100644
--- a/lib/usage.js
+++ b/lib/usage.js
@@ -64,11 +64,21 @@ module.exports = function usage (yargs, y18n) {
   }
 
   // methods for ouputting/building help (usage) message.
-  let usage
+  let usages = []
+  let usageDisabled = false
   self.usage = (msg) => {
-    usage = msg
+    if (msg === null) {
+      usageDisabled = true
+      usages = []
+      return
+    }
+    usageDisabled = false
+    usages.push(msg)
+  }
+  self.getUsage = () => {
+    if (usageDisabled) return null
+    return usages.reduce((usageMsg, msg) => `${usageMsg}${msg}\n`, '') || undefined
   }
-  self.getUsage = () => usage
 
   let examples = []
   self.example = (cmd, description) => {
@@ -151,9 +161,9 @@ module.exports = function usage (yargs, y18n) {
     })
 
     // the usage string.
-    if (usage) {
-      const u = usage.replace(/\$0/g, yargs.$0)
-      ui.div(`${u}\n`)
+    if (usages.length && !usageDisabled) {
+      const u = self.getUsage().replace(/\$0/g, yargs.$0)
+      ui.div(`${u}`)
     }
 
     // your application's commands, i.e., non-option
@@ -435,7 +445,8 @@ module.exports = function usage (yargs, y18n) {
     // do not reset fails here
     failMessage = null
     failureOutput = false
-    usage = undefined
+    usages = []
+    usageDisabled = false
     epilog = undefined
     examples = []
     commands = []
@@ -448,7 +459,8 @@ module.exports = function usage (yargs, y18n) {
     frozen = {}
     frozen.failMessage = failMessage
     frozen.failureOutput = failureOutput
-    frozen.usage = usage
+    frozen.usages = usages
+    frozen.usageDisabled = usageDisabled
     frozen.epilog = epilog
     frozen.examples = examples
     frozen.commands = commands
@@ -457,7 +469,8 @@ module.exports = function usage (yargs, y18n) {
   self.unfreeze = function unfreeze () {
     failMessage = frozen.failMessage
     failureOutput = frozen.failureOutput
-    usage = frozen.usage
+    usages = frozen.usages
+    usageDisabled = frozen.usageDisabled
     epilog = frozen.epilog
     examples = frozen.examples
     commands = frozen.commands


Test patch:
diff --git a/test/usage.js b/test/usage.js
index 8b5c3dc..5ed522f 100644
--- a/test/usage.js
+++ b/test/usage.js
@@ -1817,6 +1817,39 @@ describe('usage tests', () => {
         ''
       ])
     })
+
+    it('allows a builder to add more than one usage with mutiple usage calls', () => {
+      const r = checkUsage(() => yargs('upload --help')
+        .command('upload', 'upload something', yargs => yargs.usage('$0 upload [something]').usage('$0 upload [something else]'), (argv) => {})
+        .wrap(null)
+        .argv
+      )
+
+      r.logs[0].split('\n').should.deep.equal([
+        './usage upload [something]',
+        './usage upload [something else]',
+        '',
+        'Options:',
+        '  --help     Show help  [boolean]',
+        '  --version  Show version number  [boolean]',
+        ''
+      ])
+    })
+
+    it('allows a builder to disable usage with null after mutiple usage calls', () => {
+      const r = checkUsage(() => yargs('upload --help')
+        .command('upload', 'upload something', yargs => yargs.usage('$0 upload [something]').usage('$0 upload [something else]').usage(null), (argv) => {})
+        .wrap(null)
+        .argv
+      )
+
+      r.logs[0].split('\n').should.deep.equal([
+        'Options:',
+        '  --help     Show help  [boolean]',
+        '  --version  Show version number  [boolean]',
+        ''
+      ])
+    })
   })
 
   describe('epilogue', () => {