cliffy.Command | /deps.ts | alloy_folk@v1.1.1

class cliffy.Command

Re-export

import { cliffy } from "https://deno.land/x/alloy_folk@v1.1.1/deps.ts";
const { Command } = cliffy;

Type Parameters

optional

CPG extends Record<string, any> | void = void

optional

CPT extends Record<string, any> | void = CPG extends number ? any : void

optional

CO extends Record<string, any> | void = CPG extends number ? any : void

optional

CA extends Array<unknown> = CPG extends number ? any : []

optional

CG extends Record<string, any> | void = CPG extends number ? any : void

optional

CT extends Record<string, any> | void = CPG extends number ? any : { number: number; integer: number; string: string; boolean: boolean; file: string; }

optional

CGT extends Record<string, any> | void = CPG extends number ? any : void

optional

CP extends Command<any> | undefined = CPG extends number ? any : undefined

Properties

private

_allowEmpty: boolean

private

optional

_globalParent: Command<any>

private

optional

_groupName: string

private

optional

_help: IHelpHandler

private

optional

_helpOption: IDefaultOption | false

private

_meta: Record<string, string>

private

_name: string

private

optional

_parent: CP

private

optional

_shouldExit: boolean

private

_stopEarly: boolean

private

optional

_usage: string

private

_useRawArgs: boolean

private

optional

_versionOption: IDefaultOption | false

private

aliases: Array<string>

private

args: Array<IArgument>

private

optional

argsDefinition: string

private

cmd: Command<any>

private

commands: Map<string, Command<any>>

private

completions: Map<string, ICompletion>

private

optional

defaultCommand: string

private

desc: IDescription

private

envVars: Array<IEnvVar>

private

examples: Array<IExample>

private

optional

fn: IAction

private

hasDefaults: boolean

private

isExecutable: boolean

private

isGlobal: boolean

private

isHidden: boolean

private

literalArgs: Array<string>

private

options: Array<IOption>

private

rawArgs: Array<string>

private

throwOnError: boolean

private

types: Map<string, IType>

private

optional

ver: IVersionHandler

Methods

private

exit(code?)

private

getHelpHandler(): IHelpHandler

Get help handler method.

private

getVersionHandler(): IVersionHandler | undefined

Get help handler method.

private

registerDefaults(): this

protected

error(error: Error): Error

Handle error. If throwErrors is enabled the error will be returned, otherwise a formatted error message will be printed and Deno.exit(1) will be called.

protected

execute(options: Record<string, unknown>, ...args: Array<unknown>): Promise<IParseResult>

Execute command.

protected

executeExecutable(args: string[])

Execute external sub-command.

protected

parseArguments(args: string[], flags: Record<string, unknown>): CA

Parse command-line arguments.

protected

parseEnvVars(): Promise<Record<string, unknown>>

Validate environment variables.

protected

parseFlags(args: string[], env: Record<string, unknown>): IFlagsResult & { actionOption?: IOption & { action: IAction; }; }

Parse raw command line arguments.

protected

parseType(type: ITypeInfo): unknown

Parse argument type.

protected

shouldExit(): boolean

Check whether the command should exit after printing help or version.

protected

shouldThrowErrors(): boolean

Check whether the command should throw errors or exit.

action(fn: IAction<CO, CA, CG, CPG, CT, CGT, CPT, CP>): this

Set command callback method.

alias(alias: string): this

Add new command alias.

allowEmpty(allowEmpty?): this

Don't throw an error if the command was called without arguments.

arguments<A extends TypedArguments<N, Merge<CPT, Merge<CGT, CT>>>, N extends string = string>(args: N): Command<CPG, CPT, CO, A, CG, CT, CGT, CP>

Set command arguments:

requiredArg:string [optionalArg: number] [...restArgs:string]

checkVersion(): Promise<void>

Check if new version is available and add hint to version.

cmd: C,

override?: boolean,

): C extends Command<any, any, infer Options, infer Arguments, infer GlobalOptions, infer Types, infer GlobalTypes, any> ? Command<G, T, Options, Arguments, GlobalOptions, Types, GlobalTypes, OneOf<CP, this>> : never

Add new sub-command.

command<N extends string, A extends TypedCommandArguments<N, CP extends Command<any> ? CPT : Merge<CPT, CGT>>>(

desc?: string,

override?: boolean,

): CPG extends number ? Command<any> : Command<CP extends Command<any> ? CPG : Merge<CPG, CG>, CP extends Command<any> ? CPT : Merge<CPT, CGT>, void, A, void, void, void, OneOf<CP, this>>

