command-line-args - npm Package Compare versions

Comparing version 1.0.0-3 to 1.0.0

bin/cli.js

 #!/usr/bin/env node
 "use strict";
+var cliArgs = require("../");
+var os = require("os");
+var fs = require("fs");
+var path = require("path");
+var ansi = require("ansi-escape-sequences");
 
+var tmpPath = path.join(os.tmpDir(), Date.now() + "-cla.js");
+
+process.stdin
+    .pipe(fs.createWriteStream(tmpPath))
+    .on("close", parseCla);
+    
+function parseCla(){
+    var cliOptions = require(tmpPath);
+    fs.unlinkSync(tmpPath);
+    
+    var cli = cliArgs(cliOptions);
+    try {
+        console.log(cli.parse());
+    } catch(err){
+        halt(err.message);
+    }
+}
+
+function halt(msg){
+    console.error(ansi.format(msg, "red"));
+    process.exit(1);
+}

lib/command-line-args.js

@@ -12,17 +12,36 @@ "use strict";
 /**
+A library to collect command-line args and generate a usage guide.
+
 @module command-line-args
 */
-module.exports = CliArgs;
+module.exports = CommandLineArgs;
 
 /**
-@param {module:command-line-args.argDefType}
-@param {string[]}
-@returns {object}
+@class
+@classdesc A class encapsulating operations you can perform using an [OptionDefinition](#exp_module_definition--OptionDefinition) array as input.
+@param {module:definition[]} - An optional array of [OptionDefinition](#exp_module_definition--OptionDefinition) objects
 @alias module:command-line-args
+@typicalname cli
+@example
+```js
+var commandLineArgs = require("command-line-args");
+var cli = commandLineArgs([
+    { name: "file" },
+    { name: "verbose" },
+    { name: "depth"}
+]);
+```
 */
-function CliArgs(definitions, argv){
-    if (!(this instanceof CliArgs)) return new CliArgs(definitions, argv);
+function CommandLineArgs(definitions){
+    if (!(this instanceof CommandLineArgs)) return new CommandLineArgs(definitions);
     this.definitions = new Definitions(definitions);
 }
-CliArgs.prototype.parse = function(argv){
+
+/**
+Returns an object containing all the values and flags set on the command line. By default it parses the global [`process.argv`](https://nodejs.org/api/process.html#process_process_argv) array.
+
+@param [argv] {string[]} - An array of strings, which if passed will be parsed instead of `process.argv`.
+@returns {object}
+*/
+CommandLineArgs.prototype.parse = function(argv){
     var self = this;
@@ -38,6 +57,15 @@
 
-    /* validate input */
-    var invalidMessage = this.definitions.validate(argv);
-    if (invalidMessage){
-        throw Error(invalidMessage);
+    /* expand --option=name style args */
+    var optEquals = option.optEquals;
+    if (argv.some(optEquals.test.bind(optEquals))){
+        var expandedArgs = [];
+        argv.forEach(function(arg){
+            var matches = arg.match(optEquals.re);
+            if (matches){
+                expandedArgs.push(matches[1], matches[2]);
+            } else {
+                expandedArgs.push(arg);
+            }
+        });
+        argv = expandedArgs;
     }
@@ -55,2 +83,8 @@
         });
+    }    
+
+    /* validate input */
+    var invalidMessage = this.definitions.validate(argv);
+    if (invalidMessage){
+        throw Error(invalidMessage);
     }
@@ -67,3 +101,6 @@
             if (!t.isDefined(output[def.name])) outputSet(output, def.name, def.getInitialValue())
-            if (def.isBoolean()) def = null;
+            if (def.isBoolean()) {
+                outputSet(output, def.name, true);
+                def = null;
+            }
 
@@ -84,2 +121,7 @@ } else {
     });
+    
+    /* clear _initial flags */
+    o.each(output, function(value, key){
+        if (Array.isArray(value) && value._initial) delete value._initial;
+    });
 
@@ -90,3 +132,2 @@ /* group the output values */
             _all: output,
-            _none: {}
         };
@@ -105,2 +146,3 @@
             if (t.isDefined(output[def.name])){
+                if (!grouped._none) grouped._none = {};
                 grouped._none[def.name] = output[def.name];
@@ -115,11 +157,17 @@ }
 
