command-line-args - npm Package Compare versions

Comparing version 0.3.1 to 0.4.0

lib/command-line-args.js

@@ -0,1 +1,2 @@
+"use strict";
 var a = require("array-tools"),
@@ -10,2 +11,15 @@ o = require("object-tools"),
 
+/**
+@module
+@example
+```js
+var cliArgs = require("command-line-args");
+var cli = cliArgs([
+    { name: "help", type: Boolean, alias: "h" },
+    { name: "files", type: Array, defaultOption: true}
+]);
+var argv = cli.parse();
+```
+@alias cli
+*/
 module.exports = CliArgs;
@@ -15,12 +29,21 @@
 require("handlebars-ansi")(handlebars);
-handlebars.registerPartial("columns", fs.readFileSync(path.resolve(__dirname, "..", "template", "partials", "columns.hbs"), "utf8"));
+handlebars.registerPartial(
+    "columns",
+    fs.readFileSync(path.resolve(__dirname, "../template/partials/columns.hbs"), "utf8")
+);
 handlebars.logger.level = 1;
 
+/**
+A constructor function, taking your desired command-line option definitions as input, returning an instance of `command-line-args` which you can `parse()` or `getUsage()`.
+@class
+@param {module:command-line-args~OptionDefinition[]} - list of option definitions
+@alias module:command-line-args
+*/
 function CliArgs(options){
     if (!(this instanceof CliArgs)) return new CliArgs(options);
-    
+
     options.forEach(function(option){
         if (option.options) option.attributes = option.options;
     });
-    
+
     Design.call(this, options);
@@ -30,2 +53,28 @@ }
 