Add new sub-command.

complete(

complete: ICompleteHandler<Partial<CO>, Partial<CA>, CG, CPG, CT, CGT, CPT, any>,

options: ICompleteOptions & { global: boolean; },

): this

complete(

complete: ICompleteHandler<CO, CA, CG, CPG, CT, CGT, CPT, CP>,

options?: ICompleteOptions,

): this

default(name: string): this

Set default command. The default command is executed when the program was called without any argument and if no action handler is registered.

description(description: IDescription<CO, CA, CG, CPG, CT, CGT, CPT, CP>): this

Set the long command description.

env<N extends string, G extends TypedEnv<N, P, CO, Merge<CPT, Merge<CGT, CT>>, R>, MG extends MapValue<G, V>, R extends IEnvVarOptions["required"] = undefined, P extends IEnvVarOptions["prefix"] = undefined, V = undefined>(

description: string,

options: Omit<IEnvVarOptions, "value"> & { global: true; required?: R; prefix?: P; value?: IEnvVarValueHandler<MapTypes<ValueOf<G>>, V>; },

): Command<CPG, CPT, CO, CA, Merge<CG, MG>, CT, CGT, CP>

Add new environment variable.

env<N extends string, O extends TypedEnv<N, P, CO, Merge<CPT, Merge<CGT, CT>>, R>, MO extends MapValue<O, V>, R extends IEnvVarOptions["required"] = undefined, P extends IEnvVarOptions["prefix"] = undefined, V = undefined>(

description: string,

options?: Omit<IEnvVarOptions, "value"> & { required?: R; prefix?: P; value?: IEnvVarValueHandler<MapTypes<ValueOf<O>>, V>; },

): Command<CPG, CPT, Merge<CO, MO>, CA, CG, CT, CGT, CP>

example(name: string, description: string): this

Add new command example.

executable(): this

Make command executable.

getAliases(): string[]

Get command name aliases.

getArgsDefinition(): string | undefined

Get arguments definition. E.g: input-file:string output-file:string

getArgument(name: string): IArgument | undefined

Get argument by name.

getArguments(): IArgument[]

Get arguments.

getBaseCommand<C extends Command<any>>(name: string, hidden?: boolean): C | undefined

Get base command by name or alias.

getBaseCommands(hidden?: boolean): Array<Command<any>>

Get base commands.

getBaseCompletion(name: string): ICompletion | undefined

Get base completion by name.

getBaseCompletions(): ICompletion[]

Get base completions.

getBaseEnvVar(name: string, hidden?: boolean): IEnvVar | undefined

Get base environment variable by name.

getBaseEnvVars(hidden?: boolean): IEnvVar[]

Get base environment variables.

getBaseOption(name: string, hidden?: boolean): IOption | undefined

Get base option by name.

getBaseOptions(hidden?: boolean): IOption[]

Get base options.

getBaseType(name: string): IType | undefined

Get base type by name.

getBaseTypes(): IType[]

Get base types.

getCommand<C extends Command<any>>(name: string, hidden?: boolean): C | undefined

Get command by name or alias.

getCommands(hidden?: boolean): Array<Command<any>>

Get commands.

getCompletion(name: string): ICompletion | undefined

Get completion by name.

getCompletions()

Get completions.

getDescription(): string

Get command description.

getEnvVar(name: string, hidden?: boolean): IEnvVar | undefined

Get environment variable by name.

getEnvVars(hidden?: boolean): IEnvVar[]

Get environment variables.

getExample(name: string): IExample | undefined

Get example with given name.

getExamples(): IExample[]

Get all examples.

getGlobalCommand<C extends Command<any>>(name: string, hidden?: boolean): C | undefined

Get global command by name or alias.

getGlobalCommands(hidden?: boolean): Array<Command<any>>

Get global commands.

getGlobalCompletion(name: string): ICompletion | undefined

Get global completions by name.

getGlobalCompletions(): ICompletion[]

Get global completions.

getGlobalEnvVar(name: string, hidden?: boolean): IEnvVar | undefined

Get global environment variable by name.

getGlobalEnvVars(hidden?: boolean): IEnvVar[]

Get global environment variables.

getGlobalOption(name: string, hidden?: boolean): IOption | undefined

Get global option from parent command's by name.

getGlobalOptions(hidden?: boolean): IOption[]

Get global options.

