index.js

var path = require('path')
  , util = require('util')

  , middleware = require('cli-middleware')
  , utils = require('cli-util')
  , define = utils.define
  , merge = utils.merge
  , funcname = utils.funcname
  , logger = require('cli-logger')

  , cli = require('cli-define')
  , Program = cli.Program
  , Option = cli.Option
  , Flag = cli.Flag
  , Command = cli.Command
  , key = cli.key

  , clierr = require('cli-error')
  , errors = clierr.errors
  , ErrorDefinition = clierr.ErrorDefinition
  , CliError = clierr.CliError

  // TODO: make ExecError available
  , errs = {}
  , types = require('cli-types')
  , conflict = require('cli-conflict')
  , system = require('cli-system')

  , syslog = require('./lib/syslog').log;

var debug = !!process.env.CLI_TOOLKIT_DEBUG;

// backward compatible property access
system.include(true);

var all = system.standard();

errs.type = types.ArgumentTypeError;

var defaults = require('./lib/defaults');

var CommandProgram = function() {
  Program.apply(this, arguments);

  var conf = merge(defaults, {}, {copy: true})

  // private
  define(this, '_middleware', undefined, true);
  define(this, '_conf', conf, true);
  define(this, '_request', undefined, true);
  define(this, '_middlecache', [], true);

  // TODO: remove this circular reference
  this._conf.stash = this;

  // public
  define(this, 'errors', errors, false);
}

util.inherits(CommandProgram, Program);

/**
 *  Get or set the middleware request object.
 *
 *  @param req The request object.
 */
function request(req) {
  if(!arguments.length) return this._request;
  this._request = req;
  return this;
}
define(CommandProgram.prototype, 'request', request, false);

/**
 *  Wrap an error from an error definition, string
 *  or Error instance.
 *
 *  @param err The error definition, string or Error.
 *  @param parameters The message replacement parameters.
 *  @param source A source error to wrap.
 */
function wrap(err, parameters, source) {
  var msg = 'Cannot wrap invalid error \'' + err + '\'';
  if(!err) {
    throw new TypeError(msg);
  }
  var e, code = err.code || errors.EGENERIC.code;
  if(err instanceof CliError) {
    e = err;
  }else if(err instanceof ErrorDefinition) {
    e = err.toError(source, parameters);
    if(!source) e.shift();
    e.parameters = parameters;
    //e.key = err.key;
  }else if(err instanceof Error) {
    e = new CliError(err, code, parameters);
    e.key = err.key || errors.EGENERIC.key;
    err.key = e.key;
  }else if(typeof err === 'string') {
    e = new CliError(source || err, code, parameters);
  }else{
    throw new TypeError(msg);
  }
  return e;
}
define(CommandProgram.prototype, 'wrap', wrap, false);

/**
 *  Raise an error from an error definition or error
 *  instance.
 *
 *  @param err The error definition.
 *  @param parameters The message replacement parameters.
 *  @param source A source error to wrap.
 */
function raise(err, parameters, source) {
  var e = this.wrap(err, parameters, source);
  this.emit('raise', e, errors, err, parameters, source);
  this.emit('error', e, errors, err, parameters, source);
  return e;
}
define(CommandProgram.prototype, 'raise', raise, false);

/**
 *  Define program middleware.
 */
function use(middleware) {
  var i, nm, closure, conf = this.configure();
  var ind = -1, args = [].slice.call(arguments, 1);
  if(middleware === false) {
    this._middlecache = [];
    this._middleware = [];
    return this;
  }
  if(typeof middleware === 'number') {
    ind = middleware;
    middleware = arguments[1];
    args = [].slice.call(arguments, 2);
  }
  if(!arguments.length && this._middleware === undefined) {
    //if(!all) {
      //all = system.standard();
    //}
    for(i = 0;i < all.length;i++) {
      if(conf && conf.middleware) {
        closure = all[i].call(this);
        if(typeof closure !== 'function') {
          continue;
        }
        nm = funcname(closure);
        //console.log('got name %s', nm);
        if(nm && conf.middleware[nm] === false) {
          continue;
        }
      }
      this.use(all[i]);
    }
    return this;
  }
  if(typeof middleware != 'function') {
    throw new Error('Invalid middleware, must be a function');
  }
  closure = middleware.apply(this, args);
  if(this._middlecache && ~this._middlecache.indexOf(middleware)) {
    throw new Error('Invalid middleware, duplicate detected');
  }
  if(typeof(closure) == 'function') {
    if(this._middleware === undefined) this._middleware = [];
    if(ind < 0 || ind >= this._middleware.length) {
      //console.log('adding closure... %s', closure);
      this._middleware.push(closure);
    }else{
      this._middleware.splice(ind, 0, closure);
    }
  }

  this._middlecache.push(middleware);

  return this;
}
define(CommandProgram.prototype, 'use', use, false);

/**
 *  Default error handler for the error event.
 *
 *  @param e The error instance.
 */
