yargs 4.3.2 → 4.6.0

package/CHANGELOG.md

@@ -1,4 +1,55 @@
-## Change Log
+# Change Log
+
+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="4.6.0"></a>
+# [4.6.0](https://github.com/yargs/yargs/compare/v4.5.0...v4.6.0) (2016-04-11)
+
+
+### Bug Fixes
+
+* **my brand!:** I agree with [@osher](https://github.com/osher) lightweight isn't a huge selling point of ours any longer, see [#468](https://github.com/yargs/yargs/issues/468) ([c46d7e1](https://github.com/yargs/yargs/commit/c46d7e1))
+
+### Features
+
+* switch to standard-version for release management ([f70f801](https://github.com/yargs/yargs/commit/f70f801))
+* upgrade to version of yargs-parser that introduces some slick new features, great work [@elas7](https://github.com/elas7). update cliui, replace win-spawn, replace badge. ([#475](https://github.com/yargs/yargs/issues/475)) ([f915dd4](https://github.com/yargs/yargs/commit/f915dd4))
+
+
+
+<a name="4.5.0"></a>
+# [4.5.0](https://github.com/yargs/yargs/compare/v4.4.0...v4.5.0) (2016-04-05)
+
+
+### Bug Fixes
+
+* **windows:** handle $0 better on Windows platforms ([eb6e03f](https://github.com/yargs/yargs/commit/eb6e03f))
+
+### Features
+
+* **commands:** implemented variadic positional arguments ([51d926e](https://github.com/yargs/yargs/commit/51d926e))
+* **completion:** completion now better handles aliases, and avoids duplicating keys. ([86416c8](https://github.com/yargs/yargs/commit/86416c8))
+* **config:** If invoking .config() without parameters, set a default option ([0413dd1](https://github.com/yargs/yargs/commit/0413dd1))
+* **conventional-changelog:** switching to using conventional-changelog for generating the changelog ([a2b5a2a](https://github.com/yargs/yargs/commit/a2b5a2a))
+
+
+
+### v4.4.0 (2016/04/03 21:10 +07:00)
+
+- [#454](https://github.com/yargs/yargs/pull/454) fix demand() when second argument is an array (@elas7)
+- [#452](https://github.com/yargs/yargs/pull/452) fix code example for `.help()` docs (@maxrimue)
+- [#450](https://github.com/yargs/yargs/pull/450) fix for bash completion trailing space edge-case (@elas7)
+- [#448](https://github.com/yargs/yargs/pull/448) allow a method to be passed to `showHelp`, rather than a log-level (@osher)
+- [#446](https://github.com/yargs/yargs/pull/446) update yargs-parser, y18n, nyc, cliui, pkg-conf (@bcoe)
+- [#436](https://github.com/yargs/yargs/pull/436) the rebase method is only used by tests, do not export it in two places (@elas7)
+- [#428](https://github.com/yargs/yargs/pull/428) initial support for subcommands (@nexdrew)
+
+### v4.3.2 (2016/3/20 15:07 +07:00)
+
+- [#445](https://github.com/yargs/yargs/pull/445) strict mode was failing if no commands were registered (@nexdrew)
+- [#443](https://github.com/yargs/yargs/pull/443) adds Italian translation \o/ (@madrisan)
+- [#441](https://github.com/yargs/yargs/pull/441) remove duplicate keys from array options configuration (@elas7)
+- [#437](https://github.com/yargs/yargs/pull/437) standardize tests for .command() (@lrlna)
 
 ### v4.3.0 (2016/3/12 14:19 +07:00)
 

package/LICENSE

@@ -1,4 +1,5 @@
 Copyright 2010 James Halliday (mail@substack.net)
+Modified work Copyright 2014 Contributors (ben@npmjs.com)
 
 This project is free software released under the MIT/X11 license:
 

package/README.md

@@ -10,7 +10,8 @@ With yargs, ye be havin' a map that leads straight to yer treasure! Treasure of
 [![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)
+[![js-standard-style][standard-image]][standard-url]
+[![standard-version][standard-version-image]][standard-version-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) :)
 
@@ -454,9 +455,11 @@ var argv = require('yargs')
 ```
 
 .command(cmd, desc, [builder], [handler])
--------------------
+-----------------------------------------
 .command(cmd, desc, [module])
--------------------
+-----------------------------
+.command(module)
+----------------
 
 Document the commands exposed by your application.
 
@@ -528,16 +531,33 @@ yargs.command('get <source> [proxy]', 'make a get HTTP request')
   .argv
 ```
 
+#### Variadic Positional Arguments
+
+The last positional argument can optionally accept an array of
+values, by using the `..` operator:
+
+```js
+yargs.command('download <url> [files..]', 'download several files')
+  .help()
+  .argv
+```
+
 ### Providing a Command Module
 
 For complicated commands you can pull the logic into a module. A module
 simply needs to export:
 
-* `exports.builder`: which describes the options that a command accepts.
+* `exports.command`: string that executes this command when given on the command line, may contain positional args
+* `exports.describe`: string used as the description for the command in help text, use `false` for a hidden command
+* `exports.builder`: object declaring the options the command accepts, or a function accepting and returning a yargs instance
 * `exports.handler`: a function which will be passed the parsed argv.
 
 ```js
 // my-module.js
+exports.command = 'get <source> [proxy]'
+
+exports.describe = 'make a get HTTP request'
+
 exports.builder = {
   banana: {
     default: 'cool'
@@ -554,14 +574,22 @@ exports.handler = function (argv) {
 
 You then register the module like so:
 
+```js
+yargs.command(require('my-module'))
+  .help()
+  .argv
+```
+
+Or if the module does not export `command` and `describe` (or if you just want to override them):
+
 ```js
 yargs.command('get <source> [proxy]', 'make a get HTTP request', require('my-module'))
   .help()
   .argv
 ```
 
-.completion(cmd, [description], [fn]);
--------------
+.completion([cmd], [description], [fn]);
+----------------------------------------
 
 Enable bash-completion shortcuts for commands and options.
 
@@ -576,6 +604,9 @@ that generates bash completion scripts.
 shiver me timbers is pretty awesome, you can provide your own completion
 method.
 
+If invoked without parameters, `.completion()` will make `completion` the command to output
+the completion script.
+
 ```js
 var argv = require('yargs')
   .completion('completion', function(current, argv) {
@@ -619,13 +650,15 @@ var argv = require('yargs')
   .argv;
 ```
 
-<a name="config"></a>.config(key, [description], [parseFn])
+<a name="config"></a>.config([key], [description], [parseFn])
 ------------
 
 Tells the parser that if the option specified by `key` is passed in, it
 should be interpreted as a path to a JSON config file. The file is loaded
 and parsed, and its properties are set as arguments.
 
+If invoked without parameters, `.config()` will make `--config` the option to pass the JSON config file.
+
 An optional `description` can be provided to customize the config (`key`) option
 in the usage string.
 
@@ -729,6 +762,9 @@ Should yargs attempt to detect the os' locale? Defaults to `true`.
 Tell yargs to parse environment variables matching the given prefix and apply
 them to argv as though they were command line arguments.
 
+Use the "__" separator in the environment variable to indicate nested options.
+(e.g. prefix_nested__foo => nested.foo)
+
 If this method is called with no argument or with an empty string or with `true`,
 then all env vars will be applied to argv.
 
@@ -813,7 +849,19 @@ yargs have been validated.
 
 Method to execute when a failure occurs, rather than printing the failure message.
 
-`fn` is called with the failure message that would have been printed.
+`fn` is called with the failure message that would have been printed and the
+`Error` instance originally thrown, if any.
+
+```js
+var argv = require('yargs')
+  .fail(function (msg, err) {
+    if (err) throw err // preserve stack
+    console.error('You broke it!')
+    console.error(msg)
+    process.exit(1)
+  })
+  .argv
+```
 
 <a name="global"></a>.global(globals)
 ------------
@@ -880,9 +928,10 @@ help output.
 Example:
 
 ```js
-var yargs = require("yargs")['--help']
-  .usage("$0 -operand1 number -operand2 number -operation [add|subtract]");
+var yargs = require("yargs")(['--help'])
+  .usage("$0 -operand1 number -operand2 number -operation [add|subtract]")
   .help()
+  .argv
 ```
 
 Later on, `argv` can be retrieved with `yargs.argv`.
@@ -953,10 +1002,12 @@ Locales currently supported:
 * **es:** Spanish.
 * **fr:** French.
 * **id:** Indonesian.
+* **it:** Italian.
 * **ja:** Japanese.
 * **ko:** Korean.
 * **nb:** Norwegian Bokmål.
 * **pirate:** American Pirate.
+* **pl:** Polish.
 * **pt:** Portuguese.
 * **pt_BR:** Brazilian Portuguese.
 * **tr:** Turkish.
@@ -1427,3 +1478,5 @@ This module is loosely inspired by Perl's
 [windows-image]: https://img.shields.io/appveyor/ci/bcoe/yargs/master.svg?label=Windows%20Tests
 [standard-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg
 [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

package/completion.sh.hbs

@@ -10,10 +10,10 @@ _yargs_completions()
     local cur_word args type_list
 
     cur_word="${COMP_WORDS[COMP_CWORD]}"
-    args=$(printf "%s " "${COMP_WORDS[@]}")
+    args=("${COMP_WORDS[@]}")
 
     # ask yargs to generate completions.
-    type_list=`{{app_path}} --get-yargs-completions $args`
+    type_list=$({{app_path}} --get-yargs-completions "${args[@]}")
 
     COMPREPLY=( $(compgen -W "${type_list}" -- ${cur_word}) )
 

package/index.js

@@ -5,7 +5,7 @@ var yargs = require('./yargs')
 
 Argv(process.argv.slice(2))
 
-var exports = module.exports = Argv
+module.exports = Argv
 
 function Argv (processArgs, cwd) {
   var argv = yargs(processArgs, cwd, require)
@@ -13,8 +13,6 @@ function Argv (processArgs, cwd) {
   return argv
 }
 
-exports.rebase = yargs.rebase
-
 /*  Hack an instance of Argv with process.argv into Argv
     so people can do
     require('yargs')(['--beeble=1','-z','zizzle']).argv

package/lib/command.js

@@ -45,15 +45,26 @@ module.exports = function (yargs, usage, validation) {
 
   function parseCommand (cmd) {
     var splitCommand = cmd.split(/\s/)
-    var bregex = /[\][<>]/g
+    var bregex = /\.*[\][<>]/g
     var parsedCommand = {
       cmd: (splitCommand.shift()).replace(bregex, ''),
       demanded: [],
       optional: []
     }
-    splitCommand.forEach(function (cmd) {
-      if (/^\[/.test(cmd)) parsedCommand.optional.push(cmd.replace(bregex, ''))
-      else parsedCommand.demanded.push(cmd.replace(bregex, ''))
+    splitCommand.forEach(function (cmd, i) {
+      var variadic = false
+      if (/\.+[\]>]/.test(cmd) && i === splitCommand.length - 1) variadic = true
+      if (/^\[/.test(cmd)) {
+        parsedCommand.optional.push({
+          cmd: cmd.replace(bregex, ''),
+          variadic: variadic
+        })
+      } else {
+        parsedCommand.demanded.push({
+          cmd: cmd.replace(bregex, ''),
+          variadic: variadic
+        })
+      }
     })
     return parsedCommand
   }
@@ -70,6 +81,9 @@ module.exports = function (yargs, usage, validation) {
     var argv = parsed.argv
     var commandHandler = handlers[command]
     var innerArgv = argv
+    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.
@@ -79,48 +93,53 @@ module.exports = function (yargs, usage, validation) {
       // original command string as usage() for consistent behavior with
       // options object below
       if (yargs.parsed === false && typeof yargs.getUsageInstance().getUsage() === 'undefined') {
-        yargs.usage('$0 ' + commandHandler.original)
+        yargs.usage('$0 ' + (parentCommands.length ? parentCommands.join(' ') + ' ' : '') + commandHandler.original)
       }
       innerArgv = innerArgv ? innerArgv.argv : argv
     } else if (commandHandler.builder && 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)
-      innerArgv.usage('$0 ' + commandHandler.original)
+      innerArgv.usage('$0 ' + (parentCommands.length ? parentCommands.join(' ') + ' ' : '') + commandHandler.original)
       Object.keys(commandHandler.builder).forEach(function (key) {
         innerArgv.option(key, commandHandler.builder[key])
       })
       innerArgv = innerArgv.argv
     }
 
-    populatePositional(commandHandler, innerArgv)
+    populatePositional(commandHandler, innerArgv, currentContext)
 
     if (commandHandler.handler) {
       commandHandler.handler(innerArgv)
     }
+    currentContext.commands.pop()
     return innerArgv
   }
 
-  function populatePositional (commandHandler, argv) {
-    var cmd = argv._.shift() // nuke the first argument (the current command)
+  function populatePositional (commandHandler, argv, context) {
+    argv._ = argv._.slice(context.commands.length) // nuke the current commands
     var demanded = commandHandler.demanded.slice(0)
     var optional = commandHandler.optional.slice(0)
 
     validation.positionalCount(demanded.length, argv._.length)
 
     while (demanded.length) {
-      if (!argv._.length) break
       var demand = demanded.shift()
-      argv[demand] = argv._.shift()
+      if (demand.variadic) argv[demand.cmd] = []
+      if (!argv._.length) break
+      if (demand.variadic) argv[demand.cmd] = argv._.splice(0)
+      else argv[demand.cmd] = argv._.shift()
     }
 
     while (optional.length) {
-      if (!argv._.length) break
       var maybe = optional.shift()
-      argv[maybe] = argv._.shift()
+      if (maybe.variadic) argv[maybe.cmd] = []
+      if (!argv._.length) break
+      if (maybe.variadic) argv[maybe.cmd] = argv._.splice(0)
+      else argv[maybe.cmd] = argv._.shift()
     }
 
-    argv._.unshift(cmd)
+    argv._ = context.commands.concat(argv._)
   }
 
   self.reset = function () {

package/lib/completion.js

@@ -14,6 +14,7 @@ module.exports = function (yargs, usage, command) {
     var current = process.argv[process.argv.length - 1]
     var previous = process.argv.slice(process.argv.indexOf('--' + self.completionKey) + 1)
     var argv = yargs.parse(previous)
+    var aliases = yargs.parsed.aliases
 
     // a custom completion function can be provided
     // to completion().
@@ -57,7 +58,14 @@ module.exports = function (yargs, usage, command) {
 
     if (current.match(/^-/)) {
       Object.keys(yargs.getOptions().key).forEach(function (key) {
-        completions.push('--' + key)
+        // If the key and its aliases aren't in 'previous', add the key to 'completions'
+        var keyAndAliases = [key].concat(aliases[key] || [])
+        var notInPrevious = keyAndAliases.every(function (val) {
+          return previous.indexOf('--' + val) === -1
+        })
+        if (notInPrevious) {
+          completions.push('--' + key)
+        }
       })
     }
 

package/lib/usage.js

@@ -320,8 +320,9 @@ module.exports = function (yargs, y18n) {
   }
 
   self.showHelp = function (level) {
-    level = level || 'error'
-    console[level](self.help())
+    if (!level) level = 'error'
+    var emit = typeof level === 'function' ? level : console[ level ]
+    emit(self.help())
   }
 
   self.functionDescription = function (fn) {

package/lib/validation.js

@@ -109,6 +109,7 @@ module.exports = function (yargs, usage, y18n) {
     var demanded = yargs.getDemanded()
     var commandKeys = yargs.getCommandInstance().getCommands()
     var unknown = []
+    var currentContext = yargs.getContext()
 
     Object.keys(aliases).forEach(function (key) {
       aliases[key].forEach(function (alias) {
@@ -126,7 +127,7 @@ module.exports = function (yargs, usage, y18n) {
     })
 
     if (commandKeys.length > 0) {
-      argv._.forEach(function (key) {
+      argv._.slice(currentContext.commands.length).forEach(function (key) {
         if (commandKeys.indexOf(key) === -1) {
           unknown.push(key)
         }

package/locales/en.json

@@ -5,6 +5,7 @@
   "boolean": "boolean",
   "count": "count",
   "string": "string",
+  "number": "number",
   "array": "array",
   "required": "required",
   "default:": "default:",

package/locales/it.json

@@ -5,6 +5,7 @@
   "boolean": "booleano",
   "count": "contatore",
   "string": "stringa",
+  "number": "numero",
   "array": "vettore",
   "required": "richiesto",
   "default:": "predefinito:",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yargs",
-  "version": "4.3.2",
-  "description": "Light-weight option parsing with an argv hash. No optstrings attached.",
+  "version": "4.6.0",
+  "description": "yargs the modern, pirate-themed, successor to optimist.",
   "main": "./index.js",
   "files": [
     "index.js",
@@ -13,36 +13,38 @@
   ],
   "dependencies": {
     "camelcase": "^2.0.1",
-    "cliui": "^3.0.3",
+    "cliui": "^3.2.0",
     "decamelize": "^1.1.1",
     "lodash.assign": "^4.0.3",
     "os-locale": "^1.4.0",
-    "pkg-conf": "^1.1.1",
+    "pkg-conf": "^1.1.2",
     "read-pkg-up": "^1.0.1",
     "require-main-filename": "^1.0.1",
     "string-width": "^1.0.1",
     "window-size": "^0.2.0",
-    "y18n": "^3.2.0",
-    "yargs-parser": "^2.1.1"
+    "y18n": "^3.2.1",
+    "yargs-parser": "^2.4.0"
   },
   "devDependencies": {
     "chai": "^3.4.1",
-    "chalk": "^1.1.1",
-    "coveralls": "^2.11.4",
+    "chalk": "^1.1.3",
+    "coveralls": "^2.11.9",
     "cpr": "^1.0.0",
+    "cross-spawn-async": "^2.2.1",
     "es6-promise": "^3.0.2",
     "hashish": "0.0.4",
     "mocha": "^2.4.5",
-    "nyc": "^6.0.0",
+    "nyc": "^6.1.1",
     "rimraf": "^2.5.0",
     "standard": "^6.0.5",
-    "which": "^1.1.2",
-    "win-spawn": "^2.0.0"
+    "standard-version": "^2.1.2",
+    "which": "^1.1.2"
   },
   "scripts": {
     "pretest": "standard",
     "test": "nyc --cache mocha --require ./test/before.js --timeout=4000 --check-leaks",
-    "coverage": "nyc report --reporter=text-lcov | coveralls"
+    "coverage": "nyc report --reporter=text-lcov | coveralls",
+    "version": "standard-version"
   },
   "repository": {
     "type": "git",
@@ -67,4 +69,4 @@
   "engine": {
     "node": ">=0.10"
   }
-}
+}

package/yargs.js

@@ -35,9 +35,9 @@ function Yargs (processArgs, cwd, parentRequire) {
     .map(function (x, i) {
       // ignore the node bin, specify this in your
       // bin file with #!/usr/bin/env node
-      if (i === 0 && /\b(node|iojs)$/.test(x)) return
+      if (i === 0 && /\b(node|iojs)(\.exe)?$/.test(x)) return
       var b = rebase(cwd, x)
-      return x.match(/^\//) && b.length < x.length ? b : x
+      return x.match(/^(\/|([a-zA-Z]:)?\\)/) && b.length < x.length ? b : x
     })
     .join(' ').trim()
 
@@ -47,11 +47,19 @@ 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
+  var context = { resets: -1, commands: [] }
+  self.getContext = function () {
+    return context
+  }
+
   // puts yargs back into an initial state. any keys
   // that have been set to "global" will not be reset
   // by this action.
   var options
   self.resetOptions = self.reset = function (aliases) {
+    context.resets++
     aliases = aliases || {}
     options = options || {}
     // put yargs back into an initial state, this
@@ -171,6 +179,8 @@ function Yargs (processArgs, cwd, parentRequire) {
       parseFn = msg
       msg = null
     }
+
+    key = key || 'config'
     self.describe(key, msg || usage.deferY18nLookup('Path to JSON config file'))
     ;(Array.isArray(key) ? key : [key]).forEach(function (k) {
       options.config[k] = parseFn || true
@@ -234,6 +244,7 @@ function Yargs (processArgs, cwd, parentRequire) {
       max.forEach(function (key) {
         self.demand(key, msg)
       })
+      max = Infinity
     } else if (typeof max !== 'number') {
       msg = max
       max = Infinity