coa 0.3.7 → 0.4.1

package/.npmignore

@@ -1,3 +1,6 @@
 .idea
 *.iml
-node_modules
+node_modules/
+!node_modules/coa*.js
+lib-cov/
+html-report/

package/.travis.yml

@@ -0,0 +1,11 @@
+language: node_js
+
+node_js:
+  - "0.6"
+  - "0.8"
+  - "0.10"
+  - "0.11"
+
+matrix:
+  allow_failures:
+    - node_js: 0.11

package/GNUmakefile

@@ -1,15 +1,34 @@
+BIN = ./node_modules/.bin
+
 .PHONY: all
 all: lib
 
 lib: $(foreach s,$(wildcard src/*.coffee),$(patsubst src/%.coffee,lib/%.js,$s))
 
+lib-cov: clean-coverage lib
+	$(BIN)/istanbul instrument --output lib-cov --no-compact --variable global.__coverage__ lib
+
 lib/%.js: src/%.coffee
-	./node_modules/.bin/coffee -cb -o $(@D) $<
+	$(BIN)/coffee -cb -o $(@D) $<
 
 .PHONY: test
 test: lib
-	./node_modules/.bin/vows --spec
+	$(BIN)/mocha
+
+.PHONY: coverage
+coverage: lib-cov
+	COVER=1 $(BIN)/mocha --reporter mocha-istanbul
+	@echo
+	@echo Open html-report/index.html file in your browser
 
 .PHONY: watch
 watch:
-	coffee --watch --bare --output lib src/*.coffee
+	$(BIN)/coffee --watch --bare --output lib src/*.coffee
+
+.PHONY: clean
+clean: clean-coverage
+
+.PHONY: clean-coverage
+clean-coverage:
+	-rm -rf lib-cov
+	-rm -rf html-report

package/README.md

@@ -1,4 +1,5 @@
 # Command-Option-Argument
+[![build status](https://secure.travis-ci.org/veged/coa.png)](http://travis-ci.org/veged/coa)
 
 ## What is it?
 
@@ -8,6 +9,7 @@ Once you write definition in terms of commands, options and arguments you automa
 * Command line help text
 * Program API for use COA-based programs as modules
 * Shell completion
+* Subcommand extendibility by external node modules
 
 ### Other features
 
@@ -18,6 +20,8 @@ Once you write definition in terms of commands, options and arguments you automa
 
 ### TODO
 
+* --Subcommand extendibility--
+* Shell completion helpers
 * Localization
 * Shell-mode
 * Configs
@@ -43,14 +47,22 @@ require('coa').Cmd() // main (top level) command declaration
                 .version;
         })
         .end() // end option chain and return to main command
-    .cmd().name('subcommand').apply(require('./subcommand').COA).end() // load subcommand from module
+    .cmd()
+        .name('subcommand')
+        .apply(require('./subcommand')) // load subcommand from module
+        .end()
     .cmd() // inplace subcommand declaration
-        .name('othercommand').title('Awesome other subcommand').helpful()
+        .name('othercommand')
+        .title('Awesome other subcommand')
+        .helpful()
         .opt()
-            .name('input').title('input file, required')
-            .short('i').long('input')
+            .name('input')
+            .title('input file, required')
+            .short('i')
+            .long('input')
             .val(function(v) { // validator function, also for translate simple values
-                return require('fs').createReadStream(v) })
+                return require('fs').createReadStream(v);
+            })
             .req() // make option required
             .end() // end option chain and return to command
         .end() // end subcommand chain and return to parent command
@@ -59,12 +71,14 @@ require('coa').Cmd() // main (top level) command declaration
 
 ````javascript
 // subcommand.js
-exports.COA = function() {
+module.exports = function() {
     this
         .title('Awesome subcommand').helpful()
         .opt()
-            .name('output').title('output file')
-            .short('o').long('output')
+            .name('output')
+            .title('output file')
+            .short('o')
+            .long('output')
             .output() // use default preset for "output" option declaration
             .end()
 };
@@ -139,6 +153,16 @@ Adds shell completion to command, adds "completion" subcommand, that makes all t
 Must be called only on root command.<br>
 **@returns** *COA.Cmd* `this` instance (for chainability)
 
+#### Cmd.extendable
+Adds ability to extend command by external node modules.<br>
+**@param** *String* `[pattern]` Pattern of modules names to search.
+    Should be simple string with `%s` placeholder like `coa-program-%s-subcommand`
+    or without it — it will be treated as module name prefix then. E.g. `coa-program-`.<br>
+    Node module should export function or `Cmd` object. Function will be passed
+    to `Cmd.apply()` method of created subcommand object using `Cmd.cmd()` method. And
+    `Cmd` object will be passed to `Cmd.cmd()` method.
+**@returns** *COA.Cmd* `this` instance (for chainability)
+
 #### Cmd.usage
 Build full usage text for current command instance.<br>
 **@returns** *String* `usage` text
@@ -226,6 +250,11 @@ Default value passed through validation function as ordinary value.<br>
 **@param** *Object* `_def`<br>
 **@returns** *COA.Opt* `this` instance (for chainability)
 
+#### Opt.input
+Make option value inputting stream.
+It's add useful validation and shortcut for STDIN.
+**@returns** *{COA.Opt}* `this` instance (for chainability)
+
 #### Opt.output
 Make option value outputing stream.<br>
 It's add useful validation and shortcut for STDOUT.<br>

package/index.js

@@ -0,0 +1 @@
+module.exports = require(process.env.COVER? './lib-cov' : './lib');

package/lib/arg.js

@@ -1,4 +1,4 @@
-// Generated by CoffeeScript 1.3.3
+// Generated by CoffeeScript 1.6.3
 var Arg, Cmd, Color, Opt;
 
 Color = require('./color').Color;
@@ -160,6 +160,16 @@ exports.Arg = Arg = (function() {
 
   Arg.prototype.end = Cmd.prototype.end;
 
+  /**
+  Apply function with arguments in context of arg instance.
+  @param {Function} fn
+  @param {Array} args
+  @returns {COA.Arg} this instance (for chainability)
+  */
+
+
+  Arg.prototype.apply = Cmd.prototype.apply;
+
   return Arg;
 
 })();