function error(e) {
  var conf = this.configure();
  if(!(e instanceof CliError)) {
    e = this.wrap(e);
  }
  var trace =
    (conf.trace !== undefined)
      ? conf.trace : (e.code === errors.EUNCAUGHT.code);
  //console.log('conf.trace %s', conf.trace);
  //console.log('trace %s', trace);
  //console.log('code %s', e.code);
  var logger = this.log && typeof(this.log.error) === 'function';
  if(logger && conf.error.log) {
    if(conf.error.log.print) {
      var args = (e.parameters || []).slice(0);
      args.unshift(e.message);
      this.log.error.apply(this.log, args);
      if(trace) {
        var stack = e.stack;
        if(stack) {
          var lines = e._stacktrace || [];
          lines = lines.map(function(value) {
            return '  ' + value;
          })
          stack = lines.join('\n');
          this.log.error(stack);
        }
      }
    }else{
      //console.dir(e);
      this.log.error(e);
    }
  }else{
    e.error(trace)
  }
  if(conf.exit) e.exit();
}
define(CommandProgram.prototype, 'error', error, false);

/**
 *  Assigns configuration information to the program.
 *
 *  @param conf The program configuration.
 */
function configure(conf) {
  if(!arguments.length) return this._conf;
  conf = conf || {};
  this._conf = merge(conf, this._conf);
  if(conf.stash) {
    this._conf.stash = conf.stash;
  }

  // load custom error definitions
  if(conf && conf.error
    && typeof conf.error === 'object' && conf.error.locales) {
    clierr.file(conf.error, function(err) {
      if(err) throw err;
    })
  }
  return this;
}
define(CommandProgram.prototype, 'configure', configure, false);

/**
 *  Adds a version flag to the program.
 *
 *  @param semver A specific version number.
 *  @param name The argument name.
 *  @param description The argument description.
 *  @param action A function to invoke.
 */

// WARN: do not use, this is too overloaded, will be removed
// WARN: do: cli.use(require('cli-mid-version')) instead for the middleware
function version(semver, name, description, action) {
  if(arguments.length === 1 && typeof semver === 'string') {
    this._version = semver;
    return this;
  }
  if(!arguments.length && this._options.versionopt) return this._version;
  return this.use(system.version, semver, name, description, action);
}
define(CommandProgram.prototype, 'version', version, false);

/**
 *  Reset all values assigned to options.
 *
 *  Designed to be used in the scenario that you wish
 *  to re-parse through the same instance and ensure that
 *  values do not carry through.
 */
function reset(target) {
  target = target || this.configure().stash || this;
  var opts = target.options(), k;
  for(k in opts) {
    delete opts[k].value(undefined);
  }
  var cmds = target.commands();
  for(k in cmds) {
    reset(cmds[k]);
  }
}
define(CommandProgram.prototype, 'reset', reset, false);

/**
 *  Adds a help flag to the program.
 *
 *  @param name The argument name.
 *  @param description The argument description.
 *  @param action A function to invoke.
 */
function help(name, description, action) {
  return this.use(system.help, name, description, action);
}
define(CommandProgram.prototype, 'help', help, false);

/**
 *  Parse the supplied arguments and execute any commands
 *  found in the arguments, preferring the built in commands
 *  for help and version.
 *
 *  @param args The arguments to parse, default is process.argv.slice(2).
 *  @param req An existing request object to use.
 *  @param cb A complete callback function.
 */
function parse(args, req, cb) {
  if(typeof req === 'function') {
    cb = req;
    req = null;
  }
  var conf = this.configure();
  args = args || process.argv.slice(2);
  conflict.call(this);

  if(this._middleware === undefined) {
    this.use();
  }

  var opts = {
    syslog: syslog,
    list: this._middleware,
    errors: this.errors,
    bail: conf.bail,
    throws: true,
    intercept: conf.error.intercept,
    scope: this
  }
  var runner = middleware(opts);
  // NOTE: want to be using this again!
  //runner(args, req, cb);

  // NOTE: backward compatible argument order switch
  // NOTE: allows us to upgrade cli-middleware but not
  // NOTE: break absolutely everything
  runner(args, req, function(err, req) {
    if(cb) {
      cb.call(this, req, err);
    }else{
      this.emit('complete', req, err);
    }
  });
  return this;
}
define(CommandProgram.prototype, 'parse', parse, false);

module.exports = function(package, name, description, options) {
  options = options || {};
  var locales = path.join(__dirname, 'lib', 'error', 'locales');
  clierr.file({locales: locales});
  var program = cli(package, name, description, CommandProgram);
  var listeners = process.listeners('uncaughtException');
  if(!listeners.length) {
    process.on('uncaughtException', function(err) {
      err.code = errors.EUNCAUGHT.code;
      //console.dir(err);
      //console.log(err.stack);
      program.raise(err);
    })
  }
  if(debug) {
    syslog.level(logger.TRACE);
  }
  if(options.log === false) {
    syslog.level(logger.NONE);
  }
  // TODO: allow setting error configuration on the program configuration
  clierr({name: program.name()});
  return program;
}

// classes
module.exports.Interface = require('./interface');
module.exports.CommandProgram = CommandProgram;
module.exports.Program = Program;
module.exports.Command = Command;
module.exports.Option = Option;
module.exports.Flag = Flag;
module.exports.ErrorDefinition = ErrorDefinition;
module.exports.CliError = CliError;

// library exports
module.exports.defaults = defaults;

// deprecated legacy access via middleware
module.exports.middleware = system;

// new access via system (use this)
module.exports.system = system;

module.exports.help = system.help.action;
module.exports.version = system.version.action;

// dependency exports
module.exports.util = utils;
module.exports.define = cli;
module.exports.logger = logger;

// decorate with internal error classes
clierr.ArgumentTypeError = errs.type;
module.exports.error = clierr;

// internal libraries
module.exports.types = types;
module.exports.log = syslog;