yargs 13.3.2 → 14.2.1

package/CHANGELOG.md

@@ -2,6 +2,71 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [14.2.1](https://github.com/yargs/yargs/compare/v14.2.0...v14.2.1) (2019-10-30)
+
+
+### Bug Fixes
+
+* stop-parse was not being respected by commands ([#1459](https://github.com/yargs/yargs/issues/1459)) ([e78e76e](https://github.com/yargs/yargs/commit/e78e76e3ac0551d4f30c71a05ddb21582960fcef))
+
+## [14.2.0](https://github.com/yargs/yargs/compare/v14.1.0...v14.2.0) (2019-10-07)
+
+
+### Bug Fixes
+
+* async middleware was called twice ([#1422](https://github.com/yargs/yargs/issues/1422)) ([9a42b63](https://github.com/yargs/yargs/commit/9a42b63))
+* fix promise check to accept any spec conform object ([#1424](https://github.com/yargs/yargs/issues/1424)) ([0be43d2](https://github.com/yargs/yargs/commit/0be43d2))
+* groups were not being maintained for nested commands ([#1430](https://github.com/yargs/yargs/issues/1430)) ([d38650e](https://github.com/yargs/yargs/commit/d38650e))
+* **docs:** broken markdown link ([#1426](https://github.com/yargs/yargs/issues/1426)) ([236e24e](https://github.com/yargs/yargs/commit/236e24e))
+* support merging deeply nested configuration ([#1423](https://github.com/yargs/yargs/issues/1423)) ([bae66fe](https://github.com/yargs/yargs/commit/bae66fe))
+
+
+### Features
+
+* **deps:** introduce yargs-parser with support for unknown-options-as-args ([#1440](https://github.com/yargs/yargs/issues/1440)) ([4d21520](https://github.com/yargs/yargs/commit/4d21520))
+
+## [14.1.0](https://github.com/yargs/yargs/compare/v14.0.0...v14.1.0) (2019-09-06)
+
+
+### Bug Fixes
+
+* **docs:** fix incorrect parserConfiguration documentation ([2a99124](https://github.com/yargs/yargs/commit/2a99124))
+* detect zsh when zsh isnt run as a login prompt ([#1395](https://github.com/yargs/yargs/issues/1395)) ([8792d13](https://github.com/yargs/yargs/commit/8792d13))
+* populate correct value on yargs.parsed and stop warning on access ([#1412](https://github.com/yargs/yargs/issues/1412)) ([bb0eb52](https://github.com/yargs/yargs/commit/bb0eb52))
+* showCompletionScript was logging script twice ([#1388](https://github.com/yargs/yargs/issues/1388)) ([07c8537](https://github.com/yargs/yargs/commit/07c8537))
+* strict() should not ignore hyphenated arguments ([#1414](https://github.com/yargs/yargs/issues/1414)) ([b774b5e](https://github.com/yargs/yargs/commit/b774b5e))
+* **docs:** formalize existing callback argument to showHelp ([#1386](https://github.com/yargs/yargs/issues/1386)) ([d217764](https://github.com/yargs/yargs/commit/d217764))
+
+
+### Features
+
+* make it possible to merge configurations when extending other config. ([#1411](https://github.com/yargs/yargs/issues/1411)) ([5d7ad98](https://github.com/yargs/yargs/commit/5d7ad98))
+
+## [14.0.0](https://github.com/yargs/yargs/compare/v13.3.0...v14.0.0) (2019-07-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* we now only officially support yargs.$0 parameter and discourage direct access to yargs.parsed
+* previously to this fix methods like `yargs.getOptions()` contained the state of the last command to execute.
+* do not allow additional positionals in strict mode
+
+### Bug Fixes
+
+* calling parse multiple times now appropriately maintains state ([#1137](https://github.com/yargs/yargs/issues/1137)) ([#1369](https://github.com/yargs/yargs/issues/1369)) ([026b151](https://github.com/yargs/yargs/commit/026b151))
+* prefer user supplied script name in usage ([#1383](https://github.com/yargs/yargs/issues/1383)) ([28c74b9](https://github.com/yargs/yargs/commit/28c74b9))
+* **deps:** use decamelize from npm instead of vendored copy ([#1377](https://github.com/yargs/yargs/issues/1377)) ([015eeb9](https://github.com/yargs/yargs/commit/015eeb9))
+* **examples:** fix usage-options.js to reflect current API ([#1375](https://github.com/yargs/yargs/issues/1375)) ([6e5b76b](https://github.com/yargs/yargs/commit/6e5b76b))
+* do not allow additional positionals in strict mode ([35d777c](https://github.com/yargs/yargs/commit/35d777c))
+* properties accessed on singleton now reflect current state of instance ([#1366](https://github.com/yargs/yargs/issues/1366)) ([409d35b](https://github.com/yargs/yargs/commit/409d35b))
+* tolerate null prototype for config objects with `extends` ([#1376](https://github.com/yargs/yargs/issues/1376)) ([3d26d11](https://github.com/yargs/yargs/commit/3d26d11)), closes [#1372](https://github.com/yargs/yargs/issues/1372)
+* yargs.parsed now populated before returning, when yargs.parse() called with no args (#1382) ([e3981fd](https://github.com/yargs/yargs/commit/e3981fd)), closes [#1382](https://github.com/yargs/yargs/issues/1382)
+
+### Features
+
+* adds support for multiple epilog messages ([#1384](https://github.com/yargs/yargs/issues/1384)) ([07a5554](https://github.com/yargs/yargs/commit/07a5554))
+* allow completionCommand to be set via showCompletionScript ([#1385](https://github.com/yargs/yargs/issues/1385)) ([5562853](https://github.com/yargs/yargs/commit/5562853))
+
 ## [13.3.0](https://www.github.com/yargs/yargs/compare/v13.2.4...v13.3.0) (2019-06-10)
 
 

package/README.md

@@ -5,6 +5,7 @@
 <p align="center">
   <b >Yargs be a node.js library fer hearties tryin' ter parse optstrings</b>
 </p>
+
 <br>
 
 [![Build Status][travis-image]][travis-url]
@@ -15,7 +16,7 @@
 [![Slack][slack-image]][slack-url]
 
 ## Description :
-Yargs helps you build interactive command line tools, by parsing arguments and generating an elegant user interface. 
+Yargs helps you build interactive command line tools, by parsing arguments and generating an elegant user interface.
 
 It gives you:
 
@@ -79,13 +80,24 @@ require('yargs') // eslint-disable-line
   })
   .option('verbose', {
     alias: 'v',
-    default: false
+    type: 'boolean',
+    description: 'Run with verbose logging'
   })
   .argv
 ```
 
 Run the example above with `--help` to see the help for the application.
 
+## TypeScript
+
+yargs has type definitions at [@types/yargs][type-definitions].
+
+```
+npm i @types/yargs --save-dev
+```
+
+See usage examples in [docs](/docs/typescript.md).
+
 ## Community :
 
 Having problems? want to contribute? join our [community slack](http://devtoolscommunity.herokuapp.com).
@@ -102,6 +114,7 @@ Having problems? want to contribute? join our [community slack](http://devtoolsc
   * [Numbers](/docs/tricks.md#numbers)
   * [Arrays](/docs/tricks.md#arrays)
   * [Objects](/docs/tricks.md#objects)
+  * [Quotes](/docs/tricks.md#quotes)
 * [Advanced Topics](/docs/advanced.md)
   * [Composing Your App Using Commands](/docs/advanced.md#commands)
   * [Building Configurable CLI Apps](/docs/advanced.md#configuration)
@@ -120,3 +133,4 @@ Having problems? want to contribute? join our [community slack](http://devtoolsc
 [conventional-commits-url]: https://conventionalcommits.org/
 [slack-image]: http://devtoolscommunity.herokuapp.com/badge.svg
 [slack-url]: http://devtoolscommunity.herokuapp.com
+[type-definitions]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/yargs

package/index.js

@@ -25,8 +25,15 @@ function singletonify (inst) {
   Object.keys(inst).forEach((key) => {
     if (key === 'argv') {
       Argv.__defineGetter__(key, inst.__lookupGetter__(key))
+    } else if (typeof inst[key] === 'function') {
+      Argv[key] = inst[key].bind(inst)
     } else {
-      Argv[key] = typeof inst[key] === 'function' ? inst[key].bind(inst) : inst[key]
+      Argv.__defineGetter__('$0', () => {
+        return inst.$0
+      })
+      Argv.__defineGetter__('parsed', () => {
+        return inst.parsed
+      })
     }
   })
 }

package/lib/apply-extends.js

@@ -16,10 +16,24 @@ function getPathToDefaultConfig (cwd, pathToExtend) {
   return path.resolve(cwd, pathToExtend)
 }
 
-function applyExtends (config, cwd) {
+function mergeDeep (config1, config2) {
+  const target = {}
+  const isObject = obj => obj && typeof obj === 'object' && !Array.isArray(obj)
+  Object.assign(target, config1)
+  for (let key of Object.keys(config2)) {
+    if (isObject(config2[key]) && isObject(target[key])) {
+      target[key] = mergeDeep(config1[key], config2[key])
+    } else {
+      target[key] = config2[key]
+    }
+  }
+  return target
+}
+
+function applyExtends (config, cwd, mergeExtends) {
   let defaultConfig = {}
 
-  if (config.hasOwnProperty('extends')) {
+  if (Object.prototype.hasOwnProperty.call(config, 'extends')) {
     if (typeof config.extends !== 'string') return defaultConfig
     const isPath = /\.json|\..*rc$/.test(config.extends)
     let pathToDefault = null
@@ -42,12 +56,12 @@ function applyExtends (config, cwd) {
 
     defaultConfig = isPath ? JSON.parse(fs.readFileSync(pathToDefault, 'utf8')) : require(config.extends)
     delete config.extends
-    defaultConfig = applyExtends(defaultConfig, path.dirname(pathToDefault))
+    defaultConfig = applyExtends(defaultConfig, path.dirname(pathToDefault), mergeExtends)
   }
 
   previouslyVisitedConfigs = []
 
-  return Object.assign({}, defaultConfig, config)
+  return mergeExtends ? mergeDeep(defaultConfig, config) : Object.assign({}, defaultConfig, config)
 }
 
 module.exports = applyExtends

package/lib/command.js

@@ -174,7 +174,7 @@ module.exports = function command (yargs, usage, validation, globalMiddleware) {
     let numFiles = currentContext.files.length
     const parentCommands = currentContext.commands.slice()
 
-    // what does yargs look like after the buidler is run?
+    // what does yargs look like after the builder is run?
     let innerArgv = parsed.argv
     let innerYargs = null
     let positionalMap = {}
@@ -186,24 +186,17 @@ module.exports = function command (yargs, usage, validation, globalMiddleware) {
       // a function can be provided, which builds
       // up a yargs chain and possibly returns it.
       innerYargs = commandHandler.builder(yargs.reset(parsed.aliases))
-      // if the builder function did not yet parse argv with reset yargs
-      // and did not explicitly set a usage() string, then apply the
-      // original command string as usage() for consistent behavior with
-      // options object below.
-      if (yargs.parsed === false) {
-        if (shouldUpdateUsage(yargs)) {
-          yargs.getUsageInstance().usage(
-            usageFromParentCommandsCommandHandler(parentCommands, commandHandler),
-            commandHandler.description
-          )
-        }
-        innerArgv = innerYargs ? innerYargs._parseArgs(null, null, true, commandIndex) : yargs._parseArgs(null, null, true, commandIndex)
-      } else {
-        innerArgv = yargs.parsed.argv
+      if (!innerYargs || (typeof innerYargs._parseArgs !== 'function')) {
+        innerYargs = yargs
       }
-
-      if (innerYargs && yargs.parsed === false) aliases = innerYargs.parsed.aliases
-      else aliases = yargs.parsed.aliases
+      if (shouldUpdateUsage(innerYargs)) {
+        innerYargs.getUsageInstance().usage(
+          usageFromParentCommandsCommandHandler(parentCommands, commandHandler),
+          commandHandler.description
+        )
+      }
+      innerArgv = innerYargs._parseArgs(null, null, true, commandIndex)
+      aliases = innerYargs.parsed.aliases
     } else if (typeof commandHandler.builder === 'object') {
       // as a short hand, an object can instead be provided, specifying
       // the options that a command takes.
@@ -234,17 +227,28 @@ module.exports = function command (yargs, usage, validation, globalMiddleware) {
 
     if (commandHandler.handler && !yargs._hasOutput()) {
       yargs._setHasOutput()
+      // to simplify the parsing of positionals in commands,
+      // we temporarily populate '--' rather than _, with arguments
+      const populateDoubleDash = !!yargs.getOptions().configuration['populate--']
+      if (!populateDoubleDash) yargs._copyDoubleDash(innerArgv)
 
       innerArgv = applyMiddleware(innerArgv, yargs, middlewares, false)
-
-      const handlerResult = isPromise(innerArgv)
-        ? innerArgv.then(argv => commandHandler.handler(argv))
-        : commandHandler.handler(innerArgv)
+      let handlerResult
+      if (isPromise(innerArgv)) {
+        handlerResult = innerArgv.then(argv => commandHandler.handler(argv))
+      } else {
+        handlerResult = commandHandler.handler(innerArgv)
+      }
 
       if (isPromise(handlerResult)) {
-        handlerResult.catch(error =>
-          yargs.getUsageInstance().fail(null, error)
-        )
+        yargs.getUsageInstance().cacheHelpMessage()
+        handlerResult.catch(error => {
+          try {
+            yargs.getUsageInstance().fail(null, error)
+          } catch (err) {
+            // fail's throwing would cause an unhandled rejection.
+          }
+        })
       }
     }
 
@@ -348,7 +352,12 @@ module.exports = function command (yargs, usage, validation, globalMiddleware) {
     // short-circuit parse.
     if (!unparsed.length) return
 
-    const parsed = Parser.detailed(unparsed, options)
+    const config = Object.assign({}, options.configuration, {
+      'populate--': true
+    })
+    const parsed = Parser.detailed(unparsed, Object.assign({}, options, {
+      configuration: config
+    }))
 
     if (parsed.error) {
       yargs.getUsageInstance().fail(parsed.error.message, parsed.error)
@@ -419,18 +428,19 @@ module.exports = function command (yargs, usage, validation, globalMiddleware) {
   // the state of commands such that
   // we can apply .parse() multiple times
   // with the same yargs instance.
-  let frozen
+  let frozens = []
   self.freeze = () => {
-    frozen = {}
+    let frozen = {}
+    frozens.push(frozen)
     frozen.handlers = handlers
     frozen.aliasMap = aliasMap
     frozen.defaultCommand = defaultCommand
   }
   self.unfreeze = () => {
+    let frozen = frozens.pop()
     handlers = frozen.handlers
     aliasMap = frozen.aliasMap
     defaultCommand = frozen.defaultCommand
-    frozen = undefined
   }
 
   return self

package/lib/completion.js

@@ -8,7 +8,8 @@ module.exports = function completion (yargs, usage, command) {
     completionKey: 'get-yargs-completions'
   }
 
-  const zshShell = process.env.SHELL && process.env.SHELL.indexOf('zsh') !== -1
+  const zshShell = (process.env.SHELL && process.env.SHELL.indexOf('zsh') !== -1) ||
+    (process.env.ZSH_NAME && process.env.ZSH_NAME.indexOf('zsh') !== -1)
   // get a list of completion commands.
   // 'args' is the array of strings from the line to be completed
   self.getCompletion = function getCompletion (args, done) {

package/lib/is-promise.js

@@ -1,3 +1,3 @@
 module.exports = function isPromise (maybePromise) {
-  return maybePromise instanceof Promise
+  return !!maybePromise && !!maybePromise.then && (typeof maybePromise.then === 'function')
 }

package/lib/middleware.js

@@ -40,8 +40,7 @@ function applyMiddleware (argv, yargs, middlewares, beforeValidation) {
   const beforeValidationError = new Error('middleware cannot return a promise when applyBeforeValidation is true')
   return middlewares
     .reduce((accumulation, middleware) => {
-      if (middleware.applyBeforeValidation !== beforeValidation &&
-          !isPromise(accumulation)) {
+      if (middleware.applyBeforeValidation !== beforeValidation) {
         return accumulation
       }
 

package/lib/usage.js

@@ -1,7 +1,7 @@
 'use strict'
 // this file handles outputting usage instructions,
 // failures, etc. keeps logging in one place.
-const decamelize = require('./decamelize')
+const decamelize = require('decamelize')
 const stringWidth = require('string-width')
 const objFilter = require('./obj-filter')
 const path = require('path')
@@ -122,9 +122,9 @@ module.exports = function usage (yargs, y18n) {
   }
   self.getDescriptions = () => descriptions
 
-  let epilog
+  let epilogs = []
   self.epilog = (msg) => {
-    epilog = msg
+    epilogs.push(msg)
   }
 
   let wrapSet = false
@@ -148,10 +148,11 @@ module.exports = function usage (yargs, y18n) {
 
   const defaultGroup = 'Options:'
   self.help = function help () {
+    if (cachedHelpMessage) return cachedHelpMessage
     normalizeAliases()
 
     // handle old demanded API
-    const base$0 = path.basename(yargs.$0)
+    const base$0 = yargs.customScriptName ? yargs.$0 : path.basename(yargs.$0)
     const demandedOptions = yargs.getDemandedOptions()
     const demandedCommands = yargs.getDemandedCommands()
     const groups = yargs.getGroups()
@@ -345,8 +346,8 @@ module.exports = function usage (yargs, y18n) {
     }
 
     // the usage string.
-    if (epilog) {
-      const e = epilog.replace(/\$0/g, base$0)
+    if (epilogs.length > 0) {
+      const e = epilogs.map(epilog => epilog.replace(/\$0/g, base$0)).join('\n')
       ui.div(`${e}\n`)
     }
 
@@ -403,6 +404,13 @@ module.exports = function usage (yargs, y18n) {
     })
   }
 
+  // if yargs is executing an async handler, we take a snapshot of the
+  // help message to display on failure:
+  let cachedHelpMessage
+  self.cacheHelpMessage = function () {
+    cachedHelpMessage = this.help()
+  }
+
   // given a set of keys, place any keys that are
   // ungrouped under the 'Options:' grouping.
   function addUngroupedKeys (keys, aliases, groups) {
@@ -505,35 +513,36 @@ module.exports = function usage (yargs, y18n) {
     failureOutput = false
     usages = []
     usageDisabled = false
-    epilog = undefined
+    epilogs = []
     examples = []
     commands = []
     descriptions = objFilter(descriptions, (k, v) => !localLookup[k])
     return self
   }
 
-  let frozen
+  let frozens = []
   self.freeze = function freeze () {
-    frozen = {}
+    let frozen = {}
+    frozens.push(frozen)
     frozen.failMessage = failMessage
     frozen.failureOutput = failureOutput
     frozen.usages = usages
     frozen.usageDisabled = usageDisabled
-    frozen.epilog = epilog
+    frozen.epilogs = epilogs
     frozen.examples = examples
     frozen.commands = commands
     frozen.descriptions = descriptions
   }
   self.unfreeze = function unfreeze () {
+    let frozen = frozens.pop()
     failMessage = frozen.failMessage
     failureOutput = frozen.failureOutput
     usages = frozen.usages
     usageDisabled = frozen.usageDisabled
-    epilog = frozen.epilog
+    epilogs = frozen.epilogs
     examples = frozen.examples
     commands = frozen.commands
     descriptions = frozen.descriptions
-    frozen = undefined
   }
 
   return self

package/lib/validation.js

@@ -96,13 +96,13 @@ module.exports = function validation (yargs, usage, y18n) {
       if (specialKeys.indexOf(key) === -1 &&
         !positionalMap.hasOwnProperty(key) &&
         !yargs._getParseContext().hasOwnProperty(key) &&
-        !aliases.hasOwnProperty(key)
+        !self.isValidAndSomeAliasIsNotNew(key, aliases)
       ) {
         unknown.push(key)
       }
     })
 
-    if (commandKeys.length > 0) {
+    if ((currentContext.commands.length > 0) || (commandKeys.length > 0)) {
       argv._.slice(currentContext.commands.length).forEach((key) => {
         if (commandKeys.indexOf(key) === -1) {
           unknown.push(key)
@@ -120,6 +120,21 @@ module.exports = function validation (yargs, usage, y18n) {
     }
   }
 
+  // check for a key that is not an alias, or for which every alias is new,
+  // implying that it was invented by the parser, e.g., during camelization
+  self.isValidAndSomeAliasIsNotNew = function isValidAndSomeAliasIsNotNew (key, aliases) {
+    if (!aliases.hasOwnProperty(key)) {
+      return false
+    }
+    const newAliases = yargs.parsed.newAliases
+    for (let a of [key, ...aliases[key]]) {
+      if (!newAliases.hasOwnProperty(a) || !newAliases[key]) {
+        return true
+      }
+    }
+    return false
+  }
+
   // validate arguments limited to enumerated choices
   self.limitedChoices = function limitedChoices (argv) {
     const options = yargs.getOptions()
@@ -209,43 +224,36 @@ module.exports = function validation (yargs, usage, y18n) {
     return implied
   }
 
+  function keyExists (argv, val) {
+    // convert string '1' to number 1
+    let num = Number(val)
+    val = isNaN(num) ? val : num
+
+    if (typeof val === 'number') {
+      // check length of argv._
+      val = argv._.length >= val
+    } else if (val.match(/^--no-.+/)) {
+      // check if key/value doesn't exist
+      val = val.match(/^--no-(.+)/)[1]
+      val = !argv[val]
+    } else {
+      // check if key/value exists
+      val = argv[val]
+    }
+    return val
+  }
+
   self.implications = function implications (argv) {
     const implyFail = []
 
     Object.keys(implied).forEach((key) => {
       const origKey = key
       ;(implied[key] || []).forEach((value) => {
-        let num
         let key = origKey
         const origValue = value
+        key = keyExists(argv, key)
+        value = keyExists(argv, value)
 
-        // convert string '1' to number 1
-        num = Number(key)
-        key = isNaN(num) ? key : num
-
-        if (typeof key === 'number') {
-          // check length of argv._
-          key = argv._.length >= key
-        } else if (key.match(/^--no-.+/)) {
-          // check if key doesn't exist
-          key = key.match(/^--no-(.+)/)[1]
-          key = !argv[key]
-        } else {
-          // check if key exists
-          key = argv[key]
-        }
-
-        num = Number(value)
-        value = isNaN(num) ? value : num
-
-        if (typeof value === 'number') {
-          value = argv._.length >= value
-        } else if (value.match(/^--no-.+/)) {
-          value = value.match(/^--no-(.+)/)[1]
-          value = !argv[value]
-        } else {
-          value = argv[value]
-        }
         if (key && !value) {
           implyFail.push(` ${origKey} -> ${origValue}`)
         }
@@ -323,18 +331,19 @@ module.exports = function validation (yargs, usage, y18n) {
     return self
   }
 
-  let frozen
+  let frozens = []
   self.freeze = function freeze () {
-    frozen = {}
+    let frozen = {}
+    frozens.push(frozen)
     frozen.implied = implied
     frozen.checks = checks
     frozen.conflicting = conflicting
   }
   self.unfreeze = function unfreeze () {
+    let frozen = frozens.pop()
     implied = frozen.implied
     checks = frozen.checks
     conflicting = frozen.conflicting
-    frozen = undefined
   }
 
   return self

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yargs",
-  "version": "13.3.2",
+  "version": "14.2.1",
   "description": "yargs the modern, pirate-themed, successor to optimist.",
   "main": "./index.js",
   "contributors": [
@@ -20,6 +20,7 @@
   ],
   "dependencies": {
     "cliui": "^5.0.0",
+    "decamelize": "^1.2.0",
     "find-up": "^3.0.0",
     "get-caller-file": "^2.0.1",
     "require-directory": "^2.1.1",
@@ -28,7 +29,7 @@
     "string-width": "^3.0.0",
     "which-module": "^2.0.0",
     "y18n": "^4.0.0",
-    "yargs-parser": "^13.1.2"
+    "yargs-parser": "^15.0.0"
   },
   "devDependencies": {
     "chai": "^4.2.0",
@@ -42,7 +43,7 @@
     "nyc": "^14.1.0",
     "rimraf": "^2.6.3",
     "standard": "^12.0.1",
-    "standard-version": "^6.0.1",
+    "standard-version": "^7.0.0",
     "which": "^1.3.1",
     "yargs-test-extends": "^1.0.1"
   },

package/yargs.js

@@ -37,7 +37,8 @@ function Yargs (processArgs, cwd, parentRequire) {
 
   if (!cwd) cwd = process.cwd()
 
-  self.scriptName = function scriptName (scriptName) {
+  self.scriptName = function (scriptName) {
+    self.customScriptName = true
     self.$0 = scriptName
     return self
   }
@@ -93,14 +94,17 @@ function Yargs (processArgs, cwd, parentRequire) {
       })
     })
 
-    // preserve all groups not set to local.
-    preservedGroups = Object.keys(groups).reduce((acc, groupName) => {
-      const keys = groups[groupName].filter(key => !(key in localLookup))
-      if (keys.length > 0) {
-        acc[groupName] = keys
-      }
-      return acc
-    }, {})
+    // add all groups not set to local to preserved groups
+    Object.assign(
+      preservedGroups,
+      Object.keys(groups).reduce((acc, groupName) => {
+        const keys = groups[groupName].filter(key => !(key in localLookup))
+        if (keys.length > 0) {
+          acc[groupName] = keys
+        }
+        return acc
+      }, {})
+    )
     // groups can now be reset
     groups = {}
 
@@ -144,9 +148,10 @@ function Yargs (processArgs, cwd, parentRequire) {
   self.resetOptions()
 
   // temporary hack: allow "freezing" of reset-able state for parse(msg, cb)
-  let frozen
+  let frozens = []
   function freeze () {
-    frozen = {}
+    let frozen = {}
+    frozens.push(frozen)
     frozen.options = options
     frozen.configObjects = options.configObjects.slice(0)
     frozen.exitProcess = exitProcess
@@ -160,8 +165,11 @@ function Yargs (processArgs, cwd, parentRequire) {
     frozen.exitError = exitError
     frozen.hasOutput = hasOutput
     frozen.parsed = self.parsed
+    frozen.parseFn = parseFn
+    frozen.parseContext = parseContext
   }
   function unfreeze () {
+    let frozen = frozens.pop()
     options = frozen.options
     options.configObjects = frozen.configObjects
     exitProcess = frozen.exitProcess
@@ -175,9 +183,8 @@ function Yargs (processArgs, cwd, parentRequire) {
     command.unfreeze()
     strict = frozen.strict
     completionCommand = frozen.completionCommand
-    parseFn = null
-    parseContext = null
-    frozen = undefined
+    parseFn = frozen.parseFn
+    parseContext = frozen.parseContext
   }
 
   self.boolean = function (keys) {
@@ -231,7 +238,6 @@ function Yargs (processArgs, cwd, parentRequire) {
   function populateParserHintArray (type, keys, value) {
     keys = [].concat(keys)
     keys.forEach((key) => {
-      key = sanitizeKey(key)
       options[type].push(key)
     })
   }
@@ -287,8 +293,8 @@ function Yargs (processArgs, cwd, parentRequire) {
 
   function populateParserHintObject (builder, isArray, type, key, value) {
     if (Array.isArray(key)) {
-      const temp = Object.create(null)
       // an array of keys with one value ['x', 'y', 'z'], function parse () {}
+      const temp = {}
       key.forEach((k) => {
         temp[k] = value
       })
@@ -299,7 +305,6 @@ function Yargs (processArgs, cwd, parentRequire) {
         builder(k, key[k])
       })
     } else {
-      key = sanitizeKey(key)
       // a single key value pair 'x', parse() {}
       if (isArray) {
         options[type][key] = (options[type][key] || []).concat(value)
@@ -309,13 +314,6 @@ function Yargs (processArgs, cwd, parentRequire) {
     }
   }
 
-  // TODO(bcoe): in future major versions move more objects towards
-  // Object.create(null):
-  function sanitizeKey (key) {
-    if (key === '__proto__') return '___proto___'
-    return key
-  }
-
   function deleteFromParserHintObject (optionKey) {
     // delete from all parsing hints:
     // boolean, array, key, alias, etc.
@@ -335,7 +333,7 @@ function Yargs (processArgs, cwd, parentRequire) {
     argsert('[object|string] [string|function] [function]', [key, msg, parseFn], arguments.length)
     // allow a config object to be provided directly.
     if (typeof key === 'object') {
-      key = applyExtends(key, cwd)
+      key = applyExtends(key, cwd, self.getParserConfiguration()['deep-merge-config'])
       options.configObjects = (options.configObjects || []).concat(key)
       return self
     }
@@ -509,7 +507,7 @@ function Yargs (processArgs, cwd, parentRequire) {
 
     // If an object exists in the key, add it to options.configObjects
     if (obj[key] && typeof obj[key] === 'object') {
-      conf = applyExtends(obj[key], rootPath || cwd)
+      conf = applyExtends(obj[key], rootPath || cwd, self.getParserConfiguration()['deep-merge-config'])
       options.configObjects = (options.configObjects || []).concat(conf)
     }
 
@@ -547,8 +545,14 @@ function Yargs (processArgs, cwd, parentRequire) {
   let parseContext = null
   self.parse = function parse (args, shortCircuit, _parseFn) {
     argsert('[string|array] [function|boolean|object] [function]', [args, shortCircuit, _parseFn], arguments.length)
+    freeze()
     if (typeof args === 'undefined') {
-      return self._parseArgs(processArgs)
+      const argv = self._parseArgs(processArgs)
+      const tmpParsed = self.parsed
+      unfreeze()
+      // TODO: remove this compatibility hack when we release yargs@15.x:
+      self.parsed = tmpParsed
+      return argv
     }
 
     // a context object can optionally be provided, this allows
@@ -569,7 +573,6 @@ function Yargs (processArgs, cwd, parentRequire) {
     // skipping validation, etc.
     if (!shortCircuit) processArgs = args
 
-    freeze()
     if (parseFn) exitProcess = false
 
     const parsed = self._parseArgs(args, shortCircuit)
@@ -910,7 +913,7 @@ function Yargs (processArgs, cwd, parentRequire) {
     }
 
     // register the completion command.
-    completionCommand = cmd || 'completion'
+    completionCommand = cmd || completionCommand || 'completion'
     if (!desc && desc !== false) {
       desc = 'generate completion script'
     }
@@ -922,10 +925,10 @@ function Yargs (processArgs, cwd, parentRequire) {
     return self
   }
 
-  self.showCompletionScript = function ($0) {
-    argsert('[string]', [$0], arguments.length)
+  self.showCompletionScript = function ($0, cmd) {
+    argsert('[string] [string]', [$0, cmd], arguments.length)
     $0 = $0 || self.$0
-    _logger.log(completion.generateCompletionScript($0, completionCommand))
+    _logger.log(completion.generateCompletionScript($0, cmd || completionCommand || 'completion'))
     return self
   }
 
@@ -1022,21 +1025,27 @@ function Yargs (processArgs, cwd, parentRequire) {
     enumerable: true
   })
 
-  self._parseArgs = function parseArgs (args, shortCircuit, _skipValidation, commandIndex) {
-    let skipValidation = !!_skipValidation
+  self._parseArgs = function parseArgs (args, shortCircuit, _calledFromCommand, commandIndex) {
+    let skipValidation = !!_calledFromCommand
     args = args || processArgs
 
     options.__ = y18n.__
     options.configuration = self.getParserConfiguration()
-
     // Deprecated
     let pkgConfig = pkgUp()['yargs']
     if (pkgConfig) {
-      console.warn('Configuring yargs through package.json is deprecated and will be removed in the next major release, please use the JS API instead.')
+      console.warn('Configuring yargs through package.json is deprecated and will be removed in a future major release, please use the JS API instead.')
       options.configuration = Object.assign({}, pkgConfig, options.configuration)
     }
 
-    const parsed = Parser.detailed(args, options)
+    const populateDoubleDash = !!options.configuration['populate--']
+    const config = Object.assign({}, options.configuration, {
+      'populate--': true
+    })
+    const parsed = Parser.detailed(args, Object.assign({}, options, {
+      configuration: config
+    }))
+
     let argv = parsed.argv
     if (parseContext) argv = Object.assign({}, argv, parseContext)
     const aliases = parsed.aliases
@@ -1051,7 +1060,7 @@ function Yargs (processArgs, cwd, parentRequire) {
       // are two passes through the parser. If completion
       // is being performed short-circuit on the first pass.
       if (shortCircuit) {
-        return argv
+        return (populateDoubleDash || _calledFromCommand) ? argv : self._copyDoubleDash(argv)
       }
 
       // if there's a handler associated with a
@@ -1084,7 +1093,8 @@ function Yargs (processArgs, cwd, parentRequire) {
               // commands are executed using a recursive algorithm that executes
               // the deepest command first; we keep track of the position in the
               // argv._ array that is currently being executed.
-              return command.runCommand(cmd, self, parsed, i + 1)
+              const innerArgv = command.runCommand(cmd, self, parsed, i + 1)
+              return populateDoubleDash ? innerArgv : self._copyDoubleDash(innerArgv)
             } else if (!firstUnknownCommand && cmd !== completionCommand) {
               firstUnknownCommand = cmd
               break
@@ -1093,7 +1103,8 @@ function Yargs (processArgs, cwd, parentRequire) {
 
           // run the default command, if defined
           if (command.hasDefaultCommand() && !skipDefaultCommand) {
-            return command.runCommand(null, self, parsed)
+            const innerArgv = command.runCommand(null, self, parsed)
+            return populateDoubleDash ? innerArgv : self._copyDoubleDash(innerArgv)
           }
 
           // recommend a command if recommendCommands() has
@@ -1110,7 +1121,8 @@ function Yargs (processArgs, cwd, parentRequire) {
           self.exit(0)
         }
       } else if (command.hasDefaultCommand() && !skipDefaultCommand) {
-        return command.runCommand(null, self, parsed)
+        const innerArgv = command.runCommand(null, self, parsed)
+        return populateDoubleDash ? innerArgv : self._copyDoubleDash(innerArgv)
       }
 
       // we must run completions first, a user might
@@ -1128,7 +1140,7 @@ function Yargs (processArgs, cwd, parentRequire) {
 
           self.exit(0)
         })
-        return argv
+        return (populateDoubleDash || _calledFromCommand) ? argv : self._copyDoubleDash(argv)
       }
 
       // Handle 'help' and 'version' options
@@ -1172,6 +1184,16 @@ function Yargs (processArgs, cwd, parentRequire) {
       else throw err
     }
 
+    return (populateDoubleDash || _calledFromCommand) ? argv : self._copyDoubleDash(argv)
+  }
+
+  // to simplify the parsing of positionals in commands,
+  // we temporarily populate '--' rather than _, with arguments
+  // after the '--' directive. After the parse, we copy these back.
+  self._copyDoubleDash = function (argv) {
+    if (!argv._) return argv
+    argv._.push.apply(argv._, argv['--'])
+    delete argv['--']
     return argv
   }
 

package/lib/decamelize.js

@@ -1,32 +0,0 @@
-/*
-MIT License
-
-Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-the Software, and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-*/
-'use strict'
-
-module.exports = (text, separator) => {
-  separator = typeof separator === 'undefined' ? '_' : separator
-
-  return text
-    .replace(/([a-z\d])([A-Z])/g, `$1${separator}$2`)
-    .replace(/([A-Z]+)([A-Z][a-z\d]+)/g, `$1${separator}$2`)
-    .toLowerCase()
-}