Popular
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306import {CommandInstance, isCommandBuilderCallback} from './command.js';import {PlatformShim, assertNotStrictEqual} from './typings/common-types.js';import * as templates from './completion-templates.js';import {isPromise} from './utils/is-promise.js';import {parseCommand} from './parse-command.js';import {UsageInstance} from './usage.js';import {YargsInstance} from './yargs-factory.js';import {Arguments, DetailedArguments} from './typings/yargs-parser-types.js';
// add bash completions to your// yargs-powered applications.
type CompletionCallback = ( err: Error | null, completions: string[] | undefined) => void;
/** Instance of the completion module. */export interface CompletionInstance { completionKey: string; generateCompletionScript($0: string, cmd: string): string; getCompletion( args: string[], done: (err: Error | null, completions: string[] | undefined) => void ): any; registerFunction(fn: CompletionFunction): void; setParsed(parsed: DetailedArguments): void;}
export class Completion implements CompletionInstance { completionKey = 'get-yargs-completions';
private aliases: DetailedArguments['aliases'] | null = null; private customCompletionFunction: CompletionFunction | null = null; private readonly zshShell: boolean;
constructor( private readonly yargs: YargsInstance, private readonly usage: UsageInstance, private readonly command: CommandInstance, private readonly shim: PlatformShim ) { this.zshShell = (this.shim.getEnv('SHELL')?.includes('zsh') || this.shim.getEnv('ZSH_NAME')?.includes('zsh')) ?? false; }
private defaultCompletion( args: string[], argv: Arguments, current: string, done: CompletionCallback ): Arguments | void { const handlers = this.command.getCommandHandlers(); for (let i = 0, ii = args.length; i < ii; ++i) { if (handlers[args[i]] && handlers[args[i]].builder) { const builder = handlers[args[i]].builder; if (isCommandBuilderCallback(builder)) { const y = this.yargs.getInternalMethods().reset(); builder(y, true); return y.argv; } } }
const completions: string[] = [];
this.commandCompletions(completions, args, current); this.optionCompletions(completions, args, argv, current); done(null, completions); }
// Default completions for commands private commandCompletions( completions: string[], args: string[], current: string ) { const parentCommands = this.yargs.getInternalMethods().getContext() .commands; if ( !current.match(/^-/) && parentCommands[parentCommands.length - 1] !== current ) { this.usage.getCommands().forEach(usageCommand => { const commandName = parseCommand(usageCommand[0]).cmd; if (args.indexOf(commandName) === -1) { if (!this.zshShell) { completions.push(commandName); } else { const desc = usageCommand[1] || ''; completions.push(commandName.replace(/:/g, '\\:') + ':' + desc); } } }); } }
// Default completions for - and -- options private optionCompletions( completions: string[], args: string[], argv: Arguments, current: string ) { if (current.match(/^-/) || (current === '' && completions.length === 0)) { const options = this.yargs.getOptions(); const positionalKeys = this.yargs.getGroups()[this.usage.getPositionalGroupName()] || [];
Object.keys(options.key).forEach(key => { const negable = !!options.configuration['boolean-negation'] && options.boolean.includes(key); const isPositionalKey = positionalKeys.includes(key);
// If the key is not positional and its aliases aren't in 'args', add the key to 'completions' if ( !isPositionalKey && !this.argsContainKey(args, argv, key, negable) ) { this.completeOptionKey(key, completions, current); if (negable && !!options.default[key]) this.completeOptionKey(`no-${key}`, completions, current); } }); } }
private argsContainKey( args: string[], argv: Arguments, key: string, negable: boolean ): boolean { if (args.indexOf(`--${key}`) !== -1) return true; if (negable && args.indexOf(`--no-${key}`) !== -1) return true; if (this.aliases) { // search for aliases in parsed argv // can't do the same thing for main option names because argv can contain default values for (const alias of this.aliases[key]) { if (argv[alias] !== undefined) return true; } } return false; }
// Add completion for a single - or -- option private completeOptionKey( key: string, completions: string[], current: string ) { const descs = this.usage.getDescriptions(); const startsByTwoDashes = (s: string) => /^--/.test(s); const isShortOption = (s: string) => /^[^0-9]$/.test(s); const dashes = !startsByTwoDashes(current) && isShortOption(key) ? '-' : '--'; if (!this.zshShell) { completions.push(dashes + key); } else { const desc = descs[key] || ''; completions.push( dashes + `${key.replace(/:/g, '\\:')}:${desc.replace('__yargsString__:', '')}` ); } }
// a custom completion function can be provided // to completion(). private customCompletion( args: string[], argv: Arguments, current: string, done: CompletionCallback ) { assertNotStrictEqual(this.customCompletionFunction, null, this.shim);
if (isSyncCompletionFunction(this.customCompletionFunction)) { const result = this.customCompletionFunction(current, argv);
// promise based completion function. if (isPromise(result)) { return result .then(list => { this.shim.process.nextTick(() => { done(null, list); }); }) .catch(err => { this.shim.process.nextTick(() => { done(err, undefined); }); }); } // synchronous completion function. return done(null, result); } else if (isFallbackCompletionFunction(this.customCompletionFunction)) { return (this.customCompletionFunction as FallbackCompletionFunction)( current, argv, (onCompleted = done) => this.defaultCompletion(args, argv, current, onCompleted), completions => { done(null, completions); } ); } else { return (this.customCompletionFunction as AsyncCompletionFunction)( current, argv, completions => { done(null, completions); } ); } }
// get a list of completion commands. // 'args' is the array of strings from the line to be completed getCompletion(args: string[], done: CompletionCallback): any { const current = args.length ? args[args.length - 1] : ''; const argv = this.yargs.parse(args, true);
const completionFunction = this.customCompletionFunction ? (argv: Arguments) => this.customCompletion(args, argv, current, done) : (argv: Arguments) => this.defaultCompletion(args, argv, current, done);
return isPromise(argv) ? argv.then(completionFunction) : completionFunction(argv); }
// generate the completion script to add to your .bashrc. generateCompletionScript($0: string, cmd: string): string { let script = this.zshShell ? templates.completionZshTemplate : templates.completionShTemplate; const name = this.shim.path.basename($0);
// add ./to applications not yet installed as bin. if ($0.match(/\.js$/)) $0 = `./${$0}`;
script = script.replace(/{{app_name}}/g, name); script = script.replace(/{{completion_command}}/g, cmd); return script.replace(/{{app_path}}/g, $0); }
// register a function to perform your own custom // completions., this function can be either // synchrnous or asynchronous. registerFunction(fn: CompletionFunction) { this.customCompletionFunction = fn; }
setParsed(parsed: DetailedArguments) { this.aliases = parsed.aliases; }}
// For backwards compatibilityexport function completion( yargs: YargsInstance, usage: UsageInstance, command: CommandInstance, shim: PlatformShim): CompletionInstance { return new Completion(yargs, usage, command, shim);}
export type CompletionFunction = | SyncCompletionFunction | AsyncCompletionFunction | FallbackCompletionFunction;
interface SyncCompletionFunction { (current: string, argv: Arguments): string[] | Promise<string[]>;}
interface AsyncCompletionFunction { (current: string, argv: Arguments, done: (completions: string[]) => any): any;}
interface FallbackCompletionFunction { ( current: string, argv: Arguments, completionFilter: (onCompleted?: CompletionCallback) => any, done: (completions: string[]) => any ): any;}
function isSyncCompletionFunction( completionFunction: CompletionFunction): completionFunction is SyncCompletionFunction { return completionFunction.length < 3;}
function isFallbackCompletionFunction( completionFunction: CompletionFunction): completionFunction is FallbackCompletionFunction { return completionFunction.length > 3;}