yargs 3.23.0 → 3.27.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## Change Log
 
+### v3.26.0 (2015/09/25 2:14 +00:00)
+
+- [#263](https://github.com/bcoe/yargs/pull/263) document count() and option() object keys (@nexdrew)
+- [#259](https://github.com/bcoe/yargs/pull/259) remove util in readme (@38elements)
+- [#258](https://github.com/bcoe/yargs/pull/258) node v4 builds, update deps (@nexdrew)
+- [#257](https://github.com/bcoe/yargs/pull/257) fix spelling errors (@dkoleary88)
+
+### v3.25.0 (2015/09/13 7:38 -07:00)
+
+- [#254](https://github.com/bcoe/yargs/pull/254) adds Japanese translation (@oti)
+- [#253](https://github.com/bcoe/yargs/pull/253) fixes for tests on Windows (@bcoe)
+
+### v3.24.0 (2015/09/04 12:02 +00:00)
+
+- [#248](https://github.com/bcoe/yargs/pull/248) reinstate os-locale, no spawning (@nexdrew)
+- [#249](https://github.com/bcoe/yargs/pull/249) use travis container-based infrastructure (@nexdrew)
+- [#247](https://github.com/bcoe/yargs/pull/247) upgrade standard (@nexdrew)
+
 ### v3.23.0 (2015/08/30 23:00 +00:00)
 
 - [#246](https://github.com/bcoe/yargs/pull/246) detect locale based only on environment variables (@bcoe)

package/README.md

@@ -66,7 +66,6 @@ bool.js:
 
 ````javascript
 #!/usr/bin/env node
-var util = require('util');
 var argv = require('yargs').argv;
 
 if (argv.s) {
@@ -180,7 +179,7 @@ console.log("The area is:", argv.w * argv.h);
 
     Missing required arguments: h
 
-After yer demands have been met, demand more! Ask for non-hypenated arguments!
+After yer demands have been met, demand more! Ask for non-hyphenated arguments!
 -----------------------------------------
 
 demand_count.js:
@@ -367,7 +366,7 @@ require('yargs').parse([ '-x', '1', '-y', '2' ])
 
 The rest of these methods below come in just before the terminating `.argv`.
 
-.alias(key, alias)
+<a name="alias"></a>.alias(key, alias)
 ------------------
 
 Set key names as equivalent such that updates to a key will propagate to aliases
@@ -387,18 +386,18 @@ Arguments without a corresponding flag show up in the `argv._` array.
 The script name or node command is available at `argv.$0` similarly to how `$0`
 works in bash or perl.
 
-If `yargs` is executed in an environment that embeds node and there's no script name (e.g. [Electron]
-(http://electron.atom.io/) or [nw.js](http://nwjs.io/)), it will ignore the first parameter since it
+If `yargs` is executed in an environment that embeds node and there's no script name (e.g.
+[Electron](http://electron.atom.io/) or [nw.js](http://nwjs.io/)), it will ignore the first parameter since it
 expects it to be the script name. In order to override this behavior, use `.parse(process.argv.slice(1))`
 instead of `.argv` and the first parameter won't be ignored.
 
-.array(key)
+<a name="array"></a>.array(key)
 ----------
 
 Tell the parser to interpret `key` as an array. If `.array('foo')` is set,
 `--foo foo bar` will be parsed as `['foo', 'bar']` rather than as `'foo'`.
 
-.boolean(key)
+<a name="boolean"></a>.boolean(key)
 -------------
 
 Interpret `key` as a boolean. If a non-flag option follows `key` in
@@ -419,7 +418,7 @@ Check that certain conditions are met in the provided arguments.
 If `fn` throws or returns a non-truthy value, show the thrown error, usage information, and
 exit.
 
-.choices(key, choices)
+<a name="choices"></a>.choices(key, choices)
 ----------------------
 
 Limit valid values for `key` to a predefined set of `choices`, given as an array
@@ -530,7 +529,7 @@ var argv = require('yargs')
   .argv;
 ```
 
-.config(key, [description])
+<a name="config"></a>.config(key, [description])
 ------------
 
 Tells the parser that if the option specified by `key` is passed in, it
@@ -539,7 +538,13 @@ and parsed, and its properties are set as arguments. If present, the
 `description` parameter customizes the description of the config (`key`) option
 in the usage string.
 
-.default(key, value, [description])
+<a name="count"></a>.count(key)
+------------
+
+Interpret `key` as a boolean flag, but set its parsed value to the number of
+flag occurrences rather than `true` or `false`. Default value is thus `0`.
+
+<a name="default"></a>.default(key, value, [description])
 --------------------
 
 Set `argv[key]` to `value` if no option was specified in `process.argv`.
@@ -563,7 +568,7 @@ displaying the value in the usage instructions:
 .default('timeout', 60000, '(one-minute)')
 ```
 
-<a name="demand-key-msg-boolean"></a>.demand(key, [msg | boolean])
+<a name="demand"></a>.demand(key, [msg | boolean])
 ------------------------------
 .demand(count, [max], [msg])
 ------------------------------
@@ -583,13 +588,18 @@ instead of the standard error message. This is especially helpful for the non-op
 If a `boolean` value is given, it controls whether the option is demanded;
 this is useful when using `.options()` to specify command line parameters.
 
-.describe(key, desc)
+<a name="describe"></a>.describe(key, desc)
 --------------------
 
 Describe a `key` for the generated usage information.
 
 Optionally `.describe()` can take an object that maps keys to descriptions.
 
+.detectLocale(boolean)
+-----------
+
+Should yargs attempt to detect the os' locale? Defaults to `true`.
+
 .epilog(str)
 ------------
 .epilogue(str)
@@ -709,7 +719,9 @@ Locales currently supported:
 * **en:** American English.
 * **es:** Spanish.
 * **fr:** French.
+* **ja:** Japanese.
 * **pt:** Portuguese.
+* **zh:** Chinese.
 * **pirate:** American Pirate.
 
 To submit a new translation for yargs:
@@ -717,12 +729,7 @@ To submit a new translation for yargs:
 1. use `./locales/en.json` as a starting point.
 2. submit a pull request with the new locale file.
 
-.detectLocale(boolean)
------------
-
-Should yargs attempt to detect the os' locale? defaults to `true`.
-
-.nargs(key, count)
+<a name="nargs"></a>.nargs(key, count)
 -----------
 
 The number of arguments that should be consumed after a key. This can be a
@@ -793,6 +800,27 @@ var argv = require('yargs')
 ;
 ````
 
+Valid `opt` keys include:
+
+- `alias`: string or array of strings, alias(es) for the canonical option key, see [`alias()`](#alias)
+- `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)
+- `config`: boolean, interpret option as a path to a JSON config file, see [`config()`](#config)
+- `count`: boolean, interpret option as a count of boolean flags, see [`count()`](#count)
+- `default`: value, set a default value for the option, see [`default()`](#default)
+- `defaultDescription`: string, use this description for the default value in help content, see [`default()`](#default)
+- `demand`/`require`/`required`: boolean or string, demand the option be given, with optional error message, see [`demand()`](#demand)
+- `desc`/`describe`/`description`: string, the option description for help content, see [`describe()`](#describe)
+- `nargs`: number, specify how many arguments should be consumed for the option, see [`nargs()`](#nargs)
+- `requiresArg`: boolean, require the option be specified with a value, see [`requiresArg()`](#requiresArg)
+- `string`: boolean, interpret option as a string, see [`string()`](#string)
+- `type`: one of the following strings
+    - `'array'`: synonymous for `array: true`, see [`array()`](#array)
+    - `'boolean'`: synonymous for `boolean: true`, see [`boolean()`](#boolean)
+    - `'count'`: synonymous for `count: true`, see [`count()`](#count)
+    - `'string'`: synonymous for `string: true`, see [`string()`](#string)
+
 .parse(args)
 ------------
 
@@ -803,9 +831,9 @@ Parse `args` instead of `process.argv`. Returns the `argv` object.
 .required(key, [msg | boolean])
 ------------------------------
 
-An alias for [`demand()`](#demand-key-msg-boolean). See docs there.
+An alias for [`demand()`](#demand). See docs there.
 
-.requiresArg(key)
+<a name="requiresArg"></a>.requiresArg(key)
 -----------------
 
 Specifies either a single option key (string), or an array of options that
@@ -919,7 +947,7 @@ Specify --help for available options
 Any command-line argument given that is not demanded, or does not have a
 corresponding description, will be reported as an error.
 
-.string(key)
+<a name="string"></a>.string(key)
 ------------
 
 Tell the parser logic not to interpret `key` as a number or boolean.
@@ -1016,7 +1044,7 @@ Use `--` to stop parsing flags and stuff the remainder into `argv._`.
 negate fields
 -------------
 
-If you want to explicity set a field to false instead of just leaving it
+If you want to explicitly set a field to false instead of just leaving it
 undefined or to override a default you can do `--no-key`.
 
     $ node examples/reflect.js -a --no-b

package/index.js

@@ -1,6 +1,5 @@
 var assert = require('assert')
 var Completion = require('./lib/completion')
-var locale = require('./lib/locale')
 var Parser = require('./lib/parser')
 var path = require('path')
 var Usage = require('./lib/usage')
@@ -31,8 +30,7 @@ function Argv (processArgs, cwd) {
       // bin file with #!/usr/bin/env node
       if (i === 0 && /\b(node|iojs)$/.test(x)) return
       var b = rebase(cwd, x)
-      return x.match(/^\//) && b.length < x.length
-      ? b : x
+      return x.match(/^\//) && b.length < x.length ? b : x
     })
     .join(' ').trim()
 
@@ -513,13 +511,16 @@ function Argv (processArgs, cwd) {
       return
     }
 
+    var helpOrVersion = false
     Object.keys(argv).forEach(function (key) {
       if (key === helpOpt && argv[key]) {
+        helpOrVersion = true
         self.showHelp('log')
         if (exitProcess) {
           process.exit(0)
         }
       } else if (key === versionOpt && argv[key]) {
+        helpOrVersion = true
         usage.showVersion()
         if (exitProcess) {
           process.exit(0)
@@ -527,18 +528,22 @@ function Argv (processArgs, cwd) {
       }
     })
 
-    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.limitedChoices(argv)
-      validation.implications(argv)
+    // If the help or version options where used and exitProcess is false,
+    // we won't run validations
+    if (!helpOrVersion) {
+      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.limitedChoices(argv)
+        validation.implications(argv)
+      }
     }
 
     setPlaceholderKeys(argv)
@@ -548,7 +553,14 @@ function Argv (processArgs, cwd) {
 
   function guessLocale () {
     if (!detectLocale) return
-    self.locale(locale())
+
+    try {
+      var osLocale = require('os-locale')
+      self.locale(osLocale.sync({ spawn: false }))
+    } catch (err) {
+      // if we explode looking up locale just noop
+      // we'll keep using the default language 'en'.
+    }
   }
 
   function setPlaceholderKeys (argv) {
@@ -580,9 +592,7 @@ function sigletonify (inst) {
     if (key === 'argv') {
       Argv.__defineGetter__(key, inst.__lookupGetter__(key))
     } else {
-      Argv[key] = typeof inst[key] === 'function'
-      ? inst[key].bind(inst)
-      : inst[key]
+      Argv[key] = typeof inst[key] === 'function' ? inst[key].bind(inst) : inst[key]
     }
   })
 }

package/lib/parser.js

@@ -304,8 +304,7 @@ module.exports = function (args, opts, y18n) {
           })
 
           argv.__defineGetter__(key, function () {
-            return typeof val === 'string' ?
-            path.normalize(val) : val
+            return typeof val === 'string' ? path.normalize(val) : val
           })
         })
         break

package/lib/usage.js

@@ -28,17 +28,22 @@ module.exports = function (yargs, y18n) {
     return self
   }
 
+  var failureOutput = false
   self.fail = function (msg) {
     if (fails.length) {
       fails.forEach(function (f) {
         f(msg)
       })
     } else {
-      if (showHelpOnFail) yargs.showHelp('error')
-      if (msg) console.error(msg)
-      if (failMessage) {
-        if (msg) console.error('')
-        console.error(failMessage)
+      // don't output failure message more than once
+      if (!failureOutput) {
+        failureOutput = true
+        if (showHelpOnFail) yargs.showHelp('error')
+        if (msg) console.error(msg)
+        if (failMessage) {
+          if (msg) console.error('')
+          console.error(failMessage)
+        }
       }
       if (yargs.getExitProcess()) {
         process.exit(1)

package/locales/ja.json

@@ -0,0 +1,36 @@
+{
+  "Commands:": "コマンド:",
+  "Options:": "オプション:",
+  "Examples:": "例:",
+  "boolean": "真偽",
+  "count": "カウント",
+  "string": "文字列",
+  "array": "配列",
+  "required": "必須",
+  "default:": "デフォルト:",
+  "choices:": "選択してください:",
+  "generated-value": "生成された値",
+  "Not enough non-option arguments: got %s, need at least %s": "オプションではない引数が %s 個では不足しています。少なくとも %s 個の引数が必要です:",
+  "Too many non-option arguments: got %s, maximum of %s": "オプションではない引数が %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の設定ファイルまでのpath",
+  "Show help": "ヘルプを表示",
+  "Show version number": "バージョンを表示"
+}

package/locales/zh.json

@@ -0,0 +1,36 @@
+{
+  "Commands:": "命令：",
+  "Options:": "选项：",
+  "Examples:": "示例：",
+  "boolean": "boolean",
+  "count": "count",
+  "string": "string",
+  "array": "array",
+  "required": "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": "显示版本号"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yargs",
-  "version": "3.23.0",
+  "version": "3.27.0",
   "description": "Light-weight option parsing with an argv hash. No optstrings attached.",
   "main": "./index.js",
   "files": [
@@ -14,20 +14,22 @@
     "camelcase": "^1.2.1",
     "cliui": "^2.1.0",
     "decamelize": "^1.0.0",
+    "os-locale": "^1.4.0",
     "window-size": "^0.1.2",
-    "y18n": "^3.1.0"
+    "y18n": "^3.2.0"
   },
   "devDependencies": {
-    "chai": "^3.2.0",
+    "chai": "^3.3.0",
     "coveralls": "^2.11.4",
     "hashish": "0.0.4",
-    "mocha": "^2.3.0",
-    "nyc": "^3.1.0",
-    "standard": "^5.1.1"
+    "mocha": "^2.3.3",
+    "nyc": "^3.2.2",
+    "standard": "^5.3.1",
+    "which": "^1.1.2",
+    "win-spawn": "^2.0.0"
   },
   "scripts": {
-    "test": "standard && nyc mocha --timeout=4000 --check-leaks",
-    "test-windows": "mocha --timeout=4000",
+    "test": "standard && nyc ./node_modules/.bin/_mocha --timeout=4000 --check-leaks",
     "coverage": "nyc report --reporter=text-lcov | coveralls"
   },
   "repository": {

package/lib/locale.js

@@ -1,19 +0,0 @@
-// port of https://github.com/sindresorhus/os-locale
-// that only looks at environment variables.
-module.exports = function () {
-  return getEnvLocale()
-}
-
-function getEnvLocale () {
-  var env = process.env
-  var ret = env.LC_ALL || env.LANGUAGE || env.LANG || env.LC_MESSAGES
-  return getLocale(ret)
-}
-
-function getLocale (str) {
-  return (str && str.replace(/[.:].*/, '')) || fallback()
-}
-
-function fallback () {
-  return 'en_US'
-}