electron 0.2.0 → 0.4.1

package/.npmignore

@@ -1,5 +1,7 @@
 .git*
+docs/
 support/
+examples/
 test/
 .DS_Store
 coverage.html

package/History.md

@@ -1,4 +1,39 @@
 
+0.4.1 / 2014-12-15
+==================
+
+  * Merge pull request #7 from RobertWHurst/patch-1
+  * Fix broken output in non TTY mode
+  * Merge pull request #6 from tunnckoCore/patch-1
+  * closes #4, rename displayHelp to showHelp
+
+0.4.0 / 2013-01-21 
+==================
+
+  * test: add and use bootstrap for common testing env
+  * deps: update drip to 1.1.x
+  * Merge pull request #1 from jasonrm/test-fix
+  * Fix failing tests due to incorrect usage of length/lengthOf with Chai.
+
+0.3.0 / 2012-10-07 
+==================
+
+  * update comments to reflect multiword params
+  * add support for multiword argv paramters and tests
+
+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 
 ==================
 

package/README.md

@@ -1,4 +1,149 @@
-electron
-========
+# Electron [![Build Status](https://secure.travis-ci.org/logicalparadox/electron.png?branch=master)](http://travis-ci.org/logicalparadox/electron)
 
-Event based CLI framework. 
+> 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/lib/electron/args.js

