coa 0.4.1 → 1.0.3

package/lib/coaobject.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const Q = require('q');
+
+/**
+ * COA Object
+ *
+ * Base class for all COA-related objects
+ *
+ * --------|-----|-----|-----
+ *         | Cmd | Opt | Arg
+ * --------|-----|-----|-----
+ *  name   | ✓   | ✓   | ✓
+ *  title  | ✓   | ✓   | ✓
+ *  comp   | ✓   | ✓   | ✓
+ *  reject | ✓   | ✓   | ✓
+ *  end    | ✓   | ✓   | ✓
+ *  apply  | ✓   | ✓   | ✓
+ *
+ * @class CoaObject
+ */
+module.exports = class CoaObject {
+    constructor(cmd) {
+        this._cmd = cmd;
+        this._name = null;
+        this._title = null;
+        this._comp = null;
+    }
+
+    /**
+     * Set a canonical identifier to be used anywhere in the API.
+     *
+     * @param {String} name - command, option or argument name
+     * @returns {COA.CoaObject} - this instance (for chainability)
+     */
+    name(name) {
+        this._name = name;
+        return this;
+    }
+
+    /**
+     * Set a long description to be used anywhere in text messages.
+     * @param {String} title - human readable entity title
+     * @returns {COA.CoaObject} - this instance (for chainability)
+     */
+    title(title) {
+        this._title = title;
+        return this;
+    }
+
+    /**
+     * Set custom additional completion for current object.
+     *
+     * @param {Function} comp - completion generation function,
+     *         invoked in the context of object instance.
+     *         Accepts parameters:
+     *                 - {Object} opts - completion options
+     *         It can return promise or any other value threated as a result.
+     * @returns {COA.CoaObject} - this instance (for chainability)
+     */
+    comp(comp) {
+        this._comp = comp;
+        return this;
+    }
+
+    /**
+     * Apply function with arguments in a context of object instance.
+     *
+     * @param {Function} fn - body
+     * @param {Array.<*>} args... - arguments
+     * @returns {COA.CoaObject} - this instance (for chainability)
+     */
+    apply(fn) {
+        arguments.length > 1?
+            fn.apply(this, [].slice.call(arguments, 1))
+            : fn.call(this);
+
+        return this;
+    }
+
+    /**
+     * Return reject of actions results promise with error code.
+     * Use in .act() for return with error.
+     * @param {Object} reason - reject reason
+     *         You can customize toString() method and exitCode property
+     *         of reason object.
+     * @returns {Q.promise} rejected promise
+     */
+    reject(reason) {
+        return Q.reject(reason);
+    }
+
+    /**
+     * Finish chain for current subcommand and return parent command instance.
+     * @returns {COA.Cmd} parent command
+     */
+    end() {
+        return this._cmd;
+    }
+};

package/lib/coaparam.js

@@ -0,0 +1,125 @@
+'use strict';
+
+const fs = require('fs');
+
+const CoaObject = require('./coaobject');
+
+/**
+ * COA Parameter
+ *
+ * Base class for options and arguments
+ *
+ * --------|-----|-----|-----
+ *         | Cmd | Opt | Arg
+ * --------|-----|-----|-----
+ *  arr    |     | ✓   | ✓
+ *  req    |     | ✓   | ✓
+ *  val    |     | ✓   | ✓
+ *  def    |     | ✓   | ✓
+ *  input  |     | ✓   | ✓
+ *  output |     | ✓   | ✓
+ *
+ * @class CoaParam
+ * @extends CoaObject
+ */
+module.exports = class CoaParam extends CoaObject {
+    constructor(cmd) {
+        super(cmd);
+
+        this._arr = false;
+        this._req = false;
+        this._val = undefined;
+        this._def = undefined;
+    }
+
+    /**
+     * Makes a param accepts multiple values.
+     * Otherwise, the value will be used by the latter passed.
+     *
+     * @returns {COA.CoaParam} - this instance (for chainability)
+     */
+    arr() {
+        this._arr = true;
+        return this;
+    }
+
+    /**
+     * Makes a param required.
+     *
+     * @returns {COA.CoaParam} - this instance (for chainability)
+     */
+    req() {
+        this._req = true;
+        return this;
+    }
+
+    /**
+     * Set a validation (or value) function for param.
+     * Value from command line passes through before becoming available from API.
+     * Using for validation and convertion simple types to any values.
+     *
+     * @param {Function} val - validating function,
+     *         invoked in the context of option instance
+     *         and has one parameter with value from command line.
+     * @returns {COA.CoaParam} - this instance (for chainability)
+     */
+    val(val) {
+        this._val = val;
+        return this;
+    }
+
+    /**
+     * Set a default value for param.
+     * Default value passed through validation function as ordinary value.
+     *
+     * @param {*} def - default value of function generator
+     * @returns {COA.CoaParam} - this instance (for chainability)
+     */
+    def(def) {
+        this._def = def;
+        return this;
+    }
+
+    /**
+     * Make option value inputting stream.
+     * It's add useful validation and shortcut for STDIN.
+     *
+     * @returns {COA.CoaParam} - this instance (for chainability)
+     */
+    input() {
+        process.stdin.pause();
+        return this
+            .def(process.stdin)
+            .val(function(v) {
+                if(typeof v !== 'string')
+                    return v;
+
+                if(v === '-')
+                    return process.stdin;
+
+                const s = fs.createReadStream(v, { encoding : 'utf8' });
+                s.pause();
+                return s;
+            });
+    }
+
+    /**
+     * Make option value outputing stream.
+     * It's add useful validation and shortcut for STDOUT.
+     *
+     * @returns {COA.CoaParam} - this instance (for chainability)
+     */
+    output() {
+        return this
+            .def(process.stdout)
+            .val(function(v) {
+                if(typeof v !== 'string')
+                    return v;
+
+                if(v === '-')
+                    return process.stdout;
+
+                return fs.createWriteStream(v, { encoding : 'utf8' });
+            });
+    }
+};

