node/deps/npm/lib/help.js

module.exports = help

help.completion = function (opts, cb) {
  if (opts.conf.argv.remain.length > 2) return cb(null, [])
  getSections(cb)
}

var path = require("path")
  , spawn = require("./utils/spawn")
  , npm = require("./npm.js")
  , log = require("npmlog")
  , opener = require("opener")
  , glob = require("glob")

function help (args, cb) {
  npm.spinner.stop()
  var argv = npm.config.get("argv").cooked

  var argnum = 0
  if (args.length === 2 && ~~args[0]) {
    argnum = ~~args.shift()
  }

  // npm help foo bar baz: search topics
  if (args.length > 1 && args[0]) {
    return npm.commands["help-search"](args, argnum, cb)
  }

  var section = npm.deref(args[0]) || args[0]

  // npm help <noargs>:  show basic usage
  if (!section) {
    var valid = argv[0] === "help" ? 0 : 1
    return npmUsage(valid, cb)
  }


  // npm <cmd> -h: show command usage
  if ( npm.config.get("usage")
    && npm.commands[section]
    && npm.commands[section].usage
  ) {
    npm.config.set("loglevel", "silent")
    log.level = "silent"
    console.log(npm.commands[section].usage)
    return cb()
  }

  // npm apihelp <section>: Prefer section 3 over section 1
  var apihelp = argv.length && -1 !== argv[0].indexOf("api")
  var pref = apihelp ? [3, 1, 5, 7] : [1, 3, 5, 7]
  if (argnum)
    pref = [ argnum ].concat(pref.filter(function (n) {
      return n !== argnum
    }))

  // npm help <section>: Try to find the path
  var manroot = path.resolve(__dirname, "..", "man")

  // legacy
  if (section === "global") section = "folders"
  else if (section === "json") section = "package.json"

  // find either /section.n or /npm-section.n
  // The glob is used in the glob.  The regexp is used much
  // further down.  Globs and regexps are different
  var compextglob = ".+(gz|bz2|lzma|[FYzZ]|xz)"
  var compextre = "\\.(gz|bz2|lzma|[FYzZ]|xz)$"
  var f = "+(npm-" + section + "|" + section + ").[0-9]?(" + compextglob + ")"
  return glob(manroot + "/*/" + f, function (er, mans) {
    if (er) return cb(er)

    if (!mans.length) return npm.commands["help-search"](args, cb)

    mans = mans.map(function (man) {
      var ext = path.extname(man)
      if (man.match(new RegExp(compextre))) man = path.basename(man, ext)

      return man
    })

    viewMan(pickMan(mans, pref), cb)
  })
}

function pickMan (mans, pref_) {
  var nre = /([0-9]+)$/
  var pref = {}
  pref_.forEach(function (sect, i) {
    pref[sect] = i
  })
  mans = mans.sort(function (a, b) {
    var an = a.match(nre)[1]
    var bn = b.match(nre)[1]
    return an === bn ? (a > b ? -1 : 1)
         : pref[an] < pref[bn] ? -1
         : 1
  })
  return mans[0]
}

function viewMan (man, cb) {
  var nre = /([0-9]+)$/
  var num = man.match(nre)[1]
  var section = path.basename(man, "." + num)

  // at this point, we know that the specified man page exists
  var manpath = path.join(__dirname, "..", "man")
    , env = {}
  Object.keys(process.env).forEach(function (i) {
    env[i] = process.env[i]
  })
  env.MANPATH = manpath
  var viewer = npm.config.get("viewer")

  var conf
  switch (viewer) {
    case "woman":
      var a = ["-e", "(woman-find-file \"" + man + "\")"]
      conf = { env: env, stdio: "inherit" }
      var woman = spawn("emacsclient", a, conf)
      woman.on("close", cb)
      break

    case "browser":
      opener(htmlMan(man), { command: npm.config.get("browser") }, cb)
      break

    default:
      conf = { env: env, stdio: "inherit" }
      var manProcess = spawn("man", [num, section], conf)
      manProcess.on("close", cb)
      break
  }
}

function htmlMan (man) {
  var sect = +man.match(/([0-9]+)$/)[1]
  var f = path.basename(man).replace(/([0-9]+)$/, "html")
  switch (sect) {
    case 1:
      sect = "cli"
      break
    case 3:
      sect = "api"
      break
    case 5:
      sect = "files"
      break
    case 7:
      sect = "misc"
      break
    default:
      throw new Error("invalid man section: " + sect)
  }
  return path.resolve(__dirname, "..", "html", "doc", sect, f)
}

function npmUsage (valid, cb) {
  npm.config.set("loglevel", "silent")
  log.level = "silent"
  console.log(
    [ "\nUsage: npm <command>"
      , ""
      , "where <command> is one of:"
      , npm.config.get("long") ? usages()
        : "    " + wrap(Object.keys(npm.commands))
      , ""
      , "npm <cmd> -h     quick help on <cmd>"
      , "npm -l           display full usage info"
      , "npm faq          commonly asked questions"
      , "npm help <term>  search for help on <term>"
      , "npm help npm     involved overview"
      , ""
      , "Specify configs in the ini-formatted file:"
      , "    " + npm.config.get("userconfig")
      , "or on the command line via: npm <command> --key value"
      , "Config info can be viewed via: npm help config"
      , ""
      , "npm@" + npm.version + " " + path.dirname(__dirname)
      ].join("\n"))
  cb(valid)
}

function usages () {
  // return a string of <cmd>: <usage>
  var maxLen = 0
  return Object.keys(npm.commands).filter(function (c) {
    return c === npm.deref(c)
  }).reduce(function (set, c) {
    set.push([c, npm.commands[c].usage || ""])
    maxLen = Math.max(maxLen, c.length)
    return set
  }, []).map(function (item) {
    var c = item[0]
      , usage = item[1]
    return "\n    " + c + (new Array(maxLen - c.length + 2).join(" "))
         + (usage.split("\n")
            .join("\n" + (new Array(maxLen + 6).join(" "))))
  }).join("\n")
}


function wrap (arr) {
  var out = [""]
    , l = 0
    , line

  line = process.stdout.columns
  if (!line)
    line = 60
  else
    line = Math.min(60, Math.max(line - 16, 24))

  arr.sort(function (a,b) { return a<b?-1:1 })
    .forEach(function (c) {
      if (out[l].length + c.length + 2 < line) {
        out[l] += ", "+c
      } else {
        out[l++] += ","
        out[l] = c
      }
    })
  return out.join("\n    ").substr(2)
}

function getSections (cb) {
  var g = path.resolve(__dirname, "../man/man[0-9]/*.[0-9]")
  glob(g, function (er, files) {
    if (er)
      return cb(er)
    cb(null, Object.keys(files.reduce(function (acc, file) {
      file = path.basename(file).replace(/\.[0-9]+$/, "")
      file = file.replace(/^npm-/, "")
      acc[file] = true
      return acc
    }, { help: true })))
  })
}