node_modules/coa/lib/cmd.js

/* eslint-disable class-methods-use-this */
'use strict';

const
    UTIL = require('util'),
    PATH = require('path'),
    EOL = require('os').EOL,

    Q = require('q'),
    chalk = require('chalk'),

    CoaObject = require('./coaobject'),
    Opt = require('./opt'),
    Arg = require('./arg'),
    completion = require('./completion');

/**
 * Command
 *
 * Top level entity. Commands may have options and arguments.
 *
 * @namespace
 * @class Cmd
 * @extends CoaObject
 */
class Cmd extends CoaObject {
    /**
     * @constructs
     * @param {COA.Cmd} [cmd] parent command
     */
    constructor(cmd) {
        super(cmd);

        this._parent(cmd);
        this._cmds = [];
        this._cmdsByName = {};
        this._opts = [];
        this._optsByKey = {};
        this._args = [];
        this._api = null;
        this._ext = false;
    }

    static create(cmd) {
        return new Cmd(cmd);
    }

    /**
     * Returns object containing all its subcommands as methods
     * to use from other programs.
     *
     * @returns {Object}
     */
    get api() {
        // Need _this here because of passed arguments into _api
        const _this = this;
        this._api || (this._api = function () {
            return _this.invoke.apply(_this, arguments);
        });

        const cmds = this._cmdsByName;
        Object.keys(cmds).forEach(cmd => { this._api[cmd] = cmds[cmd].api; });

        return this._api;
    }

    _parent(cmd) {
        this._cmd = cmd || this;

        this.isRootCmd ||
            cmd._cmds.push(this) &&
            this._name &&
            (this._cmd._cmdsByName[this._name] = this);

        return this;
    }

    get isRootCmd() {
        return this._cmd === this;
    }

    /**
     * Set a canonical command identifier to be used anywhere in the API.
     *
     * @param {String} name - command name
     * @returns {COA.Cmd} - this instance (for chainability)
     */
    name(name) {
        super.name(name);

        this.isRootCmd ||
            (this._cmd._cmdsByName[name] = this);

        return this;
    }

    /**
     * Create new or add existing subcommand for current command.
     *
     * @param {COA.Cmd} [cmd] existing command instance
     * @returns {COA.Cmd} new subcommand instance
     */
    cmd(cmd) {
        return cmd?
            cmd._parent(this)
            : new Cmd(this);
    }

    /**
     * Create option for current command.
     *
     * @returns {COA.Opt} new option instance
     */
    opt() {
        return new Opt(this);
    }

    /**
     * Create argument for current command.
     *
     * @returns {COA.Opt} new argument instance
     */
    arg() {
        return new Arg(this);
    }

    /**
     * Add (or set) action for current command.
     *
     * @param {Function} act - action function,
     *         invoked in the context of command instance
     *         and has the parameters:
     *                 - {Object} opts - parsed options
     *                 - {String[]} args - parsed arguments
     *                 - {Object} res - actions result accumulator
     *         It can return rejected promise by Cmd.reject (in case of error)
     *         or any other value treated as result.
     * @param {Boolean} [force=false] flag for set action instead add to existings
     * @returns {COA.Cmd} - this instance (for chainability)
     */
    act(act, force) {
        if(!act) return this;

        (!this._act || force) && (this._act = []);
        this._act.push(act);

        return this;
    }

    /**
     * Make command "helpful", i.e. add -h --help flags for print usage.
     *
     * @returns {COA.Cmd} - this instance (for chainability)
     */
    helpful() {
        return this.opt()
            .name('help')
            .title('Help')
            .short('h')
            .long('help')
            .flag()
            .only()
            .act(function() {
                return this.usage();
            })
            .end();
    }