@@ -11,7 +11,7 @@
 module.exports = Args;
 
 /**
- * ## Argument Parsing
+ * ## Argument Parsing Utility
  *
  * The electron argument parser takes the node.js standard
  * `process.argv` array and constructs an object with helpers
@@ -30,8 +30,8 @@ module.exports = Args;
  * ##### Commands
  *
  * Commands are the simplest of arguments. They are any arguments
- * that are listed to that do not start with the `-` prefix. Essentially,
- * they are a list of keys.
+ * 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' ];
@@ -58,7 +58,15 @@ module.exports = Args;
  *       , w: 'now'
  *     };
  *
- * @header Argument Parsing
+ * You can also specify paramters with multiple words by surrounding the
+ * phrase with double-quotes.
+ *
+ *     // $ node cli.js --say "hello universe"
+ *     argv.params === {
+ *       say: 'hello universe'
+ *     };
+ *
+ * @header Argument Parsing Utility
  */
 
 function Args (args) {
@@ -144,7 +152,8 @@ Args.prototype.param = filter('params');
 function processArgs (args) {
   var param_key = null
     , parts = args.slice(2)
-    , input = this;
+    , input = this
+    , isStr = false;
 
   function checkParamKey () {
     if (param_key !== null) {
@@ -153,6 +162,10 @@ function processArgs (args) {
     }
   }
 
+  function appendStr (key, str) {
+    input.params[key] += ' ' + str;
+  }
+
   parts.forEach(function (part) {
     if (part.substr(0, 2) === '--') {
       checkParamKey();
@@ -183,8 +196,19 @@ function processArgs (args) {
     part = Number(part) || part
 
     if (param_key !== null) {
-      input.params[param_key] = part;
-      param_key = null;
+      if (part[0] === '"') {
+        isStr = true;
+        input.params[param_key] = part.substr(1);
+      } else if (isStr && part[part.length - 1] === '"') {
+        isStr = false;
+        appendStr(param_key, part.substr(0, part.length - 1));
+        param_key = null;
+      } else if (isStr) {
+        appendStr(param_key, part);
+      } else {
+        input.params[param_key] = part;
+        param_key = null;
+      }
     } else {
       input.commands.push(part);
     }

package/lib/electron/program.js

@@ -8,7 +8,7 @@
  * External dependancies
  */
 
-var Drip = require('drip')
+var EventEmitter = require('drip').EnhancedEmitter
   , tty = require('tty')
   , util = require('util');
 
@@ -56,7 +56,28 @@ module.exports = Program;
 /**
  * ## Program Framework
  *
+ * The primary export of the electron module is a function
+ * that composes a new program framework. The returned
+ * `program` is a chainable api that allow you to change
+ * settings, define commands, and start launch the program.
  *
+ * The primary argument provided on construction is the base
+ * name used through the help documentation. In a majority of
+ * of cases, this would be the command executed from your terminal
+ * used launch the program.
+ *
+ * In the case of scripts with the header of `#!/usr/bin/env node`,
+ * you should use a variant of the following.
+ *
+ *     var program = electron('microscope');
+ *
+ * If you are however launching your program from a `.js` file,
+ * the recommended construction pattern is the following.
+ *
+ *     var program = electrong('node microscope.js');
+ *
+ * You can then chain any of the following commands to further
+ * define your application and commands.
  *
  * @header Program Framework
  */
@@ -67,8 +88,9 @@ function Program (base, opts) {
    * @param {Object} options
    */
 
-  Drip.call(this, { delimeter: ' ' });
+  EventEmitter.call(this, { delimeter: ' ' });
   this.commands = [];
+  this._colorized = false;
   this.opts = defaults(opts || {}, {
       useColors: istty
     , version: null
@@ -89,7 +111,7 @@ function Program (base, opts) {
  * Inherit from Drip event emitter.
  */
 
-util.inherits(Program, Drip);
+util.inherits(Program, EventEmitter);
 
 /**
  * ### .command (name)
@@ -231,7 +253,7 @@ Program.prototype.parse = function (args) {
 
   argv.cwd = this.opts.cwd;
   if (argv.mode('help', 'h')) {
-    displayHelp.call(this);
+    this.showHelp();
   } else if (argv.mode('version', 'v')) {
     displayVersion.call(this);
   } else if (!command.length) {
@@ -415,6 +437,7 @@ Program.prototype.theme = function (name, spec) {
  * Just in case, if the current program is not running as a TTY,
  * no string changes will be made.
  *
+ *     program.colorize();
  *     console.log('hello universe'.green);
  *
  * ##### Colors
@@ -432,6 +455,7 @@ Program.prototype.theme = function (name, spec) {
  */
 
 Program.prototype.colorize = function (noColors) {
+  if (this._colorized) return this;
   var self = this
     , colors = {
           'red': 31
@@ -447,11 +471,15 @@ Program.prototype.colorize = function (noColors) {
   Object.keys(colors).forEach(function (color) {
     Object.defineProperty(String.prototype, color,
       { get: function () {
-          if (noColors || !self.opts.useColors) return this;
+          if (noColors || !self.opts.useColors) return this + '';
           return '\033[' + colors[color] + 'm' + this + '\033[0m';
-      }
+        }
+      , configurable: true
     });
   });
+
+  this._colorized = true;
+  return this;
 };
 
 /*!
@@ -497,22 +525,22 @@ function mountCommands () {
  * @api private
  */
 
-function displayVersion () {
+function displayVersion() {
   process.stdout.write(this.opts.version + '\n');
   process.exit();
 }
 
 /*!
- * displayHelp ()
+ * ### displayHelp()
  *
  * Execute the custom help theme or find the respective
  * electron theme and execute.
  *
  * @ctx program
- * @api private
+ * @api public
  */
 
-function displayHelp () {
+Program.prototype.showHelp = function () {
   if ('function' === typeof this.opts.theme)
     return this.opts.theme.call(this);
 

package/lib/electron.js

@@ -27,13 +27,14 @@ exports.defineProgram = defineProgram;
  * Electron version
  */
 
-exports.version = '0.2.0';
+exports.version = '0.4.0';
 
 /*!
  * Argv parsing factory
  */
 
 exports.argv = function (args) {
+  args = args || process.argv;
   var argv = new Args(args);
   return argv;
 };

package/package.json

@@ -1,8 +1,11 @@
 {
   "author": "Jake Luer <jake@alogicalparadox.com>",
   "name": "electron",
-  "description": "Event-based tiny CLI famework.",
-  "version": "0.2.0",
+  "description": "A simple command-line interface framework for node.js.",
+  "keywords": [ "cli", "command", "option", "parser", "argv" ],
+  "homepage": "http://alogicalparadox.com/electron",
+  "license": "MIT",
+  "version": "0.4.1",
   "repository": {
     "type": "git",
     "url": "git://github.com/logicalparadox/electron.git"
@@ -12,7 +15,7 @@
     "test": "make test"
   },
   "dependencies": {
-      "drip": "0.3.x"
+      "drip": "1.1.x"
   },
   "devDependencies": {
       "mocha": "*"

package/docs/data/codex.json

@@ -1,30 +0,0 @@
-{
-    "locals": {
-      "title": "Electron"
-    }
-
-  , "plugins": [
-    { "name": "code"
-    , "files": [
-          { "name": "index"
-          , "title": "Electron Argument Parsing"
-          , "file": "../../lib/electron/args.js"
-          , "description": ":)"
-          , "template": "index"
-          , "render-file": false }
-        , { "name": "index"
-          , "title": "Electron Program Framework"
-          , "file": "../../lib/electron/program.js"
-          , "description": ":)"
-          , "template": "index"
-          , "render-file": false }
-        , { "name": "index"
-          , "title": "Electron Command Construction"
-          , "file": "../../lib/electron/command.js"
-          , "description": ":)"
-          , "template": "index"
-          , "render-file": false }
-      ]
-    }
-  ]
-}

package/docs/data/index.md

@@ -1,19 +0,0 @@
----
-  title: Electron
----
-
-> A tiny cli framework for node.js.
-
-## Features
-
-- tbd
-
-## Installation
-
-##### Node 
-
-`electron` package is available through [npm](http://npmjs.org).
-
-```bash
-npm install electron
-```