yargs 4.8.0 → 5.0.0

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 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.
 
+<a name="5.0.0"></a>
+# [5.0.0](https://github.com/yargs/yargs/compare/v4.8.1...v5.0.0) (2016-08-14)
+
+
+### Bug Fixes
+
+* **default:** Remove undocumented alias of default() ([#469](https://github.com/yargs/yargs/issues/469)) ([b8591b2](https://github.com/yargs/yargs/commit/b8591b2))
+* remove deprecated zh.json ([#578](https://github.com/yargs/yargs/issues/578)) ([317c62c](https://github.com/yargs/yargs/commit/317c62c))
+
+
+### Features
+
+* .help() API can now enable implicit help command ([#574](https://github.com/yargs/yargs/issues/574)) ([7645019](https://github.com/yargs/yargs/commit/7645019))
+* **command:** builder function no longer needs to return the yargs instance ([#549](https://github.com/yargs/yargs/issues/549)) ([eaa2873](https://github.com/yargs/yargs/commit/eaa2873))
+* add coerce api ([#586](https://github.com/yargs/yargs/issues/586)) ([1d53ccb](https://github.com/yargs/yargs/commit/1d53ccb))
+* adds recommendCommands() for command suggestions ([#580](https://github.com/yargs/yargs/issues/580)) ([59474dc](https://github.com/yargs/yargs/commit/59474dc))
+* apply .env() globally ([#553](https://github.com/yargs/yargs/issues/553)) ([be65728](https://github.com/yargs/yargs/commit/be65728))
+* apply default builder to command() and apply fail() handlers globally ([#583](https://github.com/yargs/yargs/issues/583)) ([0aaa68b](https://github.com/yargs/yargs/commit/0aaa68b))
+* interpret demand() numbers as relative to executing command ([#582](https://github.com/yargs/yargs/issues/582)) ([927810c](https://github.com/yargs/yargs/commit/927810c))
+* update yargs-parser to version 3.1.0 ([#581](https://github.com/yargs/yargs/issues/581)) ([882a127](https://github.com/yargs/yargs/commit/882a127))
+
+
+### Performance Improvements
+
+* defer requiring most external libs until needed ([#584](https://github.com/yargs/yargs/issues/584)) ([f9b0ed4](https://github.com/yargs/yargs/commit/f9b0ed4))
+
+
+### BREAKING CHANGES
+
+* fail is now applied globally.
+* we now default to an empty builder function when command is executed with no builder.
+* yargs-parser now better handles negative integer values, at the cost of handling numeric option names, e.g., -1 hello 
+* default: removed undocumented `defaults` alias for `default`.
+* introduces a default `help` command which outputs help, as an alternative to a help flag.
+
+
+
+<a name="4.8.1"></a>
+## [4.8.1](https://github.com/yargs/yargs/compare/v4.8.0...v4.8.1) (2016-07-16)
+
+
+### Bug Fixes
+
+* **commandDir:** make dir relative to caller instead of require.main.filename ([#548](https://github.com/yargs/yargs/issues/548)) ([3c2e479](https://github.com/yargs/yargs/commit/3c2e479))
+* add config lookup for .implies() ([#556](https://github.com/yargs/yargs/issues/556)) ([8d7585c](https://github.com/yargs/yargs/commit/8d7585c))
+* cache pkg lookups by path to avoid returning the wrong one ([#552](https://github.com/yargs/yargs/issues/552)) ([fea7e0b](https://github.com/yargs/yargs/commit/fea7e0b))
+* positional arguments were not being handled appropriately by parse() ([#559](https://github.com/yargs/yargs/issues/559)) ([063a866](https://github.com/yargs/yargs/commit/063a866))
+* pull in [@nexdrew](https://github.com/nexdrew)'s fixes to yargs-parser ([#560](https://github.com/yargs/yargs/issues/560)) ([c77c080](https://github.com/yargs/yargs/commit/c77c080)), closes [#560](https://github.com/yargs/yargs/issues/560)
+
+
+
 <a name="4.8.0"></a>
 # [4.8.0](https://github.com/yargs/yargs/compare/v4.7.1...v4.8.0) (2016-07-09)
 

package/README.md

@@ -1,4 +1,4 @@
-yargs
+  yargs
 ========
 
 Yargs be a node.js library fer hearties tryin' ter parse optstrings.
@@ -6,12 +6,12 @@ Yargs be a node.js library fer hearties tryin' ter parse optstrings.
 With yargs, ye be havin' a map that leads straight to yer treasure! Treasure of course, being a simple option hash.
 
 [![Build Status][travis-image]][travis-url]
-[![Dependency Status][gemnasium-image]][gemnasium-url]
 [![Coverage Status][coveralls-image]][coveralls-url]
 [![NPM version][npm-image]][npm-url]
 [![Windows Tests][windows-image]][windows-url]
 [![js-standard-style][standard-image]][standard-url]
 [![standard-version][standard-version-image]][standard-version-url]
+[![Gitter][gitter-image]][gitter-url]
 
 > Yargs is the official successor to optimist. Please feel free to submit issues and pull requests. If you'd like to contribute and don't know where to start, have a look at [the issue list](https://github.com/yargs/yargs/issues) :)
 
@@ -294,12 +294,11 @@ line_count.js:
 var argv = require('yargs')
     .usage('Usage: $0 <command> [options]')
     .command('count', 'Count the lines in a file')
-    .demand(1)
     .example('$0 count -f foo.js', 'count the lines in the given file')
-    .demand('f')
     .alias('f', 'file')
     .nargs('f', 1)
     .describe('f', 'Load a file')
+    .demand(1, ['f'])
     .help('h')
     .alias('h', 'help')
     .epilog('copyright 2015')
@@ -453,6 +452,49 @@ var argv = require('yargs')
   .argv
 ```
 
+<a name="coerce"></a>.coerce(key, fn)
+----------------
+
+Provide a synchronous function to coerce or transform the value(s) given on the
+command line for `key`.
+
+The coercion function should accept one argument, representing the parsed value
+from the command line, and should return a new value or throw an error. The
+returned value will be used as the value for `key` (or one of its aliases) in
+`argv`. If the function throws, the error will be treated as a validation
+failure, delegating to either a custom [`.fail()`](#fail) handler or printing
+the error message in the console.
+
+```js
+var argv = require('yargs')
+  .coerce('file', function (arg) {
+    return require('fs').readFileSync(arg, 'utf8')
+  })
+  .argv
+```
+
+Optionally `.coerce()` can take an object that maps several keys to their
+respective coercion function.
+
+```js
+var argv = require('yargs')
+  .coerce({
+    date: Date.parse,
+    json: JSON.parse
+  })
+  .argv
+```
+
+You can also map the same function to several keys at one time. Just pass an
+array of keys as the first argument to `.coerce()`:
+
+```js
+var path = require('path')
+var argv = require('yargs')
+  .coerce(['src', 'dest'], path.resolve)
+  .argv
+```
+
 .command(cmd, desc, [builder], [handler])
 -----------------------------------------
 .command(cmd, desc, [module])
@@ -1006,7 +1048,7 @@ By default, yargs exits the process when the user passes a help flag, uses the
 `.exitProcess(false)` disables this behavior, enabling further actions after
 yargs have been validated.
 
-.fail(fn)
+<a name="fail"></a>.fail(fn)
 ---------
 
 Method to execute when a failure occurs, rather than printing the failure message.
@@ -1100,15 +1142,31 @@ var yargs = require('yargs')(['--help'])
     Options:
       --help  Show help  [boolean]
 
-<a name="help"></a>.help([option, [description]])
-------------------------------
+<a name="help"></a>.help()
+-----------------------------------------
+.help([option | boolean])
+-----------------------------------------
+.help([option, [description | boolean]])
+-----------------------------------------
+.help([option, [description, [boolean]]])
+-----------------------------------------
 
-Add an option (e.g. `--help`) that displays the usage string and exits the
-process. If present, the `description` parameter customizes the description of
+Add an option (e.g. `--help`) and implicit command that displays the usage
+string and exits the process.
+
+If present, the `description` parameter customizes the description of
 the help option in the usage string.
 
-If invoked without parameters, `.help()` will make `--help` the option to trigger
-help output.
+If a boolean argument is provided, it will enable or disable the use of an
+implicit command. The implicit command is enabled by default, but it can be
+disabled by passing `false`.
+
+Note that any multi-char aliases (e.g. `help`) used for the help option will
+also be used for the implicit command. If there are no multi-char aliases (e.g.
+`h`), then all single-char aliases will be used for the command.
+
+If invoked without parameters, `.help()` will use `--help` as the option and
+`help` as the implicit command to trigger help output.
 
 Example:
 
@@ -1309,6 +1367,7 @@ Valid `opt` keys include:
 - `array`: boolean, interpret option as an array, see [`array()`](#array)
 - `boolean`: boolean, interpret option as a boolean flag, see [`boolean()`](#boolean)
 - `choices`: value or array of values, limit valid option arguments to a predefined set, see [`choices()`](#choices)
+- `coerce`: function, coerce or transform parsed command line values into another value, see [`coerce()`](#coerce)
 - `config`: boolean, interpret option as a path to a JSON config file, see [`config()`](#config)
 - `configParser`: function, provide a custom config parsing function, see [`config()`](#config)
 - `count`: boolean, interpret option as a count of boolean flags, see [`count()`](#count)
@@ -1347,6 +1406,12 @@ as a configuration object.
 `cwd` can optionally be provided, the package.json will be read
 from this location.
 
+.recommendCommands()
+---------------------------
+
+Should yargs provide suggestions regarding similar commands if no matching
+command is found?
+
 .require(key, [msg | boolean])
 ------------------------------
 .required(key, [msg | boolean])
@@ -1660,8 +1725,6 @@ This module is loosely inspired by Perl's
 
 [travis-url]: https://travis-ci.org/yargs/yargs
 [travis-image]: https://img.shields.io/travis/yargs/yargs/master.svg
-[gemnasium-url]: https://gemnasium.com/yargs/yargs
-[gemnasium-image]: https://img.shields.io/gemnasium/yargs/yargs.svg
 [coveralls-url]: https://coveralls.io/github/yargs/yargs
 [coveralls-image]: https://img.shields.io/coveralls/yargs/yargs.svg
 [npm-url]: https://www.npmjs.com/package/yargs
@@ -1672,3 +1735,5 @@ This module is loosely inspired by Perl's
 [standard-url]: http://standardjs.com/
 [standard-version-image]: https://img.shields.io/badge/release-standard%20version-brightgreen.svg
 [standard-version-url]: https://github.com/conventional-changelog/standard-version
+[gitter-image]: https://img.shields.io/gitter/room/nwjs/nw.js.svg?maxAge=2592000
+[gitter-url]: https://gitter.im/yargs/Lobby?utm_source=share-link&utm_medium=link&utm_campaign=share-link

package/lib/command.js

@@ -1,7 +1,5 @@
 const path = require('path')
 const inspect = require('util').inspect
-const requireDirectory = require('require-directory')
-const whichModule = require('which-module')
 
 // handles parsing positional arguments,
 // and populating argv with said positional
@@ -34,18 +32,14 @@ module.exports = function (yargs, usage, validation) {
     handlers[parsedCommand.cmd] = {
       original: cmd,
       handler: handler,
-      // TODO: default to a noop builder in
-      // yargs@5.x
-      builder: builder,
+      builder: builder || {},
       demanded: parsedCommand.demanded,
       optional: parsedCommand.optional
     }
   }
 
-  self.addDirectory = function (dir, context, req, mainFilename, opts) {
+  self.addDirectory = function (dir, context, req, callerFile, opts) {
     opts = opts || {}
-    // dir should be relative to the command module
-    dir = path.join(context.dirs[context.commands.join('|')] || '', dir)
     // disable recursion to support nested directories of subcommands
     if (typeof opts.recurse !== 'boolean') opts.recurse = false
     // exclude 'json', 'coffee' from require-directory defaults
@@ -62,20 +56,17 @@ module.exports = function (yargs, usage, validation) {
         if (~context.files.indexOf(joined)) return visited
         // keep track of visited files in context.files
         context.files.push(joined)
-        // map "command path" to the directory path it came from
-        // so that dir can be relative in the API
-        context.dirs[context.commands.concat(parseCommand(visited.command || commandFromFilename(filename)).cmd).join('|')] = dir
         self.addHandler(visited)
       }
       return visited
     }
-    requireDirectory({ require: req, filename: mainFilename }, dir, opts)
+    require('require-directory')({ require: req, filename: callerFile }, dir, opts)
   }
 
   // lookup module object from require()d command and derive name
   // if module was not require()d and no name given, throw error
   function moduleName (obj) {
-    const mod = whichModule(obj)
+    const mod = require('which-module')(obj)
     if (!mod) throw new Error('No command name given for module: ' + inspect(obj))
     return commandFromFilename(mod.filename)
   }
@@ -134,19 +125,23 @@ module.exports = function (yargs, usage, validation) {
     var currentContext = yargs.getContext()
     var parentCommands = currentContext.commands.slice()
     currentContext.commands.push(command)
-    if (commandHandler.builder && typeof commandHandler.builder === 'function') {
-      // a function can be provided, which interacts which builds
-      // up a yargs chain and returns it.
+    if (typeof commandHandler.builder === 'function') {
+      // a function can be provided, which builds
+      // up a yargs chain and possibly returns it.
       innerArgv = 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 && typeof yargs.getUsageInstance().getUsage() === 'undefined') {
-        yargs.usage('$0 ' + (parentCommands.length ? parentCommands.join(' ') + ' ' : '') + commandHandler.original)
+      if (yargs.parsed === false) {
+        if (typeof yargs.getUsageInstance().getUsage() === 'undefined') {
+          yargs.usage('$0 ' + (parentCommands.length ? parentCommands.join(' ') + ' ' : '') + commandHandler.original)
+        }
+        innerArgv = innerArgv ? innerArgv.argv : yargs.argv
+      } else {
+        innerArgv = yargs.parsed.argv
       }
-      innerArgv = innerArgv ? innerArgv.argv : argv
-    } else if (commandHandler.builder && typeof commandHandler.builder === 'object') {
+    } else if (typeof commandHandler.builder === 'object') {
       // as a short hand, an object can instead be provided, specifying
       // the options that a command takes.
       innerArgv = yargs.reset(parsed.aliases)
@@ -157,7 +152,7 @@ module.exports = function (yargs, usage, validation) {
       innerArgv = innerArgv.argv
     }
 
-    populatePositional(commandHandler, innerArgv, currentContext)
+    populatePositional(commandHandler, innerArgv, currentContext, yargs)
 
     if (commandHandler.handler) {
       commandHandler.handler(innerArgv)
@@ -166,7 +161,7 @@ module.exports = function (yargs, usage, validation) {
     return innerArgv
   }
 
-  function populatePositional (commandHandler, argv, context) {
+  function populatePositional (commandHandler, argv, context, yargs) {
     argv._ = argv._.slice(context.commands.length) // nuke the current commands
     var demanded = commandHandler.demanded.slice(0)
     var optional = commandHandler.optional.slice(0)
@@ -179,6 +174,7 @@ module.exports = function (yargs, usage, validation) {
       if (!argv._.length) break
       if (demand.variadic) argv[demand.cmd] = argv._.splice(0)
       else argv[demand.cmd] = argv._.shift()
+      postProcessPositional(yargs, argv, demand.cmd)
     }
 
     while (optional.length) {
@@ -187,11 +183,24 @@ module.exports = function (yargs, usage, validation) {
       if (!argv._.length) break
       if (maybe.variadic) argv[maybe.cmd] = argv._.splice(0)
       else argv[maybe.cmd] = argv._.shift()
+      postProcessPositional(yargs, argv, maybe.cmd)
     }
 
     argv._ = context.commands.concat(argv._)
   }
 
+  // TODO move positional arg logic to yargs-parser and remove this duplication
+  function postProcessPositional (yargs, argv, key) {
+    var coerce = yargs.getOptions().coerce[key]
+    if (typeof coerce === 'function') {
+      try {
+        argv[key] = coerce(argv[key])
+      } catch (err) {
+        yargs.getUsageInstance().fail(err.message, err)
+      }
+    }
+  }
+
   self.reset = function () {
     handlers = {}
     return self

package/lib/levenshtein.js

@@ -0,0 +1,47 @@
+/*
+Copyright (c) 2011 Andrei Mackenzie
+
+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.
+*/
+
+// levenshtein distance algorithm, pulled from Andrei Mackenzie's MIT licensed.
+// gist, which can be found here: https://gist.github.com/andrei-m/982927
+
+// Compute the edit distance between the two given strings
+module.exports = function (a, b) {
+  if (a.length === 0) return b.length
+  if (b.length === 0) return a.length
+
+  var matrix = []
+
+  // increment along the first column of each row
+  var i
+  for (i = 0; i <= b.length; i++) {
+    matrix[i] = [i]
+  }
+
+  // increment each column in the first row
+  var j
+  for (j = 0; j <= a.length; j++) {
+    matrix[0][j] = j
+  }
+
+  // Fill in the rest of the matrix
+  for (i = 1; i <= b.length; i++) {
+    for (j = 1; j <= a.length; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) {
+        matrix[i][j] = matrix[i - 1][j - 1]
+      } else {
+        matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, // substitution
+                                Math.min(matrix[i][j - 1] + 1, // insertion
+                                         matrix[i - 1][j] + 1)) // deletion
+      }
+    }
+  }
+
+  return matrix[b.length][a.length]
+}

package/lib/usage.js

@@ -1,9 +1,6 @@
 // this file handles outputting usage instructions,
 // failures, etc. keeps logging in one place.
-const cliui = require('cliui')
-const decamelize = require('decamelize')
 const stringWidth = require('string-width')
-const wsize = require('window-size')
 const objFilter = require('./obj-filter')
 const setBlocking = require('set-blocking')
 
@@ -34,9 +31,9 @@ module.exports = function (yargs, y18n) {
   var failureOutput = false
   self.fail = function (msg, err) {
     if (fails.length) {
-      fails.forEach(function (f) {
-        f(msg, err)
-      })
+      for (var i = fails.length - 1; i >= 0; --i) {
+        fails[i](msg, err)
+      }
     } else {
       if (yargs.getExitProcess()) setBlocking(true)
 
@@ -125,7 +122,7 @@ module.exports = function (yargs, y18n) {
         return acc
       }, {})
     )
-    var ui = cliui({
+    var ui = require('cliui')({
       width: wrap,
       wrap: !!wrap
     })
@@ -329,7 +326,7 @@ module.exports = function (yargs, y18n) {
   }
 
   self.functionDescription = function (fn) {
-    var description = fn.name ? decamelize(fn.name, '-') : __('generated-value')
+    var description = fn.name ? require('decamelize')(fn.name, '-') : __('generated-value')
     return ['(', description, ')'].join('')
   }
 
@@ -375,6 +372,7 @@ module.exports = function (yargs, y18n) {
 
   // guess the width of the console window, max-width 80.
   function windowWidth () {
+    const wsize = require('window-size')
     return wsize.width ? Math.min(80, wsize.width) : null
   }
 
@@ -391,7 +389,7 @@ module.exports = function (yargs, y18n) {
 
   self.reset = function (globalLookup) {
     // do not reset wrap here
-    fails = []
+    // do not reset fails here
     failMessage = null
     failureOutput = false
     usage = undefined

package/lib/validation.js

@@ -11,18 +11,19 @@ module.exports = function (yargs, usage, y18n) {
   // arguments were provided, i.e., '_'.
   self.nonOptionCount = function (argv) {
     const demanded = yargs.getDemanded()
-    const _s = argv._.length
+    // don't count currently executing commands
+    const _s = argv._.length - yargs.getContext().commands.length
 
     if (demanded._ && (_s < demanded._.count || _s > demanded._.max)) {
       if (demanded._.msg !== undefined) {
         usage.fail(demanded._.msg)
       } else if (_s < demanded._.count) {
         usage.fail(
-          __('Not enough non-option arguments: got %s, need at least %s', argv._.length, demanded._.count)
+          __('Not enough non-option arguments: got %s, need at least %s', _s, demanded._.count)
         )
       } else {
         usage.fail(
-          __('Too many non-option arguments: got %s, maximum of %s', argv._.length, demanded._.max)
+          __('Too many non-option arguments: got %s, maximum of %s', _s, demanded._.max)
         )
       }
     }
@@ -219,6 +220,12 @@ module.exports = function (yargs, usage, y18n) {
     const implyFail = []
 
     Object.keys(implied).forEach(function (key) {
+      var booleanNegation
+      if (yargs.getOptions().configuration['boolean-negation'] === false) {
+        booleanNegation = false
+      } else {
+        booleanNegation = true
+      }
       var num
       const origKey = key
       var value = implied[key]
@@ -230,7 +237,7 @@ module.exports = function (yargs, usage, y18n) {
       if (typeof key === 'number') {
         // check length of argv._
         key = argv._.length >= key
-      } else if (key.match(/^--no-.+/)) {
+      } else if (key.match(/^--no-.+/) && booleanNegation) {
         // check if key doesn't exist
         key = key.match(/^--no-(.+)/)[1]
         key = !argv[key]
@@ -244,7 +251,7 @@ module.exports = function (yargs, usage, y18n) {
 
       if (typeof value === 'number') {
         value = argv._.length >= value
-      } else if (value.match(/^--no-.+/)) {
+      } else if (value.match(/^--no-.+/) && booleanNegation) {
         value = value.match(/^--no-(.+)/)[1]
         value = !argv[value]
       } else {
@@ -267,6 +274,23 @@ module.exports = function (yargs, usage, y18n) {
     }
   }
 
+  self.recommendCommands = function (cmd, potentialCommands) {
+    const distance = require('./levenshtein')
+    const threshold = 3 // if it takes more than three edits, let's move on.
+    potentialCommands = potentialCommands.sort(function (a, b) { return b.length - a.length })
+
+    var recommended = null
+    var bestDistance = Infinity
+    for (var i = 0, candidate; (candidate = potentialCommands[i]) !== undefined; i++) {
+      var d = distance(cmd, candidate)
+      if (d <= threshold && d < bestDistance) {
+        bestDistance = d
+        recommended = candidate
+      }
+    }
+    if (recommended) usage.fail(__('Did you mean %s?', recommended))
+  }
+
   self.reset = function (globalLookup) {
     implied = objFilter(implied, function (k, v) {
       return globalLookup[k]

package/locales/de.json

@@ -33,5 +33,6 @@
   "Invalid JSON config file: %s": "Fehlerhafte JSON-Config Datei: %s",
   "Path to JSON config file": "Pfad zur JSON-Config Datei",
   "Show help": "Hilfe anzeigen",
-  "Show version number": "Version anzeigen"
+  "Show version number": "Version anzeigen",
+  "Did you mean %s?": "Meintest du %s?"
 }

package/locales/en.json

@@ -33,5 +33,6 @@
   "Invalid JSON config file: %s": "Invalid JSON config file: %s",
   "Path to JSON config file": "Path to JSON config file",
   "Show help": "Show help",
-  "Show version number": "Show version number"
+  "Show version number": "Show version number",
+  "Did you mean %s?": "Did you mean %s?"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yargs",
-  "version": "4.8.0",
+  "version": "5.0.0",
   "description": "yargs the modern, pirate-themed, successor to optimist.",
   "main": "./index.js",
   "files": [
@@ -14,28 +14,29 @@
   "dependencies": {
     "cliui": "^3.2.0",
     "decamelize": "^1.1.1",
-    "lodash.assign": "^4.0.3",
+    "get-caller-file": "^1.0.1",
+    "lodash.assign": "^4.2.0",
     "os-locale": "^1.4.0",
     "read-pkg-up": "^1.0.1",
     "require-directory": "^2.1.1",
     "require-main-filename": "^1.0.1",
     "set-blocking": "^2.0.0",
-    "string-width": "^1.0.1",
+    "string-width": "^1.0.2",
     "which-module": "^1.0.0",
     "window-size": "^0.2.0",
     "y18n": "^3.2.1",
-    "yargs-parser": "^2.4.0"
+    "yargs-parser": "^3.2.0"
   },
   "devDependencies": {
     "chai": "^3.4.1",
     "chalk": "^1.1.3",
-    "coveralls": "^2.11.9",
+    "coveralls": "^2.11.11",
     "cpr": "^1.0.0",
-    "cross-spawn-async": "^2.2.1",
+    "cross-spawn": "^4.0.0",
     "es6-promise": "^3.0.2",
     "hashish": "0.0.4",
-    "mocha": "^2.5.2",
-    "nyc": "^7.0.0",
+    "mocha": "^3.0.1",
+    "nyc": "^8.1.0",
     "rimraf": "^2.5.0",
     "standard": "^7.0.0",
     "standard-version": "^2.2.1",

package/yargs.js

@@ -1,5 +1,4 @@
 const assert = require('assert')
-const assign = require('lodash.assign')
 const Command = require('./lib/command')
 const Completion = require('./lib/completion')
 const Parser = require('yargs-parser')
@@ -7,7 +6,6 @@ const path = require('path')
 const Usage = require('./lib/usage')
 const Validation = require('./lib/validation')
 const Y18n = require('y18n')
-const requireMainFilename = require('require-main-filename')
 const objFilter = require('./lib/obj-filter')
 const setBlocking = require('set-blocking')
 
@@ -49,7 +47,7 @@ function Yargs (processArgs, cwd, parentRequire) {
 
   // use context object to keep track of resets, subcommand execution, etc
   // submodules should modify and check the state of context as necessary
-  const context = { resets: -1, commands: [], dirs: {}, files: [] }
+  const context = { resets: -1, commands: [], files: [] }
   self.getContext = function () {
     return context
   }
@@ -98,7 +96,7 @@ function Yargs (processArgs, cwd, parentRequire) {
 
     var objectOptions = [
       'narg', 'key', 'alias', 'default', 'defaultDescription',
-      'config', 'choices', 'demanded'
+      'config', 'choices', 'demanded', 'coerce'
     ]
 
     arrayOptions.forEach(function (k) {
@@ -113,7 +111,7 @@ function Yargs (processArgs, cwd, parentRequire) {
       })
     })
 
-    tmpOptions.envPrefix = undefined
+    tmpOptions.envPrefix = options.envPrefix
     options = tmpOptions
 
     // if this is the first time being executed, create
@@ -207,7 +205,7 @@ function Yargs (processArgs, cwd, parentRequire) {
 
   self.commandDir = function (dir, opts) {
     const req = parentRequire || require
-    command.addDirectory(dir, self.getContext(), req, requireMainFilename(req), opts)
+    command.addDirectory(dir, self.getContext(), req, require('get-caller-file')(), opts)
     return self
   }
 
@@ -244,6 +242,19 @@ function Yargs (processArgs, cwd, parentRequire) {
     return self
   }
 
+  self.coerce = function (key, fn) {
+    if (typeof key === 'object' && !Array.isArray(key)) {
+      Object.keys(key).forEach(function (k) {
+        self.coerce(k, key[k])
+      })
+    } else {
+      [].concat(key).forEach(function (k) {
+        options.coerce[k] = fn
+      })
+    }
+    return self
+  }
+
   self.count = function (counts) {
     options.count.push.apply(options.count, [].concat(counts))
     return self
@@ -355,23 +366,25 @@ function Yargs (processArgs, cwd, parentRequire) {
     return self
   }
 
-  var pkg = null
+  var pkgs = {}
   function pkgUp (path) {
-    if (pkg && !path) return pkg
+    var npath = path || '*'
+    if (pkgs[npath]) return pkgs[npath]
     const readPkgUp = require('read-pkg-up')
 
     var obj = {}
     try {
       obj = readPkgUp.sync({
-        cwd: path || requireMainFilename(parentRequire || require)
+        cwd: path || require('require-main-filename')(parentRequire || require)
       })
     } catch (noop) {}
 
-    if (obj.pkg) pkg = obj.pkg
-    return pkg || {}
+    pkgs[npath] = obj.pkg || {}
+    return pkgs[npath]
   }
 
   self.parse = function (args, shortCircuit) {
+    if (!shortCircuit) processArgs = args
     return parseArgs(args, shortCircuit)
   }
 
@@ -401,6 +414,8 @@ function Yargs (processArgs, cwd, parentRequire) {
         self.normalize(key)
       } if ('choices' in opt) {
         self.choices(key, opt.choices)
+      } if ('coerce' in opt) {
+        self.coerce(key, opt.coerce)
       } if ('group' in opt) {
         self.group(key, opt.group)
       } if (opt.global) {
@@ -458,7 +473,7 @@ function Yargs (processArgs, cwd, parentRequire) {
   }
   self.getGroups = function () {
     // combine explicit and preserved groups. explicit groups should be first
-    return assign({}, groups, preservedGroups)
+    return require('lodash.assign')({}, groups, preservedGroups)
   }
 
   // as long as options.envPrefix is not undefined,
@@ -518,12 +533,33 @@ function Yargs (processArgs, cwd, parentRequire) {
   }
 
   var helpOpt = null
-  self.addHelpOpt = self.help = function (opt, msg) {
-    opt = opt || 'help'
-    helpOpt = opt
-    self.boolean(opt)
-    self.global(opt)
-    self.describe(opt, msg || usage.deferY18nLookup('Show help'))
+  var useHelpOptAsCommand = false // a call to .help() will enable this
+  self.addHelpOpt = self.help = function (opt, msg, addImplicitCmd) {
+    // argument shuffle
+    if (arguments.length === 0) {
+      useHelpOptAsCommand = true
+    } else if (arguments.length === 1) {
+      if (typeof opt === 'boolean') {
+        useHelpOptAsCommand = opt
+        opt = null
+      } else {
+        useHelpOptAsCommand = true
+      }
+    } else if (arguments.length === 2) {
+      if (typeof msg === 'boolean') {
+        useHelpOptAsCommand = msg
+        msg = null
+      } else {
+        useHelpOptAsCommand = true
+      }
+    } else {
+      useHelpOptAsCommand = Boolean(addImplicitCmd)
+    }
+    // use arguments, fallback to defaults for opt and msg
+    helpOpt = opt || 'help'
+    self.boolean(helpOpt)
+    self.global(helpOpt)
+    self.describe(helpOpt, msg || usage.deferY18nLookup('Show help'))
     return self
   }
 
@@ -602,6 +638,12 @@ function Yargs (processArgs, cwd, parentRequire) {
     return detectLocale
   }
 
+  var recommendCommands
+  self.recommendCommands = function () {
+    recommendCommands = true
+    return self
+  }
+
   self.getUsageInstance = function () {
     return usage
   }
@@ -635,7 +677,7 @@ function Yargs (processArgs, cwd, parentRequire) {
 
   function parseArgs (args, shortCircuit) {
     options.__ = y18n.__
-    options.configuration = pkgUp()['yargs'] || {}
+    options.configuration = pkgUp(cwd)['yargs'] || {}
     const parsed = Parser.detailed(args, options)
     const argv = parsed.argv
     var aliases = parsed.aliases
@@ -652,22 +694,56 @@ function Yargs (processArgs, cwd, parentRequire) {
       return argv
     }
 
-    // if there's a handler associated with a
-    // command defer processing to it.
-    var handlerKeys = command.getCommands()
-    for (var i = 0, cmd; (cmd = argv._[i]) !== undefined; i++) {
-      if (~handlerKeys.indexOf(cmd) && cmd !== completionCommand) {
-        setPlaceholderKeys(argv)
-        return command.runCommand(cmd, self, parsed)
+    if (argv._.length) {
+      // check for helpOpt in argv._ before running commands
+      // assumes helpOpt must be valid if useHelpOptAsCommand is true
+      if (useHelpOptAsCommand) {
+        // consider any multi-char helpOpt alias as a valid help command
+        // unless all helpOpt aliases are single-char
+        // note that parsed.aliases is a normalized bidirectional map :)
+        var helpCmds = [helpOpt].concat(aliases[helpOpt])
+        var multiCharHelpCmds = helpCmds.filter(function (k) {
+          return k.length > 1
+        })
+        if (multiCharHelpCmds.length) helpCmds = multiCharHelpCmds
+        // look for and strip any helpCmds from argv._
+        argv._ = argv._.filter(function (cmd) {
+          if (~helpCmds.indexOf(cmd)) {
+            argv[helpOpt] = true
+            return false
+          }
+          return true
+        })
       }
-    }
 
-    // generate a completion script for adding to ~/.bashrc.
-    if (completionCommand && ~argv._.indexOf(completionCommand) && !argv[completion.completionKey]) {
-      if (exitProcess) setBlocking(true)
-      self.showCompletionScript()
-      if (exitProcess) {
-        process.exit(0)
+      // if there's a handler associated with a
+      // command defer processing to it.
+      var handlerKeys = command.getCommands()
+      if (handlerKeys.length) {
+        var firstUnknownCommand
+        for (var i = 0, cmd; (cmd = argv._[i]) !== undefined; i++) {
+          if (~handlerKeys.indexOf(cmd) && cmd !== completionCommand) {
+            setPlaceholderKeys(argv)
+            return command.runCommand(cmd, self, parsed)
+          } else if (!firstUnknownCommand && cmd !== completionCommand) {
+            firstUnknownCommand = cmd
+          }
+        }
+
+        // recommend a command if recommendCommands() has
+        // been enabled, and no commands were found to execute
+        if (recommendCommands && firstUnknownCommand) {
+          validation.recommendCommands(firstUnknownCommand, handlerKeys)
+        }
+      }
+
+      // generate a completion script for adding to ~/.bashrc.
+      if (completionCommand && ~argv._.indexOf(completionCommand) && !argv[completion.completionKey]) {
+        if (exitProcess) setBlocking(true)
+        self.showCompletionScript()
+        if (exitProcess) {
+          process.exit(0)
+        }
       }
     }
 

package/locales/zh.json

@@ -1,37 +0,0 @@
-{
-  "Commands:": "命令：",
-  "Options:": "选项：",
-  "Examples:": "示例：",
-  "boolean": "布尔",
-  "count": "计数",
-  "string": "字符串",
-  "number": "数字",
-  "array": "数组",
-  "required": "必需",
-  "default:": "默认值:",
-  "choices:": "可选值:",
-  "generated-value": "生成的值",
-  "Not enough non-option arguments: got %s, need at least %s": "缺少 non-option 参数：传入了 %s 个, 至少需要 %s 个",
-  "Too many non-option arguments: got %s, maximum of %s": "non-option 参数过多：传入了 %s 个, 最大允许 %s 个",
-  "Missing argument value: %s": {
-    "one": "没有给此选项指定值：%s",
-    "other": "没有给这些选项指定值：%s"
-  },
-  "Missing required argument: %s": {
-    "one": "缺少必须的选项：%s",
-    "other": "缺少这些必须的选项：%s"
-  },
-  "Unknown argument: %s": {
-    "one": "无法识别的选项：%s",
-    "other": "无法识别这些选项：%s"
-  },
-  "Invalid values:": "无效的选项值：",
-  "Argument: %s, Given: %s, Choices: %s": "选项名称: %s, 传入的值: %s, 可选的值：%s",
-  "Argument check failed: %s": "选项值验证失败：%s",
-  "Implications failed:": "缺少依赖的选项：",
-  "Not enough arguments following: %s": "没有提供足够的值给此选项：%s",
-  "Invalid JSON config file: %s": "无效的 JSON 配置文件：%s",
-  "Path to JSON config file": "JSON 配置文件的路径",
-  "Show help": "显示帮助信息",
-  "Show version number": "显示版本号"
-}