    /**
     * Adds shell completion to command, adds "completion" subcommand,
     * that makes all the magic.
     * Must be called only on root command.
     *
     * @returns {COA.Cmd} - this instance (for chainability)
     */
    completable() {
        return this.cmd()
            .name('completion')
            .apply(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) {
        this._ext = pattern || true;
        return this;
    }

    _exit(msg, code) {
        return process.once('exit', function(exitCode) {
            msg && console[code === 0 ? 'log' : 'error'](msg);
            process.exit(code || exitCode || 0);
        });
    }

    /**
     * Build full usage text for current command instance.
     *
     * @returns {String} usage text
     */
    usage() {
        const res = [];

        this._title && res.push(this._fullTitle());

        res.push('', 'Usage:');

        this._cmds.length
            && res.push([
                '', '', chalk.redBright(this._fullName()), chalk.blueBright('COMMAND'),
                chalk.greenBright('[OPTIONS]'), chalk.magentaBright('[ARGS]')
            ].join(' '));

        (this._opts.length + this._args.length)
            && res.push([
                '', '', chalk.redBright(this._fullName()),
                chalk.greenBright('[OPTIONS]'), chalk.magentaBright('[ARGS]')
            ].join(' '));

        res.push(
            this._usages(this._cmds, 'Commands'),
            this._usages(this._opts, 'Options'),
            this._usages(this._args, 'Arguments')
        );

        return res.join(EOL);
    }

    _usage() {
        return chalk.blueBright(this._name) + ' : ' + this._title;
    }

    _usages(os, title) {
        if(!os.length) return;

        return ['', title + ':']
            .concat(os.map(o => `  ${o._usage()}`))
            .join(EOL);
    }

    _fullTitle() {
        return `${this.isRootCmd? '' : this._cmd._fullTitle() + EOL}${this._title}`;
    }

    _fullName() {
        return `${this.isRootCmd? '' : this._cmd._fullName() + ' '}${PATH.basename(this._name)}`;
    }

    _ejectOpt(opts, opt) {
        const pos = opts.indexOf(opt);
        if(pos === -1) return;

        return opts[pos]._arr?
            opts[pos] :
            opts.splice(pos, 1)[0];
    }

    _checkRequired(opts, args) {
        if(this._opts.some(opt => opt._only && opts.hasOwnProperty(opt._name))) return;

        const all = this._opts.concat(this._args);
        let i;
        while(i = all.shift())
            if(i._req && i._checkParsed(opts, args))
                return this.reject(i._requiredText());
    }

    _parseCmd(argv, unparsed) {
        unparsed || (unparsed = []);

        let i,
            optSeen = false;
        while(i = argv.shift()) {
            i.indexOf('-') || (optSeen = true);

            if(optSeen || !/^\w[\w-_]*$/.test(i)) {
                unparsed.push(i);
                continue;
            }

            let pkg, cmd = this._cmdsByName[i];
            if(!cmd && this._ext) {
                if(this._ext === true) {
                    pkg = i;
                    let c = this;
                    while(true) { // eslint-disable-line
                        pkg = c._name + '-' + pkg;
                        if(c.isRootCmd) break;
                        c = c._cmd;
                    }
                } else if(typeof this._ext === 'string')
                    pkg = ~this._ext.indexOf('%s')?
                        UTIL.format(this._ext, i) :
                        this._ext + i;

                let cmdDesc;
                try {
                    cmdDesc = require(pkg);
                } catch(e) {
                    // Dummy
                }

                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 a function or COA.Cmd() object');

                    cmd = this._cmdsByName[i];
                }
            }

            if(cmd) return cmd._parseCmd(argv, unparsed);

            unparsed.push(i);
        }

        return { cmd : this, argv : unparsed };
    }