getGlobalParent(): Command<any> | undefined

Get parent command from global executed command. Be sure, to call this method only inside an action handler. Unless this or any child command was executed, this method returns always undefined.

getGlobalType(name: string): IType | undefined

Get global type by name.

getGlobalTypes(): IType[]

Get global types.

getHelp(options?: HelpOptions): string

Get generated help.

getLiteralArgs(): string[]

Get all arguments defined after the double dash.

getLongVersion(): string

Returns command name, version and meta data.

getMainCommand(): Command<any>

Get main command.

getMeta(): Record<string, string>

getMeta(name: string): string

getName(): string

Get command name.

getOption(name: string, hidden?: boolean): IOption | undefined

Get option by name.

getOptions(hidden?: boolean): IOption[]

Get options.

getParent(): CP

Get parent command.

getPath(): string

Get full command path.

getRawArgs(): string[]

Get original command-line arguments.

getShortDescription(): string

Get short command description. This is the first line of the description.

getType(name: string): IType | undefined

Get type by name.

getTypes(): IType[]

Get types.

getUsage()

getVersion(): string | undefined

Get command version.

global(): this

Make command globally available.

globalComplete(

complete: ICompleteHandler,

options?: Omit<ICompleteOptions, "global">,

): this

globalEnv<N extends string, G extends TypedEnv<N, P, CO, Merge<CPT, Merge<CGT, CT>>, R>, MG extends MapValue<G, V>, R extends IEnvVarOptions["required"] = undefined, P extends IEnvVarOptions["prefix"] = undefined, V = undefined>(

description: string,

options?: Omit<IGlobalEnvVarOptions, "value"> & { required?: R; prefix?: P; value?: IEnvVarValueHandler<MapTypes<ValueOf<G>>, V>; },

): Command<CPG, CPT, CO, CA, Merge<CG, MG>, CT, CGT, CP>

globalOption<F extends string, G extends TypedOption<F, CO, Merge<CPT, Merge<CGT, CT>>, R, D>, MG extends MapValue<G, V, C>, R extends ICommandOption["required"] = undefined, C extends ICommandOption["collect"] = undefined, D = undefined, V = undefined>(

flags: F,

desc: string,

opts?: Omit<ICommandGlobalOption<Partial<CO>, CA, MergeOptions<F, CG, G>, CPG, CT, CGT, CPT, CP>, "value"> & { default?: IDefaultValue<D>; required?: R; collect?: C; value?: IFlagValueHandler<MapTypes<ValueOf<G>>, V>; } | IFlagValueHandler<MapTypes<ValueOf<G>>, V>,

): Command<CPG, CPT, CO, CA, MergeOptions<F, CG, MG>, CT, CGT, CP>

globalType<H extends TypeOrTypeHandler<unknown>, N extends string = string>(

handler: H,

options?: Omit<ITypeOptions, "global">,

): Command<CPG, CPT, CO, CA, CG, CT, Merge<CGT, TypedType<N, H>>, CP>

group(name: string): this

Enable grouping of options and set the name of the group. All option which are added after calling the .group() method will be grouped in the help output. If the .group() method can be use multiple times to create more groups.

hasArguments()

Check if command has arguments.

hasCommand(name: string, hidden?: boolean): boolean

Checks whether a child command exists by given name or alias.

hasCommands(hidden?: boolean): boolean

Checks whether the command has sub-commands or not.

hasEnvVar(name: string, hidden?: boolean): boolean

Checks whether the command has an environment variable with given name or not.

hasEnvVars(hidden?: boolean): boolean

Checks whether the command has environment variables or not.

hasExample(name: string): boolean

Checks whether the command has an example with given name or not.

hasExamples(): boolean

Checks whether the command has examples or not.

hasOption(name: string, hidden?: boolean): boolean

Checks whether the command has an option with given name or not.

hasOptions(hidden?: boolean): boolean

Checks whether the command has options or not.

help(help: string | IHelpHandler<Partial<CO>, Partial<CA>, CG, CPG> | HelpOptions): this

Set command help.

helpOption(enable: false): this

Disable help option.

helpOption(

flags: string,

desc?: string,

opts?: ICommandOption<Partial<CO>, CA, CG, CPG, CT, CGT, CPT, CP> & { global: true; },

): this

Set global help option.

helpOption(

flags: string,

desc?: string,

opts?: ICommandOption<CO, CA, CG, CPG, CT, CGT, CPT, CP>,

): this

Set help option.

