index.d.ts 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410
  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. declare namespace commander {
  4. interface CommanderError extends Error {
  5. code: string;
  6. exitCode: number;
  7. message: string;
  8. nestedError?: string;
  9. }
  10. type CommanderErrorConstructor = new (exitCode: number, code: string, message: string) => CommanderError;
  11. interface Option {
  12. flags: string;
  13. required: boolean; // A value must be supplied when the option is specified.
  14. optional: boolean; // A value is optional when the option is specified.
  15. mandatory: boolean; // The option must have a value after parsing, which usually means it must be specified on command line.
  16. bool: boolean;
  17. short?: string;
  18. long: string;
  19. description: string;
  20. }
  21. type OptionConstructor = new (flags: string, description?: string) => Option;
  22. interface ParseOptions {
  23. from: 'node' | 'electron' | 'user';
  24. }
  25. interface Command {
  26. [key: string]: any; // options as properties
  27. args: string[];
  28. commands: Command[];
  29. /**
  30. * Set the program version to `str`.
  31. *
  32. * This method auto-registers the "-V, --version" flag
  33. * which will print the version number when passed.
  34. *
  35. * You can optionally supply the flags and description to override the defaults.
  36. */
  37. version(str: string, flags?: string, description?: string): this;
  38. /**
  39. * Define a command, implemented using an action handler.
  40. *
  41. * @remarks
  42. * The command description is supplied using `.description`, not as a parameter to `.command`.
  43. *
  44. * @example
  45. * ```ts
  46. * program
  47. * .command('clone <source> [destination]')
  48. * .description('clone a repository into a newly created directory')
  49. * .action((source, destination) => {
  50. * console.log('clone command called');
  51. * });
  52. * ```
  53. *
  54. * @param nameAndArgs - command name and arguments, args are `<required>` or `[optional]` and last may also be `variadic...`
  55. * @param opts - configuration options
  56. * @returns new command
  57. */
  58. command(nameAndArgs: string, opts?: CommandOptions): ReturnType<this['createCommand']>;
  59. /**
  60. * Define a command, implemented in a separate executable file.
  61. *
  62. * @remarks
  63. * The command description is supplied as the second parameter to `.command`.
  64. *
  65. * @example
  66. * ```ts
  67. * program
  68. * .command('start <service>', 'start named service')
  69. * .command('stop [service]', 'stop named service, or all if no name supplied');
  70. * ```
  71. *
  72. * @param nameAndArgs - command name and arguments, args are `<required>` or `[optional]` and last may also be `variadic...`
  73. * @param description - description of executable command
  74. * @param opts - configuration options
  75. * @returns `this` command for chaining
  76. */
  77. command(nameAndArgs: string, description: string, opts?: commander.ExecutableCommandOptions): this;
  78. /**
  79. * Factory routine to create a new unattached command.
  80. *
  81. * See .command() for creating an attached subcommand, which uses this routine to
  82. * create the command. You can override createCommand to customise subcommands.
  83. */
  84. createCommand(name?: string): Command;
  85. /**
  86. * Add a prepared subcommand.
  87. *
  88. * See .command() for creating an attached subcommand which inherits settings from its parent.
  89. *
  90. * @returns `this` command for chaining
  91. */
  92. addCommand(cmd: Command, opts?: CommandOptions): this;
  93. /**
  94. * Define argument syntax for command.
  95. *
  96. * @returns `this` command for chaining
  97. */
  98. arguments(desc: string): this;
  99. /**
  100. * Override default decision whether to add implicit help command.
  101. *
  102. * addHelpCommand() // force on
  103. * addHelpCommand(false); // force off
  104. * addHelpCommand('help [cmd]', 'display help for [cmd]'); // force on with custom details
  105. *
  106. * @returns `this` command for chaining
  107. */
  108. addHelpCommand(enableOrNameAndArgs?: string | boolean, description?: string): this;
  109. /**
  110. * Register callback to use as replacement for calling process.exit.
  111. */
  112. exitOverride(callback?: (err: CommanderError) => never|void): this;
  113. /**
  114. * Register callback `fn` for the command.
  115. *
  116. * @example
  117. * program
  118. * .command('help')
  119. * .description('display verbose help')
  120. * .action(function() {
  121. * // output help here
  122. * });
  123. *
  124. * @returns `this` command for chaining
  125. */
  126. action(fn: (...args: any[]) => void | Promise<void>): this;
  127. /**
  128. * Define option with `flags`, `description` and optional
  129. * coercion `fn`.
  130. *
  131. * The `flags` string should contain both the short and long flags,
  132. * separated by comma, a pipe or space. The following are all valid
  133. * all will output this way when `--help` is used.
  134. *
  135. * "-p, --pepper"
  136. * "-p|--pepper"
  137. * "-p --pepper"
  138. *
  139. * @example
  140. * // simple boolean defaulting to false
  141. * program.option('-p, --pepper', 'add pepper');
  142. *
  143. * --pepper
  144. * program.pepper
  145. * // => Boolean
  146. *
  147. * // simple boolean defaulting to true
  148. * program.option('-C, --no-cheese', 'remove cheese');
  149. *
  150. * program.cheese
  151. * // => true
  152. *
  153. * --no-cheese
  154. * program.cheese
  155. * // => false
  156. *
  157. * // required argument
  158. * program.option('-C, --chdir <path>', 'change the working directory');
  159. *
  160. * --chdir /tmp
  161. * program.chdir
  162. * // => "/tmp"
  163. *
  164. * // optional argument
  165. * program.option('-c, --cheese [type]', 'add cheese [marble]');
  166. *
  167. * @returns `this` command for chaining
  168. */
  169. option(flags: string, description?: string, defaultValue?: string | boolean): this;
  170. option(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean): this;
  171. option<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
  172. /**
  173. * Define a required option, which must have a value after parsing. This usually means
  174. * the option must be specified on the command line. (Otherwise the same as .option().)
  175. *
  176. * The `flags` string should contain both the short and long flags, separated by comma, a pipe or space.
  177. */
  178. requiredOption(flags: string, description?: string, defaultValue?: string | boolean): this;
  179. requiredOption(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean): this;
  180. requiredOption<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
  181. /**
  182. * Whether to store option values as properties on command object,
  183. * or store separately (specify false). In both cases the option values can be accessed using .opts().
  184. *
  185. * @returns `this` command for chaining
  186. */
  187. storeOptionsAsProperties(value?: boolean): this;
  188. /**
  189. * Whether to pass command to action handler,
  190. * or just the options (specify false).
  191. *
  192. * @returns `this` command for chaining
  193. */
  194. passCommandToAction(value?: boolean): this;
  195. /**
  196. * Alter parsing of short flags with optional values.
  197. *
  198. * @example
  199. * // for `.option('-f,--flag [value]'):
  200. * .combineFlagAndOptionalValue(true) // `-f80` is treated like `--flag=80`, this is the default behaviour
  201. * .combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
  202. *
  203. * @returns `this` command for chaining
  204. */
  205. combineFlagAndOptionalValue(arg?: boolean): this;
  206. /**
  207. * Allow unknown options on the command line.
  208. *
  209. * @param [arg] if `true` or omitted, no error will be thrown for unknown options.
  210. * @returns `this` command for chaining
  211. */
  212. allowUnknownOption(arg?: boolean): this;
  213. /**
  214. * Parse `argv`, setting options and invoking commands when defined.
  215. *
  216. * The default expectation is that the arguments are from node and have the application as argv[0]
  217. * and the script being run in argv[1], with user parameters after that.
  218. *
  219. * Examples:
  220. *
  221. * program.parse(process.argv);
  222. * program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
  223. * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
  224. *
  225. * @returns `this` command for chaining
  226. */
  227. parse(argv?: string[], options?: ParseOptions): this;
  228. /**
  229. * Parse `argv`, setting options and invoking commands when defined.
  230. *
  231. * Use parseAsync instead of parse if any of your action handlers are async. Returns a Promise.
  232. *
  233. * The default expectation is that the arguments are from node and have the application as argv[0]
  234. * and the script being run in argv[1], with user parameters after that.
  235. *
  236. * Examples:
  237. *
  238. * program.parseAsync(process.argv);
  239. * program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
  240. * program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
  241. *
  242. * @returns Promise
  243. */
  244. parseAsync(argv?: string[], options?: ParseOptions): Promise<this>;
  245. /**
  246. * Parse options from `argv` removing known options,
  247. * and return argv split into operands and unknown arguments.
  248. *
  249. * @example
  250. * argv => operands, unknown
  251. * --known kkk op => [op], []
  252. * op --known kkk => [op], []
  253. * sub --unknown uuu op => [sub], [--unknown uuu op]
  254. * sub -- --unknown uuu op => [sub --unknown uuu op], []
  255. */
  256. parseOptions(argv: string[]): commander.ParseOptionsResult;
  257. /**
  258. * Return an object containing options as key-value pairs
  259. */
  260. opts(): { [key: string]: any };
  261. /**
  262. * Set the description.
  263. *
  264. * @returns `this` command for chaining
  265. */
  266. description(str: string, argsDescription?: {[argName: string]: string}): this;
  267. /**
  268. * Get the description.
  269. */
  270. description(): string;
  271. /**
  272. * Set an alias for the command.
  273. *
  274. * You may call more than once to add multiple aliases. Only the first alias is shown in the auto-generated help.
  275. *
  276. * @returns `this` command for chaining
  277. */
  278. alias(alias: string): this;
  279. /**
  280. * Get alias for the command.
  281. */
  282. alias(): string;
  283. /**
  284. * Set aliases for the command.
  285. *
  286. * Only the first alias is shown in the auto-generated help.
  287. *
  288. * @returns `this` command for chaining
  289. */
  290. aliases(aliases: string[]): this;
  291. /**
  292. * Get aliases for the command.
  293. */
  294. aliases(): string[];
  295. /**
  296. * Set the command usage.
  297. *
  298. * @returns `this` command for chaining
  299. */
  300. usage(str: string): this;
  301. /**
  302. * Get the command usage.
  303. */
  304. usage(): string;
  305. /**
  306. * Set the name of the command.
  307. *
  308. * @returns `this` command for chaining
  309. */
  310. name(str: string): this;
  311. /**
  312. * Get the name of the command.
  313. */
  314. name(): string;
  315. /**
  316. * Output help information for this command.
  317. *
  318. * When listener(s) are available for the helpLongFlag
  319. * those callbacks are invoked.
  320. */
  321. outputHelp(cb?: (str: string) => string): void;
  322. /**
  323. * Return command help documentation.
  324. */
  325. helpInformation(): string;
  326. /**
  327. * You can pass in flags and a description to override the help
  328. * flags and help description for your command. Pass in false
  329. * to disable the built-in help option.
  330. */
  331. helpOption(flags?: string | boolean, description?: string): this;
  332. /**
  333. * Output help information and exit.
  334. */
  335. help(cb?: (str: string) => string): never;
  336. /**
  337. * Add a listener (callback) for when events occur. (Implemented using EventEmitter.)
  338. *
  339. * @example
  340. * program
  341. * .on('--help', () -> {
  342. * console.log('See web site for more information.');
  343. * });
  344. */
  345. on(event: string | symbol, listener: (...args: any[]) => void): this;
  346. }
  347. type CommandConstructor = new (name?: string) => Command;
  348. interface CommandOptions {
  349. noHelp?: boolean; // old name for hidden
  350. hidden?: boolean;
  351. isDefault?: boolean;
  352. }
  353. interface ExecutableCommandOptions extends CommandOptions {
  354. executableFile?: string;
  355. }
  356. interface ParseOptionsResult {
  357. operands: string[];
  358. unknown: string[];
  359. }
  360. interface CommanderStatic extends Command {
  361. program: Command;
  362. Command: CommandConstructor;
  363. Option: OptionConstructor;
  364. CommanderError: CommanderErrorConstructor;
  365. }
  366. }
  367. // Declaring namespace AND global
  368. // eslint-disable-next-line @typescript-eslint/no-redeclare
  369. declare const commander: commander.CommanderStatic;
  370. export = commander;