lib/src/cli/Directive.ts

490 lines
16 KiB
TypeScript
Raw Normal View History

2021-06-03 03:36:25 +00:00
import {Injectable, Inject} from '../di'
import {infer, ErrorWithContext} from '../util'
import {CLIOption} from './directive/options/CLIOption'
import {PositionalOption} from './directive/options/PositionalOption'
import {FlagOption} from './directive/options/FlagOption'
import {AppClass} from '../lifecycle/AppClass'
import {Logging} from '../service/Logging'
2021-06-02 01:59:40 +00:00
/**
* Type alias for a definition of a command-line option.
*
* This can be either an instance of CLIOption or a string describing an option.
*
* @example
* Some examples of positional/flag options defined by strings:
* `'{file name} | canonical name of the resource to create'`
*
* `'--push -p {value} | the value to be pushed'`
*
* `'--force -f | do a force push'`
*/
export type OptionDefinition = CLIOption<any> | string
/**
* An error thrown when an invalid option was detected.
*/
export class OptionValidationError extends ErrorWithContext {}
/**
* A base class representing a sub-command in the command-line utility.
*/
@Injectable()
export abstract class Directive extends AppClass {
@Inject()
protected readonly logging!: Logging
/** Parsed option values. */
2021-06-03 03:36:25 +00:00
private optionValues: any
2021-06-02 01:59:40 +00:00
/**
* Get the keyword or array of keywords that will specify this directive.
*
* @example
* If this returns `['up', 'start']`, the directive can be run by either of:
*
* ```shell
* ./ex up
* ./ex start
* ```
*/
public abstract getKeywords(): string | string[]
/**
* Get the usage description of this directive. Should be brief (1 sentence).
*/
public abstract getDescription(): string
/**
* Optionally, specify a longer usage text that is shown on the directive's `--help` page.
*/
public getHelpText(): string {
return ''
}
/**
* Get an array of options defined for this command.
*/
public getOptions(): OptionDefinition[] {
return []
}
/**
* Called when the directive is run from the command line.
*
* The raw arguments are provided as `argv`, but you are encouraged to use
* `getOptions()` and `option()` helpers to access the parsed options instead.
*
* @param argv
*/
public abstract handle(argv: string[]): void | Promise<void>
/**
* Sets the parsed option values.
* @param optionValues
* @private
*/
2021-06-03 03:36:25 +00:00
private setOptionValues(optionValues: any) {
this.optionValues = optionValues
2021-06-02 01:59:40 +00:00
}
/**
* Get the value of a parsed option. If none exists, return `defaultValue`.
* @param name
* @param defaultValue
*/
2021-06-03 03:36:25 +00:00
public option(name: string, defaultValue?: unknown): any {
if ( name in this.optionValues ) {
return this.optionValues[name]
2021-06-02 01:59:40 +00:00
}
return defaultValue
}
/**
* Invoke this directive with the specified arguments.
*
* If usage was requested (see `didRequestUsage()`), it prints the extended usage info.
*
* Otherwise, it parses the options from `argv` and calls `handle()`.
*
* @param argv
*/
2021-06-03 03:36:25 +00:00
async invoke(argv: string[]): Promise<void> {
2021-06-02 01:59:40 +00:00
const options = this.getResolvedOptions()
if ( this.didRequestUsage(argv) ) {
2021-06-03 03:36:25 +00:00
const positionalArguments: PositionalOption<any>[] = []
options.forEach(opt => {
if ( opt instanceof PositionalOption ) {
positionalArguments.push(opt)
}
})
2021-06-02 01:59:40 +00:00
2021-06-03 03:36:25 +00:00
const flagArguments: FlagOption<any>[] = []
options.forEach(opt => {
if ( opt instanceof FlagOption ) {
flagArguments.push(opt)
}
})
2021-06-02 01:59:40 +00:00
const positionalDisplay: string = positionalArguments.map(x => `<${x.getArgumentName()}>`).join(' ')
const flagDisplay: string = flagArguments.length ? ' [...flags]' : ''
2021-06-03 03:36:25 +00:00
this.nativeOutput([
2021-06-02 01:59:40 +00:00
'',
`DIRECTIVE: ${this.getMainKeyword()} - ${this.getDescription()}`,
'',
`USAGE: ${this.getMainKeyword()} ${positionalDisplay}${flagDisplay}`,
].join('\n'))
if ( positionalArguments.length ) {
2021-06-03 03:36:25 +00:00
this.nativeOutput([
2021-06-02 01:59:40 +00:00
'',
`POSITIONAL ARGUMENTS:`,
...(positionalArguments.map(arg => {
return ` ${arg.getArgumentName()}${arg.message ? ' - ' + arg.message : ''}`
})),
].join('\n'))
}
if ( flagArguments.length ) {
2021-06-03 03:36:25 +00:00
this.nativeOutput([
2021-06-02 01:59:40 +00:00
'',
`FLAGS:`,
...(flagArguments.map(arg => {
return ` ${arg.shortFlag ? arg.shortFlag + ', ' : ''}${arg.longFlag}${arg.argumentDescription ? ' {' + arg.argumentDescription + '}' : ''}${arg.message ? ' - ' + arg.message : ''}`
})),
].join('\n'))
}
const help = this.getHelpText()
if ( help ) {
2021-06-03 03:36:25 +00:00
this.nativeOutput('\n' + help)
2021-06-02 01:59:40 +00:00
}
2021-06-03 03:36:25 +00:00
this.nativeOutput('\n')
2021-06-02 01:59:40 +00:00
} else {
try {
const optionValues = this.parseOptions(options, argv)
2021-06-03 03:36:25 +00:00
this.setOptionValues(optionValues)
2021-06-02 01:59:40 +00:00
await this.handle(argv)
2021-10-18 18:03:28 +00:00
} catch (e: unknown) {
if ( e instanceof Error ) {
this.nativeOutput(e.message)
this.error(e)
2021-10-18 18:03:28 +00:00
}
2021-06-02 01:59:40 +00:00
if ( e instanceof OptionValidationError ) {
// expecting, value, requirements
if ( e.context.expecting ) {
2021-06-03 03:36:25 +00:00
this.nativeOutput(` - Expecting: ${e.context.expecting}`)
2021-06-02 01:59:40 +00:00
}
if ( e.context.requirements && Array.isArray(e.context.requirements) ) {
for ( const req of e.context.requirements ) {
2021-06-03 03:36:25 +00:00
this.nativeOutput(` - ${req}`)
2021-06-02 01:59:40 +00:00
}
}
if ( e.context.value ) {
2021-06-03 03:36:25 +00:00
this.nativeOutput(` - ${e.context.value}`)
2021-06-02 01:59:40 +00:00
}
}
2021-10-18 18:03:28 +00:00
2021-06-03 03:36:25 +00:00
this.nativeOutput('\nUse --help for more info.')
2021-06-02 01:59:40 +00:00
}
}
}
/**
* Resolve the array of option definitions to CLIOption instances.
* Of note, this resolves the string-form definitions to actual CLIOption instances.
*/
public getResolvedOptions(): CLIOption<any>[] {
return this.getOptions().map(option => {
if ( typeof option === 'string' ) {
return this.instantiateOptionFromString(option)
} else {
return option
}
})
}
/**
* Get the main keyword displayed for this directive.
* @example
* If `getKeywords()` returns `['up', 'start']`, this will return `'up'`.
*/
public getMainKeyword(): string {
const kws = this.getKeywords()
if ( Array.isArray(kws) ) {
return kws[0]
}
return kws
}
/**
* Returns true if the given keyword should invoke this directive.
* @param name
*/
2021-06-03 03:36:25 +00:00
public matchesKeyword(name: string): boolean {
2021-06-02 01:59:40 +00:00
let kws = this.getKeywords()
2021-06-03 03:36:25 +00:00
if ( !Array.isArray(kws) ) {
kws = [kws]
}
2021-06-02 01:59:40 +00:00
return kws.includes(name)
}
/**
* Print the given output to the log as success text.
* @param output
*/
2021-06-03 03:36:25 +00:00
success(output: unknown): void {
2021-06-02 01:59:40 +00:00
this.logging.success(output, true)
}
/**
* Print the given output to the log as error text.
* @param output
*/
2021-06-03 03:36:25 +00:00
error(output: unknown): void {
2021-06-02 01:59:40 +00:00
this.logging.error(output, true)
}
/**
* Print the given output to the log as warning text.
* @param output
*/
2021-06-03 03:36:25 +00:00
warn(output: unknown): void {
2021-06-02 01:59:40 +00:00
this.logging.warn(output, true)
}
/**
* Print the given output to the log as info text.
* @param output
*/
2021-06-03 03:36:25 +00:00
info(output: unknown): void {
2021-06-02 01:59:40 +00:00
this.logging.info(output, true)
}
/**
* Print the given output to the log as debugging text.
* @param output
*/
2021-06-03 03:36:25 +00:00
debug(output: unknown): void {
2021-06-02 01:59:40 +00:00
this.logging.debug(output, true)
}
/**
* Print the given output to the log as verbose text.
* @param output
*/
2021-06-03 03:36:25 +00:00
verbose(output: unknown): void {
2021-06-02 01:59:40 +00:00
this.logging.verbose(output, true)
}
/**
* Get the flag option that signals help. Usually, this is named 'help'
* and supports the flags '--help' and '-?'.
*/
2021-06-03 03:36:25 +00:00
getHelpOption(): FlagOption<any> {
2021-06-02 01:59:40 +00:00
return new FlagOption('--help', '-?', 'usage information about this directive')
}
/**
* Process the raw CLI arguments using an array of option class instances to build
* a mapping of option names to provided values.
*/
2021-06-03 03:36:25 +00:00
parseOptions(options: CLIOption<any>[], args: string[]): {[key: string]: any} {
let positionalArguments: PositionalOption<any>[] = []
options.forEach(opt => {
if ( opt instanceof PositionalOption ) {
positionalArguments.push(opt)
}
})
const flagArguments: FlagOption<any>[] = []
options.forEach(opt => {
if ( opt instanceof FlagOption ) {
flagArguments.push(opt)
}
})
2021-06-02 01:59:40 +00:00
const optionValue: any = {}
flagArguments.push(this.getHelpOption())
let expectingFlagArgument = false
let positionalFlagName = ''
for ( const value of args ) {
if ( value.startsWith('--') ) {
if ( expectingFlagArgument ) {
throw new OptionValidationError(`Unexpected flag argument. Expecting argument for flag: ${positionalFlagName}`, {
expecting: positionalFlagName,
})
} else {
const flagArgument = flagArguments.filter(x => x.longFlag === value)
if ( flagArgument.length < 1 ) {
throw new OptionValidationError(`Unknown flag argument: ${value}`, {
value,
})
} else {
if ( flagArgument[0].argumentDescription ) {
positionalFlagName = flagArgument[0].getArgumentName()
expectingFlagArgument = true
} else {
optionValue[flagArgument[0].getArgumentName()] = true
}
}
}
} else if ( value.startsWith('-') ) {
if ( expectingFlagArgument ) {
throw new OptionValidationError(`Unknown flag argument: ${value}`, {
expecting: positionalFlagName,
})
} else {
const flagArgument = flagArguments.filter(x => x.shortFlag === value)
if ( flagArgument.length < 1 ) {
throw new OptionValidationError(`Unknown flag argument: ${value}`, {
2021-06-03 03:36:25 +00:00
value,
2021-06-02 01:59:40 +00:00
})
} else {
if ( flagArgument[0].argumentDescription ) {
positionalFlagName = flagArgument[0].getArgumentName()
expectingFlagArgument = true
} else {
optionValue[flagArgument[0].getArgumentName()] = true
}
}
}
} else if ( expectingFlagArgument ) {
const inferredValue = infer(value)
const optionInstance = flagArguments.filter(x => x.getArgumentName() === positionalFlagName)[0]
if ( !optionInstance.validate(inferredValue) ) {
throw new OptionValidationError(`Invalid value for argument: ${positionalFlagName}`, {
requirements: optionInstance.getRequirementDisplays(),
})
}
optionValue[positionalFlagName] = inferredValue
expectingFlagArgument = false
} else {
if ( positionalArguments.length < 1 ) {
throw new OptionValidationError(`Unknown positional argument: ${value}`, {
2021-06-03 03:36:25 +00:00
value,
2021-06-02 01:59:40 +00:00
})
} else {
const inferredValue = infer(value)
if ( !positionalArguments[0].validate(inferredValue) ) {
throw new OptionValidationError(`Invalid value for argument: ${positionalArguments[0].getArgumentName()}`, {
requirements: positionalArguments[0].getRequirementDisplays(),
})
}
optionValue[positionalArguments[0].getArgumentName()] = infer(value)
positionalArguments = positionalArguments.slice(1)
}
}
}
if ( expectingFlagArgument ) {
throw new OptionValidationError(`Missing argument for flag: ${positionalFlagName}`, {
2021-06-03 03:36:25 +00:00
expecting: positionalFlagName,
2021-06-02 01:59:40 +00:00
})
}
if ( positionalArguments.length > 0 ) {
throw new OptionValidationError(`Missing required argument: ${positionalArguments[0].getArgumentName()}`, {
2021-06-03 03:36:25 +00:00
expecting: positionalArguments[0].getArgumentName(),
2021-06-02 01:59:40 +00:00
})
}
return optionValue
}
/**
* Create an instance of CLIOption based on a string definition of a particular format.
*
* e.g. '{file name} | canonical name of the resource to create'
* e.g. '--push -p {value} | the value to be pushed'
* e.g. '--force -f | do a force push'
*
* @param string
*/
protected instantiateOptionFromString(string: string): CLIOption<any> {
if ( string.startsWith('{') ) {
// The string is a positional argument
const stringParts = string.split('|').map(x => x.trim())
const name = stringParts[0].replace(/\{|\}/g, '')
return stringParts.length > 1 ? (new PositionalOption(name, stringParts[1])) : (new PositionalOption(name))
} else {
// The string is a flag argument
const stringParts = string.split('|').map(x => x.trim())
// Parse the flag parts first
const hasArgument = stringParts[0].indexOf('{') >= 0
const flagString = hasArgument ? stringParts[0].substr(0, stringParts[0].indexOf('{')).trim() : stringParts[0].trim()
const flagParts = flagString.split(' ')
let longFlag = flagParts[0].startsWith('--') ? flagParts[0] : undefined
if ( !longFlag && flagParts.length > 1 ) {
if ( flagParts[1].startsWith('--') ) {
longFlag = flagParts[1]
}
}
let shortFlag = flagParts[0].length === 2 ? flagParts[0] : undefined
if ( !shortFlag && flagParts.length > 1 ) {
if ( flagParts[1].length === 2 ) {
shortFlag = flagParts[1]
}
}
const argumentDescription = hasArgument ? stringParts[0].substring(stringParts[0].indexOf('{')+1, stringParts[0].indexOf('}')) : undefined
const description = stringParts.length > 1 ? stringParts[1] : undefined
return new FlagOption(longFlag, shortFlag, description, argumentDescription)
}
}
/**
* Determines if, at any point in the arguments, the help option's short or long flag appears.
* @returns {boolean} - true if the help flag appeared
*/
2021-06-03 03:36:25 +00:00
didRequestUsage(argv: string[]): boolean {
const helpOption = this.getHelpOption()
2021-06-02 01:59:40 +00:00
for ( const arg of argv ) {
2021-06-03 03:36:25 +00:00
if ( arg.trim() === helpOption.longFlag || arg.trim() === helpOption.shortFlag ) {
2021-06-02 01:59:40 +00:00
return true
}
}
return false
}
2021-06-03 03:36:25 +00:00
protected nativeOutput(...outputs: any[]): void {
console.log(...outputs) // eslint-disable-line no-console
}
/**
* Get a promise that resolves after SIGINT is received, executing a
* callback beforehand.
* @param callback
* @protected
*/
protected async untilInterrupt(callback?: () => unknown): Promise<void> {
return new Promise<void>(res => {
process.on('SIGINT', async () => {
if ( callback ) {
await callback()
}
res()
})
})
}
2021-06-02 01:59:40 +00:00
}