electron 0.2.0 → 0.2.1

package/.npmignore

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

package/History.md

@@ -1,4 +1,17 @@
 
+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,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/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,7 @@ module.exports = Args;
  *       , w: 'now'
  *     };
  *
- * @header Argument Parsing
+ * @header Argument Parsing Utility
  */
 
 function Args (args) {

package/lib/electron/program.js

@@ -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
  */
@@ -69,6 +90,7 @@ function Program (base, opts) {
 
   Drip.call(this, { delimeter: ' ' });
   this.commands = [];
+  this._colorized = false;
   this.opts = defaults(opts || {}, {
       useColors: istty
     , version: null
@@ -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
@@ -449,9 +473,13 @@ Program.prototype.colorize = function (noColors) {
       { get: function () {
           if (noColors || !self.opts.useColors) return this;
           return '\033[' + colors[color] + 'm' + this + '\033[0m';
-      }
+        }
+      , configurable: true
     });
   });
+
+  this._colorized = true;
+  return this;
 };
 
 /*!

package/lib/electron.js

@@ -34,6 +34,7 @@ exports.version = '0.2.0';
  */
 
 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.2.1",
   "repository": {
     "type": "git",
     "url": "git://github.com/logicalparadox/electron.git"

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
-```