electron 0.1.0 → 0.2.1

package/.npmignore

@@ -1,4 +1,5 @@
 .git*
+docs/
 support/
 test/
 .DS_Store

package/History.md

@@ -1,4 +1,59 @@
 
+0.2.1 / 2012-06-11 
+==================
+
+  * fix doc asset links
+  * generate docs
+  * comment typos
+  * doc website header
+  * readme
+  * argv export default to using process.argv
+  * added travis support
+  * commentt program header
+  * fix bug that caused error on multiple calls to `program.colorize`
+
+0.2.0 / 2012-06-10 
+==================
+
+  * sep update drip 0.3.x
+  * docs
+  * comment adjustments for docs
+  * rearrange examples
+  * update examples, change default to use `simple` theme
+  * fix copyright headers
+  * add support for program description
+  * add simple theme and theme comments like what
+  * command comments like what
+  * typos in program comments
+  * comments like what for program
+  * improve support for wildcard events using drip 0.3.0
+  * improve test coverage for wildcard commands
+  * clean theme supports refactored command option parsing
+  * tests for program and command
+  * refactor command option parsing to support default value
+  * program has theme support
+  * examples update to include default and absetn
+  * program support for `default` and `absent` commands
+  * refactor Cli as Program, add istty detection and `useColor` option
+  * Args commented for doc generation
+  * test coverage support
+  * add tests for argv parser
+  * expose `electron.argv` as argv parser factory on module main export
+  * refactor arg parser to user `commands` instead of `args` and filter helper works for all three types
+  * add cli colorize helper
+
+0.1.2 / 2012-05-23 
+==================
+
+  * refactor parse to return `this`
+
+0.1.1 / 2012-05-22 
+==================
+
+  * parse args now moved to Args constructor
+  * example update
+  * argument lookups
+
 0.1.0 / 2012-05-18 
 ==================
 

package/README.md

