| "use strict"; |
| Object.defineProperty(exports, "__esModule", { value: true }); |
| exports.isCommandBuilderCallback = exports.isCommandBuilderDefinition = exports.isCommandHandlerDefinition = exports.command = void 0; |
| const common_types_1 = require("./common-types"); |
| const is_promise_1 = require("./is-promise"); |
| const middleware_1 = require("./middleware"); |
| const parse_command_1 = require("./parse-command"); |
| const path = require("path"); |
| const util_1 = require("util"); |
| const yargs_1 = require("./yargs"); |
| const requireDirectory = require("require-directory"); |
| const whichModule = require("which-module"); |
| const Parser = require("yargs-parser"); |
| const DEFAULT_MARKER = /(^\*)|(^\$0)/; |
| // handles parsing positional arguments, |
| // and populating argv with said positional |
| // arguments. |
| function command(yargs, usage, validation, globalMiddleware = []) { |
| const self = {}; |
| let handlers = {}; |
| let aliasMap = {}; |
| let defaultCommand; |
| self.addHandler = function addHandler(cmd, description, builder, handler, commandMiddleware, deprecated) { |
| let aliases = []; |
| const middlewares = middleware_1.commandMiddlewareFactory(commandMiddleware); |
| handler = handler || (() => { }); |
| if (Array.isArray(cmd)) { |
| aliases = cmd.slice(1); |
| cmd = cmd[0]; |
| } |
| else if (isCommandHandlerDefinition(cmd)) { |
| let command = (Array.isArray(cmd.command) || typeof cmd.command === 'string') ? cmd.command : moduleName(cmd); |
| if (cmd.aliases) |
| command = [].concat(command).concat(cmd.aliases); |
| self.addHandler(command, extractDesc(cmd), cmd.builder, cmd.handler, cmd.middlewares, cmd.deprecated); |
| return; |
| } |
| // allow a module to be provided instead of separate builder and handler |
| if (isCommandBuilderDefinition(builder)) { |
| self.addHandler([cmd].concat(aliases), description, builder.builder, builder.handler, builder.middlewares, builder.deprecated); |
| return; |
| } |
| // parse positionals out of cmd string |
| const parsedCommand = parse_command_1.parseCommand(cmd); |
| // remove positional args from aliases only |
| aliases = aliases.map(alias => parse_command_1.parseCommand(alias).cmd); |
| // check for default and filter out '*'' |
| let isDefault = false; |
| const parsedAliases = [parsedCommand.cmd].concat(aliases).filter((c) => { |
| if (DEFAULT_MARKER.test(c)) { |
| isDefault = true; |
| return false; |
| } |
| return true; |
| }); |
| // standardize on $0 for default command. |
| if (parsedAliases.length === 0 && isDefault) |
| parsedAliases.push('$0'); |
| // shift cmd and aliases after filtering out '*' |
| if (isDefault) { |
| parsedCommand.cmd = parsedAliases[0]; |
| aliases = parsedAliases.slice(1); |
| cmd = cmd.replace(DEFAULT_MARKER, parsedCommand.cmd); |
| } |
| // populate aliasMap |
| aliases.forEach((alias) => { |
| aliasMap[alias] = parsedCommand.cmd; |
| }); |
| if (description !== false) { |
| usage.command(cmd, description, isDefault, aliases, deprecated); |
| } |
| handlers[parsedCommand.cmd] = { |
| original: cmd, |
| description, |
| handler, |
| builder: builder || {}, |
| middlewares, |
| deprecated, |
| demanded: parsedCommand.demanded, |
| optional: parsedCommand.optional |
| }; |
| if (isDefault) |
| defaultCommand = handlers[parsedCommand.cmd]; |
| }; |
| self.addDirectory = function addDirectory(dir, context, req, callerFile, opts) { |
| opts = opts || {}; |
| // disable recursion to support nested directories of subcommands |
| if (typeof opts.recurse !== 'boolean') |
| opts.recurse = false; |
| // exclude 'json', 'coffee' from require-directory defaults |
| if (!Array.isArray(opts.extensions)) |
| opts.extensions = ['js']; |
| // allow consumer to define their own visitor function |
| const parentVisit = typeof opts.visit === 'function' ? opts.visit : (o) => o; |
| // call addHandler via visitor function |
| opts.visit = function visit(obj, joined, filename) { |
| const visited = parentVisit(obj, joined, filename); |
| // allow consumer to skip modules with their own visitor |
| if (visited) { |
| // check for cyclic reference |
| // each command file path should only be seen once per execution |
| if (~context.files.indexOf(joined)) |
| return visited; |
| // keep track of visited files in context.files |
| context.files.push(joined); |
| self.addHandler(visited); |
| } |
| return visited; |
| }; |
| requireDirectory({ require: req, filename: callerFile }, dir, opts); |
| }; |
| // lookup module object from require()d command and derive name |
| // if module was not require()d and no name given, throw error |
| function moduleName(obj) { |
| const mod = whichModule(obj); |
| if (!mod) |
| throw new Error(`No command name given for module: ${util_1.inspect(obj)}`); |
| return commandFromFilename(mod.filename); |
| } |
| // derive command name from filename |
| function commandFromFilename(filename) { |
| return path.basename(filename, path.extname(filename)); |
| } |
| function extractDesc({ describe, description, desc }) { |
| for (const test of [describe, description, desc]) { |
| if (typeof test === 'string' || test === false) |
| return test; |
| common_types_1.assertNotStrictEqual(test, true); |
| } |
| return false; |
| } |
| self.getCommands = () => Object.keys(handlers).concat(Object.keys(aliasMap)); |
| self.getCommandHandlers = () => handlers; |
| self.hasDefaultCommand = () => !!defaultCommand; |
| self.runCommand = function runCommand(command, yargs, parsed, commandIndex) { |
| let aliases = parsed.aliases; |
| const commandHandler = handlers[command] || handlers[aliasMap[command]] || defaultCommand; |
| const currentContext = yargs.getContext(); |
| let numFiles = currentContext.files.length; |
| const parentCommands = currentContext.commands.slice(); |
| // what does yargs look like after the builder is run? |
| let innerArgv = parsed.argv; |
| let positionalMap = {}; |
| if (command) { |
| currentContext.commands.push(command); |
| currentContext.fullCommands.push(commandHandler.original); |
| } |
| const builder = commandHandler.builder; |
| if (isCommandBuilderCallback(builder)) { |
| // a function can be provided, which builds |
| // up a yargs chain and possibly returns it. |
| const builderOutput = builder(yargs.reset(parsed.aliases)); |
| const innerYargs = yargs_1.isYargsInstance(builderOutput) ? builderOutput : yargs; |
| if (shouldUpdateUsage(innerYargs)) { |
| innerYargs.getUsageInstance().usage(usageFromParentCommandsCommandHandler(parentCommands, commandHandler), commandHandler.description); |
| } |
| innerArgv = innerYargs._parseArgs(null, null, true, commandIndex); |
| aliases = innerYargs.parsed.aliases; |
| } |
| else if (isCommandBuilderOptionDefinitions(builder)) { |
| // as a short hand, an object can instead be provided, specifying |
| // the options that a command takes. |
| const innerYargs = yargs.reset(parsed.aliases); |
| if (shouldUpdateUsage(innerYargs)) { |
| innerYargs.getUsageInstance().usage(usageFromParentCommandsCommandHandler(parentCommands, commandHandler), commandHandler.description); |
| } |
| Object.keys(commandHandler.builder).forEach((key) => { |
| innerYargs.option(key, builder[key]); |
| }); |
| innerArgv = innerYargs._parseArgs(null, null, true, commandIndex); |
| aliases = innerYargs.parsed.aliases; |
| } |
| if (!yargs._hasOutput()) { |
| positionalMap = populatePositionals(commandHandler, innerArgv, currentContext); |
| } |
| const middlewares = globalMiddleware.slice(0).concat(commandHandler.middlewares); |
| middleware_1.applyMiddleware(innerArgv, yargs, middlewares, true); |
| // we apply validation post-hoc, so that custom |
| // checks get passed populated positional arguments. |
| if (!yargs._hasOutput()) { |
| yargs._runValidation(innerArgv, aliases, positionalMap, yargs.parsed.error, !command); |
| } |
| if (commandHandler.handler && !yargs._hasOutput()) { |
| yargs._setHasOutput(); |
| // to simplify the parsing of positionals in commands, |
| // we temporarily populate '--' rather than _, with arguments |
| const populateDoubleDash = !!yargs.getOptions().configuration['populate--']; |
| if (!populateDoubleDash) |
| yargs._copyDoubleDash(innerArgv); |
| innerArgv = middleware_1.applyMiddleware(innerArgv, yargs, middlewares, false); |
| let handlerResult; |
| if (is_promise_1.isPromise(innerArgv)) { |
| handlerResult = innerArgv.then(argv => commandHandler.handler(argv)); |
| } |
| else { |
| handlerResult = commandHandler.handler(innerArgv); |
| } |
| const handlerFinishCommand = yargs.getHandlerFinishCommand(); |
| if (is_promise_1.isPromise(handlerResult)) { |
| yargs.getUsageInstance().cacheHelpMessage(); |
| handlerResult |
| .then(value => { |
| if (handlerFinishCommand) { |
| handlerFinishCommand(value); |
| } |
| }) |
| .catch(error => { |
| try { |
| yargs.getUsageInstance().fail(null, error); |
| } |
| catch (err) { |
| // fail's throwing would cause an unhandled rejection. |
| } |
| }) |
| .then(() => { |
| yargs.getUsageInstance().clearCachedHelpMessage(); |
| }); |
| } |
| else { |
| if (handlerFinishCommand) { |
| handlerFinishCommand(handlerResult); |
| } |
| } |
| } |
| if (command) { |
| currentContext.commands.pop(); |
| currentContext.fullCommands.pop(); |
| } |
| numFiles = currentContext.files.length - numFiles; |
| if (numFiles > 0) |
| currentContext.files.splice(numFiles * -1, numFiles); |
| return innerArgv; |
| }; |
| function shouldUpdateUsage(yargs) { |
| return !yargs.getUsageInstance().getUsageDisabled() && |
| yargs.getUsageInstance().getUsage().length === 0; |
| } |
| function usageFromParentCommandsCommandHandler(parentCommands, commandHandler) { |
| const c = DEFAULT_MARKER.test(commandHandler.original) ? commandHandler.original.replace(DEFAULT_MARKER, '').trim() : commandHandler.original; |
| const pc = parentCommands.filter((c) => { return !DEFAULT_MARKER.test(c); }); |
| pc.push(c); |
| return `$0 ${pc.join(' ')}`; |
| } |
| self.runDefaultBuilderOn = function (yargs) { |
| common_types_1.assertNotStrictEqual(defaultCommand, undefined); |
| if (shouldUpdateUsage(yargs)) { |
| // build the root-level command string from the default string. |
| const commandString = DEFAULT_MARKER.test(defaultCommand.original) |
| ? defaultCommand.original : defaultCommand.original.replace(/^[^[\]<>]*/, '$0 '); |
| yargs.getUsageInstance().usage(commandString, defaultCommand.description); |
| } |
| const builder = defaultCommand.builder; |
| if (isCommandBuilderCallback(builder)) { |
| builder(yargs); |
| } |
| else { |
| Object.keys(builder).forEach((key) => { |
| yargs.option(key, builder[key]); |
| }); |
| } |
| }; |
| // transcribe all positional arguments "command <foo> <bar> [apple]" |
| // onto argv. |
| function populatePositionals(commandHandler, argv, context) { |
| argv._ = argv._.slice(context.commands.length); // nuke the current commands |
| const demanded = commandHandler.demanded.slice(0); |
| const optional = commandHandler.optional.slice(0); |
| const positionalMap = {}; |
| validation.positionalCount(demanded.length, argv._.length); |
| while (demanded.length) { |
| const demand = demanded.shift(); |
| populatePositional(demand, argv, positionalMap); |
| } |
| while (optional.length) { |
| const maybe = optional.shift(); |
| populatePositional(maybe, argv, positionalMap); |
| } |
| argv._ = context.commands.concat(argv._); |
| postProcessPositionals(argv, positionalMap, self.cmdToParseOptions(commandHandler.original)); |
| return positionalMap; |
| } |
| function populatePositional(positional, argv, positionalMap) { |
| const cmd = positional.cmd[0]; |
| if (positional.variadic) { |
| positionalMap[cmd] = argv._.splice(0).map(String); |
| } |
| else { |
| if (argv._.length) |
| positionalMap[cmd] = [String(argv._.shift())]; |
| } |
| } |
| // we run yargs-parser against the positional arguments |
| // applying the same parsing logic used for flags. |
| function postProcessPositionals(argv, positionalMap, parseOptions) { |
| // combine the parsing hints we've inferred from the command |
| // string with explicitly configured parsing hints. |
| const options = Object.assign({}, yargs.getOptions()); |
| options.default = Object.assign(parseOptions.default, options.default); |
| for (const key of Object.keys(parseOptions.alias)) { |
| options.alias[key] = (options.alias[key] || []).concat(parseOptions.alias[key]); |
| } |
| options.array = options.array.concat(parseOptions.array); |
| delete options.config; // don't load config when processing positionals. |
| const unparsed = []; |
| Object.keys(positionalMap).forEach((key) => { |
| positionalMap[key].map((value) => { |
| if (options.configuration['unknown-options-as-args']) |
| options.key[key] = true; |
| unparsed.push(`--${key}`); |
| unparsed.push(value); |
| }); |
| }); |
| // short-circuit parse. |
| if (!unparsed.length) |
| return; |
| const config = Object.assign({}, options.configuration, { |
| 'populate--': true |
| }); |
| const parsed = Parser.detailed(unparsed, Object.assign({}, options, { |
| configuration: config |
| })); |
| if (parsed.error) { |
| yargs.getUsageInstance().fail(parsed.error.message, parsed.error); |
| } |
| else { |
| // only copy over positional keys (don't overwrite |
| // flag arguments that were already parsed). |
| const positionalKeys = Object.keys(positionalMap); |
| Object.keys(positionalMap).forEach((key) => { |
| positionalKeys.push(...parsed.aliases[key]); |
| }); |
| Object.keys(parsed.argv).forEach((key) => { |
| if (positionalKeys.indexOf(key) !== -1) { |
| // any new aliases need to be placed in positionalMap, which |
| // is used for validation. |
| if (!positionalMap[key]) |
| positionalMap[key] = parsed.argv[key]; |
| argv[key] = parsed.argv[key]; |
| } |
| }); |
| } |
| } |
| self.cmdToParseOptions = function (cmdString) { |
| const parseOptions = { |
| array: [], |
| default: {}, |
| alias: {}, |
| demand: {} |
| }; |
| const parsed = parse_command_1.parseCommand(cmdString); |
| parsed.demanded.forEach((d) => { |
| const [cmd, ...aliases] = d.cmd; |
| if (d.variadic) { |
| parseOptions.array.push(cmd); |
| parseOptions.default[cmd] = []; |
| } |
| parseOptions.alias[cmd] = aliases; |
| parseOptions.demand[cmd] = true; |
| }); |
| parsed.optional.forEach((o) => { |
| const [cmd, ...aliases] = o.cmd; |
| if (o.variadic) { |
| parseOptions.array.push(cmd); |
| parseOptions.default[cmd] = []; |
| } |
| parseOptions.alias[cmd] = aliases; |
| }); |
| return parseOptions; |
| }; |
| self.reset = () => { |
| handlers = {}; |
| aliasMap = {}; |
| defaultCommand = undefined; |
| return self; |
| }; |
| // used by yargs.parse() to freeze |
| // the state of commands such that |
| // we can apply .parse() multiple times |
| // with the same yargs instance. |
| const frozens = []; |
| self.freeze = () => { |
| frozens.push({ |
| handlers, |
| aliasMap, |
| defaultCommand |
| }); |
| }; |
| self.unfreeze = () => { |
| const frozen = frozens.pop(); |
| common_types_1.assertNotStrictEqual(frozen, undefined); |
| ({ |
| handlers, |
| aliasMap, |
| defaultCommand |
| } = frozen); |
| }; |
| return self; |
| } |
| exports.command = command; |
| function isCommandHandlerDefinition(cmd) { |
| return typeof cmd === 'object'; |
| } |
| exports.isCommandHandlerDefinition = isCommandHandlerDefinition; |
| function isCommandBuilderDefinition(builder) { |
| return typeof builder === 'object' && |
| !!builder.builder && |
| typeof builder.handler === 'function'; |
| } |
| exports.isCommandBuilderDefinition = isCommandBuilderDefinition; |
| function isCommandBuilderCallback(builder) { |
| return typeof builder === 'function'; |
| } |
| exports.isCommandBuilderCallback = isCommandBuilderCallback; |
| function isCommandBuilderOptionDefinitions(builder) { |
| return typeof builder === 'object'; |
| } |