4
1

index.d.ts 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627
  1. // Type definitions for commander
  2. // Original definitions by: Alan Agius <https://github.com/alan-agius4>, Marcelo Dezem <https://github.com/mdezem>, vvakame <https://github.com/vvakame>, Jules Randolph <https://github.com/sveinburne>
  3. // Using method rather than property for method-signature-style, to document method overloads separately. Allow either.
  4. /* eslint-disable @typescript-eslint/method-signature-style */
  5. /* eslint-disable @typescript-eslint/no-explicit-any */
  6. declare namespace commander {
  7. interface CommanderError extends Error {
  8. code: string;
  9. exitCode: number;
  10. message: string;
  11. nestedError?: string;
  12. }
  13. type CommanderErrorConstructor = new (exitCode: number, code: string, message: string) => CommanderError;
  14. // eslint-disable-next-line @typescript-eslint/no-empty-interface
  15. interface InvalidOptionArgumentError extends CommanderError {
  16. }
  17. type InvalidOptionArgumentErrorConstructor = new (message: string) => InvalidOptionArgumentError;
  18. interface Option {
  19. flags: string;
  20. description: string;
  21. required: boolean; // A value must be supplied when the option is specified.
  22. optional: boolean; // A value is optional when the option is specified.
  23. variadic: boolean;
  24. mandatory: boolean; // The option must have a value after parsing, which usually means it must be specified on command line.
  25. optionFlags: string;
  26. short?: string;
  27. long?: string;
  28. negate: boolean;
  29. defaultValue?: any;
  30. defaultValueDescription?: string;
  31. parseArg?: <T>(value: string, previous: T) => T;
  32. hidden: boolean;
  33. argChoices?: string[];
  34. /**
  35. * Set the default value, and optionally supply the description to be displayed in the help.
  36. */
  37. default(value: any, description?: string): this;
  38. /**
  39. * Calculate the full description, including defaultValue etc.
  40. */
  41. fullDescription(): string;
  42. /**
  43. * Set the custom handler for processing CLI option arguments into option values.
  44. */
  45. argParser<T>(fn: (value: string, previous: T) => T): this;
  46. /**
  47. * Whether the option is mandatory and must have a value after parsing.
  48. */
  49. makeOptionMandatory(mandatory?: boolean): this;
  50. /**
  51. * Hide option in help.
  52. */
  53. hideHelp(hide?: boolean): this;
  54. /**
  55. * Validation of option argument failed.
  56. * Intended for use from custom argument processing functions.
  57. */
  58. argumentRejected(messsage: string): never;
  59. /**
  60. * Only allow option value to be one of choices.
  61. */
  62. choices(values: string[]): this;
  63. /**
  64. * Return option name.
  65. */
  66. name(): string;
  67. /**
  68. * Return option name, in a camelcase format that can be used
  69. * as a object attribute key.
  70. */
  71. attributeName(): string;
  72. }
  73. type OptionConstructor = new (flags: string, description?: string) => Option;
  74. interface Help {
  75. /** output helpWidth, long lines are wrapped to fit */
  76. helpWidth?: number;
  77. sortSubcommands: boolean;
  78. sortOptions: boolean;
  79. /** Get the command term to show in the list of subcommands. */
  80. subcommandTerm(cmd: Command): string;
  81. /** Get the command description to show in the list of subcommands. */
  82. subcommandDescription(cmd: Command): string;
  83. /** Get the option term to show in the list of options. */
  84. optionTerm(option: Option): string;
  85. /** Get the option description to show in the list of options. */
  86. optionDescription(option: Option): string;
  87. /** Get the command usage to be displayed at the top of the built-in help. */
  88. commandUsage(cmd: Command): string;
  89. /** Get the description for the command. */
  90. commandDescription(cmd: Command): string;
  91. /** Get an array of the visible subcommands. Includes a placeholder for the implicit help command, if there is one. */
  92. visibleCommands(cmd: Command): Command[];
  93. /** Get an array of the visible options. Includes a placeholder for the implicit help option, if there is one. */
  94. visibleOptions(cmd: Command): Option[];
  95. /** Get an array of the arguments which have descriptions. */
  96. visibleArguments(cmd: Command): Array<{ term: string; description: string}>;
  97. /** Get the longest command term length. */
  98. longestSubcommandTermLength(cmd: Command, helper: Help): number;
  99. /** Get the longest option term length. */
  100. longestOptionTermLength(cmd: Command, helper: Help): number;
  101. /** Get the longest argument term length. */
  102. longestArgumentTermLength(cmd: Command, helper: Help): number;
  103. /** Calculate the pad width from the maximum term length. */
  104. padWidth(cmd: Command, helper: Help): number;
  105. /**
  106. * Wrap the given string to width characters per line, with lines after the first indented.
  107. * Do not wrap if insufficient room for wrapping (minColumnWidth), or string is manually formatted.
  108. */
  109. wrap(str: string, width: number, indent: number, minColumnWidth?: number): string;
  110. /** Generate the built-in help text. */
  111. formatHelp(cmd: Command, helper: Help): string;
  112. }
  113. type HelpConstructor = new () => Help;
  114. type HelpConfiguration = Partial<Help>;
  115. interface ParseOptions {
  116. from: 'node' | 'electron' | 'user';
  117. }
  118. interface HelpContext { // optional parameter for .help() and .outputHelp()
  119. error: boolean;
  120. }
  121. interface AddHelpTextContext { // passed to text function used with .addHelpText()
  122. error: boolean;
  123. command: Command;
  124. }
  125. interface OutputConfiguration {
  126. writeOut?(str: string): void;
  127. writeErr?(str: string): void;
  128. getOutHelpWidth?(): number;
  129. getErrHelpWidth?(): number;
  130. outputError?(str: string, write: (str: string) => void): void;
  131. }
  132. type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
  133. interface OptionValues {
  134. [key: string]: any;
  135. }
  136. interface Command {
  137. args: string[];
  138. commands: Command[];
  139. parent: Command | null;
  140. /**
  141. * Set the program version to `str`.
  142. *
  143. * This method auto-registers the "-V, --version" flag
  144. * which will print the version number when passed.
  145. *
  146. * You can optionally supply the flags and description to override the defaults.
  147. */
  148. version(str: string, flags?: string, description?: string): this;
  149. /**
  150. * Define a command, implemented using an action handler.
  151. *
  152. * @remarks
  153. * The command description is supplied using `.description`, not as a parameter to `.command`.
  154. *
  155. * @example
  156. * ```ts
  157. * program
  158. * .command('clone <source> [destination]')
  159. * .description('clone a repository into a newly created directory')
  160. * .action((source, destination) => {
  161. * console.log('clone command called');
  162. * });
  163. * ```
  164. *
  165. * @param nameAndArgs - command name and arguments, args are `<required>` or `[optional]` and last may also be `variadic...`
  166. * @param opts - configuration options
  167. * @returns new command
  168. */
  169. command(nameAndArgs: string, opts?: CommandOptions): ReturnType<this['createCommand']>;
  170. /**
  171. * Define a command, implemented in a separate executable file.
  172. *
  173. * @remarks
  174. * The command description is supplied as the second parameter to `.command`.
  175. *
  176. * @example
  177. * ```ts
  178. * program
  179. * .command('start <service>', 'start named service')
  180. * .command('stop [service]', 'stop named service, or all if no name supplied');
  181. * ```
  182. *
  183. * @param nameAndArgs - command name and arguments, args are `<required>` or `[optional]` and last may also be `variadic...`
  184. * @param description - description of executable command
  185. * @param opts - configuration options
  186. * @returns `this` command for chaining
  187. */
  188. command(nameAndArgs: string, description: string, opts?: commander.ExecutableCommandOptions): this;
  189. /**
  190. * Factory routine to create a new unattached command.
  191. *
  192. * See .command() for creating an attached subcommand, which uses this routine to
  193. * create the command. You can override createCommand to customise subcommands.
  194. */
  195. createCommand(name?: string): Command;
  196. /**
  197. * Add a prepared subcommand.
  198. *
  199. * See .command() for creating an attached subcommand which inherits settings from its parent.
  200. *
  201. * @returns `this` command for chaining
  202. */
  203. addCommand(cmd: Command, opts?: CommandOptions): this;
  204. /**
  205. * Define argument syntax for command.
  206. *
  207. * @returns `this` command for chaining
  208. */
  209. arguments(desc: string): this;
  210. /**
  211. * Override default decision whether to add implicit help command.
  212. *
  213. * addHelpCommand() // force on
  214. * addHelpCommand(false); // force off
  215. * addHelpCommand('help [cmd]', 'display help for [cmd]'); // force on with custom details
  216. *
  217. * @returns `this` command for chaining
  218. */
  219. addHelpCommand(enableOrNameAndArgs?: string | boolean, description?: string): this;
  220. /**
  221. * Register callback to use as replacement for calling process.exit.
  222. */
  223. exitOverride(callback?: (err: CommanderError) => never|void): this;
  224. /**
  225. * You can customise the help with a subclass of Help by overriding createHelp,
  226. * or by overriding Help properties using configureHelp().
  227. */
  228. createHelp(): Help;
  229. /**
  230. * You can customise the help by overriding Help properties using configureHelp(),
  231. * or with a subclass of Help by overriding createHelp().
  232. */
  233. configureHelp(configuration: HelpConfiguration): this;
  234. /** Get configuration */
  235. configureHelp(): HelpConfiguration;
  236. /**
  237. * The default output goes to stdout and stderr. You can customise this for special
  238. * applications. You can also customise the display of errors by overriding outputError.
  239. *
  240. * The configuration properties are all functions:
  241. *
  242. * // functions to change where being written, stdout and stderr
  243. * writeOut(str)
  244. * writeErr(str)
  245. * // matching functions to specify width for wrapping help
  246. * getOutHelpWidth()
  247. * getErrHelpWidth()
  248. * // functions based on what is being written out
  249. * outputError(str, write) // used for displaying errors, and not used for displaying help
  250. */
  251. configureOutput(configuration: OutputConfiguration): this;
  252. /** Get configuration */
  253. configureOutput(): OutputConfiguration;
  254. /**
  255. * Register callback `fn` for the command.
  256. *
  257. * @example
  258. * program
  259. * .command('help')
  260. * .description('display verbose help')
  261. * .action(function() {
  262. * // output help here
  263. * });
  264. *
  265. * @returns `this` command for chaining
  266. */
  267. action(fn: (...args: any[]) => void | Promise<void>): this;
  268. /**
  269. * Define option with `flags`, `description` and optional
  270. * coercion `fn`.
  271. *
  272. * The `flags` string contains the short and/or long flags,
  273. * separated by comma, a pipe or space. The following are all valid
  274. * all will output this way when `--help` is used.
  275. *
  276. * "-p, --pepper"
  277. * "-p|--pepper"
  278. * "-p --pepper"
  279. *
  280. * @example
  281. * // simple boolean defaulting to false
  282. * program.option('-p, --pepper', 'add pepper');
  283. *
  284. * --pepper
  285. * program.pepper
  286. * // => Boolean
  287. *
  288. * // simple boolean defaulting to true
  289. * program.option('-C, --no-cheese', 'remove cheese');
  290. *
  291. * program.cheese
  292. * // => true
  293. *
  294. * --no-cheese
  295. * program.cheese
  296. * // => false
  297. *
  298. * // required argument
  299. * program.option('-C, --chdir <path>', 'change the working directory');
  300. *
  301. * --chdir /tmp
  302. * program.chdir
  303. * // => "/tmp"
  304. *
  305. * // optional argument
  306. * program.option('-c, --cheese [type]', 'add cheese [marble]');
  307. *
  308. * @returns `this` command for chaining
  309. */
  310. option(flags: string, description?: string, defaultValue?: string | boolean): this;
  311. option<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
  312. /** @deprecated since v7, instead use choices or a custom function */
  313. option(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean): this;
  314. /**
  315. * Define a required option, which must have a value after parsing. This usually means
  316. * the option must be specified on the command line. (Otherwise the same as .option().)
  317. *
  318. * The `flags` string contains the short and/or long flags, separated by comma, a pipe or space.
  319. */
  320. requiredOption(flags: string, description?: string, defaultValue?: string | boolean): this;
  321. requiredOption<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
  322. /** @deprecated since v7, instead use choices or a custom function */
  323. requiredOption(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean): this;
  324. /**
  325. * Factory routine to create a new unattached option.
  326. *
  327. * See .option() for creating an attached option, which uses this routine to
  328. * create the option. You can override createOption to return a custom option.
  329. */
  330. createOption(flags: string, description?: string): Option;
  331. /**
  332. * Add a prepared Option.
  333. *
  334. * See .option() and .requiredOption() for creating and attaching an option in a single call.
  335. */
  336. addOption(option: Option): this;
  337. /**
  338. * Whether to store option values as properties on command object,
  339. * or store separately (specify false). In both cases the option values can be accessed using .opts().
  340. *
  341. * @returns `this` command for chaining
  342. */
  343. storeOptionsAsProperties(): this & OptionValues;
  344. storeOptionsAsProperties(storeAsProperties: true): this & OptionValues;
  345. storeOptionsAsProperties(storeAsProperties?: boolean): this;
  346. /**
  347. * Alter parsing of short flags with optional values.
  348. *
  349. * @example
  350. * // for `.option('-f,--flag [value]'):
  351. * .combineFlagAndOptionalValue(true) // `-f80` is treated like `--flag=80`, this is the default behaviour
  352. * .combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
  353. *
  354. * @returns `this` command for chaining
  355. */
  356. combineFlagAndOptionalValue(combine?: boolean): this;
  357. /**
  358. * Allow unknown options on the command line.
  359. *
  360. * @returns `this` command for chaining
  361. */
  362. allowUnknownOption(allowUnknown?: boolean): this;
  363. /**
  364. * Allow excess command-arguments on the command line. Pass false to make excess arguments an error.
  365. *
  366. * @returns `this` command for chaining
  367. */
  368. allowExcessArguments(allowExcess?: boolean): this;
  369. /**
  370. * Enable positional options. Positional means global options are specified before subcommands which lets
  371. * subcommands reuse the same option names, and also enables subcommands to turn on passThroughOptions.
  372. *
  373. * The default behaviour is non-positional and global options may appear anywhere on the command line.
  374. *
  375. * @returns `this` command for chaining
  376. */
  377. enablePositionalOptions(positional?: boolean): this;
  378. /**
  379. * Pass through options that come after command-arguments rather than treat them as command-options,
  380. * so actual command-options come before command-arguments. Turning this on for a subcommand requires
  381. * positional options to have been enabled on the program (parent commands).
  382. *
  383. * The default behaviour is non-positional and options may appear before or after command-arguments.
  384. *
  385. * @returns `this` command for chaining
  386. */
  387. passThroughOptions(passThrough?: boolean): this;
  388. /**
  389. * Parse `argv`, setting options and invoking commands when defined.
  390. *
  391. * The default expectation is that the arguments are from node and have the application as argv[0]
  392. * and the script being run in argv[1], with user parameters after that.
  393. *
  394. * Examples:
  395. *
  396. * program.parse(process.argv);
  397. * program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
  398. * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
  399. *
  400. * @returns `this` command for chaining
  401. */
  402. parse(argv?: string[], options?: ParseOptions): this;
  403. /**
  404. * Parse `argv`, setting options and invoking commands when defined.
  405. *
  406. * Use parseAsync instead of parse if any of your action handlers are async. Returns a Promise.
  407. *
  408. * The default expectation is that the arguments are from node and have the application as argv[0]
  409. * and the script being run in argv[1], with user parameters after that.
  410. *
  411. * Examples:
  412. *
  413. * program.parseAsync(process.argv);
  414. * program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
  415. * program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
  416. *
  417. * @returns Promise
  418. */
  419. parseAsync(argv?: string[], options?: ParseOptions): Promise<this>;
  420. /**
  421. * Parse options from `argv` removing known options,
  422. * and return argv split into operands and unknown arguments.
  423. *
  424. * @example
  425. * argv => operands, unknown
  426. * --known kkk op => [op], []
  427. * op --known kkk => [op], []
  428. * sub --unknown uuu op => [sub], [--unknown uuu op]
  429. * sub -- --unknown uuu op => [sub --unknown uuu op], []
  430. */
  431. parseOptions(argv: string[]): commander.ParseOptionsResult;
  432. /**
  433. * Return an object containing options as key-value pairs
  434. */
  435. opts(): OptionValues;
  436. /**
  437. * Set the description.
  438. *
  439. * @returns `this` command for chaining
  440. */
  441. description(str: string, argsDescription?: {[argName: string]: string}): this;
  442. /**
  443. * Get the description.
  444. */
  445. description(): string;
  446. /**
  447. * Set an alias for the command.
  448. *
  449. * You may call more than once to add multiple aliases. Only the first alias is shown in the auto-generated help.
  450. *
  451. * @returns `this` command for chaining
  452. */
  453. alias(alias: string): this;
  454. /**
  455. * Get alias for the command.
  456. */
  457. alias(): string;
  458. /**
  459. * Set aliases for the command.
  460. *
  461. * Only the first alias is shown in the auto-generated help.
  462. *
  463. * @returns `this` command for chaining
  464. */
  465. aliases(aliases: string[]): this;
  466. /**
  467. * Get aliases for the command.
  468. */
  469. aliases(): string[];
  470. /**
  471. * Set the command usage.
  472. *
  473. * @returns `this` command for chaining
  474. */
  475. usage(str: string): this;
  476. /**
  477. * Get the command usage.
  478. */
  479. usage(): string;
  480. /**
  481. * Set the name of the command.
  482. *
  483. * @returns `this` command for chaining
  484. */
  485. name(str: string): this;
  486. /**
  487. * Get the name of the command.
  488. */
  489. name(): string;
  490. /**
  491. * Output help information for this command.
  492. *
  493. * Outputs built-in help, and custom text added using `.addHelpText()`.
  494. *
  495. */
  496. outputHelp(context?: HelpContext): void;
  497. /** @deprecated since v7 */
  498. outputHelp(cb?: (str: string) => string): void;
  499. /**
  500. * Return command help documentation.
  501. */
  502. helpInformation(context?: HelpContext): string;
  503. /**
  504. * You can pass in flags and a description to override the help
  505. * flags and help description for your command. Pass in false
  506. * to disable the built-in help option.
  507. */
  508. helpOption(flags?: string | boolean, description?: string): this;
  509. /**
  510. * Output help information and exit.
  511. *
  512. * Outputs built-in help, and custom text added using `.addHelpText()`.
  513. */
  514. help(context?: HelpContext): never;
  515. /** @deprecated since v7 */
  516. help(cb?: (str: string) => string): never;
  517. /**
  518. * Add additional text to be displayed with the built-in help.
  519. *
  520. * Position is 'before' or 'after' to affect just this command,
  521. * and 'beforeAll' or 'afterAll' to affect this command and all its subcommands.
  522. */
  523. addHelpText(position: AddHelpTextPosition, text: string): this;
  524. addHelpText(position: AddHelpTextPosition, text: (context: AddHelpTextContext) => string | undefined): this;
  525. /**
  526. * Add a listener (callback) for when events occur. (Implemented using EventEmitter.)
  527. */
  528. on(event: string | symbol, listener: (...args: any[]) => void): this;
  529. }
  530. type CommandConstructor = new (name?: string) => Command;
  531. interface CommandOptions {
  532. hidden?: boolean;
  533. isDefault?: boolean;
  534. /** @deprecated since v7, replaced by hidden */
  535. noHelp?: boolean;
  536. }
  537. interface ExecutableCommandOptions extends CommandOptions {
  538. executableFile?: string;
  539. }
  540. // eslint-disable-next-line @typescript-eslint/no-unused-vars
  541. interface ParseOptionsResult {
  542. operands: string[];
  543. unknown: string[];
  544. }
  545. // eslint-disable-next-line @typescript-eslint/no-unused-vars
  546. interface CommanderStatic extends Command {
  547. program: Command;
  548. Command: CommandConstructor;
  549. Option: OptionConstructor;
  550. CommanderError: CommanderErrorConstructor;
  551. InvalidOptionArgumentError: InvalidOptionArgumentErrorConstructor;
  552. Help: HelpConstructor;
  553. }
  554. }
  555. // Declaring namespace AND global
  556. // eslint-disable-next-line @typescript-eslint/no-redeclare
  557. declare const commander: commander.CommanderStatic;
  558. export = commander;