yargs.js 27 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037
  1. const assign = require('./lib/assign')
  2. const Command = require('./lib/command')
  3. const Completion = require('./lib/completion')
  4. const Parser = require('yargs-parser')
  5. const path = require('path')
  6. const Usage = require('./lib/usage')
  7. const Validation = require('./lib/validation')
  8. const Y18n = require('y18n')
  9. const objFilter = require('./lib/obj-filter')
  10. const setBlocking = require('set-blocking')
  11. var exports = module.exports = Yargs
  12. function Yargs (processArgs, cwd, parentRequire) {
  13. processArgs = processArgs || [] // handle calling yargs().
  14. const self = {}
  15. var command = null
  16. var completion = null
  17. var groups = {}
  18. var output = ''
  19. var preservedGroups = {}
  20. var usage = null
  21. var validation = null
  22. const y18n = Y18n({
  23. directory: path.resolve(__dirname, './locales'),
  24. updateFiles: false
  25. })
  26. if (!cwd) cwd = process.cwd()
  27. self.$0 = process.argv
  28. .slice(0, 2)
  29. .map(function (x, i) {
  30. // ignore the node bin, specify this in your
  31. // bin file with #!/usr/bin/env node
  32. if (i === 0 && /\b(node|iojs)(\.exe)?$/.test(x)) return
  33. var b = rebase(cwd, x)
  34. return x.match(/^(\/|([a-zA-Z]:)?\\)/) && b.length < x.length ? b : x
  35. })
  36. .join(' ').trim()
  37. if (process.env._ !== undefined && process.argv[1] === process.env._) {
  38. self.$0 = process.env._.replace(
  39. path.dirname(process.execPath) + '/', ''
  40. )
  41. }
  42. // use context object to keep track of resets, subcommand execution, etc
  43. // submodules should modify and check the state of context as necessary
  44. const context = { resets: -1, commands: [], files: [] }
  45. self.getContext = function () {
  46. return context
  47. }
  48. // puts yargs back into an initial state. any keys
  49. // that have been set to "global" will not be reset
  50. // by this action.
  51. var options
  52. self.resetOptions = self.reset = function (aliases) {
  53. context.resets++
  54. aliases = aliases || {}
  55. options = options || {}
  56. // put yargs back into an initial state, this
  57. // logic is used to build a nested command
  58. // hierarchy.
  59. var tmpOptions = {}
  60. tmpOptions.global = options.global ? options.global : []
  61. tmpOptions.configObjects = options.configObjects ? options.configObjects : []
  62. // if a key has been set as a global, we
  63. // do not want to reset it or its aliases.
  64. var globalLookup = {}
  65. tmpOptions.global.forEach(function (g) {
  66. globalLookup[g] = true
  67. ;(aliases[g] || []).forEach(function (a) {
  68. globalLookup[a] = true
  69. })
  70. })
  71. // preserve groups containing global keys
  72. preservedGroups = Object.keys(groups).reduce(function (acc, groupName) {
  73. var keys = groups[groupName].filter(function (key) {
  74. return key in globalLookup
  75. })
  76. if (keys.length > 0) {
  77. acc[groupName] = keys
  78. }
  79. return acc
  80. }, {})
  81. // groups can now be reset
  82. groups = {}
  83. var arrayOptions = [
  84. 'array', 'boolean', 'string', 'requiresArg', 'skipValidation',
  85. 'count', 'normalize', 'number'
  86. ]
  87. var objectOptions = [
  88. 'narg', 'key', 'alias', 'default', 'defaultDescription',
  89. 'config', 'choices', 'demandedOptions', 'demandedCommands', 'coerce'
  90. ]
  91. arrayOptions.forEach(function (k) {
  92. tmpOptions[k] = (options[k] || []).filter(function (k) {
  93. return globalLookup[k]
  94. })
  95. })
  96. objectOptions.forEach(function (k) {
  97. tmpOptions[k] = objFilter(options[k], function (k, v) {
  98. return globalLookup[k]
  99. })
  100. })
  101. tmpOptions.envPrefix = options.envPrefix
  102. options = tmpOptions
  103. // if this is the first time being executed, create
  104. // instances of all our helpers -- otherwise just reset.
  105. usage = usage ? usage.reset(globalLookup) : Usage(self, y18n)
  106. validation = validation ? validation.reset(globalLookup) : Validation(self, usage, y18n)
  107. command = command ? command.reset() : Command(self, usage, validation)
  108. if (!completion) completion = Completion(self, usage, command)
  109. strict = false
  110. completionCommand = null
  111. output = ''
  112. exitError = null
  113. hasOutput = false
  114. self.parsed = false
  115. return self
  116. }
  117. self.resetOptions()
  118. // temporary hack: allow "freezing" of reset-able state for parse(msg, cb)
  119. var frozen
  120. function freeze () {
  121. frozen = {}
  122. frozen.options = options
  123. frozen.configObjects = options.configObjects.slice(0)
  124. frozen.exitProcess = exitProcess
  125. frozen.groups = groups
  126. usage.freeze()
  127. validation.freeze()
  128. command.freeze()
  129. frozen.strict = strict
  130. frozen.completionCommand = completionCommand
  131. frozen.output = output
  132. frozen.exitError = exitError
  133. frozen.hasOutput = hasOutput
  134. frozen.parsed = self.parsed
  135. }
  136. function unfreeze () {
  137. options = frozen.options
  138. options.configObjects = frozen.configObjects
  139. exitProcess = frozen.exitProcess
  140. groups = frozen.groups
  141. output = frozen.output
  142. exitError = frozen.exitError
  143. hasOutput = frozen.hasOutput
  144. self.parsed = frozen.parsed
  145. usage.unfreeze()
  146. validation.unfreeze()
  147. command.unfreeze()
  148. strict = frozen.strict
  149. completionCommand = frozen.completionCommand
  150. parseFn = null
  151. parseContext = null
  152. frozen = undefined
  153. }
  154. self.boolean = function (bools) {
  155. options.boolean.push.apply(options.boolean, [].concat(bools))
  156. return self
  157. }
  158. self.array = function (arrays) {
  159. options.array.push.apply(options.array, [].concat(arrays))
  160. return self
  161. }
  162. self.nargs = function (key, n) {
  163. if (typeof key === 'object') {
  164. Object.keys(key).forEach(function (k) {
  165. self.nargs(k, key[k])
  166. })
  167. } else {
  168. options.narg[key] = n
  169. }
  170. return self
  171. }
  172. self.number = function (numbers) {
  173. options.number.push.apply(options.number, [].concat(numbers))
  174. return self
  175. }
  176. self.choices = function (key, values) {
  177. if (typeof key === 'object') {
  178. Object.keys(key).forEach(function (k) {
  179. self.choices(k, key[k])
  180. })
  181. } else {
  182. options.choices[key] = (options.choices[key] || []).concat(values)
  183. }
  184. return self
  185. }
  186. self.normalize = function (strings) {
  187. options.normalize.push.apply(options.normalize, [].concat(strings))
  188. return self
  189. }
  190. self.config = function (key, msg, parseFn) {
  191. // allow to pass a configuration object
  192. if (typeof key === 'object') {
  193. options.configObjects = (options.configObjects || []).concat(key)
  194. return self
  195. }
  196. // allow to provide a parsing function
  197. if (typeof msg === 'function') {
  198. parseFn = msg
  199. msg = null
  200. }
  201. key = key || 'config'
  202. self.describe(key, msg || usage.deferY18nLookup('Path to JSON config file'))
  203. ;(Array.isArray(key) ? key : [key]).forEach(function (k) {
  204. options.config[k] = parseFn || true
  205. })
  206. return self
  207. }
  208. self.example = function (cmd, description) {
  209. usage.example(cmd, description)
  210. return self
  211. }
  212. self.command = function (cmd, description, builder, handler) {
  213. command.addHandler(cmd, description, builder, handler)
  214. return self
  215. }
  216. self.commandDir = function (dir, opts) {
  217. const req = parentRequire || require
  218. command.addDirectory(dir, self.getContext(), req, require('get-caller-file')(), opts)
  219. return self
  220. }
  221. self.string = function (strings) {
  222. options.string.push.apply(options.string, [].concat(strings))
  223. return self
  224. }
  225. // The 'defaults' alias is deprecated. It will be removed in the next major version.
  226. self.default = self.defaults = function (key, value, defaultDescription) {
  227. if (typeof key === 'object') {
  228. Object.keys(key).forEach(function (k) {
  229. self.default(k, key[k])
  230. })
  231. } else {
  232. if (defaultDescription) options.defaultDescription[key] = defaultDescription
  233. if (typeof value === 'function') {
  234. if (!options.defaultDescription[key]) options.defaultDescription[key] = usage.functionDescription(value)
  235. value = value.call()
  236. }
  237. options.default[key] = value
  238. }
  239. return self
  240. }
  241. self.alias = function (x, y) {
  242. if (typeof x === 'object') {
  243. Object.keys(x).forEach(function (key) {
  244. self.alias(key, x[key])
  245. })
  246. } else {
  247. options.alias[x] = (options.alias[x] || []).concat(y)
  248. }
  249. return self
  250. }
  251. self.coerce = function (key, fn) {
  252. if (typeof key === 'object' && !Array.isArray(key)) {
  253. Object.keys(key).forEach(function (k) {
  254. self.coerce(k, key[k])
  255. })
  256. } else {
  257. [].concat(key).forEach(function (k) {
  258. options.coerce[k] = fn
  259. })
  260. }
  261. return self
  262. }
  263. self.count = function (counts) {
  264. options.count.push.apply(options.count, [].concat(counts))
  265. return self
  266. }
  267. // deprecated: the demand API is too overloaded, and is being
  268. // deprecated in favor of .demandCommand() .demandOption().
  269. self.demand = self.required = self.require = function (keys, max, msg) {
  270. // you can optionally provide a 'max' key,
  271. // which will raise an exception if too many '_'
  272. // options are provided.
  273. if (Array.isArray(max)) {
  274. max.forEach(function (key) {
  275. self.demandOption(key, msg)
  276. })
  277. max = Infinity
  278. } else if (typeof max !== 'number') {
  279. msg = max
  280. max = Infinity
  281. }
  282. if (typeof keys === 'number') {
  283. self.demandCommand(keys, max, msg)
  284. } else if (Array.isArray(keys)) {
  285. keys.forEach(function (key) {
  286. self.demandOption(key, msg)
  287. })
  288. } else {
  289. if (typeof msg === 'string') {
  290. self.demandOption(keys, msg)
  291. } else if (msg === true || typeof msg === 'undefined') {
  292. self.demandOption(keys)
  293. }
  294. }
  295. return self
  296. }
  297. self.demandOption = function (key, msg) {
  298. if (Array.isArray(key)) {
  299. key.forEach(function (key) {
  300. self.demandOption(key, msg)
  301. })
  302. } else {
  303. if (typeof msg === 'string') {
  304. options.demandedOptions[key] = { msg: msg }
  305. // allow edge-case of options: {a: {demand: true}, b: {demand: false}}
  306. } else if (msg === true || typeof msg === 'undefined') {
  307. options.demandedOptions[key] = { msg: undefined }
  308. }
  309. }
  310. return self
  311. }
  312. self.demandCommand = function (min, max, minMsg, maxMsg) {
  313. if (typeof max !== 'number') {
  314. minMsg = max
  315. max = Infinity
  316. }
  317. options.demandedCommands._ = {
  318. min: min,
  319. max: max,
  320. minMsg: minMsg,
  321. maxMsg: maxMsg
  322. }
  323. return self
  324. }
  325. self.getDemandedOptions = function () {
  326. return options.demandedOptions
  327. }
  328. self.getDemandedCommands = function () {
  329. return options.demandedCommands
  330. }
  331. self.requiresArg = function (requiresArgs) {
  332. options.requiresArg.push.apply(options.requiresArg, [].concat(requiresArgs))
  333. return self
  334. }
  335. self.skipValidation = function (skipValidations) {
  336. options.skipValidation.push.apply(options.skipValidation, [].concat(skipValidations))
  337. return self
  338. }
  339. self.implies = function (key, value) {
  340. validation.implies(key, value)
  341. return self
  342. }
  343. self.conflicts = function (key1, key2) {
  344. validation.conflicts(key1, key2)
  345. return self
  346. }
  347. self.usage = function (msg, opts) {
  348. if (!opts && typeof msg === 'object') {
  349. opts = msg
  350. msg = null
  351. }
  352. usage.usage(msg)
  353. if (opts) self.options(opts)
  354. return self
  355. }
  356. self.epilogue = self.epilog = function (msg) {
  357. usage.epilog(msg)
  358. return self
  359. }
  360. self.fail = function (f) {
  361. usage.failFn(f)
  362. return self
  363. }
  364. self.check = function (f) {
  365. validation.check(f)
  366. return self
  367. }
  368. self.describe = function (key, desc) {
  369. if (typeof key === 'object') {
  370. Object.keys(key).forEach(function (k) {
  371. options.key[k] = true
  372. })
  373. } else {
  374. options.key[key] = true
  375. }
  376. usage.describe(key, desc)
  377. return self
  378. }
  379. self.global = function (globals) {
  380. options.global.push.apply(options.global, [].concat(globals))
  381. return self
  382. }
  383. self.pkgConf = function (key, path) {
  384. var conf = null
  385. var obj = pkgUp(path)
  386. // If an object exists in the key, add it to options.configObjects
  387. if (obj[key] && typeof obj[key] === 'object') {
  388. conf = obj[key]
  389. options.configObjects = (options.configObjects || []).concat(conf)
  390. }
  391. return self
  392. }
  393. var pkgs = {}
  394. function pkgUp (path) {
  395. var npath = path || '*'
  396. if (pkgs[npath]) return pkgs[npath]
  397. const readPkgUp = require('read-pkg-up')
  398. var obj = {}
  399. try {
  400. obj = readPkgUp.sync({
  401. cwd: path || require('require-main-filename')(parentRequire || require),
  402. normalize: false
  403. })
  404. } catch (noop) {}
  405. pkgs[npath] = obj.pkg || {}
  406. return pkgs[npath]
  407. }
  408. var parseFn = null
  409. var parseContext = null
  410. self.parse = function (args, shortCircuit, _parseFn) {
  411. // a context object can optionally be provided, this allows
  412. // additional information to be passed to a command handler.
  413. if (typeof shortCircuit === 'object') {
  414. parseContext = shortCircuit
  415. shortCircuit = _parseFn
  416. }
  417. // by providing a function as a second argument to
  418. // parse you can capture output that would otherwise
  419. // default to printing to stdout/stderr.
  420. if (typeof shortCircuit === 'function') {
  421. parseFn = shortCircuit
  422. shortCircuit = null
  423. }
  424. // completion short-circuits the parsing process,
  425. // skipping validation, etc.
  426. if (!shortCircuit) processArgs = args
  427. freeze()
  428. if (parseFn) exitProcess = false
  429. var parsed = parseArgs(args, shortCircuit)
  430. if (parseFn) parseFn(exitError, parsed, output)
  431. unfreeze()
  432. return parsed
  433. }
  434. self._hasParseCallback = function () {
  435. return !!parseFn
  436. }
  437. self.option = self.options = function (key, opt) {
  438. if (typeof key === 'object') {
  439. Object.keys(key).forEach(function (k) {
  440. self.options(k, key[k])
  441. })
  442. } else {
  443. if (typeof opt !== 'object') {
  444. opt = {}
  445. }
  446. options.key[key] = true // track manually set keys.
  447. if (opt.alias) self.alias(key, opt.alias)
  448. var demand = opt.demand || opt.required || opt.require
  449. if (demand) {
  450. self.demand(key, demand)
  451. }
  452. if ('demandOption' in opt) {
  453. self.demandOption(key, opt.demandOption)
  454. }
  455. if ('config' in opt) {
  456. self.config(key, opt.configParser)
  457. }
  458. if ('default' in opt) {
  459. self.default(key, opt.default)
  460. }
  461. if ('nargs' in opt) {
  462. self.nargs(key, opt.nargs)
  463. }
  464. if ('normalize' in opt) {
  465. self.normalize(key)
  466. }
  467. if ('choices' in opt) {
  468. self.choices(key, opt.choices)
  469. }
  470. if ('coerce' in opt) {
  471. self.coerce(key, opt.coerce)
  472. }
  473. if ('group' in opt) {
  474. self.group(key, opt.group)
  475. }
  476. if (opt.global) {
  477. self.global(key)
  478. }
  479. if (opt.boolean || opt.type === 'boolean') {
  480. self.boolean(key)
  481. if (opt.alias) self.boolean(opt.alias)
  482. }
  483. if (opt.array || opt.type === 'array') {
  484. self.array(key)
  485. if (opt.alias) self.array(opt.alias)
  486. }
  487. if (opt.number || opt.type === 'number') {
  488. self.number(key)
  489. if (opt.alias) self.number(opt.alias)
  490. }
  491. if (opt.string || opt.type === 'string') {
  492. self.string(key)
  493. if (opt.alias) self.string(opt.alias)
  494. }
  495. if (opt.count || opt.type === 'count') {
  496. self.count(key)
  497. }
  498. if (opt.defaultDescription) {
  499. options.defaultDescription[key] = opt.defaultDescription
  500. }
  501. if (opt.skipValidation) {
  502. self.skipValidation(key)
  503. }
  504. var desc = opt.describe || opt.description || opt.desc
  505. if (desc) {
  506. self.describe(key, desc)
  507. }
  508. if (opt.requiresArg) {
  509. self.requiresArg(key)
  510. }
  511. }
  512. return self
  513. }
  514. self.getOptions = function () {
  515. return options
  516. }
  517. self.group = function (opts, groupName) {
  518. var existing = preservedGroups[groupName] || groups[groupName]
  519. if (preservedGroups[groupName]) {
  520. // the preserved group will be moved to the set of explicitly declared
  521. // groups
  522. delete preservedGroups[groupName]
  523. }
  524. var seen = {}
  525. groups[groupName] = (existing || []).concat(opts).filter(function (key) {
  526. if (seen[key]) return false
  527. return (seen[key] = true)
  528. })
  529. return self
  530. }
  531. self.getGroups = function () {
  532. // combine explicit and preserved groups. explicit groups should be first
  533. return assign(groups, preservedGroups)
  534. }
  535. // as long as options.envPrefix is not undefined,
  536. // parser will apply env vars matching prefix to argv
  537. self.env = function (prefix) {
  538. if (prefix === false) options.envPrefix = undefined
  539. else options.envPrefix = prefix || ''
  540. return self
  541. }
  542. self.wrap = function (cols) {
  543. usage.wrap(cols)
  544. return self
  545. }
  546. var strict = false
  547. self.strict = function () {
  548. strict = true
  549. return self
  550. }
  551. self.getStrict = function () {
  552. return strict
  553. }
  554. self.showHelp = function (level) {
  555. if (!self.parsed) parseArgs(processArgs) // run parser, if it has not already been executed.
  556. usage.showHelp(level)
  557. return self
  558. }
  559. var versionOpt = null
  560. self.version = function (opt, msg, ver) {
  561. if (arguments.length === 0) {
  562. ver = guessVersion()
  563. opt = 'version'
  564. } else if (arguments.length === 1) {
  565. ver = opt
  566. opt = 'version'
  567. } else if (arguments.length === 2) {
  568. ver = msg
  569. }
  570. versionOpt = opt
  571. msg = msg || usage.deferY18nLookup('Show version number')
  572. usage.version(ver || undefined)
  573. self.boolean(versionOpt)
  574. self.global(versionOpt)
  575. self.describe(versionOpt, msg)
  576. return self
  577. }
  578. function guessVersion () {
  579. var obj = pkgUp()
  580. return obj.version || 'unknown'
  581. }
  582. var helpOpt = null
  583. var useHelpOptAsCommand = false // a call to .help() will enable this
  584. self.addHelpOpt = self.help = function (opt, msg, addImplicitCmd) {
  585. // argument shuffle
  586. if (arguments.length === 0) {
  587. useHelpOptAsCommand = true
  588. } else if (arguments.length === 1) {
  589. if (typeof opt === 'boolean') {
  590. useHelpOptAsCommand = opt
  591. opt = null
  592. } else {
  593. useHelpOptAsCommand = true
  594. }
  595. } else if (arguments.length === 2) {
  596. if (typeof msg === 'boolean') {
  597. useHelpOptAsCommand = msg
  598. msg = null
  599. } else {
  600. useHelpOptAsCommand = true
  601. }
  602. } else {
  603. useHelpOptAsCommand = Boolean(addImplicitCmd)
  604. }
  605. // use arguments, fallback to defaults for opt and msg
  606. helpOpt = opt || 'help'
  607. self.boolean(helpOpt)
  608. self.global(helpOpt)
  609. self.describe(helpOpt, msg || usage.deferY18nLookup('Show help'))
  610. return self
  611. }
  612. self.showHelpOnFail = function (enabled, message) {
  613. usage.showHelpOnFail(enabled, message)
  614. return self
  615. }
  616. var exitProcess = true
  617. self.exitProcess = function (enabled) {
  618. if (typeof enabled !== 'boolean') {
  619. enabled = true
  620. }
  621. exitProcess = enabled
  622. return self
  623. }
  624. self.getExitProcess = function () {
  625. return exitProcess
  626. }
  627. var completionCommand = null
  628. self.completion = function (cmd, desc, fn) {
  629. // a function to execute when generating
  630. // completions can be provided as the second
  631. // or third argument to completion.
  632. if (typeof desc === 'function') {
  633. fn = desc
  634. desc = null
  635. }
  636. // register the completion command.
  637. completionCommand = cmd || 'completion'
  638. if (!desc && desc !== false) {
  639. desc = 'generate bash completion script'
  640. }
  641. self.command(completionCommand, desc)
  642. // a function can be provided
  643. if (fn) completion.registerFunction(fn)
  644. return self
  645. }
  646. self.showCompletionScript = function ($0) {
  647. $0 = $0 || self.$0
  648. _logger.log(completion.generateCompletionScript($0))
  649. return self
  650. }
  651. self.getCompletion = function (args, done) {
  652. completion.getCompletion(args, done)
  653. }
  654. self.locale = function (locale) {
  655. if (arguments.length === 0) {
  656. guessLocale()
  657. return y18n.getLocale()
  658. }
  659. detectLocale = false
  660. y18n.setLocale(locale)
  661. return self
  662. }
  663. self.updateStrings = self.updateLocale = function (obj) {
  664. detectLocale = false
  665. y18n.updateLocale(obj)
  666. return self
  667. }
  668. var detectLocale = true
  669. self.detectLocale = function (detect) {
  670. detectLocale = detect
  671. return self
  672. }
  673. self.getDetectLocale = function () {
  674. return detectLocale
  675. }
  676. var hasOutput = false
  677. var exitError = null
  678. // maybe exit, always capture
  679. // context about why we wanted to exit.
  680. self.exit = function (code, err) {
  681. hasOutput = true
  682. exitError = err
  683. if (exitProcess) process.exit(code)
  684. }
  685. // we use a custom logger that buffers output,
  686. // so that we can print to non-CLIs, e.g., chat-bots.
  687. var _logger = {
  688. log: function () {
  689. var args = Array.prototype.slice.call(arguments)
  690. if (!self._hasParseCallback()) console.log.apply(console, args)
  691. hasOutput = true
  692. if (output.length) output += '\n'
  693. output += args.join(' ')
  694. },
  695. error: function () {
  696. var args = Array.prototype.slice.call(arguments)
  697. if (!self._hasParseCallback()) console.error.apply(console, args)
  698. hasOutput = true
  699. if (output.length) output += '\n'
  700. output += args.join(' ')
  701. }
  702. }
  703. self._getLoggerInstance = function () {
  704. return _logger
  705. }
  706. // has yargs output an error our help
  707. // message in the current execution context.
  708. self._hasOutput = function () {
  709. return hasOutput
  710. }
  711. var recommendCommands
  712. self.recommendCommands = function () {
  713. recommendCommands = true
  714. return self
  715. }
  716. self.getUsageInstance = function () {
  717. return usage
  718. }
  719. self.getValidationInstance = function () {
  720. return validation
  721. }
  722. self.getCommandInstance = function () {
  723. return command
  724. }
  725. self.terminalWidth = function () {
  726. return process.stdout.columns
  727. }
  728. Object.defineProperty(self, 'argv', {
  729. get: function () {
  730. var args = null
  731. try {
  732. args = parseArgs(processArgs)
  733. } catch (err) {
  734. usage.fail(err.message, err)
  735. }
  736. return args
  737. },
  738. enumerable: true
  739. })
  740. function parseArgs (args, shortCircuit) {
  741. options.__ = y18n.__
  742. options.configuration = pkgUp()['yargs'] || {}
  743. const parsed = Parser.detailed(args, options)
  744. var argv = parsed.argv
  745. if (parseContext) argv = assign(parseContext, argv)
  746. var aliases = parsed.aliases
  747. argv.$0 = self.$0
  748. self.parsed = parsed
  749. guessLocale() // guess locale lazily, so that it can be turned off in chain.
  750. // while building up the argv object, there
  751. // are two passes through the parser. If completion
  752. // is being performed short-circuit on the first pass.
  753. if (shortCircuit) {
  754. return argv
  755. }
  756. if (argv._.length) {
  757. // check for helpOpt in argv._ before running commands
  758. // assumes helpOpt must be valid if useHelpOptAsCommand is true
  759. if (useHelpOptAsCommand) {
  760. // consider any multi-char helpOpt alias as a valid help command
  761. // unless all helpOpt aliases are single-char
  762. // note that parsed.aliases is a normalized bidirectional map :)
  763. var helpCmds = [helpOpt].concat(aliases[helpOpt])
  764. var multiCharHelpCmds = helpCmds.filter(function (k) {
  765. return k.length > 1
  766. })
  767. if (multiCharHelpCmds.length) helpCmds = multiCharHelpCmds
  768. // look for and strip any helpCmds from argv._
  769. argv._ = argv._.filter(function (cmd) {
  770. if (~helpCmds.indexOf(cmd)) {
  771. argv[helpOpt] = true
  772. return false
  773. }
  774. return true
  775. })
  776. }
  777. // if there's a handler associated with a
  778. // command defer processing to it.
  779. var handlerKeys = command.getCommands()
  780. if (handlerKeys.length) {
  781. var firstUnknownCommand
  782. for (var i = 0, cmd; (cmd = argv._[i]) !== undefined; i++) {
  783. if (~handlerKeys.indexOf(cmd) && cmd !== completionCommand) {
  784. setPlaceholderKeys(argv)
  785. return command.runCommand(cmd, self, parsed)
  786. } else if (!firstUnknownCommand && cmd !== completionCommand) {
  787. firstUnknownCommand = cmd
  788. }
  789. }
  790. // recommend a command if recommendCommands() has
  791. // been enabled, and no commands were found to execute
  792. if (recommendCommands && firstUnknownCommand) {
  793. validation.recommendCommands(firstUnknownCommand, handlerKeys)
  794. }
  795. }
  796. // generate a completion script for adding to ~/.bashrc.
  797. if (completionCommand && ~argv._.indexOf(completionCommand) && !argv[completion.completionKey]) {
  798. if (exitProcess) setBlocking(true)
  799. self.showCompletionScript()
  800. self.exit(0)
  801. }
  802. }
  803. // we must run completions first, a user might
  804. // want to complete the --help or --version option.
  805. if (completion.completionKey in argv) {
  806. if (exitProcess) setBlocking(true)
  807. // we allow for asynchronous completions,
  808. // e.g., loading in a list of commands from an API.
  809. var completionArgs = args.slice(args.indexOf('--' + completion.completionKey) + 1)
  810. completion.getCompletion(completionArgs, function (completions) {
  811. ;(completions || []).forEach(function (completion) {
  812. _logger.log(completion)
  813. })
  814. self.exit(0)
  815. })
  816. return setPlaceholderKeys(argv)
  817. }
  818. var skipValidation = false
  819. // Handle 'help' and 'version' options
  820. Object.keys(argv).forEach(function (key) {
  821. if (key === helpOpt && argv[key]) {
  822. if (exitProcess) setBlocking(true)
  823. skipValidation = true
  824. self.showHelp('log')
  825. self.exit(0)
  826. } else if (key === versionOpt && argv[key]) {
  827. if (exitProcess) setBlocking(true)
  828. skipValidation = true
  829. usage.showVersion()
  830. self.exit(0)
  831. }
  832. })
  833. // Check if any of the options to skip validation were provided
  834. if (!skipValidation && options.skipValidation.length > 0) {
  835. skipValidation = Object.keys(argv).some(function (key) {
  836. return options.skipValidation.indexOf(key) >= 0 && argv[key] === true
  837. })
  838. }
  839. // If the help or version options where used and exitProcess is false,
  840. // or if explicitly skipped, we won't run validations
  841. if (!skipValidation) {
  842. if (parsed.error) throw parsed.error
  843. // if we're executed via bash completion, don't
  844. // bother with validation.
  845. if (!argv[completion.completionKey]) {
  846. validation.nonOptionCount(argv)
  847. validation.missingArgumentValue(argv)
  848. validation.requiredArguments(argv)
  849. if (strict) validation.unknownArguments(argv, aliases)
  850. validation.customChecks(argv, aliases)
  851. validation.limitedChoices(argv)
  852. validation.implications(argv)
  853. validation.conflicting(argv)
  854. }
  855. }
  856. return setPlaceholderKeys(argv)
  857. }
  858. function guessLocale () {
  859. if (!detectLocale) return
  860. try {
  861. const osLocale = require('os-locale')
  862. self.locale(osLocale.sync({ spawn: false }))
  863. } catch (err) {
  864. // if we explode looking up locale just noop
  865. // we'll keep using the default language 'en'.
  866. }
  867. }
  868. function setPlaceholderKeys (argv) {
  869. Object.keys(options.key).forEach(function (key) {
  870. // don't set placeholder keys for dot
  871. // notation options 'foo.bar'.
  872. if (~key.indexOf('.')) return
  873. if (typeof argv[key] === 'undefined') argv[key] = undefined
  874. })
  875. return argv
  876. }
  877. return self
  878. }
  879. // rebase an absolute path to a relative one with respect to a base directory
  880. // exported for tests
  881. exports.rebase = rebase
  882. function rebase (base, dir) {
  883. return path.relative(base, dir)
  884. }