yargs 3.7.2 → 3.10.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## Change Log
 
+### v3.10.0 (2015/05/29 04:25 +00:00)
+
+- [#165](https://github.com/bcoe/yargs/pull/165) expose yargs.terminalWidth() thanks @ensonic (@bcoe)
+- [#164](https://github.com/bcoe/yargs/pull/164) better array handling thanks @getify (@bcoe)
+
+### v3.9.1 (2015/05/20 05:14 +00:00)
+- [b6662b6](https://github.com/bcoe/yargs/commit/b6662b6774cfeab4876f41ec5e2f67b7698f4e2f) clarify .config() docs (@linclark)
+- [0291360](https://github.com/bcoe/yargs/commit/02913606285ce31ce81d7f12c48d8a3029776ec7) fixed tests, switched to nyc for coverage, fixed security issue, added Lin as collaborator (@bcoe)
+
+### v3.9.0 (2015/05/10 18:32 +00:00)
+- [#157](https://github.com/bcoe/yargs/pull/157) Merge pull request #157 from bcoe/command-yargs. allows handling of command specific arguments. Thanks for the suggestion @ohjames (@bcoe)
+- [#158](https://github.com/bcoe/yargs/pull/158) Merge pull request #158 from kemitchell/spdx-license. Update license format (@kemitchell)
+
+### v3.8.0 (2015/04/24 23:10 +00:00)
+- [#154](https://github.com/bcoe/yargs/pull/154) showHelp's method signature was misleading fixes #153 (@bcoe)
+- [#151](https://github.com/bcoe/yargs/pull/151) refactor yargs' table layout logic to use new helper library (@bcoe)
+- [#150](https://github.com/bcoe/yargs/pull/150) Fix README example in argument requirements (@annonymouse)
+
 ### v3.7.2 (2015/04/13 11:52 -07:00)
 
 * [679fbbf](https://github.com/bcoe/yargs/commit/679fbbf55904030ccee8a2635e8e5f46551ab2f0) updated yargs to use the [standard](https://github.com/feross/standard) style guide (agokjr)

package/README.md

@@ -167,7 +167,7 @@ console.log("The area is:", argv.w * argv.h);
 
 ***
 
-    $ ./area.js -w 55 -w 11
+    $ ./area.js -w 55 -h 11
     605
 
     $ node ./area.js -w 4.91 -w 2.51
@@ -501,18 +501,33 @@ present script similar to how `$0` works in bash or perl.
 
 `opts` is optional and acts like calling `.options(opts)`.
 
-.command(cmd, desc)
+.command(cmd, desc, [fn])
 -------------------
 
-Document the commands exposed by your application (stored in the `_` variable).
+Document the commands exposed by your application.
 
-As an example, here's how the npm cli might document some of its commands:
+use `desc` to provide a description for each command your application accepts (the
+values stored in `argv._`).
+
+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
+of `yargs`, which can be used to compose nested commands.
+
+Here's an example of top-level and nested commands in action:
 
 ```js
 var argv = require('yargs')
   .usage('npm <command>')
   .command('install', 'tis a mighty fine package to install')
-  .command('publish', 'shiver me timbers, should you be sharing all that')
+  .command('publish', 'shiver me timbers, should you be sharing all that', function (yargs) {
+    argv = yargs.option('f', {
+      alias: 'force',
+      description: 'yar, it usually be a bad idea'
+    })
+    .help('help')
+    .argv
+  })
+  .help('help')
   .argv;
 ```
 
@@ -580,7 +595,7 @@ regardless of whether they resemble numbers.
 ----------
 
 Tell the parser to interpret `key` as an array. If `.array('foo')` is set,
-`--foo bar` will be parsed as `['bar']` rather than as `'bar'`.
+`--foo foo bar` will be parsed as `['foo', 'bar']` rather than as `'bar'`.
 
 .nargs(key, count)
 -----------
@@ -603,8 +618,9 @@ Optionally `.nargs()` can take an object of `key`/`narg` pairs.
 .config(key)
 ------------
 
-Tells the parser to interpret `key` as a path to a JSON config file. The file
-is loaded and parsed, and its properties are set as arguments.
+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.
 
 .wrap(columns)
 --------------
@@ -614,6 +630,9 @@ Format usage output to wrap at `columns` many columns.
 By default wrap will be set to `Math.min(80, windowWidth)`. Use `.wrap(null)` to
 specify no column limit.
 
+`yargs.wrap(yargs.terminalWidth())` can be used to maximize the width
+of yargs' usage instructions.
+
 .strict()
 ---------
 

package/index.js

@@ -67,6 +67,8 @@ function Argv (processArgs, cwd) {
     helpOpt = null
     versionOpt = null
     completionOpt = null
+    commandHandlers = {}
+    self.parsed = false
 
     return self
   }
@@ -108,11 +110,17 @@ function Argv (processArgs, cwd) {
     return self
   }
 
-  self.command = function (cmd, description) {
+  self.command = function (cmd, description, fn) {
     usage.command(cmd, description)
+    if (fn) commandHandlers[cmd] = fn
     return self
   }
 
+  var commandHandlers = {}
+  self.getCommandHandlers = function () {
+    return commandHandlers
+  }
+
   self.string = function (strings) {
     options.string.push.apply(options.string, [].concat(strings))
     return self
@@ -287,9 +295,9 @@ function Argv (processArgs, cwd) {
     return strict
   }
 
-  self.showHelp = function (fn) {
+  self.showHelp = function (level) {
     if (!self.parsed) parseArgs(processArgs) // run parser, if it has not already been executed.
-    usage.showHelp(fn)
+    usage.showHelp(level)
     return self
   }
 
@@ -297,6 +305,7 @@ function Argv (processArgs, cwd) {
   self.version = function (ver, opt, msg) {
     versionOpt = opt || 'version'
     usage.version(ver)
+    self.boolean(versionOpt)
     self.describe(versionOpt, msg || 'Show version number')
     return self
   }
@@ -304,6 +313,7 @@ function Argv (processArgs, cwd) {
   var helpOpt = null
   self.addHelpOpt = function (opt, msg) {
     helpOpt = opt
+    self.boolean(opt)
     self.describe(opt, msg || 'Show help')
     return self
   }
@@ -369,6 +379,10 @@ function Argv (processArgs, cwd) {
     return validation
   }
 
+  self.terminalWidth = function () {
+    return require('window-size').width
+  }
+
   Object.defineProperty(self, 'argv', {
     get: function () {
       var args = null
@@ -386,8 +400,8 @@ function Argv (processArgs, cwd) {
 
   function parseArgs (args) {
     var parsed = Parser(args, options),
-    argv = parsed.argv,
-    aliases = parsed.aliases
+      argv = parsed.argv,
+      aliases = parsed.aliases
 
     argv.$0 = self.$0
 
@@ -401,13 +415,23 @@ function Argv (processArgs, cwd) {
       }
     }
 
+    // if there's a handler associated with a
+    // command defer processing to it.
+    var handlerKeys = Object.keys(self.getCommandHandlers())
+    for (var i = 0, command; (command = handlerKeys[i]) !== undefined; i++) {
+      if (~argv._.indexOf(command)) {
+        self.getCommandHandlers()[command](self.reset())
+        return self.argv
+      }
+    }
+
     Object.keys(argv).forEach(function (key) {
-      if (key === helpOpt) {
+      if (key === helpOpt && argv[key]) {
         self.showHelp('log')
         if (exitProcess) {
           process.exit(0)
         }
-      } else if (key === versionOpt) {
+      } else if (key === versionOpt && argv[key]) {
         usage.showVersion()
         if (exitProcess) {
           process.exit(0)

package/lib/parser.js

@@ -69,7 +69,8 @@ module.exports = function (args, opts) {
       key,
       letters,
       m,
-      next
+      next,
+      value
 
     // -- seperated by =
     if (arg.match(/^--.+=/)) {
@@ -77,7 +78,18 @@ module.exports = function (args, opts) {
       // 'dotall' regex modifier. See:
       // http://stackoverflow.com/a/1068308/13216
       m = arg.match(/^--([^=]+)=([\s\S]*)$/)
-      setArg(m[1], m[2])
+
+      // nargs format = '--f=monkey washing cat'
+      if (checkAllAliases(m[1], opts.narg)) {
+        args.splice(i + 1, m[1], m[2])
+        i = eatNargs(i, m[1], args)
+      // arrays format = '--f=a b c'
+      } else if (checkAllAliases(m[1], flags.arrays) && args.length > i + 1) {
+        args.splice(i + 1, m[1], m[2])
+        i = eatArray(i, m[1], args)
+      } else {
+        setArg(m[1], m[2])
+      }
     } else if (arg.match(/^--no-.+/)) {
       key = arg.match(/^--no-(.+)/)[1]
       setArg(key, false)
@@ -86,8 +98,12 @@ module.exports = function (args, opts) {
     } else if (arg.match(/^--.+/)) {
       key = arg.match(/^--(.+)/)[1]
 
+      // nargs format = '--foo a b c'
       if (checkAllAliases(key, opts.narg)) {
         i = eatNargs(i, key, args)
+      // array format = '--foo a b c'
+      } else if (checkAllAliases(key, flags.arrays) && args.length > i + 1) {
+        i = eatArray(i, key, args)
       } else {
         next = args[i + 1]
 
@@ -130,7 +146,21 @@ module.exports = function (args, opts) {
         next = arg.slice(j + 2)
 
         if (letters[j + 1] && letters[j + 1] === '=') {
-          setArg(letters[j], arg.slice(j + 3))
+          value = arg.slice(j + 3)
+          key = letters[j]
+
+          // nargs format = '-f=monkey washing cat'
+          if (checkAllAliases(letters[j], opts.narg)) {
+            args.splice(i + 1, 0, value)
+            i = eatNargs(i, key, args)
+          // array format = '-f=a b c'
+          } else if (checkAllAliases(key, flags.arrays) && args.length > i + 1) {
+            args.splice(i + 1, 0, value)
+            i = eatArray(i, key, args)
+          } else {
+            setArg(key, value)
+          }
+
           broken = true
           break
         }
@@ -159,8 +189,12 @@ module.exports = function (args, opts) {
       key = arg.slice(-1)[0]
 
       if (!broken && key !== '-') {
+        // nargs format = '-f a b c'
         if (checkAllAliases(key, opts.narg)) {
           i = eatNargs(i, key, args)
+        // array format = '-f a b c'
+        } else if (checkAllAliases(key, flags.arrays) && args.length > i + 1) {
+          i = eatArray(i, key, args)
         } else {
           if (args[i + 1] && !/^(-|--)[^-]/.test(args[i + 1])
           && !checkAllAliases(key, flags.bools)
@@ -207,6 +241,19 @@ module.exports = function (args, opts) {
     return (i + toEat)
   }
 
+  // if an option is an array, eat all non-hyphenated arguments
+  // following it... YUM!
+  // e.g., --foo apple banana cat becomes ["apple", "banana", "cat"]
+  function eatArray (i, key, args) {
+    for (var ii = i + 1; ii < args.length; ii++) {
+      if (/^-/.test(args[ii])) break
+      i = ii
+      setArg(key, args[ii])
+    }
+
+    return i
+  }
+
   function setArg (key, val) {
     // handle parsing boolean arguments --foo=true --bar false.
     if (checkAllAliases(key, flags.bools) || checkAllAliases(key, flags.counts)) {

package/lib/usage.js

@@ -1,7 +1,7 @@
 // this file handles outputting usage instructions,
 // failures, etc. keeps logging in one place.
-var decamelize = require('decamelize'),
-  wordwrap = require('wordwrap'),
+var cliui = require('cliui'),
+  decamelize = require('decamelize'),
   wsize = require('window-size')
 
 module.exports = function (yargs) {
@@ -94,40 +94,40 @@ module.exports = function (yargs) {
     normalizeAliases()
 
     var demanded = yargs.getDemanded(),
-    options = yargs.getOptions(),
-    keys = Object.keys(
-      Object.keys(descriptions)
-      .concat(Object.keys(demanded))
-      .concat(Object.keys(options.default))
-      .reduce(function (acc, key) {
-        if (key !== '_') acc[key] = true
-        return acc
-      }, {})
-    )
-
-    var help = keys.length ? [ 'Options:' ] : []
+      options = yargs.getOptions(),
+      keys = Object.keys(
+        Object.keys(descriptions)
+        .concat(Object.keys(demanded))
+        .concat(Object.keys(options.default))
+        .reduce(function (acc, key) {
+          if (key !== '_') acc[key] = true
+          return acc
+        }, {})
+      ),
+      ui = cliui({
+        width: wrap,
+        wrap: !!wrap
+      })
+
+    // the usage string.
+    if (usage) {
+      var u = usage.replace(/\$0/g, yargs.$0)
+      ui.div(u + '\n')
+    }
 
     // your application's commands, i.e., non-option
     // arguments populated in '_'.
     if (commands.length) {
-      help.unshift('')
+      ui.div('Commands:')
 
-      var commandsTable = {}
       commands.forEach(function (command) {
-        commandsTable[command[0]] = {
-          desc: command[1],
-          extra: ''
-        }
+        ui.div(
+          {text: command[0], padding: [0, 2, 0, 2], width: maxWidth(commands) + 4},
+          {text: command[1]}
+        )
       })
 
-      help = ['Commands:'].concat(formatTable(commandsTable, 5), help)
-    }
-
-    // the usage string.
-    if (usage) {
-      var u = usage.replace(/\$0/g, yargs.$0)
-      if (wrap) u = wordwrap(0, wrap)(u)
-      help.unshift(u, '')
+      ui.div()
     }
 
     // the options table.
@@ -150,58 +150,87 @@ module.exports = function (yargs) {
       return acc
     }, {})
 
-    var switchTable = {}
-    keys.forEach(function (key) {
-      var kswitch = switches[key]
-      var desc = descriptions[key] || ''
-      var type = null
-
-      if (~options.boolean.indexOf(key)) type = '[boolean]'
-      if (~options.count.indexOf(key)) type = '[count]'
-      if (~options.string.indexOf(key)) type = '[string]'
-      if (~options.normalize.indexOf(key)) type = '[string]'
-      if (~options.array.indexOf(key)) type = '[array]'
-
-      var extra = [
-        type,
-        demanded[key] ? '[required]' : null,
-        defaultString(options.default[key], options.defaultDescription[key])
-      ].filter(Boolean).join('  ')
-
-      switchTable[kswitch] = {
-        desc: desc,
-        extra: extra
-      }
-    })
-    help.push.apply(help, formatTable(switchTable, 3))
+    if (keys.length) {
+      ui.div('Options:')
+
+      keys.forEach(function (key) {
+        var kswitch = switches[key]
+        var desc = descriptions[key] || ''
+        var type = null
+
+        if (~options.boolean.indexOf(key)) type = '[boolean]'
+        if (~options.count.indexOf(key)) type = '[count]'
+        if (~options.string.indexOf(key)) type = '[string]'
+        if (~options.normalize.indexOf(key)) type = '[string]'
+        if (~options.array.indexOf(key)) type = '[array]'
+
+        var extra = [
+            type,
+            demanded[key] ? '[required]' : null,
+            defaultString(options.default[key], options.defaultDescription[key])
+          ].filter(Boolean).join(' ')
+
+        ui.span(
+          {text: kswitch, padding: [0, 2, 0, 2], width: maxWidth(switches) + 4},
+          desc
+        )
+
+        if (extra) ui.div({text: extra, padding: [0, 0, 0, 2], align: 'right'})
+        else ui.div()
+      })
 
-    if (keys.length) help.push('')
+      ui.div()
+    }
 
     // describe some common use-cases for your application.
     if (examples.length) {
+      ui.div('Examples:')
+
       examples.forEach(function (example) {
         example[0] = example[0].replace(/\$0/g, yargs.$0)
       })
 
-      var examplesTable = {}
       examples.forEach(function (example) {
-        examplesTable[example[0]] = {
-          desc: example[1],
-          extra: ''
-        }
+        ui.div(
+          {text: example[0], padding: [0, 2, 0, 2], width: maxWidth(examples) + 4},
+          example[1]
+        )
       })
 
-      help.push.apply(help, ['Examples:'].concat(formatTable(examplesTable, 5), ''))
+      ui.div()
     }
 
     // the usage string.
     if (epilog) {
       var e = epilog.replace(/\$0/g, yargs.$0)
-      if (wrap) e = wordwrap(0, wrap)(e)
-      help.push(e, '')
+      ui.div(e + '\n')
     }
 
-    return help.join('\n')
+    return ui.toString()
+  }
+
+  // return the maximum width of a string
+  // in the left-hand column of a table.
+  function maxWidth (table) {
+    var width = 0
+
+    // table might be of the form [leftColumn],
+    // or {key: leftColumn}}
+    if (!Array.isArray(table)) {
+      table = Object.keys(table).map(function (key) {
+        return [table[key]]
+      })
+    }
+
+    table.forEach(function (v) {
+      width = Math.max(v[0].length, width)
+    })
+
+    // if we've enabled 'wrap' we should limit
+    // the max-width of the left-column.
+    if (wrap) width = Math.min(width, parseInt(wrap * 0.5, 10))
+
+    return width
   }
 
   // make sure any options set for aliases,
@@ -265,123 +294,7 @@ module.exports = function (yargs) {
     return string + ']'
   }
 
-  // word-wrapped two-column layout used by
-  // examples, options, commands.
-  function formatTable (table, padding) {
-    var output = []
-
-    // size of left-hand-column.
-    var llen = longest(Object.keys(table))
-
-    // don't allow the left-column to take up
-    // more than half of the screen.
-    if (wrap) {
-      llen = Math.min(llen, parseInt(wrap / 2, 10))
-    }
-
-    // size of right-column.
-    var desclen = longest(Object.keys(table).map(function (k) {
-      return table[k].desc
-    }))
-
-    Object.keys(table).forEach(function (left) {
-      var desc = table[left].desc,
-        extra = table[left].extra,
-        leftLines = null
-
-      if (wrap) {
-        desc = wordwrap(llen + padding + 1, wrap)(desc)
-        .slice(llen + padding + 1)
-      }
-
-      // if we need to wrap the left-hand-column,
-      // split it on to multiple lines.
-      if (wrap && left.length > llen) {
-        leftLines = wordwrap(2, llen)(left.trim()).split('\n')
-        left = ''
-      }
-
-      var lpadding = new Array(
-        Math.max(llen - left.length + padding, 0)
-      ).join(' ')
-
-      var dpadding = new Array(
-        Math.max(desclen - desc.length + 1, 0)
-      ).join(' ')
-
-      if (!wrap && dpadding.length > 0) {
-        desc += dpadding
-      }
-
-      var prelude = '  ' + left + lpadding
-
-      var body = [ desc, extra ].filter(Boolean).join('  ')
-
-      if (wrap) {
-        var dlines = desc.split('\n')
-        var dlen = dlines.slice(-1)[0].length
-        + (dlines.length === 1 ? prelude.length : 0)
-
-        if (extra.length > wrap) {
-          body = desc + '\n' + wordwrap(llen + 4, wrap)(extra)
-        } else {
-          body = desc + (dlen + extra.length > wrap - 2
-            ? '\n'
-            + new Array(wrap - extra.length + 1).join(' ')
-            + extra
-            : new Array(wrap - extra.length - dlen + 1).join(' ')
-            + extra
-          )
-        }
-      }
-
-      if (leftLines) { // handle word-wrapping the left-hand-column.
-        var rightLines = body.split('\n'),
-          firstLine = prelude + rightLines[0],
-          lineCount = Math.max(leftLines.length, rightLines.length)
-
-        for (var i = 0; i < lineCount; i++) {
-          var l = leftLines[i],
-            r = i ? rightLines[i] : firstLine
-
-          output.push(strcpy(l, r, firstLine.length))
-        }
-      } else {
-        output.push(prelude + body)
-      }
-    })
-
-    return output
-  }
-
-  // find longest string in array of strings.
-  function longest (xs) {
-    return Math.max.apply(
-      null,
-      xs.map(function (x) { return x.length })
-    )
-  }
-
-  // copy one string into another, used when
-  // formatting usage table.
-  function strcpy (source, destination, width) {
-    var str = ''
-
-    source = source || ''
-    destination = destination || new Array(width).join(' ')
-
-    for (var i = 0; i < destination.length; i++) {
-      var char = destination.charAt(i)
-
-      if (char === ' ') char = source.charAt(i) || char
-
-      str += char
-    }
-
-    return str
-  }
-
-  // guess the width of the console window, max-width 100.
+  // guess the width of the console window, max-width 80.
   function windowWidth () {
     return wsize.width ? Math.min(80, wsize.width) : null
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yargs",
-  "version": "3.7.2",
+  "version": "3.10.0",
   "description": "Light-weight option parsing with an argv hash. No optstrings attached.",
   "main": "./index.js",
   "files": [
@@ -11,40 +11,26 @@
   ],
   "dependencies": {
     "camelcase": "^1.0.2",
+    "cliui": "^2.1.0",
     "decamelize": "^1.0.0",
-    "window-size": "0.1.0",
-    "wordwrap": "0.0.2"
+    "window-size": "0.1.0"
   },
   "devDependencies": {
     "chai": "^2.2.0",
     "coveralls": "^2.11.2",
     "hashish": "0.0.4",
     "mocha": "^2.2.1",
-    "mocha-lcov-reporter": "0.0.2",
-    "mocoverage": "^1.0.0",
-    "patched-blanket": "^1.0.1",
-    "standard": "^3.6.0"
+    "nyc": "^2.2.1",
+    "standard": "^3.11.1"
   },
   "scripts": {
-    "test": "standard && mocha --check-leaks --ui exports --require patched-blanket -R mocoverage"
+    "test": "standard && nyc mocha --check-leaks && nyc report",
+    "coverage": "nyc report --reporter=text-lcov | coveralls"
   },
   "repository": {
     "type": "git",
     "url": "http://github.com/bcoe/yargs.git"
   },
-  "config": {
-    "blanket": {
-      "pattern": [
-        "lib",
-        "index.js"
-      ],
-      "data-cover-never": [
-        "node_modules",
-        "test"
-      ],
-      "output-reporter": "spec"
-    }
-  },
   "standard": {
     "ignore": [
       "**/example/**"
@@ -86,9 +72,13 @@
     {
       "name": "Benjamin Horsleben",
       "url": "https://github.com/fizker"
+    },
+    {
+      "name": "Lin Clark",
+      "url": "https://github.com/linclark"
     }
   ],
-  "license": "MIT/X11",
+  "license": "MIT",
   "engine": {
     "node": ">=0.4"
   }