| // Type definitions for commander |
| // 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> |
| |
| // Using method rather than property for method-signature-style, to document method overloads separately. Allow either. |
| /* eslint-disable @typescript-eslint/method-signature-style */ |
| /* eslint-disable @typescript-eslint/no-explicit-any */ |
| |
| declare namespace commander { |
| |
| interface CommanderError extends Error { |
| code: string; |
| exitCode: number; |
| message: string; |
| nestedError?: string; |
| } |
| type CommanderErrorConstructor = new (exitCode: number, code: string, message: string) => CommanderError; |
| |
| // eslint-disable-next-line @typescript-eslint/no-empty-interface |
| interface InvalidOptionArgumentError extends CommanderError { |
| } |
| type InvalidOptionArgumentErrorConstructor = new (message: string) => InvalidOptionArgumentError; |
| |
| interface Option { |
| flags: string; |
| description: string; |
| |
| required: boolean; // A value must be supplied when the option is specified. |
| optional: boolean; // A value is optional when the option is specified. |
| variadic: boolean; |
| mandatory: boolean; // The option must have a value after parsing, which usually means it must be specified on command line. |
| optionFlags: string; |
| short?: string; |
| long?: string; |
| negate: boolean; |
| defaultValue?: any; |
| defaultValueDescription?: string; |
| parseArg?: <T>(value: string, previous: T) => T; |
| hidden: boolean; |
| argChoices?: string[]; |
| |
| /** |
| * Set the default value, and optionally supply the description to be displayed in the help. |
| */ |
| default(value: any, description?: string): this; |
| |
| /** |
| * Calculate the full description, including defaultValue etc. |
| */ |
| fullDescription(): string; |
| |
| /** |
| * Set the custom handler for processing CLI option arguments into option values. |
| */ |
| argParser<T>(fn: (value: string, previous: T) => T): this; |
| |
| /** |
| * Whether the option is mandatory and must have a value after parsing. |
| */ |
| makeOptionMandatory(mandatory?: boolean): this; |
| |
| /** |
| * Hide option in help. |
| */ |
| hideHelp(hide?: boolean): this; |
| |
| /** |
| * Validation of option argument failed. |
| * Intended for use from custom argument processing functions. |
| */ |
| argumentRejected(messsage: string): never; |
| |
| /** |
| * Only allow option value to be one of choices. |
| */ |
| choices(values: string[]): this; |
| |
| /** |
| * Return option name. |
| */ |
| name(): string; |
| |
| /** |
| * Return option name, in a camelcase format that can be used |
| * as a object attribute key. |
| */ |
| attributeName(): string; |
| } |
| type OptionConstructor = new (flags: string, description?: string) => Option; |
| |
| interface Help { |
| /** output helpWidth, long lines are wrapped to fit */ |
| helpWidth?: number; |
| sortSubcommands: boolean; |
| sortOptions: boolean; |
| |
| /** Get the command term to show in the list of subcommands. */ |
| subcommandTerm(cmd: Command): string; |
| /** Get the command description to show in the list of subcommands. */ |
| subcommandDescription(cmd: Command): string; |
| /** Get the option term to show in the list of options. */ |
| optionTerm(option: Option): string; |
| /** Get the option description to show in the list of options. */ |
| optionDescription(option: Option): string; |
| |
| /** Get the command usage to be displayed at the top of the built-in help. */ |
| commandUsage(cmd: Command): string; |
| /** Get the description for the command. */ |
| commandDescription(cmd: Command): string; |
| |
| /** Get an array of the visible subcommands. Includes a placeholder for the implicit help command, if there is one. */ |
| visibleCommands(cmd: Command): Command[]; |
| /** Get an array of the visible options. Includes a placeholder for the implicit help option, if there is one. */ |
| visibleOptions(cmd: Command): Option[]; |
| /** Get an array of the arguments which have descriptions. */ |
| visibleArguments(cmd: Command): Array<{ term: string; description: string}>; |
| |
| /** Get the longest command term length. */ |
| longestSubcommandTermLength(cmd: Command, helper: Help): number; |
| /** Get the longest option term length. */ |
| longestOptionTermLength(cmd: Command, helper: Help): number; |
| /** Get the longest argument term length. */ |
| longestArgumentTermLength(cmd: Command, helper: Help): number; |
| /** Calculate the pad width from the maximum term length. */ |
| padWidth(cmd: Command, helper: Help): number; |
| |
| /** |
| * Wrap the given string to width characters per line, with lines after the first indented. |
| * Do not wrap if insufficient room for wrapping (minColumnWidth), or string is manually formatted. |
| */ |
| wrap(str: string, width: number, indent: number, minColumnWidth?: number): string; |
| |
| /** Generate the built-in help text. */ |
| formatHelp(cmd: Command, helper: Help): string; |
| } |
| type HelpConstructor = new () => Help; |
| type HelpConfiguration = Partial<Help>; |
| |
| interface ParseOptions { |
| from: 'node' | 'electron' | 'user'; |
| } |
| interface HelpContext { // optional parameter for .help() and .outputHelp() |
| error: boolean; |
| } |
| interface AddHelpTextContext { // passed to text function used with .addHelpText() |
| error: boolean; |
| command: Command; |
| } |
| interface OutputConfiguration { |
| writeOut?(str: string): void; |
| writeErr?(str: string): void; |
| getOutHelpWidth?(): number; |
| getErrHelpWidth?(): number; |
| outputError?(str: string, write: (str: string) => void): void; |
| |
| } |
| |
| type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll'; |
| |
| interface OptionValues { |
| [key: string]: any; |
| } |
| |
| interface Command { |
| args: string[]; |
| commands: Command[]; |
| parent: Command | null; |
| |
| /** |
| * Set the program version to `str`. |
| * |
| * This method auto-registers the "-V, --version" flag |
| * which will print the version number when passed. |
| * |
| * You can optionally supply the flags and description to override the defaults. |
| */ |
| version(str: string, flags?: string, description?: string): this; |
| |
| /** |
| * Define a command, implemented using an action handler. |
| * |
| * @remarks |
| * The command description is supplied using `.description`, not as a parameter to `.command`. |
| * |
| * @example |
| * ```ts |
| * program |
| * .command('clone <source> [destination]') |
| * .description('clone a repository into a newly created directory') |
| * .action((source, destination) => { |
| * console.log('clone command called'); |
| * }); |
| * ``` |
| * |
| * @param nameAndArgs - command name and arguments, args are `<required>` or `[optional]` and last may also be `variadic...` |
| * @param opts - configuration options |
| * @returns new command |
| */ |
| command(nameAndArgs: string, opts?: CommandOptions): ReturnType<this['createCommand']>; |
| /** |
| * Define a command, implemented in a separate executable file. |
| * |
| * @remarks |
| * The command description is supplied as the second parameter to `.command`. |
| * |
| * @example |
| * ```ts |
| * program |
| * .command('start <service>', 'start named service') |
| * .command('stop [service]', 'stop named service, or all if no name supplied'); |
| * ``` |
| * |
| * @param nameAndArgs - command name and arguments, args are `<required>` or `[optional]` and last may also be `variadic...` |
| * @param description - description of executable command |
| * @param opts - configuration options |
| * @returns `this` command for chaining |
| */ |
| command(nameAndArgs: string, description: string, opts?: commander.ExecutableCommandOptions): this; |
| |
| /** |
| * Factory routine to create a new unattached command. |
| * |
| * See .command() for creating an attached subcommand, which uses this routine to |
| * create the command. You can override createCommand to customise subcommands. |
| */ |
| createCommand(name?: string): Command; |
| |
| /** |
| * Add a prepared subcommand. |
| * |
| * See .command() for creating an attached subcommand which inherits settings from its parent. |
| * |
| * @returns `this` command for chaining |
| */ |
| addCommand(cmd: Command, opts?: CommandOptions): this; |
| |
| /** |
| * Define argument syntax for command. |
| * |
| * @returns `this` command for chaining |
| */ |
| arguments(desc: string): this; |
| |
| /** |
| * Override default decision whether to add implicit help command. |
| * |
| * addHelpCommand() // force on |
| * addHelpCommand(false); // force off |
| * addHelpCommand('help [cmd]', 'display help for [cmd]'); // force on with custom details |
| * |
| * @returns `this` command for chaining |
| */ |
| addHelpCommand(enableOrNameAndArgs?: string | boolean, description?: string): this; |
| |
| /** |
| * Register callback to use as replacement for calling process.exit. |
| */ |
| exitOverride(callback?: (err: CommanderError) => never|void): this; |
| |
| /** |
| * You can customise the help with a subclass of Help by overriding createHelp, |
| * or by overriding Help properties using configureHelp(). |
| */ |
| createHelp(): Help; |
| |
| /** |
| * You can customise the help by overriding Help properties using configureHelp(), |
| * or with a subclass of Help by overriding createHelp(). |
| */ |
| configureHelp(configuration: HelpConfiguration): this; |
| /** Get configuration */ |
| configureHelp(): HelpConfiguration; |
| |
| /** |
| * The default output goes to stdout and stderr. You can customise this for special |
| * applications. You can also customise the display of errors by overriding outputError. |
| * |
| * The configuration properties are all functions: |
| * |
| * // functions to change where being written, stdout and stderr |
| * writeOut(str) |
| * writeErr(str) |
| * // matching functions to specify width for wrapping help |
| * getOutHelpWidth() |
| * getErrHelpWidth() |
| * // functions based on what is being written out |
| * outputError(str, write) // used for displaying errors, and not used for displaying help |
| */ |
| configureOutput(configuration: OutputConfiguration): this; |
| /** Get configuration */ |
| configureOutput(): OutputConfiguration; |
| |
| /** |
| * Register callback `fn` for the command. |
| * |
| * @example |
| * program |
| * .command('help') |
| * .description('display verbose help') |
| * .action(function() { |
| * // output help here |
| * }); |
| * |
| * @returns `this` command for chaining |
| */ |
| action(fn: (...args: any[]) => void | Promise<void>): this; |
| |
| /** |
| * Define option with `flags`, `description` and optional |
| * coercion `fn`. |
| * |
| * The `flags` string contains the short and/or long flags, |
| * separated by comma, a pipe or space. The following are all valid |
| * all will output this way when `--help` is used. |
| * |
| * "-p, --pepper" |
| * "-p|--pepper" |
| * "-p --pepper" |
| * |
| * @example |
| * // simple boolean defaulting to false |
| * program.option('-p, --pepper', 'add pepper'); |
| * |
| * --pepper |
| * program.pepper |
| * // => Boolean |
| * |
| * // simple boolean defaulting to true |
| * program.option('-C, --no-cheese', 'remove cheese'); |
| * |
| * program.cheese |
| * // => true |
| * |
| * --no-cheese |
| * program.cheese |
| * // => false |
| * |
| * // required argument |
| * program.option('-C, --chdir <path>', 'change the working directory'); |
| * |
| * --chdir /tmp |
| * program.chdir |
| * // => "/tmp" |
| * |
| * // optional argument |
| * program.option('-c, --cheese [type]', 'add cheese [marble]'); |
| * |
| * @returns `this` command for chaining |
| */ |
| option(flags: string, description?: string, defaultValue?: string | boolean): this; |
| option<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this; |
| /** @deprecated since v7, instead use choices or a custom function */ |
| option(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean): this; |
| |
| /** |
| * Define a required option, which must have a value after parsing. This usually means |
| * the option must be specified on the command line. (Otherwise the same as .option().) |
| * |
| * The `flags` string contains the short and/or long flags, separated by comma, a pipe or space. |
| */ |
| requiredOption(flags: string, description?: string, defaultValue?: string | boolean): this; |
| requiredOption<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this; |
| /** @deprecated since v7, instead use choices or a custom function */ |
| requiredOption(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean): this; |
| |
| /** |
| * Factory routine to create a new unattached option. |
| * |
| * See .option() for creating an attached option, which uses this routine to |
| * create the option. You can override createOption to return a custom option. |
| */ |
| |
| createOption(flags: string, description?: string): Option; |
| |
| /** |
| * Add a prepared Option. |
| * |
| * See .option() and .requiredOption() for creating and attaching an option in a single call. |
| */ |
| addOption(option: Option): this; |
| |
| /** |
| * Whether to store option values as properties on command object, |
| * or store separately (specify false). In both cases the option values can be accessed using .opts(). |
| * |
| * @returns `this` command for chaining |
| */ |
| storeOptionsAsProperties(): this & OptionValues; |
| storeOptionsAsProperties(storeAsProperties: true): this & OptionValues; |
| storeOptionsAsProperties(storeAsProperties?: boolean): this; |
| |
| /** |
| * Alter parsing of short flags with optional values. |
| * |
| * @example |
| * // for `.option('-f,--flag [value]'): |
| * .combineFlagAndOptionalValue(true) // `-f80` is treated like `--flag=80`, this is the default behaviour |
| * .combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b` |
| * |
| * @returns `this` command for chaining |
| */ |
| combineFlagAndOptionalValue(combine?: boolean): this; |
| |
| /** |
| * Allow unknown options on the command line. |
| * |
| * @returns `this` command for chaining |
| */ |
| allowUnknownOption(allowUnknown?: boolean): this; |
| |
| /** |
| * Allow excess command-arguments on the command line. Pass false to make excess arguments an error. |
| * |
| * @returns `this` command for chaining |
| */ |
| allowExcessArguments(allowExcess?: boolean): this; |
| |
| /** |
| * Enable positional options. Positional means global options are specified before subcommands which lets |
| * subcommands reuse the same option names, and also enables subcommands to turn on passThroughOptions. |
| * |
| * The default behaviour is non-positional and global options may appear anywhere on the command line. |
| * |
| * @returns `this` command for chaining |
| */ |
| enablePositionalOptions(positional?: boolean): this; |
| |
| /** |
| * Pass through options that come after command-arguments rather than treat them as command-options, |
| * so actual command-options come before command-arguments. Turning this on for a subcommand requires |
| * positional options to have been enabled on the program (parent commands). |
| * |
| * The default behaviour is non-positional and options may appear before or after command-arguments. |
| * |
| * @returns `this` command for chaining |
| */ |
| passThroughOptions(passThrough?: boolean): this; |
| |
| /** |
| * Parse `argv`, setting options and invoking commands when defined. |
| * |
| * The default expectation is that the arguments are from node and have the application as argv[0] |
| * and the script being run in argv[1], with user parameters after that. |
| * |
| * Examples: |
| * |
| * program.parse(process.argv); |
| * program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions |
| * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0] |
| * |
| * @returns `this` command for chaining |
| */ |
| parse(argv?: string[], options?: ParseOptions): this; |
| |
| /** |
| * Parse `argv`, setting options and invoking commands when defined. |
| * |
| * Use parseAsync instead of parse if any of your action handlers are async. Returns a Promise. |
| * |
| * The default expectation is that the arguments are from node and have the application as argv[0] |
| * and the script being run in argv[1], with user parameters after that. |
| * |
| * Examples: |
| * |
| * program.parseAsync(process.argv); |
| * program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions |
| * program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0] |
| * |
| * @returns Promise |
| */ |
| parseAsync(argv?: string[], options?: ParseOptions): Promise<this>; |
| |
| /** |
| * Parse options from `argv` removing known options, |
| * and return argv split into operands and unknown arguments. |
| * |
| * @example |
| * argv => operands, unknown |
| * --known kkk op => [op], [] |
| * op --known kkk => [op], [] |
| * sub --unknown uuu op => [sub], [--unknown uuu op] |
| * sub -- --unknown uuu op => [sub --unknown uuu op], [] |
| */ |
| parseOptions(argv: string[]): commander.ParseOptionsResult; |
| |
| /** |
| * Return an object containing options as key-value pairs |
| */ |
| opts(): OptionValues; |
| |
| /** |
| * Set the description. |
| * |
| * @returns `this` command for chaining |
| */ |
| description(str: string, argsDescription?: {[argName: string]: string}): this; |
| /** |
| * Get the description. |
| */ |
| description(): string; |
| |
| /** |
| * Set an alias for the command. |
| * |
| * You may call more than once to add multiple aliases. Only the first alias is shown in the auto-generated help. |
| * |
| * @returns `this` command for chaining |
| */ |
| alias(alias: string): this; |
| /** |
| * Get alias for the command. |
| */ |
| alias(): string; |
| |
| /** |
| * Set aliases for the command. |
| * |
| * Only the first alias is shown in the auto-generated help. |
| * |
| * @returns `this` command for chaining |
| */ |
| aliases(aliases: string[]): this; |
| /** |
| * Get aliases for the command. |
| */ |
| aliases(): string[]; |
| |
| /** |
| * Set the command usage. |
| * |
| * @returns `this` command for chaining |
| */ |
| usage(str: string): this; |
| /** |
| * Get the command usage. |
| */ |
| usage(): string; |
| |
| /** |
| * Set the name of the command. |
| * |
| * @returns `this` command for chaining |
| */ |
| name(str: string): this; |
| /** |
| * Get the name of the command. |
| */ |
| name(): string; |
| |
| /** |
| * Output help information for this command. |
| * |
| * Outputs built-in help, and custom text added using `.addHelpText()`. |
| * |
| */ |
| outputHelp(context?: HelpContext): void; |
| /** @deprecated since v7 */ |
| outputHelp(cb?: (str: string) => string): void; |
| |
| /** |
| * Return command help documentation. |
| */ |
| helpInformation(context?: HelpContext): string; |
| |
| /** |
| * You can pass in flags and a description to override the help |
| * flags and help description for your command. Pass in false |
| * to disable the built-in help option. |
| */ |
| helpOption(flags?: string | boolean, description?: string): this; |
| |
| /** |
| * Output help information and exit. |
| * |
| * Outputs built-in help, and custom text added using `.addHelpText()`. |
| */ |
| help(context?: HelpContext): never; |
| /** @deprecated since v7 */ |
| help(cb?: (str: string) => string): never; |
| |
| /** |
| * Add additional text to be displayed with the built-in help. |
| * |
| * Position is 'before' or 'after' to affect just this command, |
| * and 'beforeAll' or 'afterAll' to affect this command and all its subcommands. |
| */ |
| addHelpText(position: AddHelpTextPosition, text: string): this; |
| addHelpText(position: AddHelpTextPosition, text: (context: AddHelpTextContext) => string | undefined): this; |
| |
| /** |
| * Add a listener (callback) for when events occur. (Implemented using EventEmitter.) |
| */ |
| on(event: string | symbol, listener: (...args: any[]) => void): this; |
| } |
| type CommandConstructor = new (name?: string) => Command; |
| |
| interface CommandOptions { |
| hidden?: boolean; |
| isDefault?: boolean; |
| /** @deprecated since v7, replaced by hidden */ |
| noHelp?: boolean; |
| } |
| interface ExecutableCommandOptions extends CommandOptions { |
| executableFile?: string; |
| } |
| |
| // eslint-disable-next-line @typescript-eslint/no-unused-vars |
| interface ParseOptionsResult { |
| operands: string[]; |
| unknown: string[]; |
| } |
| |
| // eslint-disable-next-line @typescript-eslint/no-unused-vars |
| interface CommanderStatic extends Command { |
| program: Command; |
| Command: CommandConstructor; |
| Option: OptionConstructor; |
| CommanderError: CommanderErrorConstructor; |
| InvalidOptionArgumentError: InvalidOptionArgumentErrorConstructor; |
| Help: HelpConstructor; |
| } |
| |
| } |
| |
| // Declaring namespace AND global |
| // eslint-disable-next-line @typescript-eslint/no-redeclare |
| declare const commander: commander.CommanderStatic; |
| export = commander; |