+/**
+Returns a flat, or grouped object containing the values set at the command-line
+@param [argv=process.argv] {object} - Optional argv array, pass to override the default `process.argv`.
+@returns {object}
+@example
+Output from `parse()` looks something like this:
+```js
+{
+    delete: "thisfile.txt",
+    force: true
+}
+```
+
+or, if the option definitions are grouped:
+```js
+{
+    standard: {
+        delete: "thisfile.txt",
+        force: true
+    },
+    extra: {
+        intentions: "bad"
+    }
+}
+```
+*/
 CliArgs.prototype.parse = function(argv){
@@ -40,7 +89,7 @@ var shortArg = /^-(\w)/,
     argv = argv ? argv.slice(0) : process.argv.slice(2);
-    
+
 	function isOption(input){
 		return longArg.test(input) || shortArg.test(input);
 	}
-	
+
     function setOutputValue(option, value){
@@ -115,7 +164,15 @@ model[option.name] = value;
 
-CliArgs.prototype.usage = function(data){
+/**
+@param {object} options - options for template
+@param {string} options.title - a title
+@param {string} options.header - a header
+@param {string} options.footer - a footer
+@param {array} options.forms - the invocation forms
+@returns {string}
+*/
+CliArgs.prototype.getUsage = function(options){
     var self = this;
-    data = data || {};
+    options = options || {};
     var template = fs.readFileSync(path.resolve(__dirname, "..", "template", "usage.hbs"), "utf8");
-    data.options = this._attributes.map(function(option){
+    options.options = this._attributes.map(function(option){
         var type = option.type && option.type.name.toLowerCase();
@@ -126,3 +183,3 @@ type = type === "boolean" ? "" : "<" + type + ">";
     });
-    data.groups = this.groups().map(function(group){
+    options.groups = this.groups().map(function(group){
         return {
@@ -135,13 +192,23 @@ name: group,
     });
-    if (!data.columns) {
-        var width = data.options.reduce(function(prev, curr){
+    if (!options.columns) {
+        var width = options.options.reduce(function(prev, curr){
             return curr.column1.length > prev ? curr.column1.length : prev;
         }, 0);
-        data.columns = [ width + 2 ];
+        options.columns = [ width + 2 ];
     }
-    data.options = data.options.map(function(option){
-        option.description = option.description && option.description.replace(/\n/g, "\n" + s.fill(" ", data.columns[0] + 2))
+    options.options = options.options.map(function(option){
+        option.description = option.description && option.description.replace(/\n/g, "\n" + s.fill(" ", options.columns[0] + 2))
         return option;
     });
-    return handlebars.compile(template)(data);
+    return handlebars.compile(template)(options);
 };
+
+/**
+Defines an option
+@typedef {object} module:command-line-args~OptionDefinition
+@property {string} name - the option name, used as the long option (e.g. `--name`)
+@property {function} type - an optional function (e.g. `Number` or a custom function) used as a setter to enforce type.
+@property {string} alias - a single character alias, used as the short option (e.g. `-n`)
+@property {boolean} defaultOption - if values are specified without an option name, they are assigned to the defaultOption
+@property {string} description - used in the usage guide
+*/

package.json

 {
   "name": "command-line-args",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Command-line parser, usage text producer",
@@ -8,3 +8,4 @@ "repository": "https://github.com/75lb/command-line-args.git",
   "scripts": {
-    "test": "tap test/*.js"
+    "test": "tap test/*.js",
+    "docs": "jsdoc2md -t jsdoc2md/README.hbs lib/command-line-args.js > README.md"
   },
@@ -24,2 +25,3 @@ "keywords": [
   "devDependencies": {
+    "jsdoc-to-markdown": "^0.2.1",
     "tap": "^0.4.9"
@@ -26,0 +28,0 @@ },

README.md

@@ -6,6 +6,147 @@ [![view on npm](http://img.shields.io/npm/v/command-line-args.svg)](https://www.npmjs.org/package/command-line-args)
 
-**work in progress**
+**work in progress, draft documentation**
 
-command-line-args
-=================
+#command-line-args
+A command-line parser and usage-guide producer.. Particularly good at organising large sets of options. 
 
+##Install
+```sh
+$ npm install command-line-args --save
+```
+
+##Synopsis
+the following `app.js`...
+```js
+var cliArgs = require("command-line-args");
+
+/* define the command-line options */
+var cli = cliArgs([
+    { name: "verbose", type: Boolean, alias: "v", description: "Write plenty output" },
+    { name: "help", type: Boolean, description: "Print usage instructions" },
+    { name: "files", type: Array, defaultOption: true, description: "The input files" }
+]);
+
+/* parse the supplied command-line values */
+var options = cli.parse();
+
+/* generate a usage guide */
+var usage = cli.usage({
+    header: "A synopsis application.",
+    footer: "For more information, visit http://example.com"
+});
+    
+console.log(options.help ? usage : options);
+```
+...returns this output at the command line:
+```sh
+$ node app.js
+{}
+$ node app.js -v
+{ verbose: true }
+$ node app.js README.md package.json
+{ files: [ 'README.md', 'package.json' ] }
+$ node app.js README.md package.json -v
+{ verbose: true, files: [ 'README.md', 'package.json' ] }
+$ node app.js --help
+
+  A synopsis application.
+
+  Usage
+
+  -v, --verbose    Write plenty output
+  --help           Print usage instructions
+  --files <array>  The input files
+
+  For more information, visit http://example.com
+
+```
+
+#API Reference
+<a name="module_command-line-args"></a>
+##command-line-args(options)
+A constructor function, taking your desired command-line option definitions as input, returning an instance of `command-line-args` which you can `parse()` or `getUsage()`.
+
+
+- options [Array.&lt;OptionDefinition&gt;](#module_command-line-args.OptionDefinition) - list of option definitions
+
+  
+####Example
+```js
+var cliArgs = require("command-line-args");
+var cli = cliArgs([
+    { name: "help", type: Boolean, alias: "h" },
+    { name: "files", type: Array, defaultOption: true}
+]);
+var argv = cli.parse();
+```
+<a name="module_command-line-args#parse"></a>
+###cli.parse([argv])
+Returns a flat, or grouped object containing the values set at the command-line
+
+
+- [argv=process.argv] `object` - Optional argv array, pass to override the default `process.argv`.
+
+**Returns**: `object`  
+####Example
+Output from `parse()` looks something like this:
+```js
+{
+    delete: "thisfile.txt",
+    force: true
+}
+```
+
+or, if the option definitions are grouped:
+```js
+{
+    standard: {
+        delete: "thisfile.txt",
+        force: true
+    },
+    extra: {
+        intentions: "bad"
+    }
+}
+```
+<a name="module_command-line-args#getUsage"></a>
+###cli.getUsage(options)
+
+- options `object` - options for template
+- options.title `string` - a title
+- options.header `string` - a header
+- options.footer `string` - a footer
+- options.forms `array` - the invocation forms
+
+**Returns**: `string`  
+<a name="module_command-line-args.OptionDefinition"></a>
+###type: OptionDefinition
+
+Defines an option
+
+**Scope**: inner typedef of [command-line-args](#module_command-line-args)  
+**Type**: `object`  
+<a name=""></a>
+###name
+the option name, used as the long option (e.g. `--name`)
+
+**Type**: `string`  
+<a name=""></a>
+###type
+an optional function (e.g. `Number` or a custom function) used as a setter to enforce type.
+
+**Type**: `function`  
+<a name=""></a>
+###alias
+a single character alias, used as the short option (e.g. `-n`)
+
+**Type**: `string`  
+<a name=""></a>
+###defaultOption
+if values are specified without an option name, they are assigned to the defaultOption
+
+**Type**: `boolean`  
+<a name=""></a>
+###description
+used in the usage guide
+
+**Type**: `string`  

test/usage.js

@@ -13,5 +13,5 @@ var test = require("tap").test;
 test("returns string", function(t){
-    var usage = cliArgs(optionDefinitions).usage();
+    var usage = cliArgs(optionDefinitions).getUsage();
     t.equal(typeof usage, "string");
     t.end();
 });

No alert changes

Improved metrics

Total package byte prevSize

27415

increased by42.01%

Number of package files

20

increased by17.65%

Lines of code

611

increased by14.42%

Number of lines in readme file

152

increased by1281.82%

Worsened metrics

Dev dependency count

2

increased by100%

No dependency changes