coa/src/cmd.coffee

UTIL = require 'util'
PATH = require 'path'
Color = require('./color').Color
Q = require('q')
#inspect = require('eyes').inspector { maxLength: 99999, stream: process.stderr }
###*
Command
Top level entity. Commands may have options and arguments.
@namespace
@class Presents command
###
exports.Cmd = class Cmd
    ###*
    @constructs
    @param {COA.Cmd} [cmd] parent command
    ###
    constructor: (cmd) ->
        if this not instanceof Cmd
            return new Cmd cmd
        @_parent cmd
        @_cmds = []
        @_cmdsByName = {}
        @_opts = []
        @_optsByKey = {}
        @_args = []
        @_ext = false
    @get: (propertyName, func) ->
        Object.defineProperty @::, propertyName,
            configurable: true
            enumerable: true
            get: func
    ###*
    Returns object containing all its subcommands as methods
    to use from other programs.
    @returns {Object}
    ###
    @get 'api', () ->
        if not @_api
            @_api = => @invoke.apply @, arguments
        for c of @_cmdsByName
            do (c) =>
                @_api[c] = @_cmdsByName[c].api
        @_api
    _parent: (cmd) ->
        @_cmd = cmd or this
        if cmd
            cmd._cmds.push @
            if @_name then @_cmd._cmdsByName[@_name] = @
        @
    ###*
    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) ->
        if @_cmd isnt @ then @_cmd._cmdsByName[_name] = @
        @
    ###*
    Set a long description for command to be used anywhere in text messages.
    @param {String} _title command title
    @returns {COA.Cmd} this instance (for chainability)
    ###
    title: (@_title) -> @
    ###*
    Create new or add existing subcommand for current command.
    @param {COA.Cmd} [cmd] existing command instance
    @returns {COA.Cmd} new subcommand instance
    ###
    cmd: (cmd) ->
        if cmd then cmd._parent @
        else new Cmd @
    ###*
    Create option for current command.
    @returns {COA.Opt} new option instance
    ###
    opt: -> new (require('./opt').Opt) @
    ###*
    Create argument for current command.
    @returns {COA.Opt} new argument instance
    ###
    arg: -> new (require('./arg').Arg) @
    ###*
    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
            - {Array} 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) ->
        return @ unless act
        if not force and @_act
            @_act.push act
        else
            @_act = [act]
        @
    ###*
    Set custom additional completion for current command.
    @param {Function} completion generation function,
        invoked in the context of command instance.
        Accepts parameters:
            - {Object} opts completion options
        It can return promise or any other value treated as result.
    @returns {COA.Cmd} this instance (for chainability)
    ###
    comp: (@_comp) -> @
    ###*
    Apply function with arguments in context of command instance.
    @param {Function} fn
    @param {Array} args
    @returns {COA.Cmd} this instance (for chainability)
    ###
    apply: (fn, args...) ->
        fn.apply this, args
        @
    ###*
    Make command "helpful", i.e. add -h --help flags for print usage.
    @returns {COA.Cmd} this instance (for chainability)
    ###
    helpful: ->
        @opt()
            .name('help').title('Help')
            .short('h').long('help')
            .flag()
            .only()
            .act ->
                return @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: ->
        @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)
    ###
    extendable: (pattern) ->
        @_ext = pattern or true
        @
    _exit: (msg, code) ->
        process.once 'exit', ->
            if msg then console.error msg
            process.exit code or 0
    ###*
    Build full usage text for current command instance.
    @returns {String} usage text
    ###
    usage: ->
        res = []
        if @_title then res.push @_fullTitle()
        res.push('', 'Usage:')
        if @_cmds.length then res.push(['', '',
            Color('lred', @_fullName()),
            Color('lblue', 'COMMAND'),
            Color('lgreen', '[OPTIONS]'),
            Color('lpurple', '[ARGS]')].join ' ')
        if @_opts.length + @_args.length then res.push(['', '',
            Color('lred', @_fullName()),
            Color('lgreen', '[OPTIONS]'),
            Color('lpurple', '[ARGS]')].join ' ')
        res.push(
            @_usages(@_cmds, 'Commands'),
            @_usages(@_opts, 'Options'),
            @_usages(@_args, 'Arguments'))
        res.join '\n'
    _usage: ->
        Color('lblue', @_name) + ' : ' + @_title
    _usages: (os, title) ->
        unless os.length then return
        res = ['', title + ':']
        for o in os
            res.push '  ' + o._usage()
        res.join '\n'
    _fullTitle: ->
        (if @_cmd is this then '' else @_cmd._fullTitle() + '\n') + @_title
    _fullName: ->
        (if this._cmd is this then '' else @_cmd._fullName() + ' ') + PATH.basename(@_name)
    _ejectOpt: (opts, opt) ->
        if (pos = opts.indexOf(opt)) >= 0
            if opts[pos]._arr
                opts[pos]
            else
                opts.splice(pos, 1)[0]
    _checkRequired: (opts, args) ->
        if not (@_opts.filter (o) -> o._only and o._name of opts).length
            all = @_opts.concat @_args
            while i = all.shift()
                if i._req and i._checkParsed opts, args
                    return @reject i._requiredText()
    _parseCmd: (argv, unparsed = []) ->
        argv = argv.concat()
        optSeen = false
        while i = argv.shift()
            if not i.indexOf '-'
                optSeen = true
            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
        { cmd: @, argv: unparsed }
    _parseOptsAndArgs: (argv) ->
        opts = {}
        args = {}
        nonParsedOpts = @_opts.concat()
        nonParsedArgs = @_args.concat()
        while i = argv.shift()
            # opt
            if i isnt '--' and not i.indexOf '-'
                if m = i.match /^(--\w[\w-_]*)=(.*)$/
                    i = m[1]
                    # suppress 'unknown argument' error for flag options with values
                    if not @_optsByKey[i]._flag
                        argv.unshift m[2]
                if opt = @_ejectOpt nonParsedOpts, @_optsByKey[i]
                    if Q.isRejected(res = opt._parse argv, opts)
                        return res
                else
                    return @reject "Unknown option: #{ i }"
            # arg
            else
                if i is '--'
                    i = argv.splice(0)
                i = if Array.isArray(i) then i else [i]
                while a = i.shift()
                    if arg = nonParsedArgs.shift()
                        if arg._arr then nonParsedArgs.unshift arg
                        if Q.isRejected(res = arg._parse a, args)
                            return res
                    else
                        return @reject "Unknown argument: #{ a }"
        # set defaults
        {
            opts: @_setDefaults(opts, nonParsedOpts),
            args: @_setDefaults(args, nonParsedArgs)
        }
    _setDefaults: (params, desc) ->
        for i in desc
            if i._name not of params and '_def' of i
                i._saveVal params, i._def
        params
    _processParams: (params, desc) ->
        notExists = []
        for i in desc
            n = i._name
            if n not of params
                notExists.push i
                continue
            vals = params[n]
            delete params[n]
            if not Array.isArray vals
                vals = [vals]
            for v in vals
                if Q.isRejected(res = i._saveVal(params, v))
                    return res
        # set defaults
        @_setDefaults params, notExists
    _parseArr: (argv) ->
        Q.when @_parseCmd(argv), (p) ->
            Q.when p.cmd._parseOptsAndArgs(p.argv), (r) ->
                { cmd: p.cmd, opts: r.opts, args: r.args }
    _do: (input) ->
        Q.when input, (input) =>
            cmd = input.cmd
            [@_checkRequired].concat(cmd._act or []).reduce(
                (res, act) ->
                    Q.when res, (res) ->
                        act.call(
                            cmd
                            input.opts
                            input.args
                            res)
                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 {Array} argv
    @returns {COA.Cmd} this instance (for chainability)
    ###
    run: (argv = process.argv.slice(2)) ->
        cb = (code) => (res) =>
            if res
                @_exit res.stack ? res.toString(), res.exitCode ? code
            else
                @_exit()
        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.
    @param {String|Array} cmds  subcommand to invoke (optional)
    @param {Object} opts  command options (optional)
    @param {Object} args  command arguments (optional)
    @returns {Q.Promise}
    ###
    invoke: (cmds = [], opts = {}, args = {}) ->
        if typeof cmds == 'string'
            cmds = cmds.split(' ')
        if arguments.length < 3
            if not Array.isArray cmds
                args = opts
                opts = cmds
                cmds = []
        Q.when @_parseCmd(cmds), (p) =>
            if p.argv.length
                return @reject "Unknown command: " + cmds.join ' '
            Q.all([@_processParams(opts, @_opts), @_processParams(args, @_args)])
                .spread (opts, args) =>
                    @_do({ cmd: p.cmd, opts: opts, args: args })
                        # catch fails from .only() options
                        .fail (res) =>
                            if res and res.exitCode is 0
                                res.toString()
                            else
                                @reject(res)
    ###*
    Return reject of actions results promise with error code.
    Use in .act() for return with error.
    @param {Object} reject reason
        You can customize toString() method and exitCode property
        of reason object.
    @returns {Q.promise} rejected promise
    ###
    reject: (reason) -> Q.reject(reason)
    ###*
    Finish chain for current subcommand and return parent command instance.
    @returns {COA.Cmd} parent command
    ###
    end: -> @_cmd