package/lib/cmd.js

@@ -1,4 +1,4 @@
-// Generated by CoffeeScript 1.3.3
+// Generated by CoffeeScript 1.6.3
 var Cmd, Color, PATH, Q, UTIL,
   __slice = [].slice;
 
@@ -35,6 +35,7 @@ exports.Cmd = Cmd = (function() {
     this._opts = [];
     this._optsByKey = {};
     this._args = [];
+    this._ext = false;
   }
 
   Cmd.get = function(propertyName, func) {
@@ -70,10 +71,13 @@ exports.Cmd = Cmd = (function() {
   });
 
   Cmd.prototype._parent = function(cmd) {
+    this._cmd = cmd || this;
     if (cmd) {
       cmd._cmds.push(this);
+      if (this._name) {
+        this._cmd._cmdsByName[this._name] = this;
+      }
     }
-    this._cmd = cmd || this;
     return this;
   };
 
@@ -221,6 +225,18 @@ exports.Cmd = Cmd = (function() {
     return this.cmd().name('completion').apply(require('./completion')).end();
   };
 
+  /**
+  Allow command to be extendable by external node.js modules.
+  @param {String} [pattern]  Pattern of node.js module to find subcommands at.
+  @returns {COA.Cmd} this instance (for chainability)
+  */
+
+
+  Cmd.prototype.extendable = function(pattern) {
+    this._ext = pattern || true;
+    return this;
+  };
+
   Cmd.prototype._exit = function(msg, code) {
     return process.once('exit', function() {
       if (msg) {
@@ -304,7 +320,7 @@ exports.Cmd = Cmd = (function() {
   };
 
   Cmd.prototype._parseCmd = function(argv, unparsed) {
-    var cmd, i, optSeen;
+    var c, cmd, cmdDesc, e, i, optSeen, pkg;
     if (unparsed == null) {
       unparsed = [];
     }
@@ -314,8 +330,46 @@ exports.Cmd = Cmd = (function() {
       if (!i.indexOf('-')) {
         optSeen = true;
       }
-      if (!optSeen && /^\w[\w-_]*$/.test(i) && (cmd = this._cmdsByName[i])) {
-        return cmd._parseCmd(argv, unparsed);
+      if (!optSeen && /^\w[\w-_]*$/.test(i)) {
+        cmd = this._cmdsByName[i];
+        if (!cmd && this._ext) {
+          if (typeof this._ext === 'string') {
+            if (~this._ext.indexOf('%s')) {
+              pkg = UTIL.format(this._ext, i);
+            } else {
+              pkg = this._ext + i;
+            }
+          } else if (this._ext === true) {
+            pkg = i;
+            c = this;
+            while (true) {
+              pkg = c._name + '-' + pkg;
+              if (c._cmd === c) {
+                break;
+              }
+              c = c._cmd;
+            }
+          }
+          try {
+            cmdDesc = require(pkg);
+          } catch (_error) {
+            e = _error;
+          }
+          if (cmdDesc) {
+            if (typeof cmdDesc === 'function') {
+              this.cmd().name(i).apply(cmdDesc).end();
+            } else if (typeof cmdDesc === 'object') {
+              this.cmd(cmdDesc);
+              cmdDesc.name(i);
+            } else {
+              throw new Error('Error: Unsupported command declaration type, ' + 'should be function or COA.Cmd() object');
+            }
+            cmd = this._cmdsByName[i];
+          }
+        }
+        if (cmd) {
+          return cmd._parseCmd(argv, unparsed);
+        }
       }
       unparsed.push(i);
     }
@@ -456,10 +510,21 @@ exports.Cmd = Cmd = (function() {
         }
       };
     };
-    Q.when(this._do(this._parseArr(argv)), cb(0), cb(1)).end();
+    Q.when(this["do"](argv), cb(0), cb(1)).done();
     return this;
   };
 
+  /**
+  Convenient function to run command from tests.
+  @param {Array} argv
+  @returns {Q.Promise}
+  */
+
+
+  Cmd.prototype["do"] = function(argv) {
+    return this._do(this._parseArr(argv || []));
+  };
+
   /**
   Invoke specified (or current) command using provided
   options and arguments.

package/lib/color.js

@@ -1,4 +1,4 @@
-// Generated by CoffeeScript 1.3.3
+// Generated by CoffeeScript 1.6.3
 var colors;
 
 colors = {

package/lib/completion.js

@@ -1,4 +1,4 @@
-// Generated by CoffeeScript 1.3.3
+// Generated by CoffeeScript 1.6.3
 /**
 Most of the code adopted from the npm package shell completion code.
 See https://github.com/isaacs/npm/blob/master/lib/completion.js
@@ -21,7 +21,7 @@ module.exports = function() {
       e.errno = require('constants').ENOTSUP;
       return this.reject(e);
     }
-    if (!(process.env.COMP_CWORD != null) || !(process.env.COMP_LINE != null) || !(process.env.COMP_POINT != null)) {
+    if ((process.env.COMP_CWORD == null) || (process.env.COMP_LINE == null) || (process.env.COMP_POINT == null)) {
       return dumpScript(this._cmd._name);
     }
     console.error('COMP_LINE:  %s', process.env.COMP_LINE);
@@ -112,15 +112,15 @@ complete = function(cmd, opts) {
   }
   if (optWord && (opt = cmd._optsByKey[optWord])) {
     if (!opt._flag && opt._comp) {
-      compls = Q.join(compls, Q.when(opt._comp(opts), function(c, o) {
+      compls = Q.all([compls, opt._comp(opts)]).spread(function(c, o) {
         return c.concat(o.map(function(v) {
           return (optPrefix || '') + v;
         }));
-      }));
+      });
     }
   }
   if (cmd._comp) {
-    compls = Q.join(compls, Q.when(cmd._comp(opts)), function(c, o) {
+    compls = Q.all([compls, cmd._comp(opts)]).spread(function(c, o) {
       return c.concat(o);
     });
   }

package/lib/index.js

@@ -0,0 +1,10 @@
+// Generated by CoffeeScript 1.6.3
+exports.Cmd = require('./cmd').Cmd;
+
+exports.Opt = require('./cmd').Opt;
+
+exports.Arg = require('./cmd').Arg;
+
+exports.shell = require('./shell');
+
+exports.require = require;

package/lib/opt.js

@@ -1,4 +1,4 @@
-// Generated by CoffeeScript 1.3.3
+// Generated by CoffeeScript 1.6.3
 var Cmd, Color, Opt, Q, fs;
 
 fs = require('fs');
@@ -323,6 +323,16 @@ exports.Opt = Opt = (function() {
 
   Opt.prototype.end = Cmd.prototype.end;
 
+  /**
+  Apply function with arguments in context of option instance.
+  @param {Function} fn
+  @param {Array} args
+  @returns {COA.Opt} this instance (for chainability)
+  */
+
+
+  Opt.prototype.apply = Cmd.prototype.apply;
+
   return Opt;
 
 })();

package/lib/shell.js

@@ -1,5 +1,4 @@
-// Generated by CoffeeScript 1.3.3
-
+// Generated by CoffeeScript 1.6.3
 exports.unescape = function(w) {
   w = w.charAt(0) === '"' ? w.replace(/^"|([^\\])"$/g, '$1') : w.replace(/\\ /g, ' ');
   return w.replace(/\\("|'|\$|`|\\)/g, '$1');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "coa",
   "description": "Command-Option-Argument: Yet another parser for command line options.",
-  "version": "0.3.7",
+  "version": "0.4.1",
   "homepage": "http://github.com/veged/coa",
   "author": "Sergey Berezhnoy <veged@ya.ru> (http://github.com/veged)",
   "maintainers": [
@@ -18,13 +18,20 @@
   "directories": {
     "lib": "./lib"
   },
-  "main": "./lib/coa.js",
   "dependencies": {
-    "q": "~0.8.8"
+    "q": "~0.9.6"
   },
   "devDependencies": {
-    "coffee-script": "~1.3.3",
-    "vows": "~0.6.4"
+    "coffee-script": "~1.6.3",
+    "istanbul": "~0.1.40",
+    "mocha-as-promised": "*",
+    "mocha-istanbul": "*",
+    "mocha": "~1.12.0",
+    "chai": "~1.7.2"
+  },
+  "scripts": {
+    "test": "make test",
+    "coverage": "make coverage"
   },
   "engines": {
     "node": ">= 0.6.0"

package/src/arg.coffee

@@ -120,3 +120,11 @@ exports.Arg = class Arg
     @returns {COA.Cmd} parent command
     ###
     end: Cmd::end
+
+    ###*
+    Apply function with arguments in context of arg instance.
+    @param {Function} fn
+    @param {Array} args
+    @returns {COA.Arg} this instance (for chainability)
+    ###
+    apply: Cmd::apply

package/src/cmd.coffee

@@ -32,6 +32,8 @@ exports.Cmd = class Cmd
 
         @_args = []
 
+        @_ext = false
+
     @get: (propertyName, func) ->
         Object.defineProperty @::, propertyName,
             configurable: true
@@ -52,8 +54,10 @@ exports.Cmd = class Cmd
         @_api
 
     _parent: (cmd) ->
-        if cmd then cmd._cmds.push @
         @_cmd = cmd or this
+        if cmd
+            cmd._cmds.push @
+            if @_name then @_cmd._cmdsByName[@_name] = @
         @
 
     ###*
@@ -163,6 +167,15 @@ exports.Cmd = class Cmd
             .apply(require './completion')
             .end()
 
+    ###*
+    Allow command to be extendable by external node.js modules.
+    @param {String} [pattern]  Pattern of node.js module to find subcommands at.
+    @returns {COA.Cmd} this instance (for chainability)
+    ###
+    extendable: (pattern) ->
+        @_ext = pattern or true
+        @
+
     _exit: (msg, code) ->
         process.once 'exit', ->
             if msg then UTIL.error msg
@@ -233,8 +246,49 @@ exports.Cmd = class Cmd
         while i = argv.shift()
             if not i.indexOf '-'
                 optSeen = true
-            if not optSeen and /^\w[\w-_]*$/.test(i) and cmd = @_cmdsByName[i]
-                return cmd._parseCmd argv, unparsed
+            if not optSeen and /^\w[\w-_]*$/.test(i)
+                cmd = @_cmdsByName[i]
+
+                if not cmd and @_ext
+                    # construct package name to require
+                    if typeof @_ext is 'string'
+                        if ~@_ext.indexOf('%s')
+                            # use formatted string
+                            pkg = UTIL.format(@_ext, i)
+                        else
+                            # just append subcommand name to the prefix
+                            pkg = @_ext + i
+                    else if @_ext is true
+                        # use default scheme: <command>-<subcommand>-<subcommand> and so on
+                        pkg = i
+                        c = @
+                        loop
+                            pkg = c._name + '-' + pkg
+                            if c._cmd is c then break
+                            c = c._cmd
+
+                    try
+                        cmdDesc = require(pkg)
+                    catch e
+
+                    if cmdDesc
+                        if typeof cmdDesc == 'function'
+                            # set create subcommand, set its name and apply imported function
+                            @cmd()
+                                .name(i)
+                                .apply(cmdDesc)
+                                .end()
+                        else if typeof cmdDesc == 'object'
+                            # register subcommand
+                            @cmd(cmdDesc)
+                            # set command name
+                            cmdDesc.name(i)
+                        else
+                            throw new Error 'Error: Unsupported command declaration type, ' +
+                                'should be function or COA.Cmd() object'
+                        cmd = @_cmdsByName[i]
+                if cmd
+                    return cmd._parseCmd argv, unparsed
 
             unparsed.push i
 
@@ -342,9 +396,17 @@ exports.Cmd = class Cmd
                 @_exit res.stack ? res.toString(), res.exitCode ? code
             else
                 @_exit()
-        Q.when(@_do(@_parseArr argv), cb(0), cb(1)).end()
+        Q.when(@do(argv), cb(0), cb(1)).done()
         @
 
+    ###*
+    Convenient function to run command from tests.
+    @param {Array} argv
+    @returns {Q.Promise}
+    ###
+    do: (argv) ->
+        @_do(@_parseArr argv || [])
+
     ###*
     Invoke specified (or current) command using provided
     options and arguments.

package/src/completion.coffee

@@ -137,15 +137,17 @@ complete = (cmd, opts) ->
     # complete on opt values: completion
     if optWord and opt = cmd._optsByKey[optWord]
         if not opt._flag and opt._comp
-            compls = Q.join compls, Q.when opt._comp(opts), (c, o) ->
-                c.concat o.map (v) -> (optPrefix or '') + v
+            compls = Q.all([compls, opt._comp(opts)])
+                .spread (c, o) ->
+                    c.concat o.map (v) -> (optPrefix or '') + v
 
     # TODO: complete on args values (context aware, custom completion?)
 
     # custom completion on cmds
     if cmd._comp
-        compls = Q.join compls, Q.when(cmd._comp(opts)), (c, o) ->
-            c.concat o
+        compls = Q.all([compls, cmd._comp(opts)])
+            .spread (c, o) ->
+                c.concat o
 
     # TODO: context aware custom completion on cmds, opts and args
     # (can depend on already entered values, especially options)

package/src/index.coffee

@@ -0,0 +1,5 @@
+exports.Cmd = require('./cmd').Cmd
+exports.Opt = require('./cmd').Opt
+exports.Arg = require('./cmd').Arg
+exports.shell = require('./shell')
+exports.require = require;

package/src/opt.coffee

@@ -233,3 +233,11 @@ exports.Opt = class Opt
     @returns {COA.Cmd} parent command
     ###
     end: Cmd::end
+
+    ###*
+    Apply function with arguments in context of option instance.
+    @param {Function} fn
+    @param {Array} args
+    @returns {COA.Opt} this instance (for chainability)
+    ###
+    apply: Cmd::apply