deps/npm/lib/help.js

   1
   2 module.exports = help
   3
   4 help.completion = function (opts, cb) {
   5   if (opts.conf.argv.remain.length > 2) return cb(null, [])
   6   getSections(cb)
   7 }
   8
   9 var fs = require("graceful-fs")
  10   , path = require("path")
  11   , spawn = require("child_process").spawn
  12   , npm = require("./npm.js")
  13   , log = require("npmlog")
  14   , opener = require("opener")
  15   , glob = require("glob")
  16
  17 function help (args, cb) {
  18   var argv = npm.config.get("argv").cooked
  19
  20   var argnum = 0
  21   if (args.length === 2 && ~~args[0]) {
  22     argnum = ~~args.shift()
  23   }
  24
  25   // npm help foo bar baz: search topics
  26   if (args.length > 1 && args[0]) {
  27     return npm.commands["help-search"](args, argnum, cb)
  28   }
  29
  30   var section = npm.deref(args[0]) || args[0]
  31
  32   // npm help <noargs>:  show basic usage
  33   if (!section)
  34     return npmUsage(cb)
  35
  36   // npm <cmd> -h: show command usage
  37   if ( npm.config.get("usage")
  38     && npm.commands[section]
  39     && npm.commands[section].usage
  40   ) {
  41     npm.config.set("loglevel", "silent")
  42     log.level = "silent"
  43     console.log(npm.commands[section].usage)
  44     return cb()
  45   }
  46
  47   // npm apihelp <section>: Prefer section 3 over section 1
  48   var apihelp = argv.length && -1 !== argv[0].indexOf("api")
  49   var pref = apihelp ? [3, 1, 5, 7] : [1, 3, 5, 7]
  50   if (argnum)
  51     pref = [ argnum ].concat(pref.filter(function (n) {
  52       return n !== argnum
  53     }))
  54
  55   // npm help <section>: Try to find the path
  56   var manroot = path.resolve(__dirname, "..", "man")
  57   var htmlroot = path.resolve(__dirname, "..", "html", "doc")
  58
  59   // legacy
  60   if (section === "global")
  61     section = "folders"
  62   else if (section === "json")
  63     section = "package.json"
  64
  65   // find either /section.n or /npm-section.n
  66   var f = "+(npm-" + section + "|" + section + ").[0-9]"
  67   return glob(manroot + "/*/" + f, function (er, mans) {
  68     if (er)
  69       return cb(er)
  70
  71     if (!mans.length)
  72       return npm.commands["help-search"](args, cb)
  73
  74     viewMan(pickMan(mans, pref), cb)
  75   })
  76 }
  77
  78 function pickMan (mans, pref_) {
  79   var nre = /([0-9]+)$/
  80   var pref = {}
  81   pref_.forEach(function (sect, i) {
  82     pref[sect] = i
  83   })
  84   mans = mans.sort(function (a, b) {
  85     var an = a.match(nre)[1]
  86     var bn = b.match(nre)[1]
  87     return an === bn ? (a > b ? -1 : 1)
  88          : pref[an] < pref[bn] ? -1
  89          : 1
  90   })
  91   return mans[0]
  92 }
  93
  94 function viewMan (man, cb) {
  95   var nre = /([0-9]+)$/
  96   var num = man.match(nre)[1]
  97   var section = path.basename(man, "." + num)
  98
  99   // at this point, we know that the specified man page exists
 100   var manpath = path.join(__dirname, "..", "man")
 101     , env = {}
 102   Object.keys(process.env).forEach(function (i) {
 103     env[i] = process.env[i]
 104   })
 105   env.MANPATH = manpath
 106   var viewer = npm.config.get("viewer")
 107
 108   switch (viewer) {
 109     case "woman":
 110       var a = ["-e", "(woman-find-file \"" + man + "\")"]
 111       var conf = { env: env, customFds: [ 0, 1, 2] }
 112       var woman = spawn("emacsclient", a, conf)
 113       woman.on("close", cb)
 114       break
 115
 116     case "browser":
 117       opener(htmlMan(man), { command: npm.config.get("browser") }, cb)
 118       break
 119
 120     default:
 121       var conf = { env: env, customFds: [ 0, 1, 2] }
 122       var man = spawn("man", [num, section], conf)
 123       man.on("close", cb)
 124       break
 125   }
 126 }
 127
 128 function htmlMan (man) {
 129   var sect = +man.match(/([0-9]+)$/)[1]
 130   var f = path.basename(man).replace(/([0-9]+)$/, "html")
 131   switch (sect) {
 132     case 1:
 133       sect = "cli"
 134       break
 135     case 3:
 136       sect = "api"
 137       break
 138     case 5:
 139       sect = "files"
 140       break
 141     case 7:
 142       sect = "misc"
 143       break
 144     default:
 145       throw new Error("invalid man section: " + sect)
 146   }
 147   return path.resolve(__dirname, "..", "html", "doc", sect, f)
 148 }
 149
 150 function npmUsage (cb) {
 151   npm.config.set("loglevel", "silent")
 152   log.level = "silent"
 153   console.log
 154     ( ["\nUsage: npm <command>"
 155       , ""
 156       , "where <command> is one of:"
 157       , npm.config.get("long") ? usages()
 158         : "    " + wrap(Object.keys(npm.commands))
 159       , ""
 160       , "npm <cmd> -h     quick help on <cmd>"
 161       , "npm -l           display full usage info"
 162       , "npm faq          commonly asked questions"
 163       , "npm help <term>  search for help on <term>"
 164       , "npm help npm     involved overview"
 165       , ""
 166       , "Specify configs in the ini-formatted file:"
 167       , "    " + npm.config.get("userconfig")
 168       , "or on the command line via: npm <command> --key value"
 169       , "Config info can be viewed via: npm help config"
 170       , ""
 171       , "npm@" + npm.version + " " + path.dirname(__dirname)
 172       ].join("\n"))
 173   cb()
 174 }
 175
 176 function usages () {
 177   // return a string of <cmd>: <usage>
 178   var maxLen = 0
 179   return Object.keys(npm.commands).filter(function (c) {
 180     return c === npm.deref(c)
 181   }).reduce(function (set, c) {
 182     set.push([c, npm.commands[c].usage || ""])
 183     maxLen = Math.max(maxLen, c.length)
 184     return set
 185   }, []).map(function (item) {
 186     var c = item[0]
 187       , usage = item[1]
 188     return "\n    " + c + (new Array(maxLen - c.length + 2).join(" "))
 189          + (usage.split("\n")
 190             .join("\n" + (new Array(maxLen + 6).join(" "))))
 191   }).join("\n")
 192   return out
 193 }
 194
 195
 196 function wrap (arr) {
 197   var out = ['']
 198     , l = 0
 199     , line
 200
 201   line = process.stdout.columns
 202   if (!line)
 203     line = 60
 204   else
 205     line = Math.min(60, Math.max(line - 16, 24))
 206
 207   arr.sort(function (a,b) { return a<b?-1:1 })
 208     .forEach(function (c) {
 209       if (out[l].length + c.length + 2 < line) {
 210         out[l] += ', '+c
 211       } else {
 212         out[l++] += ','
 213         out[l] = c
 214       }
 215     })
 216   return out.join("\n    ").substr(2)
 217 }
 218
 219 function getSections (cb) {
 220   var g = path.resolve(__dirname, "../man/man[0-9]/*.[0-9]")
 221   glob(g, function (er, files) {
 222     if (er)
 223       return cb(er)
 224     cb(null, Object.keys(files.reduce(function (acc, file) {
 225       file = path.basename(file).replace(/\.[0-9]+$/, "")
 226       file = file.replace(/^npm-/, "")
 227       acc[file] = true
 228       return acc
 229     }, { help: true })))
 230   })
 231 }