yargs 3.11.0 → 3.15.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## Change Log
 
+### v3.15.0 (2015/07/06 06:01 +00:00)
+- [#197](https://github.com/bcoe/yargs/pull/197) tweaks to how errors bubble up from parser.js (@bcoe)
+- [#193](https://github.com/bcoe/yargs/pull/193) upgraded nyc, reporting now happens by default (@bcoe)
+
+### v3.14.0 (2015/06/28 02:12 +00:00)
+
+- [#192](https://github.com/bcoe/yargs/pull/192) standard style nits (@bcoe)
+- [#190](https://github.com/bcoe/yargs/pull/190) allow for hidden commands, e.g.,
+  .completion('completion', false) (@tschaub)
+
+### v3.13.0 (2015/06/24 04:12 +00:00)
+
+- [#187](https://github.com/bcoe/yargs/pull/187) completion now behaves differently
+  if it is being run in the context of a command (@tschaub)
+- [#186](https://github.com/bcoe/yargs/pull/186) if no matches are found for a completion
+  default to filename completion (@tschaub)
+
+### v3.12.0 (2015/06/19 03:23 +00:00)
+- [#183](https://github.com/bcoe/yargs/pull/183) don't complete commands if they've already been completed (@tschaub)
+- [#181](https://github.com/bcoe/yargs/pull/181) various fixes for completion. (@bcoe, @tschaub)
+- [#182](https://github.com/bcoe/yargs/pull/182) you can now set a maximum # of of required arguments (@bcoe)
+
 ### v3.11.0 (2015/06/15 05:15 +00:00)
 
 - [#173](https://github.com/bcoe/yargs/pull/173) update standard, window-size, chai (@bcoe)

package/README.md

@@ -398,17 +398,20 @@ displaying the value in the usage instructions:
 ```
 
 .demand(key, [msg | boolean])
------------------------------
+------------------------------
 .require(key, [msg | boolean])
 ------------------------------
 .required(key, [msg | boolean])
--------------------------------
+------------------------------
+.demand(count, [max], [msg])
+------------------------------
 
 If `key` is a string, show the usage information and exit if `key` wasn't
 specified in `process.argv`.
 
 If `key` is a number, demand at least as many non-option arguments, which show
-up in `argv._`.
+up in `argv._`. A second number can also optionally be provided, which indicates
+the maximum number of non-option arguments.
 
 If `key` is an Array, demand each element.
 
@@ -506,8 +509,10 @@ present script similar to how `$0` works in bash or perl.
 
 Document the commands exposed by your application.
 
-use `desc` to provide a description for each command your application accepts (the
-values stored in `argv._`).
+Use `desc` to provide a description for each command your application accepts (the
+values stored in `argv._`).  Set `desc` to `false` to create a hidden command.
+Hidden commands don't show up in the help output and aren't available for
+completion.
 
 Optionally, you can provide a handler `fn` which will be executed when
 a given command is provided. The handler will be executed with an instance

package/completion.sh.hbs

@@ -16,6 +16,12 @@ _yargs_completions()
     type_list=`{{app_path}} --get-yargs-completions $args`
 
     COMPREPLY=( $(compgen -W "${type_list}" -- ${cur_word}) )
+
+    # if no match was found, fall back to filename completion
+    if [ ${#COMPREPLY[@]} -eq 0 ]; then
+      COMPREPLY=( $(compgen -f -- "${cur_word}" ) )
+    fi
+
     return 0
 }
 complete -F _yargs_completions {{app_name}}

package/index.js

@@ -66,7 +66,6 @@ function Argv (processArgs, cwd) {
     strict = false
     helpOpt = null
     versionOpt = null
-    completionOpt = null
     commandHandlers = {}
     self.parsed = false
 
@@ -112,7 +111,9 @@ function Argv (processArgs, cwd) {
   }
 
   self.command = function (cmd, description, fn) {
-    usage.command(cmd, description)
+    if (description !== false) {
+      usage.command(cmd, description)
+    }
     if (fn) commandHandlers[cmd] = fn
     return self
   }
@@ -160,10 +161,18 @@ function Argv (processArgs, cwd) {
   }
 
   var demanded = {}
-  self.demand = self.required = self.require = function (keys, msg) {
+  self.demand = self.required = self.require = function (keys, max, msg) {
+    // you can optionally provide a 'max' key,
+    // which will raise an exception if too many '_'
+    // options are provided.
+    if (typeof max !== 'number') {
+      msg = max
+      max = Infinity
+    }
+
     if (typeof keys === 'number') {
-      if (!demanded._) demanded._ = { count: 0, msg: null }
-      demanded._.count += keys
+      if (!demanded._) demanded._ = { count: 0, msg: null, max: max }
+      demanded._.count = keys
       demanded._.msg = msg
     } else if (Array.isArray(keys)) {
       keys.forEach(function (key) {
@@ -344,7 +353,6 @@ function Argv (processArgs, cwd) {
     return usage.help()
   }
 
-  var completionOpt = null
   var completionCommand = null
   self.completion = function (cmd, desc, fn) {
     // a function to execute when generating
@@ -356,9 +364,11 @@ function Argv (processArgs, cwd) {
     }
 
     // register the completion command.
-    completionCommand = cmd
-    completionOpt = completion.completionKey
-    self.command(completionCommand, desc || 'generate bash completion script')
+    completionCommand = cmd || 'completion'
+    if (!desc && desc !== false) {
+      desc = 'generate bash completion script'
+    }
+    self.command(completionCommand, desc)
 
     // a function can be provided
     if (fn) completion.registerFunction(fn)
@@ -408,12 +418,13 @@ function Argv (processArgs, cwd) {
 
     self.parsed = parsed
 
-    // generate a completion script for adding to ~/.bashrc.
-    if (completionCommand && ~argv._.indexOf(completionCommand)) {
-      self.showCompletionScript()
-      if (exitProcess) {
-        process.exit(0)
-      }
+    // while building up the argv object, there
+    // are two passes through the parser. If completion
+    // is being performed short-circuit on the first pass.
+    if (completionCommand &&
+      (process.argv.join(' ')).indexOf(completion.completionKey) !== -1 &&
+      !argv[completion.completionKey]) {
+      return argv
     }
 
     // if there's a handler associated with a
@@ -426,6 +437,31 @@ function Argv (processArgs, cwd) {
       }
     }
 
+    // generate a completion script for adding to ~/.bashrc.
+    if (completionCommand && ~argv._.indexOf(completionCommand) && !argv[completion.completionKey]) {
+      self.showCompletionScript()
+      if (exitProcess) {
+        process.exit(0)
+      }
+    }
+
+    // we must run completions first, a user might
+    // want to complete the --help or --version option.
+    if (completion.completionKey in argv) {
+      // we allow for asynchronous completions,
+      // e.g., loading in a list of commands from an API.
+      completion.getCompletion(function (completions) {
+        ;(completions || []).forEach(function (completion) {
+          console.log(completion)
+        })
+
+        if (exitProcess) {
+          process.exit(0)
+        }
+      })
+      return
+    }
+
     Object.keys(argv).forEach(function (key) {
       if (key === helpOpt && argv[key]) {
         self.showHelp('log')
@@ -437,32 +473,22 @@ function Argv (processArgs, cwd) {
         if (exitProcess) {
           process.exit(0)
         }
-      } else if (key === completionOpt) {
-        // we allow for asynchronous completions,
-        // e.g., loading in a list of commands from an API.
-        completion.getCompletion(function (completions) {
-          ;(completions || []).forEach(function (completion) {
-            console.log(completion)
-          })
-
-          if (exitProcess) {
-            process.exit(0)
-          }
-        })
-        return
       }
     })
 
-    validation.nonOptionCount(argv)
-    validation.missingArgumentValue(argv)
-    validation.requiredArguments(argv)
-
-    if (strict) {
-      validation.unknownArguments(argv, aliases)
+    if (parsed.error) throw parsed.error
+
+    // if we're executed via bash completion, don't
+    // bother with validation.
+    if (!argv[completion.completionKey]) {
+      validation.nonOptionCount(argv)
+      validation.missingArgumentValue(argv)
+      validation.requiredArguments(argv)
+      if (strict) validation.unknownArguments(argv, aliases)
+      validation.customChecks(argv, aliases)
+      validation.implications(argv)
     }
 
-    validation.customChecks(argv, aliases)
-    validation.implications(argv)
     setPlaceholderKeys(argv)
 
     return argv

package/lib/completion.js

@@ -29,9 +29,18 @@ module.exports = function (yargs, usage) {
       }
     }
 
+    var handlers = yargs.getCommandHandlers()
+    for (var i = 0, ii = previous.length; i < ii; ++i) {
+      if (handlers[previous[i]]) {
+        return handlers[previous[i]](yargs.reset())
+      }
+    }
+
     if (!current.match(/^-/)) {
       usage.getCommands().forEach(function (command) {
-        completions.push(command[0])
+        if (previous.indexOf(command[0]) === -1) {
+          completions.push(command[0])
+        }
       })
     }
 

package/lib/parser.js

@@ -9,6 +9,8 @@ function increment (orig) {
 
 module.exports = function (args, opts) {
   if (!opts) opts = {}
+
+  var error = null
   var flags = { arrays: {}, bools: {}, strings: {}, counts: {}, normalize: {}, configs: {} }
 
   ;[].concat(opts['array']).filter(Boolean).forEach(function (key) {
@@ -64,13 +66,13 @@ module.exports = function (args, opts) {
   }
 
   for (var i = 0; i < args.length; i++) {
-    var arg = args[i],
-      broken,
-      key,
-      letters,
-      m,
-      next,
-      value
+    var arg = args[i]
+    var broken
+    var key
+    var letters
+    var m
+    var next
+    var value
 
     // -- seperated by =
     if (arg.match(/^--.+=/)) {
@@ -232,7 +234,7 @@ module.exports = function (args, opts) {
   function eatNargs (i, key, args) {
     var toEat = checkAllAliases(key, opts.narg)
 
-    if (args.length - (i + 1) < toEat) throw Error('not enough arguments following: ' + key)
+    if (args.length - (i + 1) < toEat) error = Error('not enough arguments following: ' + key)
 
     for (var ii = i + 1; ii < (toEat + i + 1); ii++) {
       setArg(key, args[ii])
@@ -331,7 +333,7 @@ module.exports = function (args, opts) {
             }
           })
         } catch (ex) {
-          throw Error('invalid json config file: ' + configPath)
+          if (argv[configKey]) error = Error('invalid json config file: ' + configPath)
         }
       }
     })
@@ -443,6 +445,7 @@ module.exports = function (args, opts) {
   return {
     argv: argv,
     aliases: aliases,
+    error: error,
     newAliases: newAliases
   }
 }

package/lib/validation.js

@@ -7,14 +7,19 @@ module.exports = function (yargs, usage) {
   // arguments were provided, i.e., '_'.
   self.nonOptionCount = function (argv) {
     var demanded = yargs.getDemanded()
+    var _s = argv._.length
 
-    if (demanded._ && argv._.length < demanded._.count) {
+    if (demanded._ && (_s < demanded._.count || _s > demanded._.max)) {
       if (demanded._.msg !== undefined) {
         usage.fail(demanded._.msg)
-      } else {
+      } else if (_s < demanded._.count) {
         usage.fail('Not enough non-option arguments: got ' +
           argv._.length + ', need at least ' + demanded._.count
         )
+      } else {
+        usage.fail('Too many non-option arguments: got ' +
+          argv._.length + ', maximum of ' + demanded._.max
+        )
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yargs",
-  "version": "3.11.0",
+  "version": "3.15.0",
   "description": "Light-weight option parsing with an argv hash. No optstrings attached.",
   "main": "./index.js",
   "files": [
@@ -20,11 +20,11 @@
     "coveralls": "^2.11.2",
     "hashish": "0.0.4",
     "mocha": "^2.2.1",
-    "nyc": "^2.2.1",
-    "standard": "^4.2.1"
+    "nyc": "^3.0.0",
+    "standard": "^4.4.0"
   },
   "scripts": {
-    "test": "standard && nyc mocha --check-leaks && nyc report",
+    "test": "standard && nyc mocha --check-leaks",
     "coverage": "nyc report --reporter=text-lcov | coveralls"
   },
   "repository": {
@@ -76,6 +76,10 @@
     {
       "name": "Lin Clark",
       "url": "https://github.com/linclark"
+    },
+    {
+      "name": "Tim Schaub",
+      "url": "https://github.com/tschaub"
     }
   ],
   "license": "MIT",