package/lib/color.js

@@ -1,25 +1,22 @@
-// Generated by CoffeeScript 1.6.3
-var colors;
+'use strict';
 
-colors = {
-  black: '30',
-  dgray: '1;30',
-  red: '31',
-  lred: '1;31',
-  green: '32',
-  lgreen: '1;32',
-  brown: '33',
-  yellow: '1;33',
-  blue: '34',
-  lblue: '1;34',
-  purple: '35',
-  lpurple: '1;35',
-  cyan: '36',
-  lcyan: '1;36',
-  lgray: '37',
-  white: '1;37'
+const colors = {
+    black : '30',
+    dgray : '1;30',
+    red : '31',
+    lred : '1;31',
+    green : '32',
+    lgreen : '1;32',
+    brown : '33',
+    yellow : '1;33',
+    blue : '34',
+    lblue : '1;34',
+    purple : '35',
+    lpurple : '1;35',
+    cyan : '36',
+    lcyan : '1;36',
+    lgray : '37',
+    white : '1;37'
 };
 
-exports.Color = function(c, str) {
-  return ['\x1B[', colors[c], 'm', str, '\x1B[m'].join('');
-};
+module.exports = (c, str) => `\x1B[${colors[c]}m${str}\x1B[m`;

package/lib/completion.js

@@ -1,134 +1,176 @@
-// Generated by CoffeeScript 1.6.3
+'use strict';
+
+const constants = require('constants');
+const fs = require('fs');
+const path = require('path');
+
+const Q = require('q');
+
+const shell = require('./shell');
+const escape = shell.escape;
+const unescape = shell.unescape;
+
 /**
-Most of the code adopted from the npm package shell completion code.
-See https://github.com/isaacs/npm/blob/master/lib/completion.js
-*/
+ * Most of the code adopted from the npm package shell completion code.
+ * See https://github.com/isaacs/npm/blob/master/lib/completion.js
+ *
+ * @returns {COA.CoaObject}
+ */
+module.exports = function completion() {
+    return this
+        .title('Shell completion')
+        .helpful()
+        .arg()
+            .name('raw')
+            .title('Completion words')
+            .arr()
+            .end()
+        .act((opts, args) => {
+            if(process.platform === 'win32') {
+                const e = new Error('shell completion not supported on windows');
+                e.code = 'ENOTSUP';
+                e.errno = constants.ENOTSUP;
+                return this.reject(e);
+            }
 
-var Q, complete, dumpScript, escape, getOpts, unescape;
+            // if the COMP_* isn't in the env, then just dump the script
+            if((process.env.COMP_CWORD == null)
+                || (process.env.COMP_LINE == null)
+                || (process.env.COMP_POINT == null)) {
+                return dumpScript(this._cmd._name);
+            }
 
-Q = require('q');
+            console.error('COMP_LINE:  %s', process.env.COMP_LINE);
+            console.error('COMP_CWORD: %s', process.env.COMP_CWORD);
+            console.error('COMP_POINT: %s', process.env.COMP_POINT);
+            console.error('args: %j', args.raw);
 
-escape = require('./shell').escape;
+            // completion opts
+            opts = getOpts(args.raw);
 
-unescape = require('./shell').unescape;
+            // cmd
+            const parsed = this._cmd._parseCmd(opts.partialWords);
+            return Q.when(complete(parsed.cmd, parsed.opts), compls => {
+                console.error('filtered: %j', compls);
+                return console.log(compls.map(escape).join('\n'));
+            });
+        });
+};
 
-module.exports = function() {
-  return this.title('Shell completion').helpful().arg().name('raw').title('Completion words').arr().end().act(function(opts, args) {
-    var argv, cmd, e, _ref;
-    if (process.platform === 'win32') {
-      e = new Error('shell completion not supported on windows');
-      e.code = 'ENOTSUP';
-      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)) {
-      return dumpScript(this._cmd._name);
-    }
-    console.error('COMP_LINE:  %s', process.env.COMP_LINE);
-    console.error('COMP_CWORD: %s', process.env.COMP_CWORD);
-    console.error('COMP_POINT: %s', process.env.COMP_POINT);
-    console.error('args: %j', args.raw);
-    opts = getOpts(args.raw);
-    _ref = this._cmd._parseCmd(opts.partialWords), cmd = _ref.cmd, argv = _ref.argv;
-    return Q.when(complete(cmd, opts), function(compls) {
-      console.error('filtered: %j', compls);
-      return console.log(compls.map(escape).join('\n'));
+function dumpScript(name) {
+    const defer = Q.defer();
+
+    fs.readFile(path.resolve(__dirname, 'completion.sh'), 'utf8', function(err, d) {
+        if(err) return defer.reject(err);
+        d = d.replace(/{{cmd}}/g, path.basename(name)).replace(/^\#\!.*?\n/, '');
+
+        process.stdout.on('error', onError);
+        process.stdout.write(d, () => defer.resolve());
     });
-  });
-};
 
-dumpScript = function(name) {
-  var defer, fs, path;
-  fs = require('fs');
-  path = require('path');
-  defer = Q.defer();
-  fs.readFile(path.resolve(__dirname, 'completion.sh'), 'utf8', function(err, d) {
-    var onError;
-    if (err) {
-      return defer.reject(err);
-    }
-    d = d.replace(/{{cmd}}/g, path.basename(name)).replace(/^\#\!.*?\n/, '');
-    onError = function(err) {
-      if (err.errno === require('constants').EPIPE) {
+    return defer.promise;
+
+    function onError(err) {
+        // Darwin is a real dick sometimes.
+        //
+        // This is necessary because the "source" or "." program in
+        // bash on OS X closes its file argument before reading
+        // from it, meaning that you get exactly 1 write, which will
+        // work most of the time, and will always raise an EPIPE.
+        //
+        // Really, one should not be tossing away EPIPE errors, or any
+        // errors, so casually. But, without this, `. <(cmd completion)`
+        // can never ever work on OS X.
+        if(err.errno !== constants.EPIPE) return defer.reject(err);
         process.stdout.removeListener('error', onError);
         return defer.resolve();
-      } else {
-        return defer.reject(err);
-      }
+    }
+}
+
+function getOpts(argv) {
+    // get the partial line and partial word, if the point isn't at the end
+    // ie, tabbing at: cmd foo b|ar
+    const line = process.env.COMP_LINE;
+    const w = +process.env.COMP_CWORD;
+    const point = +process.env.COMP_POINT;
+    const words = argv.map(unescape);
+    const word = words[w];
+    const partialLine = line.substr(0, point);
+    const partialWords = words.slice(0, w);
+
+    // figure out where in that last word the point is
+    let partialWord = argv[w] || '';
+    let i = partialWord.length;
+    while(partialWord.substr(0, i) !== partialLine.substr(-1 * i) && i > 0) i--;
+
+    partialWord = unescape(partialWord.substr(0, i));
+    partialWord && partialWords.push(partialWord);
+
+    return {
+        line,
+        w,
+        point,
+        words,
+        word,
+        partialLine,
+        partialWords,
+        partialWord
     };
-    process.stdout.on('error', onError);
-    return process.stdout.write(d, function() {
-      return defer.resolve();
-    });
-  });
-  return defer.promise;
-};
+}
 
-getOpts = function(argv) {
-  var i, line, partialLine, partialWord, partialWords, point, w, word, words;
-  line = process.env.COMP_LINE;
-  w = +process.env.COMP_CWORD;
-  point = +process.env.COMP_POINT;
-  words = argv.map(unescape);
-  word = words[w];
-  partialLine = line.substr(0, point);
-  partialWords = words.slice(0, w);
-  partialWord = argv[w] || '';
-  i = partialWord.length;
-  while (partialWord.substr(0, i) !== partialLine.substr(-1 * i) && i > 0) {
-    i--;
-  }
-  partialWord = unescape(partialWord.substr(0, i));
-  if (partialWord) {
-    partialWords.push(partialWord);
-  }
-  return {
-    line: line,
-    w: w,
-    point: point,
-    words: words,
-    word: word,
-    partialLine: partialLine,
-    partialWords: partialWords,
-    partialWord: partialWord
-  };
-};
+function complete(cmd, opts) {
+    let optWord, optPrefix,
+        compls = [];
 
-complete = function(cmd, opts) {
-  var compls, m, o, opt, optPrefix, optWord;
-  compls = [];
-  if (opts.partialWord.indexOf('-')) {
-    compls = Object.keys(cmd._cmdsByName);
-  } else {
-    if (m = opts.partialWord.match(/^(--\w[\w-_]*)=(.*)$/)) {
-      optWord = m[1];
-      optPrefix = optWord + '=';
-    } else {
-      compls = Object.keys(cmd._optsByKey);
-    }
-  }
-  if (!(o = opts.partialWords[opts.w - 1]).indexOf('-')) {
-    optWord = o;
-  }
-  if (optWord && (opt = cmd._optsByKey[optWord])) {
-    if (!opt._flag && opt._comp) {
-      compls = Q.all([compls, opt._comp(opts)]).spread(function(c, o) {
-        return c.concat(o.map(function(v) {
-          return (optPrefix || '') + v;
-        }));
-      });
+    // Complete on cmds
+    if(opts.partialWord.indexOf('-'))
+        compls = Object.keys(cmd._cmdsByName);
+        // Complete on required opts without '-' in last partial word
+        // (if required not already specified)
+        //
+        // Commented out because of uselessness:
+        // -b, --block suggest results in '-' on cmd line;
+        // next completion suggest all options, because of '-'
+        //.concat Object.keys(cmd._optsByKey).filter (v) -> cmd._optsByKey[v]._req
+    else {
+        // complete on opt values: --opt=| case
+        const m = opts.partialWord.match(/^(--\w[\w-_]*)=(.*)$/);
+        if(m) {
+            optWord = m[1];
+            optPrefix = optWord + '=';
+        } else
+            // complete on opts
+            // don't complete on opts in case of --opt=val completion
+            // TODO: don't complete on opts in case of unknown arg after commands
+            // TODO: complete only on opts with arr() or not already used
+            // TODO: complete only on full opts?
+            compls = Object.keys(cmd._optsByKey);
     }
-  }
-  if (cmd._comp) {
-    compls = Q.all([compls, cmd._comp(opts)]).spread(function(c, o) {
-      return c.concat(o);
-    });
-  }
-  return Q.when(compls, function(compls) {
-    console.error('partialWord: %s', opts.partialWord);
-    console.error('compls: %j', compls);
-    return compls.filter(function(c) {
-      return c.indexOf(opts.partialWord) === 0;
+
+    // complete on opt values: next arg case
+    opts.partialWords[opts.w - 1].indexOf('-') || (optWord = opts.partialWords[opts.w - 1]);
+
+    // complete on opt values: completion
+    let opt;
+    optWord
+        && (opt = cmd._optsByKey[optWord])
+        && !opt._flag
+        && opt._comp
+        && (compls = Q.join(compls,
+            Q.when(opt._comp(opts),
+                (c, o) => c.concat(o.map(v => (optPrefix || '') + v)))));
+
+    // TODO: complete on args values (context aware, custom completion?)
+
+    // custom completion on cmds
+    cmd._comp && (compls = Q.join(compls, Q.when(cmd._comp(opts)), (c, o) => c.concat(o)));
+
+    // TODO: context aware custom completion on cmds, opts and args
+    // (can depend on already entered values, especially options)
+
+    return Q.when(compls, complitions => {
+        console.error('partialWord: %s', opts.partialWord);
+        console.error('compls: %j', complitions);
+        return compls.filter(c => c.indexOf(opts.partialWord) === 0);
     });
-  });
-};
+}

package/lib/index.js

@@ -1,10 +1,14 @@
-// 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;
+const
+    Cmd = require('./cmd'),
+    Opt = require('./opt'),
+    Arg = require('./arg'),
+    shell = require('./shell');
+
+module.exports = {
+    Cmd : Cmd.create,
+    Opt : Opt.create,
+    Arg : Arg.create,
+    classes : { Cmd, Opt, Arg },
+    shell,
+    require
+};