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