-CliArgs.prototype.getUsage = function(options){
+/**
+Generates a usage guide. Please see [command-line-usage](https://github.com/75lb/command-line-usage) for full instructions of how to use.
+
+@param [options] {object} - the options to pass to [command-line-usage](https://github.com/75lb/command-line-usage)
+@returns {string}
+*/
+CommandLineArgs.prototype.getUsage = function(options){
     return cliUsage(this.definitions.val(), options);
 };
 
-CliArgs.prototype.setUsage = function(usageGenerator){
-    cliUsage = usageGenerator;
-};
-
 function outputSet(output, property, value){
+    if (output[property] && output[property]._initial){
+        output[property] = [];
+        delete output[property]._initial;
+    }
     if (Array.isArray(output[property])){
@@ -126,0 +174,0 @@ output[property].push(value);

lib/definition.js

@@ -6,12 +6,31 @@ "use strict";
 */
-module.exports = Definition;
+module.exports = OptionDefinition;
 
 /**
 @class
-@classdesc Option Definition
+@classdesc Describes a command-line option.
 @alias module:definition
+@typicalname option
 */
-function Definition(definition){
+function OptionDefinition(definition){
     /**
-    @type {string}
+    * The only required definition property is `name`, so the simplest working example is
+    * ```js
+    * [
+    *     { name: "file" },
+    *     { name: "verbose" },
+    *     { name: "depth"}
+    * ]
+    * ```
+    * 
+    * In this case, the value of each option will be either a Boolean or string.
+    *
+    * | #   | Command line args | .parse() output |
+    * | --- | -------------------- | ------------ |
+    * | 1   | `--file` | `{ file: true }` |
+    * | 2   | `--file lib.js --verbose` | `{ file: "lib.js", verbose: true }` |
+    * | 3   | `--verbose very` | `{ verbose: "very" }` |
+    * | 4   | `--depth 2` | `{ depth: "2" }` |
+    * 
+    * @type {string}
     */
@@ -21,3 +40,33 @@ this.name = definition.name;
     /**
-    @type {function}
+    * The `type` value is a setter function (you receive the output from this), enabling you to be specific about the type and value received.
+    *
+    * You can use a class, if you like:
+    * 
+    * ```js
+    * var fs = require("fs");
+    * 
+    * function FileDetails(filename){
+    *     if (!(this instanceof FileDetails)) return new FileDetails(filename);
+    *     this.filename = filename;
+    *     this.exists = fs.existsSync(filename);
+    * }
+    * 
+    * module.exports = [
+    *     { name: "file", type: FileDetails },
+    *     { name: "depth", type: Number }
+    * ];
+    * ```
+    * 
+    * | #   | Command line args| .parse() output |
+    * | --- | ----------------- | ------------ |
+    * | 1   | `--file asdf.txt` | `{ file: { filename: 'asdf.txt', exists: false } }` |
+    * 
+    * The `--depth` option expects a `Number`. If no value was set, you will receive `null`. 
+    * 
+    * | #   | Command line args | .parse() output |
+    * | --- | ----------------- | ------------ |
+    * | 2   | `--depth` | `{ depth: null }` |
+    * | 3   | `--depth 2` | `{ depth: 2 }` |
+    * 
+    * @type {function}
     */
@@ -27,14 +76,37 @@ this.type = definition.type;
     /**
-    @type {string}
+    * getopt-style short option names. Must be a single character.
+    * 
+    * ```js
+    * [
+    *   { name: "hot", alias: "h", type: Boolean },
+    *   { name: "discount", alias: "d", type: Boolean },
+    *   { name: "courses", alias: "c" , type: Number }
+    * ]
+    * ```
+    * 
+    * | #   | Command line | .parse() output |
+    * | --- | ------------ | ------------ |
+    * | 1   | `-hcd` | `{ hot: true, courses: null, discount: true }` |
+    * | 2   | `-hdc 3` | `{ hot: true, discount: true, courses: 3 }` |
+    * 
+    * @type {string}
     */
-    this.description = definition.description;
-
-    /**
-    a single character
-    @type {string}
-    */
     this.alias = definition.alias;
 
     /**
-    @type {boolean}
+    * Set this flag if the option takes a list of values. You will receive an array of values passed through the `type` function (if specified).
+    *
+    * ```js
+    * module.exports = [
+    *     { name: "files", type: String, multiple: true }
+    * ];
+    * ```
+    * 
+    * | #   | Command line | .parse() output |
+    * | --- | ------------ | ------------ |
+    * | 1   | `--files one.js two.js` | `{ files: [ 'one.js', 'two.js' ] }` |
+    * | 2   | `--files one.js --files two.js` | `{ files: [ 'one.js', 'two.js' ] }` |
+    * | 3   | `--files *` | `{ files: [ 'one.js', 'two.js' ] }` |
+    * 
+    * @type {boolean}
     */
@@ -44,3 +116,17 @@ this.multiple = definition.multiple;
     /**
-    @type {boolean}
+    * Any unclaimed command-line args will be set on this option. This flag is typically set on the most commonly-used option to make for more concise usage (i.e. `$ myapp *.js` instead of `$ myapp --files *.js`).
+    *
+    * ```js
+    * module.exports = [
+    *     { name: "files", type: String, multiple: true, defaultOption: true }
+    * ];
+    * ```
+    * 
+    * | #   | Command line | .parse() output |
+    * | --- | ------------ | ------------ |
+    * | 1   | `--files one.js two.js` | `{ files: [ 'one.js', 'two.js' ] }` |
+    * | 2   | `one.js two.js` | `{ files: [ 'one.js', 'two.js' ] }` |
+    * | 3   | `*` | `{ files: [ 'one.js', 'two.js' ] }` |
+    * 
+    * @type {boolean}
     */
@@ -50,18 +136,91 @@ this.defaultOption = definition.defaultOption;
     /**
-    @type {string|string[]}
+    * An initial value for the option.
+    *
+    * ```js
+    * module.exports = [
+    *     { name: "files", type: String, multiple: true, defaultValue: [ "one.js" ] },
+    *     { name: "max", type: Number, defaultValue: 3 }
+    * ];
+    * ```
+    * 
+    * | #   | Command line | .parse() output |
+    * | --- | ------------ | ------------ |
+    * | 1   |  | `{ files: [ 'one.js' ], max: 3 }` |
+    * | 2   | `--files two.js` | `{ files: [ 'two.js' ], max: 3 }` |
+    * | 3   | `--max 4` | `{ files: [ 'one.js' ], max: 4 }` |
+    * 
+    * @type {*}
     */
-    this.group = definition.group;
+    this.defaultValue = definition.defaultValue;
 
     /**
-    @type {boolean}
+    * When your app has a large amount of options it makes sense to organise them in groups. 
+    * 
+    * ```js
+    * module.exports = [
+    *     { name: "verbose", group: "standard" },
+    *     { name: "help", group: [ "standard", "main" ] },
+    *     { name: "compress", group: [ "server", "main" ] },
+    *     { name: "static", group: "server" },
+    *     { name: "debug" }
+    * ];
+    * ```
+    * 
+    *<table>
+    *  <tr>
+    *    <th>#</th><th>Command Line</th><th>.parse() output</th>
+    *  </tr>
+    *  <tr>
+    *    <td>1</td><td><code>--verbose</code></td><td><pre><code>
+    *{ 
+    *  _all: { verbose: true }, 
+    *  standard: { verbose: true } 
+    *}
+    *</code></pre></td>
+    *  </tr>
+    *  <tr>
+    *    <td>2</td><td><code>--debug</code></td><td><pre><code>
+    *{ 
+    *  _all: { debug: true }, 
+    *  _none: { debug: true } 
+    *}
+    *</code></pre></td>
+    *  </tr>
+    *  <tr>
+    *    <td>3</td><td><code>--verbose --debug --compress</code></td><td><pre><code>
+    *{ 
+    *  _all: { 
+    *    verbose: true, 
+    *    debug: true, 
+    *    compress: true 
+    *  }, 
+    *  standard: { verbose: true }, 
+    *  server: { compress: true }, 
+    *  main: { compress: true }, 
+    *  _none: { debug: true } 
+    *}
+    *</code></pre></td>
+    *  </tr>
+    *  <tr>
+    *    <td>4</td><td><code>--compress</code></td><td><pre><code>
+    *{ 
+    *  _all: { compress: true }, 
+    *  server: { compress: true }, 
+    *  main: { compress: true } 
+    *}
+    *</code></pre></td>
+    *  </tr>
+    *</table>
+    *
+    * @type {string|string[]}
     */
-    this.required = definition.required;
+    this.group = definition.group;
 
-    /**
-    @type {boolean}
-    */
-    this.value = definition.value;
+    /* pick up any remaining properties */    
+    for (var prop in definition){
+        if (!this[prop]) this[prop] = definition[prop];
+    }
 }
 
-Definition.prototype.getInitialValue = function(){
+OptionDefinition.prototype.getInitialValue = function(){
     if (this.multiple){
@@ -75,4 +234,4 @@ return [];
 };
-Definition.prototype.isBoolean = function(){
+OptionDefinition.prototype.isBoolean = function(){
     return this.type === Boolean;
 };

lib/definitions.js

@@ -9,2 +9,3 @@ "use strict";
 @module definitions
+@private
 */
@@ -52,3 +53,6 @@ module.exports = Definitions;
     this.forEach(function(def){
-        if (def.value) output[def.name] = def.value;
+        if (def.defaultValue) output[def.name] = def.defaultValue;
+        if (Array.isArray(output[def.name])){
+            output[def.name]._initial = true;
+        }
     });
@@ -55,0 +59,0 @@ return output;

lib/option.js

@@ -5,2 +5,3 @@ "use strict";
 @module option
+@private
 */
@@ -24,5 +25,6 @@
         return this.short.test(arg) || this.long.test(arg);
-    }
+    },
+    optEquals: new Arg(/^(--[\w-]+)=(.*)/)
 };
 
 module.exports = option;

package.json

 {
   "name": "command-line-args",
-  "version": "1.0.0-3",
-  "description": "Command-line parser, usage text producer",
+  "version": "1.0.0",
+  "description": "A library to collect command-line args and generate a usage guide.",
   "repository": "https://github.com/75lb/command-line-args.git",
   "main": "lib/command-line-args",
-  "cla": "bin.cli.js",
+  "bin": "bin/cli.js",
   "scripts": {
     "test": "tape test/*.js",
-    "docs": "jsdoc2md -t jsdoc2md/README.hbs lib/*.js > README.md; echo"
+    "docs": "jsdoc2md -l off -t jsdoc2md/README.hbs lib/*.js > README.md; echo"
   },
@@ -21,3 +21,4 @@ "keywords": [
     "cli",
-    "command"
+    "command",
+    "line"
   ],
@@ -28,5 +29,7 @@ "author": "Lloyd Brookes",
     "jsdoc-to-markdown": "^1.1.1",
-    "tape": "^4"
+    "tape": "^4",
+    "test-value": "^1.0.0"
   },
   "dependencies": {
+    "ansi-escape-sequences": "^2.1.1",
     "array-tools": "^2",
@@ -33,0 +36,0 @@ "command-line-usage": "^1",

README.md

@@ -7,15 +7,60 @@ [![view on npm](http://img.shields.io/npm/v/command-line-args.svg)](https://www.npmjs.org/package/command-line-args)
 # command-line-args
-Collect command-line options, generate a usage guide..
+A library to collect command-line args and generate a usage guide.
 
-- Support most option notation styles
-    - long options (`--find lib.js`)
-    - short options (`-f lib.js`)
-    - getopt-style combinations (`-xvf  lib.js`)
-    - option=val style (`--find=lib.js`)
-- Customisable usage guide generator
-- Modular - define reusage option sets.
-- Split options into groups, for apps with a large set of options.
-- Fine control over validation, type
+## Synopsis
+You can set options using the main notation standards (getopt, getopt_long, etc.). These commands are all equivalent, setting the same values:
+```
+$ my-app --verbose --timeout=1000 --src one.js --src two.js
+$ my-app --verbose --timeout 1000 --src one.js two.js
+$ my-app -vt 1000 --src one.js two.js
+$ my-app -vt 1000 one.js two.js
+```
 
+To access the values, first describe the options your app accepts (see [option definitions](#option-definitions)).
+```js
+var commandLineArgs = require("command-line-args");
+
+var cli = commandLineArgs([
+    { name: "verbose", alias: "v", type: Boolean },
+    { name: "src", type: String, multiple: true, defaultOption: true },
+    { name: "timeout", alias: "t", type: Number }
+]);
+```
+The [`type`](#module_definition--OptionDefinition+type) property is a setter function (the value you receive is the output of this), giving you full control over the value received.
+
+Next, collect the command line args using [.parse()](#module_command-line-args--CommandLineArgs+parse):
+```js
+var options = cli.parse();
+```
+
+`options` now looks like this:
+```js
+{
+    files: [
+        "one.js",
+        "two.js"
+    ],
+    verbose: true,
+    timeout: 1000
+}
+```
+
+When dealing with large amounts of options it often makes sense to [group](#module_definition--Definition+group) them.
+
+The [.getUsage()](#module_command-line-args--CommandLineArgs+getUsage) method generates a usage guide. If you add descriptions to each option definition and call `.getUsage()` with some template data, for example:
+```js
+var usage = cli.getUsage({
+    title: "my-app",
+    description: "Generates something useful",
+    footer: "Project home: [underline]{https://github.com/me/my-app}"
+});
+```
+
+..then `usage`, written to the terminal, looks something like:
+
+![usage](https://raw.githubusercontent.com/75lb/command-line-usage/master/example/screens/typical.png)
+
 ## Install
+
+### as a library
 ```sh
@@ -25,77 +70,278 @@ $ npm install command-line-args --save
 
+### as a tool
+```sh
+$ npm install -g command-line-args
+```
 
+If you install globally you get the `command-line-args` test-harness. You test by piping in a module which exports an option definitions array. You can then view the `.parse()` output for the args you pass.
+
+For example:
+
+```sh
+$ cat example/typical.js | command-line-args lib/* --timeout=1000
+{ src:
+   [ 'lib/command-line-args.js',
+     'lib/definition.js',
+     'lib/definitions.js',
+     'lib/option.js' ],
+  timeout: 1000 }
+```
+
 # API Reference
-## Modules
-<dl>
-<dt><a href="#module_command-line-args">command-line-args</a></dt>
-<dd></dd>
-<dt><a href="#module_definition">definition</a></dt>
-<dd></dd>
-<dt><a href="#module_definitions">definitions</a></dt>
-<dd></dd>
-<dt><a href="#module_option">option</a></dt>
-<dd></dd>
-</dl>
 <a name="module_command-line-args"></a>
 ## command-line-args
-<a name="exp_module_command-line-args--CliArgs"></a>
-### CliArgs(definitions, argv) ⇒ <code>object</code> ⏏
-**Kind**: Exported function  
+A library to collect command-line args and generate a usage guide.
 
-| Param | Type |
-| --- | --- |
-| definitions | <code>module:command-line-args.argDefType</code> | 
-| argv | <code>Array.&lt;string&gt;</code> | 
 
-<a name="module_definition"></a>
-## definition
+* [command-line-args](#module_command-line-args)
+  * [CommandLineArgs](#exp_module_command-line-args--CommandLineArgs) ⏏
+    * [new CommandLineArgs(definitions)](#new_module_command-line-args--CommandLineArgs_new)
+    * [.parse([argv])](#module_command-line-args--CommandLineArgs+parse) ⇒ <code>object</code>
+    * [.getUsage([options])](#module_command-line-args--CommandLineArgs+getUsage) ⇒ <code>string</code>
 
-* [definition](#module_definition)
-  * [Definition](#exp_module_definition--Definition) ⏏
-    * [.name](#module_definition--Definition+name) : <code>string</code>
-    * [.type](#module_definition--Definition+type) : <code>function</code>
-    * [.description](#module_definition--Definition+description) : <code>string</code>
-    * [.alias](#module_definition--Definition+alias) : <code>string</code>
-    * [.multiple](#module_definition--Definition+multiple) : <code>boolean</code>
-    * [.defaultOption](#module_definition--Definition+defaultOption) : <code>boolean</code>
-    * [.group](#module_definition--Definition+group) : <code>string</code> &#124; <code>Array.&lt;string&gt;</code>
-    * [.value](#module_definition--Definition+value) : <code>boolean</code>
+<a name="exp_module_command-line-args--CommandLineArgs"></a>
+### CommandLineArgs ⏏
+A class encapsulating operations you can perform using an [OptionDefinition](#exp_module_definition--OptionDefinition) array as input.
 
-<a name="exp_module_definition--Definition"></a>
-### Definition ⏏
-Option Definition
+**Kind**: Exported class  
+<a name="new_module_command-line-args--CommandLineArgs_new"></a>
+#### new CommandLineArgs(definitions)
 
+| Param | Type | Description |
+| --- | --- | --- |
+| definitions | <code>[Array.&lt;definition&gt;](#module_definition)</code> | An optional array of [OptionDefinition](#exp_module_definition--OptionDefinition) objects |
+
+**Example**  
+```js
+var commandLineArgs = require("command-line-args");
+var cli = commandLineArgs([
+    { name: "file" },
+    { name: "verbose" },
+    { name: "depth"}
+]);
+```
+<a name="module_command-line-args--CommandLineArgs+parse"></a>
+#### cli.parse([argv]) ⇒ <code>object</code>
+Returns an object containing all the values and flags set on the command line. By default it parses the global [`process.argv`](https://nodejs.org/api/process.html#process_process_argv) array.
+
+**Kind**: instance method of <code>[CommandLineArgs](#exp_module_command-line-args--CommandLineArgs)</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [argv] | <code>Array.&lt;string&gt;</code> | An array of strings, which if passed will be parsed instead of `process.argv`. |
+
+<a name="module_command-line-args--CommandLineArgs+getUsage"></a>
+#### cli.getUsage([options]) ⇒ <code>string</code>
+Generates a usage guide. Please see [command-line-usage](https://github.com/75lb/command-line-usage) for full instructions of how to use.
+
+**Kind**: instance method of <code>[CommandLineArgs](#exp_module_command-line-args--CommandLineArgs)</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [options] | <code>object</code> | the options to pass to [command-line-usage](https://github.com/75lb/command-line-usage) |
+
+
+<a name="exp_module_definition--OptionDefinition"></a>
+## OptionDefinition ⏏
+Describes a command-line option.
+
 **Kind**: Exported class  
-<a name="module_definition--Definition+name"></a>
-#### definition.name : <code>string</code>
-**Kind**: instance property of <code>[Definition](#exp_module_definition--Definition)</code>  
-<a name="module_definition--Definition+type"></a>
-#### definition.type : <code>function</code>
-**Kind**: instance property of <code>[Definition](#exp_module_definition--Definition)</code>  
-<a name="module_definition--Definition+description"></a>
-#### definition.description : <code>string</code>
-**Kind**: instance property of <code>[Definition](#exp_module_definition--Definition)</code>  
-<a name="module_definition--Definition+alias"></a>
-#### definition.alias : <code>string</code>
-a single character
+* [OptionDefinition](#exp_module_definition--OptionDefinition) ⏏
+  * [.name](#module_definition--OptionDefinition+name) : <code>string</code>
+  * [.type](#module_definition--OptionDefinition+type) : <code>function</code>
+  * [.alias](#module_definition--OptionDefinition+alias) : <code>string</code>
+  * [.multiple](#module_definition--OptionDefinition+multiple) : <code>boolean</code>
+  * [.defaultOption](#module_definition--OptionDefinition+defaultOption) : <code>boolean</code>
+  * [.defaultValue](#module_definition--OptionDefinition+defaultValue) : <code>\*</code>
+  * [.group](#module_definition--OptionDefinition+group) : <code>string</code> &#124; <code>Array.&lt;string&gt;</code>
 
-**Kind**: instance property of <code>[Definition](#exp_module_definition--Definition)</code>  
-<a name="module_definition--Definition+multiple"></a>
-#### definition.multiple : <code>boolean</code>
-**Kind**: instance property of <code>[Definition](#exp_module_definition--Definition)</code>  
-<a name="module_definition--Definition+defaultOption"></a>
-#### definition.defaultOption : <code>boolean</code>
-**Kind**: instance property of <code>[Definition](#exp_module_definition--Definition)</code>  
-<a name="module_definition--Definition+group"></a>
-#### definition.group : <code>string</code> &#124; <code>Array.&lt;string&gt;</code>
-**Kind**: instance property of <code>[Definition](#exp_module_definition--Definition)</code>  
-<a name="module_definition--Definition+value"></a>
-#### definition.value : <code>boolean</code>
-**Kind**: instance property of <code>[Definition](#exp_module_definition--Definition)</code>  
-<a name="module_definitions"></a>
-## definitions
-<a name="module_option"></a>
-## option
+<a name="module_definition--OptionDefinition+name"></a>
+### option.name : <code>string</code>
+The only required definition property is `name`, so the simplest working example is
+```js
+[
+    { name: "file" },
+    { name: "verbose" },
+    { name: "depth"}
+]
+```
+
+In this case, the value of each option will be either a Boolean or string.
+
+| #   | Command line args | .parse() output |
+| --- | -------------------- | ------------ |
+| 1   | `--file` | `{ file: true }` |
+| 2   | `--file lib.js --verbose` | `{ file: "lib.js", verbose: true }` |
+| 3   | `--verbose very` | `{ verbose: "very" }` |
+| 4   | `--depth 2` | `{ depth: "2" }` |
+
+**Kind**: instance property of <code>[OptionDefinition](#exp_module_definition--OptionDefinition)</code>  
+<a name="module_definition--OptionDefinition+type"></a>
+### option.type : <code>function</code>
+The `type` value is a setter function (you receive the output from this), enabling you to be specific about the type and value received.
+
+You can use a class, if you like:
+
+```js
+var fs = require("fs");
+
+function FileDetails(filename){
+    if (!(this instanceof FileDetails)) return new FileDetails(filename);
+    this.filename = filename;
+    this.exists = fs.existsSync(filename);
+}
+
+module.exports = [
+    { name: "file", type: FileDetails },
+    { name: "depth", type: Number }
+];
+```
+
+| #   | Command line args| .parse() output |
+| --- | ----------------- | ------------ |
+| 1   | `--file asdf.txt` | `{ file: { filename: 'asdf.txt', exists: false } }` |
+
+The `--depth` option expects a `Number`. If no value was set, you will receive `null`. 
+
+| #   | Command line args | .parse() output |
+| --- | ----------------- | ------------ |
+| 2   | `--depth` | `{ depth: null }` |
+| 3   | `--depth 2` | `{ depth: 2 }` |
+
+**Kind**: instance property of <code>[OptionDefinition](#exp_module_definition--OptionDefinition)</code>  
+<a name="module_definition--OptionDefinition+alias"></a>
+### option.alias : <code>string</code>
+getopt-style short option names. Must be a single character.
+
+```js
+[
+  { name: "hot", alias: "h", type: Boolean },
+  { name: "discount", alias: "d", type: Boolean },
+  { name: "courses", alias: "c" , type: Number }
+]
+```
+
+| #   | Command line | .parse() output |
+| --- | ------------ | ------------ |
+| 1   | `-hcd` | `{ hot: true, courses: null, discount: true }` |
+| 2   | `-hdc 3` | `{ hot: true, discount: true, courses: 3 }` |
+
+**Kind**: instance property of <code>[OptionDefinition](#exp_module_definition--OptionDefinition)</code>  
+<a name="module_definition--OptionDefinition+multiple"></a>
+### option.multiple : <code>boolean</code>
+Set this flag if the option takes a list of values. You will receive an array of values passed through the `type` function (if specified).
+
+```js
+module.exports = [
+    { name: "files", type: String, multiple: true }
+];
+```
+
+| #   | Command line | .parse() output |
+| --- | ------------ | ------------ |
+| 1   | `--files one.js two.js` | `{ files: [ 'one.js', 'two.js' ] }` |
+| 2   | `--files one.js --files two.js` | `{ files: [ 'one.js', 'two.js' ] }` |
+| 3   | `--files *` | `{ files: [ 'one.js', 'two.js' ] }` |
+
+**Kind**: instance property of <code>[OptionDefinition](#exp_module_definition--OptionDefinition)</code>  
+<a name="module_definition--OptionDefinition+defaultOption"></a>
+### option.defaultOption : <code>boolean</code>
+Any unclaimed command-line args will be set on this option. This flag is typically set on the most commonly-used option to make for more concise usage (i.e. `$ myapp *.js` instead of `$ myapp --files *.js`).
+
+```js
+module.exports = [
+    { name: "files", type: String, multiple: true, defaultOption: true }
+];
+```
+
+| #   | Command line | .parse() output |
+| --- | ------------ | ------------ |
+| 1   | `--files one.js two.js` | `{ files: [ 'one.js', 'two.js' ] }` |
+| 2   | `one.js two.js` | `{ files: [ 'one.js', 'two.js' ] }` |
+| 3   | `*` | `{ files: [ 'one.js', 'two.js' ] }` |
+
+**Kind**: instance property of <code>[OptionDefinition](#exp_module_definition--OptionDefinition)</code>  
+<a name="module_definition--OptionDefinition+defaultValue"></a>
+### option.defaultValue : <code>\*</code>
+An initial value for the option.
+
+```js
+module.exports = [
+    { name: "files", type: String, multiple: true, defaultValue: [ "one.js" ] },
+    { name: "max", type: Number, defaultValue: 3 }
+];
+```
+
+| #   | Command line | .parse() output |
+| --- | ------------ | ------------ |
+| 1   |  | `{ files: [ 'one.js' ], max: 3 }` |
+| 2   | `--files two.js` | `{ files: [ 'two.js' ], max: 3 }` |
+| 3   | `--max 4` | `{ files: [ 'one.js' ], max: 4 }` |
+
+**Kind**: instance property of <code>[OptionDefinition](#exp_module_definition--OptionDefinition)</code>  
+<a name="module_definition--OptionDefinition+group"></a>
+### option.group : <code>string</code> &#124; <code>Array.&lt;string&gt;</code>
+When your app has a large amount of options it makes sense to organise them in groups. 
+
+```js
+module.exports = [
+    { name: "verbose", group: "standard" },
+    { name: "help", group: [ "standard", "main" ] },
+    { name: "compress", group: [ "server", "main" ] },
+    { name: "static", group: "server" },
+    { name: "debug" }
+];
+```
+
+<table>
+ <tr>
+   <th>#</th><th>Command Line</th><th>.parse() output</th>
+ </tr>
+ <tr>
+   <td>1</td><td><code>--verbose</code></td><td><pre><code>
+{ 
+ _all: { verbose: true }, 
+ standard: { verbose: true } 
+}
+</code></pre></td>
+ </tr>
+ <tr>
+   <td>2</td><td><code>--debug</code></td><td><pre><code>
+{ 
+ _all: { debug: true }, 
+ _none: { debug: true } 
+}
+</code></pre></td>
+ </tr>
+ <tr>
+   <td>3</td><td><code>--verbose --debug --compress</code></td><td><pre><code>
+{ 
+ _all: { 
+   verbose: true, 
+   debug: true, 
+   compress: true 
+ }, 
+ standard: { verbose: true }, 
+ server: { compress: true }, 
+ main: { compress: true }, 
+ _none: { debug: true } 
+}
+</code></pre></td>
+ </tr>
+ <tr>
+   <td>4</td><td><code>--compress</code></td><td><pre><code>
+{ 
+ _all: { compress: true }, 
+ server: { compress: true }, 
+ main: { compress: true } 
+}
+</code></pre></td>
+ </tr>
+</table>
+
+**Kind**: instance property of <code>[OptionDefinition](#exp_module_definition--OptionDefinition)</code>  
+
+
 * * *
 
 &copy; 2015 Lloyd Brookes \<[e-mail]\>. Documented by [jsdoc-to-markdown](https://github.com/75lb/jsdoc-to-markdown).

test/default-value.js

@@ -5,20 +5,34 @@ var test = require("tape");
 test("default value", function(t){
-    t.deepEqual(cliArgs([ { name: "one" }, { name: "two", value: "two" } ]).parse([ "--one", "1" ]), {
+    t.deepEqual(cliArgs([ { name: "one" }, { name: "two", defaultValue: "two" } ]).parse([ "--one", "1" ]), {
         one: "1",
         two: "two"
     });
-    t.deepEqual(cliArgs([{ name: "two", value: "two" }]).parse([]), {
+    t.deepEqual(cliArgs([{ name: "two", defaultValue: "two" }]).parse([]), {
         two: "two"
     });
-    t.deepEqual(cliArgs([{ name: "two", value: "two" }]).parse([ "--two", "zwei" ]), {
+    t.deepEqual(cliArgs([{ name: "two", defaultValue: "two" }]).parse([ "--two", "zwei" ]), {
         two: "zwei"
     });
-    t.deepEqual(cliArgs([{ name: "two", multiple: true, value: ["two", "zwei"] }]).parse([ ]), {
-        two: [ "two", "zwei" ]
-    });
     t.deepEqual(
-        cliArgs([{ name: "two", multiple: true, value: ["two", "zwei"] }]).parse([ "--two", "duo" ]), 
-        { two: [ "two", "zwei", "duo" ] }
+        cliArgs([{ name: "two", multiple: true, defaultValue: ["two", "zwei"] }]).parse([ "--two", "duo" ]),
+        { two: [ "duo" ] }
     );
+
     t.end();
 });
+
+test("default value", function(t){
+    var defs = [{ name: "two", multiple: true, defaultValue: ["two", "zwei"] }];
+    var result = cliArgs(defs).parse([ ]);
+    t.deepEqual(result, { two: [ "two", "zwei" ] });
+    t.end();
+});
+
+test("default value: array as defaultOption", function(t){
+    var defs = [
+        { name: "two", multiple: true, defaultValue: ["two", "zwei"], defaultOption: true }
+    ];
+    var argv = [ "duo" ];
+    t.deepEqual(cliArgs(defs).parse(argv), { two: [ "duo" ] });
+    t.end();
+});

test/getopt.js

@@ -19,1 +19,9 @@ var test = require("tape");
 });
+
+test("getOpts: non-existent options", function(t){
+    var argv = [ "-sdf" ];
+    t.throws(function(){
+        cliArgs(optionDefinitions).parse(argv);
+    }, /invalid/i);
+    t.end();
+});

test/grouping.js

@@ -20,3 +20,2 @@ var test = require("tape");
         },
-        _none: {},
         _all: {
@@ -23,0 +22,0 @@ one: "1",

test/type-number-multiple.js

@@ -8,5 +8,5 @@ var test = require("tape");
 
-var argv = [ "--array", "1", "2", "3" ];
 
-test("multiple: true", function(t){
+test("number multiple: 1", function(t){
+    var argv = [ "--array", "1", "2", "3" ];
     var result = cliArgs(optionDefinitions).parse(argv);
@@ -21,1 +21,13 @@ t.deepEqual(result, {
 });
+
+test("number multiple: 2", function(t){
+    var argv = [ "--array", "1", "--array", "2", "--array", "3" ];
+    var result = cliArgs(optionDefinitions).parse(argv);
+    t.deepEqual(result, {
+        array: [ 1, 2, 3 ]
+    });
+    t.notDeepEqual(result, {
+        array: [ "1", "2", "3" ]
+    });
+    t.end();
+});

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

51326

increased by78.38%

Number of package files

40

increased by33.33%

Lines of code

1092

increased by47.77%

Number of low quality alerts

1

decreased by-50%

Number of lines in readme file

346

increased by246%

Worsened metrics

Dependency count

6

increased by20%

Dev dependency count

3

increased by50%

Number of low supply chain risk alerts

5

increased by400%

Dependency changes

• + Addedansi-escape-sequences@^2.1.1