    _parseOptsAndArgs(argv) {
        const opts = {},
            args = {},
            nonParsedOpts = this._opts.concat(),
            nonParsedArgs = this._args.concat();

        let res, i;
        while(i = argv.shift()) {
            if(i !== '--' && i[0] === '-') {
                const m = i.match(/^(--\w[\w-_]*)=(.*)$/);
                if(m) {
                    i = m[1];
                    this._optsByKey[i]._flag || argv.unshift(m[2]);
                }

                const opt = this._ejectOpt(nonParsedOpts, this._optsByKey[i]);
                if(!opt) return this.reject(`Unknown option: ${i}`);

                if(Q.isRejected(res = opt._parse(argv, opts))) return res;

                continue;
            }

            i === '--' && (i = argv.splice(0));
            Array.isArray(i) || (i = [i]);

            let a;
            while(a = i.shift()) {
                let arg = nonParsedArgs.shift();
                if(!arg) return this.reject(`Unknown argument: ${a}`);

                arg._arr && nonParsedArgs.unshift(arg);
                if(Q.isRejected(res = arg._parse(a, args))) return res;
            }
        }

        return {
            opts : this._setDefaults(opts, nonParsedOpts),
            args : this._setDefaults(args, nonParsedArgs)
        };
    }

    _setDefaults(params, desc) {
        for(const item of desc)
            item._def !== undefined &&
                !params.hasOwnProperty(item._name) &&
                item._saveVal(params, item._def);

        return params;
    }

    _processParams(params, desc) {
        const notExists = [];

        for(const item of desc) {
            const n = item._name;

            if(!params.hasOwnProperty(n)) {
                notExists.push(item);
                continue;
            }

            const vals = Array.isArray(params[n])? params[n] : [params[n]];
            delete params[n];

            let res;
            for(const v of vals)
                if(Q.isRejected(res = item._saveVal(params, v)))
                    return res;
        }

        return this._setDefaults(params, notExists);
    }

    _parseArr(argv) {
        return Q.when(this._parseCmd(argv), p =>
            Q.when(p.cmd._parseOptsAndArgs(p.argv), r => ({
                cmd : p.cmd,
                opts : r.opts,
                args : r.args
            })));
    }

    _do(inputPromise) {
        return Q.when(inputPromise, input => {
            return [this._checkRequired]
                .concat(input.cmd._act || [])
                .reduce((res, act) =>
                    Q.when(res, prev => act.call(input.cmd, input.opts, input.args, prev)),
                    undefined);
        });
    }

    /**
     * Parse arguments from simple format like NodeJS process.argv
     * and run ahead current program, i.e. call process.exit when all actions done.
     *
     * @param {String[]} argv - arguments
     * @returns {COA.Cmd} - this instance (for chainability)
     */
    run(argv) {
        argv || (argv = process.argv.slice(2));

        const cb = code =>
            res => res?
                this._exit(res.stack || res.toString(), (res.hasOwnProperty('exitCode')? res.exitCode : code) || 0) :
                this._exit();

        Q.when(this.do(argv), cb(0), cb(1)).done();

        return this;
    }

    /**
     * Invoke specified (or current) command using provided
     * options and arguments.
     *
     * @param {String|String[]} [cmds] - subcommand to invoke (optional)
     * @param {Object} [opts] - command options (optional)
     * @param {Object} [args] - command arguments (optional)
     * @returns {Q.Promise}
     */
    invoke(cmds, opts, args) {
        cmds || (cmds = []);
        opts || (opts = {});
        args || (args = {});
        typeof cmds === 'string' && (cmds = cmds.split(' '));

        if(arguments.length < 3 && !Array.isArray(cmds)) {
            args = opts;
            opts = cmds;
            cmds = [];
        }

        return Q.when(this._parseCmd(cmds), p => {
            if(p.argv.length)
                return this.reject(`Unknown command: ${cmds.join(' ')}`);

            return Q.all([
                this._processParams(opts, this._opts),
                this._processParams(args, this._args)
            ]).spread((_opts, _args) =>
                this._do({
                    cmd : p.cmd,
                    opts : _opts,
                    args : _args
                })
                .fail(res => (res && res.exitCode === 0)?
                    res.toString() :
                    this.reject(res)));
        });
    }
}

/**
 * Convenient function to run command from tests.
 *
 * @param {String[]} argv - arguments
 * @returns {Q.Promise}
 */
Cmd.prototype.do = function(argv) {
    return this._do(this._parseArr(argv || []));
};

module.exports = Cmd;