@@ -1,4 +1,151 @@
-electron
-========
+[![Build Status](https://secure.travis-ci.org/logicalparadox/electron.png?branch=master)](http://travis-ci.org/logicalparadox/electron)
 
-Event based CLI framework. 
+# Electron 
+
+> A simple command-line interface framework for [node.js](http://nodejs.org).
+
+#### Features
+
+- reimagined `process.argv` parsing utility
+- framework for single or multiple command programs
+- automatic `--help` command generation with multiple theming options
+- built in cli coloring 
+- chainable api
+
+## Quick Start Guide
+
+This "Quick Start Guide" and the full API reference can be found 
+on [electron's documentation website](http://alogicalparadox.com/electron).
+
+#### Installation
+
+The `electron` package is available through [npm](http://npmjs.org). It is recommended
+that you add it to your project's `package.json`.
+
+```bash
+npm install electron
+```
+
+#### Parsing Arguments
+
+The argument parsing utility can be used independently of the program
+framework. Just pass the `process.argv` from any node modules and your
+ready to go.
+
+The following command execution...
+
+```bash
+$ node cli.js build --minify --out saved.min.js
+```
+
+Could be captured as so...
+
+```javascript
+var argv = require('electron').argv();
+
+// objects
+argv.commands;               // [ 'build' ]
+argv.modes;                  // [ 'minify' ]
+argv.params;                 // { out: 'saved.min.js' }
+
+// helpers
+argv.command('build');       // true
+argv.mode('m', 'minify');    // true
+argv.param('o', 'out');      // 'saved.min.js'
+```
+
+Recommend reading the "Argument Parsing Utility" section of the 
+[documentation](http://alogicalpardox.com/electron)
+to learn about the methodologies and specifics of each of the helpers.
+
+#### Your First Program
+
+To construct your first program, simply execute the electron export
+with a parameter of the namespace you wish to use for your program.
+Then proceed to define your settings and commands.
+
+```javascript
+var myApp = require('../lib/myapp')
+  , program = require('electron')('myapp');
+
+/**
+ * Define your program settings
+ */
+
+program
+  .name('My Cool App')
+  .desc('http://docs.mycoolapp.com')
+  .version(myApp.version);
+
+/**
+ * Define your first command
+ */
+
+program
+  .command('build')
+  .desc('start a build task')
+  .option('-m, --minify', 'flag to set enable minification')
+  .option('-o, --out [file.js]', 'name of output file')
+  .action(function (argv) {
+    var minify = argv.mode('m', 'minify')
+      , savefile = argv.param('o', 'out')
+      , cwd = argv.cwd;
+
+   program.colorize();
+   console.log('Welcome to myApp'.gray + myApp.version);
+   console.log('It works if it ends with '.gray + 'myApp ' + 'ok'.green);
+   // etc...
+  });
+
+/**
+ * Parse argv and execute respective command
+ */
+
+program.parse();
+```
+
+Your `-h, --help` and `-v, --version` will be generated for you automatically.
+
+Recommend reading the "Program Framework" and "Constructing Commands" sections
+of the [documentation](http://alogicalpardox.com/electron)
+to learn about all of the available chainable commands and theming options 
+available to construct your programs.
+
+## Tests
+
+Tests are writting in [Mocha](http://github.com/visionmedia/mocha) using 
+the [Chai](http://chaijs.com) `should` BDD assertion library. To make sure you 
+have that installed, clone this repo, install dependacies using `npm install`.
+
+    $ npm test
+
+## Contributors
+
+Interested in contributing? Fork to get started. Contact [@logicalparadox](http://github.com/logicalparadox) 
+if you are interested in being regular contributor.
+
+* Jake Luer ([@logicalparadox](http://github.com/logicalparadox))
+
+## License
+
+(The MIT License)
+
+Copyright (c) 2012 Jake Luer <jake@alogicalparadox.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/examples/clean.js

@@ -0,0 +1,38 @@
+var electron = require('..')
+  , program = electron('node clean.js');
+
+program
+  .name('Electron Clean Theme')
+  .desc('https://github.com/logicalparadox/electron')
+  .version('0.2.x');
+
+program
+  .command('start simple')
+  .description('Start a simple task')
+  .option('-p, --port [6000]', 'Set the simple port')
+  .option('-f, --file [path]', 'Use a specific file for this task', true)
+  .option('-l, --local', 'Flag as local task')
+  .action(function (args) {
+    console.log(args.mode('l', 'local'));
+    console.log(args.param('p', 'port'));
+  });
+
+program
+  .command('start complex')
+  .description('Start a complex task')
+  .option('-p, --port [6000]', 'Set the comples port')
+  .option('-f, --file [path]', 'Use a specific file for this task', true)
+  .option('-l, --local', 'Flag as local task')
+  .action(function (args) {
+    console.log(args.mode('l', 'local'));
+    console.log(args.param('p', 'port'));
+  });
+
+program
+  .command('absent')
+  .action(function (args) {
+    var cmd = args.commands.join(' ');
+    console.log(cmd + ' is not a valid command. Try --help for a list.');
+  });
+
+program.parse();

package/examples/simple.js

@@ -0,0 +1,24 @@
+var electron = require('..');
+
+var program = electron('node simple.js');
+
+program
+  .name('Electron Simple Theme')
+  .desc('https://github.com/logicalparadox/electron')
+  .theme('simple')
+  .version('0.2.x');
+
+program
+  .command('default')
+  .desc('This is sample cli to show off the `simple` theme.')
+  .option('-p, --port [6000]', 'Set the simple port')
+  .option('-f, --file [path]', 'Use a specific file for this task', true)
+  .option('-l, --local', 'Flag as local task')
+  .option('-t, --test', 'Run the tests first')
+  .option('-w, --watch [dir]', 'Watch directory for changes')
+  .action(function (args) {
+    console.log('file:  ' + args.param('f', 'file'));
+    console.log('local: ' + args.mode('l', 'local'));
+  });
+
+program.parse();

package/lib/electron/args.js

@@ -0,0 +1,235 @@
+/*!
+ * Electron - process.argv parsing
+ * Copyright (c) 2012 Jake Luer <jake@alogicalparadox.com>
+ * MIT Licensed
+ */
+
+/*!
+ * Module export
+ */
+
+module.exports = Args;
+
+/**
+ * ## Argument Parsing Utility
+ *
+ * The electron argument parser takes the node.js standard
+ * `process.argv` array and constructs an object with helpers
+ * that can easily be queried. This helper is publicly exposed
+ * so it can be used independant of the cli framework.
+ *
+ *     var electron = require('electron')
+ *       , argv = electron.argv(process.argv);
+ *
+ * When constructed, the electron argv parser recognizes three
+ * types command line arguments: _commands_, _modes_, and _parameters_.
+ *
+ * Each of these types also has a helper that will provide quick access
+ * to whether a _command_ or _mode_ is present, or the value of a _parameter_.
+ *
+ * ##### Commands
+ *
+ * Commands are the simplest of arguments. They are any arguments
+ * that are listed to that do not start with the `-` or `--` prefix.
+ * Essentially, they are a list of keys.
+ *
+ *     // $ node cli.js hello universe
+ *     argv.commands === [ 'hello', 'universe' ];
+ *
+ * ##### Modes
+ *
+ * Modes are also a non-value list of keys, but they can be expressed
+ * differently by using the `-` or `--` prefix. When using modes, if
+ * it begins with a single `-`, each letter will be parsed as its own mode.
+ *
+ *     // $ node cli.js --universe -abc
+ *     argv.modes === [ 'universe', 'a', 'b', 'c' ];
+ *
+ * ##### Parameters
+ *
+ * Paremeters are key:value pairs that are declared in a similiar manner
+ * as modes. They can be declared in any of the following ways.
+ *
+ *     // $ node cli.js --noun unverse -v say --topic=hello -w=now
+ *     argv.params === {
+ *         noun: 'universe'
+ *       , v: 'say'
+ *       , topic: 'hello'
+ *       , w: 'now'
+ *     };
+ *
+ * @header Argument Parsing Utility
+ */
+
+function Args (args) {
+  /*!
+   * @param {Array} node.js compatible process.argv
+   */
+
+  this._raw = args;
+  this.commands = [];
+  this.modes = [];
+  this.params = {};
+  processArgs.call(this, args);
+}
+
+/**
+ * ### .command (cmd, [cmd], [...])
+ *
+ * The `command` helper takes a list of commands and will
+ * return `true` if any of them exist in the _commands_ list.
+ *
+ *     // node cli.js hello universe
+ *     var greeting = argv.command('hi', 'hello') // true
+ *       , world = argv.command('world', 'earth'); // false
+ *
+ * @param {String} command(s) to check
+ * @returns {Boolean} exists
+ * @name command
+ * @api public
+ */
+
+Args.prototype.command = filter('commands');
+
+/**
+ * ### .mode (mode, [mode], [...])
+ *
+ * The `mode` helper takes a list of modes and will
+ * return `true` if any of them exist in the _modes_ list.
+ *
+ *     // node cli.js --hello -abc
+ *     var greeting = argv.mode('h', 'hello') // true
+ *       , world = argv.mode('w', 'world'); // false
+ *
+ * @param {String} mode(s) to check
+ * @returns {Boolean} exists
+ * @name mode
+ * @api public
+ */
+
+Args.prototype.mode = filter('modes');
+
+/**
+ * ### .param (param, [param], [...])
+ *
+ * The `param` helper takes a list of parameters and will
+ * return the value of the first parameter that matches, or
+ * `null` if none of the parameters exist in the _params_ list.
+ *
+ *     // node cli.js --hello universe
+ *     var greeting = argv.param('h', 'hello') // 'universe'
+ *       , world = argv.param('w', 'world'); // null
+ *
+ * @param {String} mode(s) to check
+ * @returns {String|null} value of first matching parameter
+ * @name param
+ * @api public
+ */
+
+Args.prototype.param = filter('params');
+
+/*!
+ * ### processArgs (args)
+ *
+ * Take the raw node.js args array and parse out
+ * commands, modes, and parameters. Per node standard,
+ * the first two elements are considered to be the executor
+ * and file and irrelevant.
+ *
+ * @param {Array} process.argv
+ * @ctx Args
+ * @api private
+ */
+
+function processArgs (args) {
+  var param_key = null
+    , parts = args.slice(2)
+    , input = this;
+
+  function checkParamKey () {
+    if (param_key !== null) {
+      input.modes.push(param_key);
+      param_key = null;
+    }
+  }
+
+  parts.forEach(function (part) {
+    if (part.substr(0, 2) === '--') {
+      checkParamKey();
+      if (part.indexOf('=') !== -1) {
+        part = part.substr(2).split('=', 2);
+        return input.params[part[0]] = part[1]
+      }
+
+      return param_key = part.substr(2);
+    }
+
+    if (part[0] === '-') {
+      checkParamKey();
+      var sstr = part.substr(1);
+      if (sstr.length > 1) {
+        if (part.indexOf('=') !== -1) {
+          part = part.substr(1).split('=', 2);
+          return input.params[part[0]] = part[1]
+        }
+        for (var i = 0; i < sstr.length; i++)
+          input.modes.push(sstr[i]);
+        return;
+      } else {
+        return param_key = part.substr(1);
+      }
+    }
+
+    part = Number(part) || part
+
+    if (param_key !== null) {
+      input.params[param_key] = part;
+      param_key = null;
+    } else {
+      input.commands.push(part);
+    }
+  });
+
+  checkParamKey();
+}
+
+/*!
+ * ### filter (which)
+ *
+ * Constructs a helper function for each of the
+ * three types of process.argv types. Returns function
+ * to be mounted on to the Arg.prototype.
+ *
+ * @param {String} which argument type
+ * @returns {Function}
+ * @api private
+ */
+
+function filter (which) {
+  return function () {
+    var self = this
+      , modes = Array.prototype.slice.call(arguments)
+      , res = Array.isArray(this[which])
+        ? false
+        : null;
+
+    function check (el) {
+      if (Array.isArray(self[which])) {
+        return self[which].indexOf(el) > -1
+          ? true
+          : null;
+      } else {
+        return 'undefined' !== typeof self[which][el]
+          ? self[which][el]
+          : null;
+      }
+    }
+
+    for (var i = 0; i < modes.length; i++) {
+      var val = check(modes[i]);
+      if (val && !res) res = val;
+    }
+
+    return res;
+  };
+}

package/lib/electron/command.js

@@ -1,6 +1,26 @@
+/*!
+ * Electron - command constructor
+ * Copyright (c) 2012 Jake Luer <jake@alogicalpardox.com>
+ * MIT Licensed
+ */
+
+/*!
+ * Main export
+ */
+
 module.exports = Command;
 
-function Command(cmd) {
+/**
+ * ## Constructing Commands
+ *
+ * Once you have decided to construct a command through `program.command`
+ * you will be returned a command object that you can manipulate through
+ * chainable methods.
+ *
+ * @header Constructing Commands
+ */
+
+function Command (cmd) {
   this.opts = {
       cmd: cmd
     , desc: ''
@@ -9,18 +29,65 @@ function Command(cmd) {
   }
 }
 
-Command.prototype.description = function (desc) {
+/**
+ * ### .desc (description)
+ *
+ * Provide a description for this command to be used when
+ * being display in help.
+ *
+ *     program
+ *       .command('hello universe')
+ *       .desc('Say "Hello" to the Universe.');
+ *
+ * @param {String} description
+ * @returns `command` for chaining
+ * @name desc
+ * @api public
+ */
+
+Command.prototype.desc = function (desc) {
   this.opts.desc = desc;
   return this;
 };
 
-// ('-p, --port [6000]', 'Set the port'); => not require, default 6000
-// ('-p, --port', 'Set the port', true); => required
+/*!
+ * legacy support
+ */
+
+Command.prototype.description = Command.prototype.desc;
+
+/**
+ * ### .option (opts, description, required)
+ *
+ * You may define any number of options for
+ * each command. The `opts` string expects a comma delimited
+ * list of commands with an optional default value or
+ * indicator surrounded by brackets. You may
+ * also provide a description of the option and whether
+ * it is required.
+ *
+ * This command may be called multiple times to define multiple
+ * options.
+ *
+ *     program
+ *       .command('build')
+ *       .option('-m, --minify', 'Flag to build minify version')
+ *       .option('-f, --file [build.js]', 'Save filename', true);
+ *
+ * @param {String} options to parse
+ * @param {String} description
+ * @param {Boolean} required. defaults to false
+ * @returns `command` for chaining
+ * @name option
+ * @api public
+ */
 
 Command.prototype.option = function (opt, desc, required) {
+  var opts = prepareOptions(opt);
+
   this.opts.options.push({
-      opts: opt.split(' ')
-    , description: desc
+      opts: opts
+    , desc: desc
     , required: ('boolean' === typeof required)
       ? required
       : false
@@ -29,8 +96,64 @@ Command.prototype.option = function (opt, desc, required) {
   return this;
 };
 
+/**
+ * ### .action (function)
+ *
+ * Provide the action to be used should this command be
+ * called. The function will receive one parameter of the
+ * parsed process.argv object. Multiple calls to `action` will
+ * replace the previous defined action.
+ *
+ *     program
+ *       .command('build')
+ *       .action(function (argv) {
+ *         var minify = argv.mode('m', 'minify')
+ *           , file = argv.param('f', 'file');
+ *         // go!
+ *       });
+ *
+ * @param {Function} action to perform
+ * @returns `command` for chaining
+ * @name action
+ * @api public
+ */
+
 Command.prototype.action = function (fn) {
   if ('function' === typeof fn)
     this.opts.action = fn;
   return this;
 };
+
+/*!
+ * prepareOptions (string)
+ *
+ * Parse the parameter string provide as an option
+ * list in `option`. Returns an object that can be
+ * explored during help dislay.
+ *
+ * @param {String} options
+ * @returns {Object} parsed
+ * @api private
+ */
+
+function prepareOptions (str) {
+  var list = str.split(' ')
+    , res = { flags: [], def: null }
+    , m;
+
+  list.forEach(function (line) {
+    // remove trailing commas
+    if (line[line.length - 1] === ',')
+      line = line.substr(0, line.length - 1);
+
+    // parse out flags and default value
+    if (line.substr(0, 2) === '--')
+      res.flags.push(line.substr(2));
+    else if (line[0] === '-')
+      res.flags.push(line.substr(1));
+    else if (m = line.match(/[^\[\]]+(?=\])/g))
+      if (!res.def) res.def= m[0];
+  });
+
+  return res;
+}