helpOption(

flags: string,

desc?: string,

opts?: IAction<CO, CA, CG, CPG, CT, CGT, CPT, CP>,

): this

Set help option.

hidden(): this

Hide command from help, completions, etc.

meta(name: string, value: string): this

name(name: string): this

Set command name.

noExit(): this

Same as .throwErrors() but also prevents calling Deno.exit after printing help or version with the --help and --version option.

option<F extends string, G extends TypedOption<F, CO, Merge<CPT, Merge<CGT, CT>>, R, D>, MG extends MapValue<G, V, C>, R extends ICommandOption["required"] = undefined, C extends ICommandOption["collect"] = undefined, D = undefined, V = undefined>(

flags: F,

desc: string,

opts: Omit<ICommandOption<Partial<CO>, CA, MergeOptions<F, CG, G>, CPG, CT, CGT, CPT, CP>, "value"> & { global: true; default?: IDefaultValue<D>; required?: R; collect?: C; value?: IFlagValueHandler<MapTypes<ValueOf<G>>, V>; } | IFlagValueHandler<MapTypes<ValueOf<G>>, V>,

): Command<CPG, CPT, CO, CA, MergeOptions<F, CG, MG>, CT, CGT, CP>

Add a new option.

option<F extends string, O extends TypedOption<F, CO, Merge<CPT, Merge<CGT, CT>>, R, D>, MO extends MapValue<O, V, C>, R extends ICommandOption["required"] = undefined, C extends ICommandOption["collect"] = undefined, D = undefined, V = undefined>(

flags: F,

desc: string,

opts?: Omit<ICommandOption<MergeOptions<F, CO, O>, CA, CG, CPG, CT, CGT, CPT, CP>, "value"> & { default?: IDefaultValue<D>; required?: R; collect?: C; value?: IFlagValueHandler<MapTypes<ValueOf<O>>, V>; } | IFlagValueHandler<MapTypes<ValueOf<O>>, V>,

): Command<CPG, CPT, MergeOptions<F, CO, MO>, CA, CG, CT, CGT, CP>

parse(args?: string[]): Promise<CP extends Command<any> ? IParseResult<Record<string, unknown>, Array<unknown>, Record<string, unknown>, Record<string, unknown>, Record<string, unknown>, Record<string, unknown>, Record<string, unknown>, undefined> : IParseResult<MapTypes<CO>, MapTypes<CA>, MapTypes<CG>, MapTypes<CPG>, CT, CGT, CPT, CP>>

Parse command line arguments and execute matched command.

removeCommand(name: string): Command<any> | undefined

Remove sub-command by name or alias.

removeOption(name: string): IOption | undefined

Remove option by name.

reset(): OneOf<CP, this>

Reset internal command reference to main command.

select<O extends Record<string, unknown> | void = any, A extends Array<unknown> = any, G extends Record<string, unknown> | void = any>(name: string): Command<CPG, CPT, O, A, G, CT, CGT, CP>

Set internal command pointer to child command with given name.

showHelp(options?: HelpOptions): void

Output generated help without exiting.

showLongVersion(): void

Outputs command name, version and meta data.

showVersion(): void

Output generated help without exiting.

stopEarly(stopEarly?): this

Enable stop early. If enabled, all arguments starting from the first non option argument will be passed as arguments with type string to the command action handler.

For example: command --debug-level warning server --port 80

Will result in: - options: {debugLevel: 'warning'} - args: ['server', '--port', '80']

throwErrors(): this

Throw validation error's instead of calling Deno.exit() to handle validation error's manually.

A validation error is thrown when the command is wrongly used by the user. For example: If the user passes some invalid options or arguments to the command.

This has no effect for parent commands. Only for the command on which this method was called and all child commands.

Example:

try {
  cmd.parse();
} catch(error) {
  if (error instanceof ValidationError) {
    cmd.showHelp();
    Deno.exit(1);
  }
  throw error;
}

type<H extends TypeOrTypeHandler<unknown>, N extends string = string>(

handler: H,

options?: ITypeOptions,

): Command<CPG, CPT, CO, CA, CG, Merge<CT, TypedType<N, H>>, CGT, CP>

usage(usage: string): this

Set the command usage. Defaults to arguments.

useRawArgs(useRawArgs?): Command<void, void, void, Array<string>, void, void, void, CP>

Disable parsing arguments. If enabled the raw arguments will be passed to the action handler. This has no effect for parent or child commands. Only for the command on which this method was called.