yargs 3.30.0 → 3.31.0

package/CHANGELOG.md

@@ -1,8 +1,18 @@
 ## Change Log
 
+### v3.31.0 (2015/12/03 10:15 +07:00)
+
+- [#239](https://github.com/bcoe/yargs/pull/239) Pass argv to commands (@bcoe)
+- [#308](https://github.com/bcoe/yargs/pull/308) Yargs now handles environment variables (@nexdrew)
+- [#302](https://github.com/bcoe/yargs/pull/302) Add Indonesian translation (@rilut)
+- [#300](https://github.com/bcoe/yargs/pull/300) Add Turkish translation (@feyzo)
+- [#298](https://github.com/bcoe/yargs/pull/298) Add Norwegian Bokmål translation (@sindresorhus)
+- [#297](https://github.com/bcoe/yargs/pull/297) Fix for layout of cjk characters (@disjukr)
+- [#296](https://github.com/bcoe/yargs/pull/296) Add Korean translation (@disjukr)
+
 ### v3.30.0 (2015/11/13 16:29 +07:00)
 
-- [#293](https://github.com/bcoe/yargs/pull/293) Polish language support (@kamilogorek).
+- [#293](https://github.com/bcoe/yargs/pull/293) Polish language support (@kamilogorek)
 - [#291](https://github.com/bcoe/yargs/pull/291) fix edge-cases with `.alias()` (@bcoe)
 - [#289](https://github.com/bcoe/yargs/pull/289) group options in custom groups (@bcoe)
 

package/README.md

@@ -463,8 +463,14 @@ 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
-of `yargs`, which can be used to compose nested commands.
+a given command is provided. The handler will be called with `yargs` and
+`argv` as arguments.
+
+`yargs` is a blank instance of yargs, which can be used to compose a nested
+hierarchy of options handlers.
+
+`argv` represents the arguments parsed prior to the
+command being executed (those described in the outer yargs instance).
 
 Here's an example of top-level and nested commands in action:
 
@@ -472,7 +478,7 @@ Here's an example of top-level and nested commands in action:
 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', function (yargs) {
+  .command('publish', 'shiver me timbers, should you be sharing all that', function (yargs, argv) {
     argv = yargs.option('f', {
       alias: 'force',
       description: 'yar, it usually be a bad idea'
@@ -614,6 +620,63 @@ Optionally `.describe()` can take an object that maps keys to descriptions.
 
 Should yargs attempt to detect the os' locale? Defaults to `true`.
 
+.env([prefix])
+--------------
+
+Tell yargs to parse environment variables matching the given prefix and apply
+them to argv as though they were command line arguments.
+
+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.
+
+Program arguments are defined in this order of precedence:
+
+1. Command line args
+2. Config file
+3. Env var
+4. Configured defaults
+
+```js
+var argv = require('yargs')
+  .env('MY_PROGRAM')
+  .option('f', {
+    alias: 'fruit-thing',
+    default: 'apple'
+  })
+  .argv
+console.log(argv)
+```
+
+```
+$ node fruity.js
+{ _: [],
+  f: 'apple',
+  'fruit-thing': 'apple',
+  fruitThing: 'apple',
+  '$0': 'fruity.js' }
+```
+
+```
+$ MY_PROGRAM_FRUIT_THING=banana node fruity.js
+{ _: [],
+  fruitThing: 'banana',
+  f: 'banana',
+  'fruit-thing': 'banana',
+  '$0': 'fruity.js' }
+```
+
+```
+$ MY_PROGRAM_FRUIT_THING=banana node fruity.js -f cat
+{ _: [],
+  f: 'cat',
+  'fruit-thing': 'cat',
+  fruitThing: 'cat',
+  '$0': 'fruity.js' }
+```
+
+Env var parsing is disabled by default, but you can also explicitly disable it
+by calling `.env(false)`, e.g. if you need to undo previous configuration.
+
 .epilog(str)
 ------------
 .epilogue(str)
@@ -754,17 +817,23 @@ Locales currently supported:
 * **en:** American English.
 * **es:** Spanish.
 * **fr:** French.
+* **id:** Indonesian.
 * **ja:** Japanese.
+* **ko:** Korean.
+* **nb:** Norwegian Bokmål.
+* **pirate:** American Pirate.
 * **pt:** Portuguese.
 * **pt_BR:** Brazilian Portuguese.
+* **tr:** Turkish.
 * **zh:** Chinese.
-* **pirate:** American Pirate.
 
 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.
 
+*The [Microsoft Terminology Search](http://www.microsoft.com/Language/en-US/Search.aspx) can be useful for finding the correct terminology in your locale.*
+
 <a name="nargs"></a>.nargs(key, count)
 -----------
 

package/index.js

@@ -58,7 +58,8 @@ function Argv (processArgs, cwd) {
       requiresArg: [],
       count: [],
       normalize: [],
-      config: []
+      config: [],
+      envPrefix: undefined
     }
 
     usage = Usage(self, y18n) // handle usage output.
@@ -342,6 +343,14 @@ function Argv (processArgs, cwd) {
     return groups
   }
 
+  // as long as options.envPrefix is not undefined,
+  // parser will apply env vars matching prefix to argv
+  self.env = function (prefix) {
+    if (prefix === false) options.envPrefix = undefined
+    else options.envPrefix = prefix || ''
+    return self
+  }
+
   self.wrap = function (cols) {
     usage.wrap(cols)
     return self
@@ -510,7 +519,7 @@ function Argv (processArgs, cwd) {
     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())
+        runCommand(command, self, argv)
         return self.argv
       }
     }
@@ -592,6 +601,11 @@ function Argv (processArgs, cwd) {
     }
   }
 
+  function runCommand (command, yargs, argv) {
+    setPlaceholderKeys(argv)
+    yargs.getCommandHandlers()[command](yargs.reset(), argv)
+  }
+
   function setPlaceholderKeys (argv) {
     Object.keys(options.key).forEach(function (key) {
       // don't set placeholder keys for dot

package/lib/parser.js

@@ -220,7 +220,14 @@ module.exports = function (args, opts, y18n) {
     }
   }
 
+  // order of precedence:
+  // 1. command line arg
+  // 2. value from config file
+  // 3. value from env var
+  // 4. configured default value
+  applyEnvVars(opts, argv, true) // special case: check env vars that point to config file
   setConfig(argv)
+  applyEnvVars(opts, argv, false)
   applyDefaultsAndAliases(argv, aliases, defaults)
 
   Object.keys(flags.counts).forEach(function (key) {
@@ -351,6 +358,20 @@ module.exports = function (args, opts, y18n) {
     })
   }
 
+  function applyEnvVars (opts, argv, configOnly) {
+    if (typeof opts.envPrefix === 'undefined') return
+
+    var prefix = typeof opts.envPrefix === 'string' ? opts.envPrefix : ''
+    Object.keys(process.env).forEach(function (envVar) {
+      if (prefix === '' || envVar.lastIndexOf(prefix, 0) === 0) {
+        var key = camelCase(envVar.substring(prefix.length))
+        if (((configOnly && flags.configs[key]) || !configOnly) && (!(key in argv) || flags.defaulted[key])) {
+          setArg(key, process.env[envVar])
+        }
+      }
+    })
+  }
+
   function applyDefaultsAndAliases (obj, aliases, defaults) {
     Object.keys(defaults).forEach(function (key) {
       if (!hasKey(obj, key.split('.'))) {

package/lib/usage.js

@@ -2,6 +2,7 @@
 // failures, etc. keeps logging in one place.
 var cliui = require('cliui')
 var decamelize = require('decamelize')
+var stringWidth = require('string-width')
 var wsize = require('window-size')
 
 module.exports = function (yargs, y18n) {
@@ -260,7 +261,7 @@ module.exports = function (yargs, y18n) {
     }
 
     table.forEach(function (v) {
-      width = Math.max(v[0].length, width)
+      width = Math.max(stringWidth(v[0]), width)
     })
 
     // if we've enabled 'wrap' we should limit

package/locales/id.json

@@ -0,0 +1,37 @@
+
+{
+  "Commands:": "Perintah:",
+  "Options:": "Pilihan:",
+  "Examples:": "Contoh:",
+  "boolean": "boolean",
+  "count": "jumlah",
+  "string": "string",
+  "array": "larik",
+  "required": "diperlukan",
+  "default:": "bawaan:",
+  "choices:": "pilihan:",
+  "generated-value": "nilai-yang-dihasilkan",
+  "Not enough non-option arguments: got %s, need at least %s": "Argumen wajib kurang: hanya %s, minimal %s",
+  "Too many non-option arguments: got %s, maximum of %s": "Terlalu banyak argumen wajib: ada %s, maksimal %s",
+  "Missing argument value: %s": {
+    "one": "Kurang argumen: %s",
+    "other": "Kurang argumen: %s"
+  },
+  "Missing required argument: %s": {
+    "one": "Kurang argumen wajib: %s",
+    "other": "Kurang argumen wajib: %s"
+  },
+  "Unknown argument: %s": {
+    "one": "Argumen tak diketahui: %s",
+    "other": "Argumen tak diketahui: %s"
+  },
+  "Invalid values:": "Nilai-nilai tidak valid:",
+  "Argument: %s, Given: %s, Choices: %s": "Argumen: %s, Diberikan: %s, Pilihan: %s",
+  "Argument check failed: %s": "Pemeriksaan argument gagal: %s",
+  "Implications failed:": "Implikasi gagal:",
+  "Not enough arguments following: %s": "Kurang argumen untuk: %s",
+  "Invalid JSON config file: %s": "Berkas konfigurasi JSON tidak valid: %s",
+  "Path to JSON config file": "Alamat berkas konfigurasi JSON",
+  "Show help": "Lihat bantuan",
+  "Show version number": "Lihat nomor versi"
+}

package/locales/ko.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 설정파일 경로",
+  "Show help": "도움말을 보여줍니다",
+  "Show version number": "버전 넘버를 보여줍니다"
+}

package/locales/nb.json

@@ -0,0 +1,36 @@
+{
+  "Commands:": "Kommandoer:",
+  "Options:": "Alternativer:",
+  "Examples:": "Eksempler:",
+  "boolean": "boolsk",
+  "count": "antall",
+  "string": "streng",
+  "array": "matrise",
+  "required": "obligatorisk",
+  "default:": "standard:",
+  "choices:": "valg:",
+  "generated-value": "generert-verdi",
+  "Not enough non-option arguments: got %s, need at least %s": "Ikke nok ikke-alternativ argumenter: fikk %s, trenger minst %s",
+  "Too many non-option arguments: got %s, maximum of %s": "For mange ikke-alternativ argumenter: fikk %s, maksimum %s",
+  "Missing argument value: %s": {
+    "one": "Mangler argument verdi: %s",
+    "other": "Mangler argument verdier: %s"
+  },
+  "Missing required argument: %s": {
+    "one": "Mangler obligatorisk argument: %s",
+    "other": "Mangler obligatoriske argumenter: %s"
+  },
+  "Unknown argument: %s": {
+    "one": "Ukjent argument: %s",
+    "other": "Ukjente argumenter: %s"
+  },
+  "Invalid values:": "Ugyldige verdier:",
+  "Argument: %s, Given: %s, Choices: %s": "Argument: %s, Gitt: %s, Valg: %s",
+  "Argument check failed: %s": "Argument sjekk mislyktes: %s",
+  "Implications failed:": "Konsekvensene mislyktes:",
+  "Not enough arguments following: %s": "Ikke nok følgende argumenter: %s",
+  "Invalid JSON config file: %s": "Ugyldig JSON konfigurasjonsfil: %s",
+  "Path to JSON config file": "Bane til JSON konfigurasjonsfil",
+  "Show help": "Vis hjelp",
+  "Show version number": "Vis versjonsnummer"
+}

package/locales/tr.json

@@ -0,0 +1,36 @@
+{
+  "Commands:": "Komutlar:",
+  "Options:": "Seçenekler:",
+  "Examples:": "Örnekler:",
+  "boolean": "boolean",
+  "count": "sayı",
+  "string": "string",
+  "array": "array",
+  "required": "zorunlu",
+  "default:": "varsayılan:",
+  "choices:": "seçimler:",
+  "generated-value": "oluşturulan-değer",
+  "Not enough non-option arguments: got %s, need at least %s": "Seçenek dışı argümanlar yetersiz: %s bulundu, %s gerekli",
+  "Too many non-option arguments: got %s, maximum of %s": "Seçenek dışı argümanlar gereğinden fazla: %s bulundu, azami %s",
+  "Missing argument value: %s": {
+    "one": "Eksik argüman değeri: %s",
+    "other": "Eksik argüman değerleri: %s"
+  },
+  "Missing required argument: %s": {
+    "one": "Eksik zorunlu argüman: %s",
+    "other": "Eksik zorunlu argümanlar: %s"
+  },
+  "Unknown argument: %s": {
+    "one": "Bilinmeyen argüman: %s",
+    "other": "Bilinmeyen argümanlar: %s"
+  },
+  "Invalid values:": "Geçersiz değerler:",
+  "Argument: %s, Given: %s, Choices: %s": "Argüman: %s, Verilen: %s, Seçimler: %s",
+  "Argument check failed: %s": "Argüman kontrolü başarısız oldu: %s",
+  "Implications failed:": "Sonuçlar başarısız oldu:",
+  "Not enough arguments following: %s": "%s için yeterli argüman bulunamadı",
+  "Invalid JSON config file: %s": "Geçersiz JSON yapılandırma dosyası: %s",
+  "Path to JSON config file": "JSON yapılandırma dosya konumu",
+  "Show help": "Yardım detaylarını göster",
+  "Show version number": "Versiyon detaylarını göster"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yargs",
-  "version": "3.30.0",
+  "version": "3.31.0",
   "description": "Light-weight option parsing with an argv hash. No optstrings attached.",
   "main": "./index.js",
   "files": [
@@ -11,11 +11,12 @@
     "LICENSE"
   ],
   "dependencies": {
-    "camelcase": "^1.2.1",
+    "camelcase": "^2.0.1",
     "cliui": "^3.0.3",
     "decamelize": "^1.1.1",
     "os-locale": "^1.4.0",
-    "window-size": "^0.1.2",
+    "string-width": "^1.0.1",
+    "window-size": "^0.1.4",
     "y18n": "^3.2.0"
   },
   "devDependencies": {
@@ -24,9 +25,9 @@
     "coveralls": "^2.11.4",
     "es6-promise": "^3.0.2",
     "hashish": "0.0.4",
-    "mocha": "^2.3.3",
-    "nyc": "^3.2.2",
-    "standard": "^5.3.1",
+    "mocha": "^2.3.4",
+    "nyc": "^4.0.1",
+    "standard": "^5.4.1",
     "which": "^1.1.2",
     "win-spawn": "^2.0.0"
   },