coa 0.3.9 → 1.0.1

package/.npmignore

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

package/.travis.yml

@@ -1,10 +1,9 @@
 language: node_js
 
 node_js:
-  - 0.6
-  - 0.8
-  - 0.9
+  - "0.10"
+  - "0.11"
 
 matrix:
   allow_failures:
-    - node_js: 0.9
+    - node_js: 0.11

package/README.md

@@ -227,6 +227,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>
@@ -303,7 +308,7 @@ Make argument value outputing stream.<br>
 It's add useful validation and shortcut for STDOUT.<br>
 **@returns** *COA.Arg* `this` instance (for chainability)
 
-#### Opt.comp
+#### Arg.comp
 Set custom additional completion for current argument.<br>
 **@param** *Function* `fn` completion generation function,
     invoked in the context of command instance.

package/README.ru.md

@@ -0,0 +1,316 @@
+# Command-Option-Argument
+[![build status](https://secure.travis-ci.org/veged/coa.png)](http://travis-ci.org/veged/coa)
+
+## Что это?
+
+COA — парсер параметров командной строки, позволяющий извлечь максимум пользы от формального API вашей программы.
+Как только вы опишете определение в терминах команд, параметров и аргументов, вы автоматически получите:
+
+* Справку для командной строки
+* API для использования программы как модуля в COA-совместимых программах
+* Автодополнение для командной строки
+
+### Прочие возможности
+
+* Широкий выбор настроек для параметров и аргументов, включая множественные значения, логические значения и обязательность параметров
+* Возможность асинхронного исполнения команд, используя промисы (используется библиотека [Q](https://github.com/kriskowal/q))
+* Простота использования существующих команд как подмодулей для новых команд
+* Комбинированная валидация и анализ сложных значений
+
+## Примеры
+
+````javascript
+require('coa').Cmd() // декларация команды верхнего уровня
+    .name(process.argv[1]) // имя команды верхнего уровня, берем из имени программы
+    .title('Жутко полезная утилита для командной строки') // название для использования в справке и сообщениях
+    .helpful() // добавляем поддержку справки командной строки (-h, --help)
+    .opt() // добавляем параметр
+        .name('version') // имя параметра для использования в API
+        .title('Version') // текст для вывода в сообщениях
+        .short('v') // короткое имя параметра: -v
+        .long('version') // длинное имя параметра: --version
+        .flag() // параметр не требует ввода значения
+        .act(function(opts) {  // действия при вызове аргумента
+            // результатом является вывод текстового сообщения
+            return JSON.parse(require('fs').readFileSync(__dirname + '/package.json'))
+                .version;
+        })
+        .end() // завершаем определение параметра и возвращаемся к определению верхнего уровня
+    .cmd().name('subcommand').apply(require('./subcommand').COA).end() // загрузка подкоманды из модуля
+    .cmd() // добавляем еще одну подкоманду
+        .name('othercommand').title('Еще одна полезная подпрограмма').helpful()
+        .opt()
+            .name('input').title('input file, required')
+            .short('i').long('input')
+            .val(function(v) { // функция-валидатор, также может использоваться для трансформации значений параметров
+                return require('fs').createReadStream(v) })
+            .req() // параметр является обязательным
+            .end() // завершаем определение параметра и возвращаемся к определению команды
+        .end() // завершаем определение подкоманды и возвращаемся к определению команды верхнего уровня
+    .run(process.argv.slice(2)); // разбираем process.argv и запускаем
+````
+
+````javascript
+// subcommand.js
+exports.COA = function() {
+    this
+        .title('Полезная подпрограмма').helpful()
+        .opt()
+            .name('output').title('output file')
+            .short('o').long('output')
+            .output() // использовать стандартную настройку для параметра вывода
+            .end()
+};
+````
+
+## API
+
+### Cmd
+Команда — сущность верхнего уровня. У команды могут быть определены параметры и аргументы.
+
+#### Cmd.api
+Возвращает объект, который можно использовать в других программах. Подкоманды являются методами этого объекта.<br>
+**@returns** *{Object}*
+
+#### Cmd.name
+Определяет канонический идентификатор команды, используемый в вызовах API.<br>
+**@param** *String* `_name` имя команды<br>
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
+
+#### Cmd.title
+Определяет название команды, используемый в текстовых сообщениях.<br>
+**@param** *String* `_title` название команды<br>
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
+
+#### Cmd.cmd
+Создает новую подкоманду или добавляет ранее определенную подкоманду к текущей команде.<br>
+**@param** *COA.Cmd* `[cmd]` экземпляр ранее определенной подкоманды<br>
+**@returns** *COA.Cmd* экземпляр новой или ранее определенной подкоманды
+
+#### Cmd.opt
+Создает параметр для текущей команды.<br>
+**@returns** *COA.Opt* `new` экземпляр параметра
+
+#### Cmd.arg
+Создает аргумент для текущей команды.<br>
+**@returns** *COA.Opt* `new` экземпляр аргумента
+
+#### Cmd.act
+Добавляет (или создает) действие для текущей команды.<br>
+**@param** *Function* `act` функция,
+    выполняемая в контексте экземпляра текущей команды
+    и принимающая следующие параметры:<br>
+        - *Object* `opts` параметры команды<br>
+        - *Array* `args` аргументы команды<br>
+        - *Object* `res` объект-аккумулятор результатов<br>
+    Функция может вернуть проваленный промис из Cmd.reject (в случае ошибки)
+    или любое другое значение, рассматриваемое как результат.<br>
+**@param** *{Boolean}* [force=false] флаг, назначающий немедленное исполнение вместо добавления к списку существующих действий<br>
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
+
+#### Cmd.apply
+Исполняет функцию с переданными аргументами в контексте экземпляра текущей команды.<br>
+**@param** *Function* `fn`<br>
+**@param** *Array* `args`<br>
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
+
+#### Cmd.comp
+Назначает кастомную функцию автодополнения для текущей команды.<br>
+**@param** *Function* `fn` функция-генератор автодополнения,
+    исполняемая в контексте текущей команды.
+    Принимает параметры:<br>
+        - *Object* `opts` параметры<br>
+    Может возвращать промис или любое другое значение, рассматриваемое как результат исполнения команды.<br>
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
+
+#### Cmd.helpful
+Ставит флаг поддержки справки командной строки, т.е. вызов команды с параметрами -h --help выводит справку по работе с командой.<br>
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
+
+#### Cmd.completable
+Добавляет поддержку автодополнения командной строки. Добавляется подкоманда "completion", которая выполняет все необходимые действия.<br>
+Может быть добавлен только для главной команды.<br>
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
+
+#### Cmd.usage
+Возвращает текст справки по использованию команды для текущего экземпляра.<br>
+**@returns** *String* `usage` Текст справки по использованию
+
+#### Cmd.run
+Разбирает аргументы из значения, возвращаемого NodeJS process.argv,
+и запускает текущую программу, т.е. вызывает process.exit после завершения
+всех действий.<br>
+**@param** *Array* `argv`<br>
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
+
+#### Cmd.invoke
+Исполняет переданную (или текущую) команду с указанными параметрами и аргументами.<br>
+**@param** *String|Array* `cmds`  подкоманда для исполнения (необязательно)<br>
+**@param** *Object* `opts`  параметры, передаваемые команде (необязательно)<br>
+**@param** *Object* `args`  аргументы, передаваемые команде (необязательно)<br>
+**@returns** *Q.Promise*
+
+#### Cmd.reject
+Проваливает промисы, возращенные в действиях.<br>
+Используется в .act() для возврата с ошибкой.<br>
+**@param** *Object* `reason` причина провала<br>
+    Вы можете определить метод toString() и свойство toString()
+    объекта причины провала.<br>
+**@returns** *Q.promise* проваленный промис
+
+#### Cmd.end
+Завершает цепочку методов текущей подкоманды и возвращает экземпляр родительской команды.<br>
+**@returns** *COA.Cmd* `parent` родительская команда
+
+### Opt
+Параметр — именованная сущность. У параметра может быть определено короткое или длинное имя для использования из командной строки.<br>
+**@namespace**<br>
+**@class** Переданный параметр
+
+#### Opt.name
+Определяет канонический идентификатор параметра, используемый в вызовах API.<br>
+**@param** *String* `_name` имя параметра<br>
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
+
+#### Opt.title
+Определяет описание для параметра, используемое в текстовых сообщениях.<br>
+**@param** *String* `_title` название параметра<br>
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
+
+#### Opt.short
+Назначает ключ для короткого имени параметра, передаваемого из командной строки с одинарным дефисом (например, `-v`).<br>
+**@param** *String* `_short`<br>
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
+
+#### Opt.long
+Назначает ключ для длинного имени параметра, передаваемого из командной строки с двойным дефисом (например, `--version`).<br>
+**@param** *String* `_long`<br>
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
+
+#### Opt.flag
+Помечает параметр как логический, т.е. параметр не имеющий значения.<br>
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
+
+#### Opt.arr
+Помечает параметр как принимающий множественные значения.<br>
+Иначе будет использовано последнее переданное значение параметра.<br>
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
+
+#### Opt.req
+Помечает параметр как обязательный.<br>
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
+
+#### Opt.only
+Интерпретирует параметр как команду,
+т.е. программа будет завершена сразу после выполнения параметра.<br>
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
+
+#### Opt.val
+Назначает функцию валидации (или трансформации значения) для значения параметра.<br>
+Значение, полученное из командной строки, передается в функцию-валидатор прежде чем оно станет доступно из API.<br>
+Используется для валидации и трансформации введенных данных.<br>
+**@param** *Function* `_val` функция валидации,
+    исполняемая в контексте экземпляра параметра
+    и принимающая в качестве единственного параметра значение, полученное
+    из командной строки<br>
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
+
+#### Opt.def
+Назначает значение параметра по умолчанию. Это значение также передается
+в функцию валидации как обычное значение.<br>
+**@param** *Object* `_def`<br>
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
+
+#### Opt.input
+Помечает параметр как принимающий ввод пользователя. <br>
+Позволяет использовать валидацию для STDIN.<br>
+**@returns** *{COA.Opt}* `this` экземпляр параметра (для поддержки цепочки методов)
+
+#### Opt.output
+Помечает параметр как вывод.<br>
+Позволяет использовать валидацию для STDOUT.<br>
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
+
+#### Opt.act
+Добавляет (или создает) действие для текущего параметра команды.
+Это действие будет выполнено, если текущий параметр есть
+в списке полученных параметров (с любым значением).<br>
+**@param** *Function* `act` функция, выполняемая в контексте
+    экземпляра текущей команды и принимающая следующие параметры:<br>
+        - *Object* `opts` параметры команды<br>
+        - *Array* `args` аргументы команды<br>
+        - *Object* `res` объект-аккумулятор результатов<br>
+    Функция может вернуть проваленный промис из Cmd.reject (в случае ошибки)
+    или любое другое значение, рассматриваемое как результат.<br>
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
+
+#### Opt.comp
+Назначает кастомную функцию автодополнения для текущей команды.<br>
+**@param** *Function* `fn` функция-генератор автодоплнения, исполняемая в
+    контексте экземпляра команды.
+    Принимает параметры:<br>
+        - *Object* `opts` параметры автодополнения<br>
+    Может возвращать промис или любое другое значение, рассматриваемое как результат исполнения команды.<br>
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
+
+#### Opt.end
+Завершает цепочку методов текущего параметра и возвращает экземпляр родительской команды.<br>
+**@returns** *COA.Cmd* `parent` родительская команда
+
+
+### Arg
+Аргумент — неименованная сущность.<br>
+Аргументы передаются из командной строки как список неименованных значений.
+
+#### Arg.name
+Определяет канонический идентификатор аргумента, используемый в вызовах API.<br>
+**@param** *String* `_name` имя аргумента<br>
+**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов)
+
+#### Arg.title
+Определяет описание для аргумента, используемое в текстовых сообщениях.<br>
+**@param** *String* `_title` описание аргумента<br>
+**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов)
+
+#### Arg.arr
+Помечает аргумент как принимающий множественные значения.<br>
+Иначе будет использовано последнее переданное значение аргумента.<br>
+**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов)
+
+#### Arg.req
+Помечает аргумент как обязательный.<br>
+**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов)
+
+#### Arg.val
+Назначает функцию валидации (или трансформации значения) для аргумента.<br>
+Значение, полученное из командной строки, передается в функцию-валидатор прежде чем оно станет доступно из API.<br>
+Используется для валидации и трансформации введенных данных.<br>
+**@param** *Function* `_val` функция валидации,
+    исполняемая в контексте экземпляра аргумента
+    и принимающая в качестве единственного параметра значение, полученное
+    из командной строки<br>
+**@returns** *COA.Opt* `this` экземпляр аргумента (для поддержки цепочки методов)
+
+#### Arg.def
+Назначает дефолтное значение для аргумента. Дефолтное значение передается
+в функцию валидации как обычное значение.<br>
+**@param** *Object* `_def`<br>
+**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов)
+
+#### Arg.output
+Помечает параметр как вывод.<br>
+Позволяет назначить валидацию для STDOUT.<br>
+**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов)
+
+#### Arg.comp
+Назначает кастомную функцию автодополнения для текущего аргумента.<br>
+**@param** *Function* `fn` функция-генератор автодоплнения,
+    исполняемая в контексте текущей команды.
+    Принимает параметры:<br>
+        - *Object* `opts` параметры
+Может возвращать промис или любое другое значение, рассматриваемое как результат исполнения команды.<br>
+**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов)
+
+#### Arg.end
+Завершает цепочку методов текущего аргумента и возвращает экземпляр родительской команды.<br>
+**@returns** *COA.Cmd* `parent` родительская команда

