optionator - npm Package Compare versions

Comparing version 0.6.0 to 0.7.0

CHANGELOG.md

@@ -0,1 +1,9 @@
+# 0.7.0
+- added `concatRepeatedArrays` option: `oneValuePerFlag`, only allows one array value per flag
+- added `typeAliases` option
+- added `parseArgv` which takes an array and parses with the first two items sliced off
+- changed enum help style
+- bug fixes (#12)
+- use of `concatRepeatedArrays` and `mergeRepeatedObjects` at the top level is deprecated, use it as either a per-option option, or set them in the `defaults` object to set them for all objects
+
 # 0.6.0
@@ -2,0 +10,0 @@ - added `defaults` lib-option flag, allowing one to set default properties for all options

lib/help.js

@@ -1,9 +0,9 @@
-// Generated by LiveScript 1.3.1
+// Generated by LiveScript 1.4.0
 (function(){
-  var ref$, id, find, sort, min, max, map, unlines, nameToRaw, dasherize, wordwrap, getPreText, setHelpStyleDefaults, generateHelpForOption, generateHelp;
+  var ref$, id, find, sort, min, max, map, unlines, nameToRaw, dasherize, naturalJoin, wordwrap, getPreText, setHelpStyleDefaults, generateHelpForOption, generateHelp;
   ref$ = require('prelude-ls'), id = ref$.id, find = ref$.find, sort = ref$.sort, min = ref$.min, max = ref$.max, map = ref$.map, unlines = ref$.unlines;
-  ref$ = require('./util'), nameToRaw = ref$.nameToRaw, dasherize = ref$.dasherize;
+  ref$ = require('./util'), nameToRaw = ref$.nameToRaw, dasherize = ref$.dasherize, naturalJoin = ref$.naturalJoin;
   wordwrap = require('wordwrap');
   getPreText = function(option, arg$, maxWidth){
-    var mainName, shortNames, ref$, longNames, type, description, aliasSeparator, typeSeparator, initialIndent, names, namesString, namesStringLen, typeSeparatorString, typeSeparatorStringLen, typeString, that, wrap;
+    var mainName, shortNames, ref$, longNames, type, description, aliasSeparator, typeSeparator, initialIndent, names, namesString, namesStringLen, typeSeparatorString, typeSeparatorStringLen, wrap;
     mainName = option.option, shortNames = (ref$ = option.shortNames) != null
@@ -30,10 +30,9 @@ ? ref$
     typeSeparatorStringLen = typeSeparatorString.length;
-    typeString = (that = option['enum']) ? "One of: " + that.join(', ') : type;
-    if (maxWidth != null && !option.boolean && initialIndent + namesStringLen + typeSeparatorStringLen + typeString.length > maxWidth) {
+    if (maxWidth != null && !option.boolean && initialIndent + namesStringLen + typeSeparatorStringLen + type.length > maxWidth) {
       wrap = wordwrap(initialIndent + namesStringLen + typeSeparatorStringLen, maxWidth);
-      return namesString + "" + typeSeparatorString + wrap(typeString).replace(/^\s+/, '');
+      return namesString + "" + typeSeparatorString + wrap(type).replace(/^\s+/, '');
     } else {
       return namesString + "" + (option.boolean
         ? ''
-        : typeSeparatorString + "" + typeString);
+        : typeSeparatorString + "" + type);
     }
@@ -93,3 +92,3 @@ };
     return function(arg$){
-      var ref$, showHidden, interpolate, maxWidth, output, out, data, optionCount, totalPreLen, preLens, i$, len$, item, that, pre, desc, preLen, sortedPreLens, maxPreLen, preLenMean, x, padAmount, descSepLen, fullWrapCount, partialWrapCount, descLen, totalLen, initialSpace, wrapAllFull, i, wrap;
+      var ref$, showHidden, interpolate, maxWidth, output, out, data, optionCount, totalPreLen, preLens, i$, len$, item, that, pre, descParts, desc, preLen, sortedPreLens, maxPreLen, preLenMean, x, padAmount, descSepLen, fullWrapCount, partialWrapCount, descLen, totalLen, initialSpace, wrapAllFull, i, wrap;
       ref$ = arg$ != null
@@ -121,7 +120,13 @@ ? arg$
             pre = getPreText(item, helpStyle, maxWidth);
-            desc = item['default'] && !item.negateName
-              ? (that = item.description) != null
-                ? that + " - default: " + item['default']
-                : "default: " + item['default']
-              : (that = item.description) != null ? that : '';
+            descParts = [];
+            if ((that = item.description) != null) {
+              descParts.push(that);
+            }
+            if (that = item['enum']) {
+              descParts.push("either: " + naturalJoin(that));
+            }
+            if (item['default'] && !item.negateName) {
+              descParts.push("default: " + item['default']);
+            }
+            desc = descParts.join(' - ');
             data.push({
@@ -128,0 +133,0 @@ type: 'option',

lib/index.js

@@ -1,8 +0,8 @@
-// Generated by LiveScript 1.3.1
+// Generated by LiveScript 1.4.0
 (function(){
-  var VERSION, ref$, id, map, compact, any, groupBy, partition, chars, isItNaN, keys, Obj, camelize, deepIs, closestString, nameToRaw, dasherize, generateHelp, generateHelpForOption, parsedTypeCheck, parseType, parseLevn, camelizeKeys, parseString, main, toString$ = {}.toString, slice$ = [].slice;
-  VERSION = '0.6.0';
+  var VERSION, ref$, id, map, compact, any, groupBy, partition, chars, isItNaN, keys, Obj, camelize, deepIs, closestString, nameToRaw, dasherize, naturalJoin, generateHelp, generateHelpForOption, parsedTypeCheck, parseType, parseLevn, camelizeKeys, parseString, main, toString$ = {}.toString, slice$ = [].slice;
+  VERSION = '0.7.0';
   ref$ = require('prelude-ls'), id = ref$.id, map = ref$.map, compact = ref$.compact, any = ref$.any, groupBy = ref$.groupBy, partition = ref$.partition, chars = ref$.chars, isItNaN = ref$.isItNaN, keys = ref$.keys, Obj = ref$.Obj, camelize = ref$.camelize;
   deepIs = require('deep-is');
-  ref$ = require('./util'), closestString = ref$.closestString, nameToRaw = ref$.nameToRaw, dasherize = ref$.dasherize;
+  ref$ = require('./util'), closestString = ref$.closestString, nameToRaw = ref$.nameToRaw, dasherize = ref$.dasherize, naturalJoin = ref$.naturalJoin;
   ref$ = require('./help'), generateHelp = ref$.generateHelp, generateHelpForOption = ref$.generateHelpForOption;
@@ -38,2 +38,3 @@ ref$ = require('type-check'), parsedTypeCheck = ref$.parsedTypeCheck, parseType = ref$.parseType;
     libOptions.positionalAnywhere == null && (libOptions.positionalAnywhere = true);
+    libOptions.typeAliases == null && (libOptions.typeAliases = {});
     libOptions.defaults == null && (libOptions.defaults = {});
@@ -43,3 +44,3 @@ libOptions.defaults.concatRepeatedArrays = libOptions.concatRepeatedArrays;
     traverse = function(options){
-      var i$, len$, option, name, k, ref$, v, e, parsedPossibilities, parsedType, j$, len1$, possibility, that, rawDependsType, dependsOpts, dependsType, alias, shortNames, longNames;
+      var i$, len$, option, name, k, ref$, v, type, that, e, parsedPossibilities, parsedType, j$, len1$, possibility, rawDependsType, dependsOpts, dependsType, cra, alias, shortNames, longNames;
       if (toString$.call(options).slice(8, -1) !== 'Array') {
@@ -67,3 +68,6 @@ throw new Error('No options defined.');
             try {
-              option.parsedType = parseType(option.type);
+              type = (that = libOptions.typeAliases[option.type]) != null
+                ? that
+                : option.type;
+              option.parsedType = parseType(type);
             } catch (e$) {
@@ -121,2 +125,12 @@ e = e$;
           opts[name] = option;
+          if (option.concatRepeatedArrays != null) {
+            cra = option.concatRepeatedArrays;
+            if ('Boolean' === toString$.call(cra).slice(8, -1)) {
+              option.concatRepeatedArrays = [cra, {}];
+            } else if (cra.length === 1) {
+              option.concatRepeatedArrays = [cra[0], {}];
+            } else if (cra.length !== 2) {
+              throw new Error("Invalid setting for concatRepeatedArrays");
+            }
+          }
           if (option.alias || option.aliases) {
@@ -160,3 +174,3 @@ if (name === 'NUM') {
     parse = function(input, arg$){
-      var slice, obj, positional, restPositional, overrideRequired, prop, setValue, setDefaults, checkRequired, mutuallyExclusiveError, checkMutuallyExclusive, checkDependency, checkDependencies, args, key, value, option, ref$, i$, len$, arg, that, result, short, argName, usingAssign, val, flags, len, j$, len1$, i, flag, opt, name, negated, noedName, valPrime;
+      var slice, obj, positional, restPositional, overrideRequired, prop, setValue, setDefaults, checkRequired, mutuallyExclusiveError, checkMutuallyExclusive, checkDependency, checkDependencies, args, key, value, option, ref$, i$, len$, arg, that, result, short, argName, usingAssign, val, flags, len, j$, len1$, i, flag, opt, name, valPrime, negated, noedName;
       slice = (arg$ != null
@@ -171,3 +185,3 @@ ? arg$
       setValue = function(name, value){
-        var opt, val, e, currentType;
+        var opt, val, cra, e, currentType;
         opt = getOption(name);
@@ -178,3 +192,8 @@ if (opt.boolean) {
           try {
-            val = parseLevn(opt.parsedType, value);
+            cra = opt.concatRepeatedArrays;
+            if (cra != null && cra[0] && cra[1].oneValuePerFlag && opt.parsedType.length === 1 && opt.parsedType[0].structure === 'array') {
+              val = [parseLevn(opt.parsedType[0].of, value)];
+            } else {
+              val = parseLevn(opt.parsedType, value);
+            }
           } catch (e$) {
@@ -187,3 +206,3 @@ e = e$;
           }, opt.parsedPossibilities)) {
-            throw new Error("Option " + name + ": '" + val + "' not in [" + opt['enum'].join(', ') + "].");
+            throw new Error("Option " + name + ": '" + val + "' not one of " + naturalJoin(opt['enum']) + ".");
           }
@@ -193,3 +212,3 @@ }
         if (obj[name] != null) {
-          if (opt.concatRepeatedArrays && currentType === 'Array') {
+          if (opt.concatRepeatedArrays != null && opt.concatRepeatedArrays[0] && currentType === 'Array') {
             obj[name] = obj[name].concat(val);
@@ -357,10 +376,15 @@ } else if (opt.mergeRepeatedObjects && currentType === 'Object') {
                   positional.push(flag);
-                } else if (opt.boolean) {
-                  setValue(name, true);
                 } else if (i === len - 1) {
                   if (usingAssign) {
-                    setValue(name, val);
+                    valPrime = opt.boolean ? parseLevn([{
+                      type: 'Boolean'
+                    }], val) : val;
+                    setValue(name, valPrime);
+                  } else if (opt.boolean) {
+                    setValue(name, true);
                   } else {
                     prop = name;
                   }
+                } else if (opt.boolean) {
+                  setValue(name, true);
                 } else {
@@ -427,2 +451,7 @@ throw new Error("Can't set argument '" + flag + "' when not last flag in a group of short flags.");
       parse: parse,
+      parseArgv: function(it){
+        return parse(it, {
+          slice: 2
+        });
+      },
       generateHelp: generateHelp(libOptions),
@@ -429,0 +458,0 @@ generateHelpForOption: generateHelpForOption(getOption, libOptions)

lib/util.js

@@ -1,4 +0,4 @@
-// Generated by LiveScript 1.2.0
+// Generated by LiveScript 1.4.0
 (function(){
-  var prelude, map, sortBy, fl, closestString, nameToRaw, dasherize;
+  var prelude, map, sortBy, fl, closestString, nameToRaw, dasherize, naturalJoin;
   prelude = require('prelude-ls'), map = prelude.map, sortBy = prelude.sortBy;
@@ -41,7 +41,15 @@ fl = require('fast-levenshtein');
   };
+  naturalJoin = function(array){
+    if (array.length < 3) {
+      return array.join(' or ');
+    } else {
+      return array.slice(0, -1).join(', ') + ", or " + array[array.length - 1];
+    }
+  };
   module.exports = {
     closestString: closestString,
     nameToRaw: nameToRaw,
-    dasherize: dasherize
+    dasherize: dasherize,
+    naturalJoin: naturalJoin
   };
 }).call(this);

package.json

 {
   "name": "optionator",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "author": "George Zahariev <[e-mail]>",
   "description": "option parsing and help generation",
   "homepage": "https://github.com/gkz/optionator",
-  "keywords": "options",
+  "keywords": [
+    "options",
+    "flags",
+    "option parsing",
+    "cli"
+  ],
   "files": [
@@ -15,8 +20,3 @@ "lib",
   "bugs": "https://github.com/gkz/optionator/issues",
-  "licenses": [
-    {
-      "type": "MIT",
-      "url": "https://raw.githubusercontent.com/gkz/optionator/master/LICENSE"
-    }
-  ],
+  "license": "MIT",
   "engines": {
@@ -33,5 +33,5 @@ "node": ">= 0.8.0"
   "dependencies": {
-    "prelude-ls": "~1.1.1",
+    "prelude-ls": "~1.1.2",
     "deep-is": "~0.1.3",
-    "wordwrap": "~0.0.2",
+    "wordwrap": "~1.0.0",
     "type-check": "~0.3.1",
@@ -42,6 +42,6 @@ "levn": "~0.2.5",
   "devDependencies": {
-    "LiveScript": "~1.3.1",
-    "mocha": "~2.0.1",
-    "istanbul": "~0.1.43"
+    "livescript": "~1.4.0",
+    "mocha": "~2.2.5",
+    "istanbul": "~0.3.14"
   }
 }

README.md

@@ -6,2 +6,4 @@ # Optionator
 
+Site: http://gkz.github.io/optionator/
+
 For an online demo, check out the [Grasp online demo](http://www.graspjs.com/#demo).
@@ -22,3 +24,3 @@
 
-Over helpful features include reformatting the help text based on the size of the console, so that it fits even if the console is narrow, and accepting not just an array (eg. process.argv), but a string or object as well, making things like testing much easier.
+Other helpful features include reformatting the help text based on the size of the console, so that it fits even if the console is narrow, and accepting not just an array (eg. process.argv), but a string or object as well, making things like testing much easier.
 
@@ -28,3 +30,3 @@ ## About
 
-MIT license. Version 0.6.0
+MIT license. Version 0.7.0
 
@@ -36,21 +38,27 @@ npm install optionator
 ## Usage
-`require('optionator');` returns a function. It has one property, `VERSION`, the current version of the library as a string. This function is called with an object specifying your options and other information, see the [settings format section](#settings-format). This in turn returns an object with three properties, `parse`, `generateHelp`, and `generateHelpForOption`, which are all functions.
+`require('optionator');` returns a function. It has one property, `VERSION`, the current version of the library as a string. This function is called with an object specifying your options and other information, see the [settings format section](#settings-format). This in turn returns an object with three properties, `parse`, `parseArgv`, `generateHelp`, and `generateHelpForOption`, which are all functions.
 
 ```js
 var optionator = require('optionator')({
-  prepend: 'Usage: cmd [options]',
-  append: 'Version 1.0.0',
-  options: [{
-    option: 'help',
-    alias: 'h',
-    type: 'Boolean',
-    description: 'displays help'
-  }, {
-    option: 'count',
-    alias: 'c',
-    type: 'Int',
-    description: 'number of things',
-    example: 'cmd --count 2'
-  }]
+    prepend: 'Usage: cmd [options]',
+    append: 'Version 1.0.0',
+    options: [{
+        option: 'help',
+        alias: 'h',
+        type: 'Boolean',
+        description: 'displays help'
+    }, {
+        option: 'count',
+        alias: 'c',
+        type: 'Int',
+        description: 'number of things',
+        example: 'cmd --count 2'
+    }]
 });
+
+var options = optionator.parseArgv(process.argv);
+if (options.help) {
+    console.log(optionator.generateHelp());
+}
+...
 ```
@@ -76,2 +84,16 @@
 
+### parseArgv(input)
+`parseArgv` works exactly like `parse`, but only for array input and it slices off the first two elements.
+
+##### arguments
+* input - `[String]` - the input you wish to parse
+
+##### returns
+See "returns" section in "parse"
+
+##### example
+```js
+parseArgv(process.argv);
+```
+
 ### generateHelp(helpOptions)
@@ -134,3 +156,3 @@ `generateHelp` produces help text based on your settings.
         dependsOn: [String] | String,
-        concatRepeatedArrays: Boolean,
+        concatRepeatedArrays: Boolean | (Boolean, Object),
         mergeRepeatedObjects: Boolean,
@@ -150,5 +172,6 @@ description: String,
       mutuallyExclusive: [[String | [String]]],
-      concatRepeatedArrays: Boolean,
-      mergeRepeatedObjects: Boolean,
+      concatRepeatedArrays: Boolean | (Boolean, Object), // deprecated, set in defaults object
+      mergeRepeatedObjects: Boolean, // deprecated, set in defaults object
       positionalAnywhere: Boolean,
+      typeAliases: Object,
       defaults: Object
@@ -165,5 +188,6 @@ }
 * `mutuallyExclusive` is an optional array of arrays of either strings or arrays of strings. The top level array is a list of rules, each rule is a list of elements - each element can be either a string (the name of an option), or a list of strings (a group of option names) - there will be an error if more than one element is present
-* `concatRepeatedArrays` is an optional boolean (defaults to `false`) - when set to `true` and an option contains an array value and is repeated, the subsequent values for the flag will be appended rather than overwriting the original value - eg. option `g` of type `[String]`: `-g a -g b -g c,d` will result in `['a','b','c','d']`
-* `mergeRepeatedObjects` is an optional boolean (defaults to `false`) - when set to `true` and an option contains an object value and is repeated, the subsequent values for the flag will be merged rather than overwriting the original value - eg. option `g` of type `Object`: `-g a:1 -g b:2 -g c:3,d:4` will result in `{a: 1, b: 2, c: 3, d: 4}`
+* `concatRepeatedArrays` see description under the "Option Properties" heading - use at the top level is deprecated, if you want to set this for all options, use the `defaults` property
+* `mergeRepeatedObjects` see description under the "Option Properties" heading - use at the top level is deprecated, if you want to set this for all options, use the `defaults` property
 * `positionalAnywhere` is an optional boolean (defaults to `true`) - when `true` it allows positional arguments anywhere, when `false`, all arguments after the first positional one are taken to be positional as well, even if they look like a flag. For example, with `positionalAnywhere: false`, the arguments `--flag --boom 12 --crack` would have two positional arguments: `12` and `--crack`
+* `typeAliases` is an optional object, it allows you to set aliases for types, eg. `{Path: 'String'}` would allow you to use the type `Path` as an alias for the type `String`
 * `defaults` is an optional object following the option properties format, which specifies default values for all options. A default will be overridden if manually set. For example, you can do `default: { type: "String" }` to set the default type of all options to `String`, and then override that default in an individual option by setting the `type` property
@@ -183,4 +207,6 @@
 * `overrideRequired` is a optional boolean - if set to `true` and the option is used, and there is another option which is required but not set, it will override the need for the required option and there will be no error - this is useful if you have required options and want to use `--help` or `--version` flags
-* `concatRepeatedArrays` an optional boolean - same as the description in the Top Level Properties description, but just for this option, not all of them
-* `mergeRepeatedObjects` an optional boolean - same as the description in the Top Level Properties description, but just for this option, not all of them
+* `concatRepeatedArrays` is an optional boolean or tuple with boolean and options object (defaults to `false`) - when set to `true` and an option contains an array value and is repeated, the subsequent values for the flag will be appended rather than overwriting the original value - eg. option `g` of type `[String]`: `-g a -g b -g c,d` will result in `['a','b','c','d']`
+
+ You can supply an options object by giving the following value: `[true, options]`. The one currently supported option is `oneValuePerFlag`, this only allows one array value per flag. This is useful if your potential values contain a comma.
+* `mergeRepeatedObjects` is an optional boolean (defaults to `false`) - when set to `true` and an option contains an object value and is repeated, the subsequent values for the flag will be merged rather than overwriting the original value - eg. option `g` of type `Object`: `-g a:1 -g b:2 -g c:3,d:4` will result in `{a: 1, b: 2, c: 3, d: 4}`
 * `dependsOn` is an optional string or array of strings - if simply a string (the name of another option), it will make sure that that other option is set, if an array of strings, depending on whether `'and'` or `'or'` is first, it will either check whether all (`['and', 'option-a', 'option-b']`), or at least one (`['or', 'option-a', 'option-b']`) other options are set
@@ -187,0 +213,0 @@ * `description` is an optional string, which will be displayed next to the option in the help text

No alert changes

Improved metrics

Total package byte prevSize

61090

increased by5.66%

Lines of code

1271

increased by3.42%

Number of lines in readme file

239

increased by12.21%

Dependency changes

• + Addedwordwrap@1.0.0(transitive)

• - Removedwordwrap@0.0.3(transitive)

• Updatedprelude-ls@~1.1.2

• Updatedwordwrap@~1.0.0