package/lib/arg.js

@@ -1,4 +1,4 @@
-// Generated by CoffeeScript 1.4.0
+// Generated by CoffeeScript 1.6.3
 var Arg, Cmd, Color, Opt;
 
 Color = require('./color').Color;

package/lib/cmd.js

@@ -1,4 +1,4 @@
-// Generated by CoffeeScript 1.4.0
+// 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,10 +225,22 @@ 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) {
-        UTIL.error(msg);
+        console.error(msg);
       }
       return process.exit(code || 0);
     });
@@ -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);
     }

package/lib/color.js

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

package/lib/completion.js

@@ -1,4 +1,4 @@
-// Generated by CoffeeScript 1.4.0
+// 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);

package/lib/index.js

@@ -1,7 +1,10 @@
-// Generated by CoffeeScript 1.4.0
-
+// 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.4.0
+// Generated by CoffeeScript 1.6.3
 var Cmd, Color, Opt, Q, fs;
 
 fs = require('fs');

package/lib/shell.js

@@ -1,5 +1,4 @@
-// Generated by CoffeeScript 1.4.0
-
+// 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.9",
+  "version": "1.0.1",
   "homepage": "http://github.com/veged/coa",
   "author": "Sergey Berezhnoy <veged@ya.ru> (http://github.com/veged)",
   "maintainers": [
@@ -19,22 +19,21 @@
     "lib": "./lib"
   },
   "dependencies": {
-    "q": "~0.8.10"
+    "q": "^1.1.2"
   },
   "devDependencies": {
-    "coffee-script": "~1.4.0",
-    "istanbul": "~0.1.11",
-    "mocha-as-promised": "*",
+    "coffee-script": "~1.6.3",
+    "istanbul": "~0.1.40",
     "mocha-istanbul": "*",
-    "mocha": "~1.6.0",
-    "chai": "~1.3.0"
+    "mocha": "~1.21.4",
+    "chai": "~1.7.2"
   },
   "scripts": {
     "test": "make test",
     "coverage": "make coverage"
   },
   "engines": {
-    "node": ">= 0.6.0"
+    "node": ">= 0.8.0"
   },
   "licenses": [
     {

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,9 +167,18 @@ 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
+            if msg then console.error msg
             process.exit code or 0
 
     ###*
@@ -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
 

package/src/index.coffee

@@ -1,3 +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/test/coa.js

@@ -338,6 +338,22 @@ describe('Arg', function() {
 
 describe('Cmd', function() {
 
+    var doTest = function(o) {
+            assert.deepEqual(o, {
+                opts: { opt: 'value' },
+                args: {
+                    arg1: 'value',
+                    arg2: ['value 1', 'value 2']
+                }
+            });
+        },
+
+        invokeOpts = { opt: 'value' },
+        invokeArgs = {
+            arg1: 'value',
+            arg2:  ['value 1', 'value 2']
+        };
+
     describe('Subcommand', function() {
 
         var cmd = COA.Cmd()
@@ -357,23 +373,7 @@ describe('Cmd', function() {
                 .act(function(opts, args) {
                     return { opts: opts, args: args };
                 })
-                .end(),
-
-            doTest = function(o) {
-                    assert.deepEqual(o, {
-                        opts: { opt: 'value' },
-                        args: {
-                            arg1: 'value',
-                            arg2: ['value 1', 'value 2']
-                        }
-                    });
-                },
-
-            invokeOpts = { opt: 'value' },
-            invokeArgs = {
-                    arg1: 'value',
-                    arg2:  ['value 1', 'value 2']
-                };
+                .end();
 
         describe('when specified on command line', function() {
 
@@ -413,6 +413,80 @@ describe('Cmd', function() {
 
     });
 
+    describe('External subcommand', function() {
+
+        describe('default scheme: cmd.extendable()', function() {
+
+            describe('when described as a function', function() {
+                var cmd = COA.Cmd()
+                    .name('coa')
+                    .extendable();
+
+                it('should be invoked and accept passed opts and args', function() {
+                    return cmd.do(['test', '--opt', 'value', 'value', 'value 1', 'value 2'])
+                        .then(doTest);
+                });
+            });
+
+            describe('when described as an COA.Cmd() object', function() {
+                var cmd = COA.Cmd()
+                    .name('coa')
+                    .extendable();
+
+                it('should be invoked and accept passed opts and args', function() {
+                    return cmd.do(['test-obj', '--opt', 'value', 'value', 'value 1', 'value 2'])
+                        .then(doTest);
+                });
+            });
+
+            describe('2nd level subcommand', function() {
+                var cmd = COA.Cmd()
+                    .name('coa')
+                    .cmd()
+                    .name('test')
+                    .extendable()
+                    .end();
+
+                it('should be invoked and accept passed opts and args', function() {
+                    return cmd.do(['test', 'obj', '--opt', 'value', 'value', 'value 1', 'value 2'])
+                        .then(doTest);
+                });
+            });
+
+        });
+
+        describe("common prefix: cmd.extendable('coa-')", function() {
+
+            describe('when described as a function', function() {
+                var cmd = COA.Cmd()
+                    .name('coa')
+                    .extendable('coa-');
+
+                it('should be invoked and accept passed opts and args', function() {
+                    return cmd.do(['test', '--opt', 'value', 'value', 'value 1', 'value 2'])
+                        .then(doTest);
+                });
+            });
+
+        });
+
+        describe("format string: cmd.extendable('coa-%s')", function() {
+
+            describe('when described as a function', function() {
+                var cmd = COA.Cmd()
+                    .name('coa')
+                    .extendable('coa-%s');
+
+                it('should be invoked and accept passed opts and args', function() {
+                    return cmd.do(['test', '--opt', 'value', 'value', 'value 1', 'value 2'])
+                        .then(doTest);
+                });
+            });
+
+        });
+
+    });
+
     it('helpful(), name(), title()');
 
 });

package/test/mocha.opts

@@ -1,4 +1,2 @@
 --reporter spec
---ignore-leaks
---timeout 0
---require test/common.js
+--timeout 20

package/tests/api-h.js

@@ -6,4 +6,4 @@ require('..').Cmd()
     .then(function(res) {
         console.log(res);
     })
-    .end(); // Q.end()
+    .done(); // Q.done()

package/test/common.js

@@ -1 +0,0 @@
-require('mocha-as-promised')(require('mocha'));