mirror of
https://github.com/microsoft/vscode.git
synced 2026-04-27 03:54:24 +01:00
287 lines
9.0 KiB
TypeScript
287 lines
9.0 KiB
TypeScript
/*---------------------------------------------------------------------------------------------
|
|
* Copyright (c) Microsoft Corporation. All rights reserved.
|
|
* Licensed under the MIT License. See License.txt in the project root for license information.
|
|
*--------------------------------------------------------------------------------------------*/
|
|
|
|
declare module 'vscode' {
|
|
|
|
// https://github.com/microsoft/vscode/issues/226562
|
|
|
|
/**
|
|
* A provider that supplies terminal completion items.
|
|
*
|
|
* Implementations of this interface should return an array of {@link TerminalCompletionItem} or a
|
|
* {@link TerminalCompletionList} describing completions for the current command line.
|
|
*
|
|
* @example <caption>Simple provider returning a single completion</caption>
|
|
* window.registerTerminalCompletionProvider({
|
|
* provideTerminalCompletions(terminal, context) {
|
|
* return [{ label: '--help', replacementRange: [Math.max(0, context.cursorPosition - 2), context.cursorPosition] }];
|
|
* }
|
|
* });
|
|
*/
|
|
export interface TerminalCompletionProvider<T extends TerminalCompletionItem = TerminalCompletionItem> {
|
|
/**
|
|
* Provide completions for the given terminal and context.
|
|
* @param terminal The terminal for which completions are being provided.
|
|
* @param context Information about the terminal's current state.
|
|
* @param token A cancellation token.
|
|
* @return A list of completions.
|
|
*/
|
|
provideTerminalCompletions(terminal: Terminal, context: TerminalCompletionContext, token: CancellationToken): ProviderResult<T[] | TerminalCompletionList<T>>;
|
|
}
|
|
|
|
/**
|
|
* Represents a completion suggestion for a terminal command line.
|
|
*
|
|
* @example <caption>Completion item for `ls -|`</caption>
|
|
* const item = {
|
|
* label: '-A',
|
|
* replacementRange: [3, 4], // replace the single character at index 3
|
|
* detail: 'List all entries except for . and .. (always set for the super-user)',
|
|
* kind: TerminalCompletionItemKind.Flag
|
|
* };
|
|
*
|
|
* The fields on a completion item describe what text should be shown to the user
|
|
* and which portion of the command line should be replaced when the item is accepted.
|
|
*/
|
|
export class TerminalCompletionItem {
|
|
/**
|
|
* The label of the completion.
|
|
*/
|
|
label: string | CompletionItemLabel;
|
|
|
|
/**
|
|
* The range in the command line to replace when the completion is accepted. Defined
|
|
* as a tuple where the first entry is the inclusive start index and the second entry is the
|
|
* exclusive end index.
|
|
*/
|
|
replacementRange: readonly [number, number];
|
|
|
|
/**
|
|
* The completion's detail which appears on the right of the list.
|
|
*/
|
|
detail?: string;
|
|
|
|
/**
|
|
* A human-readable string that represents a doc-comment.
|
|
*/
|
|
documentation?: string | MarkdownString;
|
|
|
|
/**
|
|
* The completion's kind. Note that this will map to an icon. If no kind is provided, a generic icon representing plaintext will be provided.
|
|
*/
|
|
kind?: TerminalCompletionItemKind;
|
|
|
|
/**
|
|
* Creates a new terminal completion item.
|
|
*
|
|
* @param label The label of the completion.
|
|
* @param replacementRange The inclusive start and exclusive end index of the text to replace.
|
|
* @param kind The completion's kind.
|
|
*/
|
|
constructor(
|
|
label: string | CompletionItemLabel,
|
|
replacementRange: readonly [number, number],
|
|
kind?: TerminalCompletionItemKind
|
|
);
|
|
}
|
|
|
|
/**
|
|
* The kind of an individual terminal completion item.
|
|
*
|
|
* The kind is used to render an appropriate icon in the suggest list and to convey the semantic
|
|
* meaning of the suggestion (file, folder, flag, commit, branch, etc.).
|
|
*/
|
|
export enum TerminalCompletionItemKind {
|
|
/**
|
|
* A file completion item.
|
|
* Example: `README.md`
|
|
*/
|
|
File = 0,
|
|
/**
|
|
* A folder completion item.
|
|
* Example: `src/`
|
|
*/
|
|
Folder = 1,
|
|
/**
|
|
* A method completion item.
|
|
* Example: `git commit`
|
|
*/
|
|
Method = 2,
|
|
/**
|
|
* An alias completion item.
|
|
* Example: `ll` as an alias for `ls -l`
|
|
*/
|
|
Alias = 3,
|
|
/**
|
|
* An argument completion item.
|
|
* Example: `origin` in `git push origin main`
|
|
*/
|
|
Argument = 4,
|
|
/**
|
|
* An option completion item. An option value is expected to follow.
|
|
* Example: `--locale` in `code --locale en`
|
|
*/
|
|
Option = 5,
|
|
/**
|
|
* The value of an option completion item.
|
|
* Example: `en-US` in `code --locale en-US`
|
|
*/
|
|
OptionValue = 6,
|
|
/**
|
|
* A flag completion item.
|
|
* Example: `--amend` in `git commit --amend`
|
|
*/
|
|
Flag = 7,
|
|
/**
|
|
* A symbolic link file completion item.
|
|
* Example: `link.txt` (symlink to a file)
|
|
*/
|
|
SymbolicLinkFile = 8,
|
|
/**
|
|
* A symbolic link folder completion item.
|
|
* Example: `node_modules/` (symlink to a folder)
|
|
*/
|
|
SymbolicLinkFolder = 9,
|
|
/**
|
|
* A source control commit completion item.
|
|
* Example: `abc1234` (commit hash)
|
|
*/
|
|
ScmCommit = 10,
|
|
/**
|
|
* A source control branch completion item.
|
|
* Example: `main`
|
|
*/
|
|
ScmBranch = 11,
|
|
/**
|
|
* A source control tag completion item.
|
|
* Example: `v1.0.0`
|
|
*/
|
|
ScmTag = 12,
|
|
/**
|
|
* A source control stash completion item.
|
|
* Example: `stash@{0}`
|
|
*/
|
|
ScmStash = 13,
|
|
/**
|
|
* A source control remote completion item.
|
|
* Example: `origin`
|
|
*/
|
|
ScmRemote = 14,
|
|
/**
|
|
* A pull request completion item.
|
|
* Example: `#42 Add new feature`
|
|
*/
|
|
PullRequest = 15,
|
|
/**
|
|
* A closed pull request completion item.
|
|
* Example: `#41 Fix bug (closed)`
|
|
*/
|
|
PullRequestDone = 16,
|
|
}
|
|
|
|
/**
|
|
* Context information passed to {@link TerminalCompletionProvider.provideTerminalCompletions}.
|
|
*
|
|
* It contains the full command line and the current cursor position.
|
|
*/
|
|
export interface TerminalCompletionContext {
|
|
/**
|
|
* The complete terminal command line.
|
|
*/
|
|
readonly commandLine: string;
|
|
/**
|
|
* The index of the cursor in the command line.
|
|
*/
|
|
readonly cursorIndex: number;
|
|
}
|
|
|
|
/**
|
|
* Represents a collection of {@link TerminalCompletionItem completion items} to be presented
|
|
* in the terminal plus {@link TerminalCompletionList.resourceOptions} which indicate
|
|
* which file and folder resources should be requested for the terminal's cwd.
|
|
*
|
|
* @example <caption>Create a completion list that requests files for the terminal cwd</caption>
|
|
* const list = new TerminalCompletionList([
|
|
* { label: 'ls', replacementRange: [0, 0], kind: TerminalCompletionItemKind.Method }
|
|
* ], { showFiles: true, cwd: Uri.file('/home/user') });
|
|
*/
|
|
export class TerminalCompletionList<T extends TerminalCompletionItem = TerminalCompletionItem> {
|
|
|
|
/**
|
|
* Resources that should be shown in the completions list for the cwd of the terminal.
|
|
*/
|
|
resourceOptions?: TerminalCompletionResourceOptions;
|
|
|
|
/**
|
|
* The completion items.
|
|
*/
|
|
items: T[];
|
|
|
|
/**
|
|
* Creates a new completion list.
|
|
*
|
|
* @param items The completion items.
|
|
* @param resourceOptions Indicates which resources should be shown as completions for the cwd of the terminal.
|
|
*/
|
|
constructor(items: T[], resourceOptions?: TerminalCompletionResourceOptions);
|
|
}
|
|
|
|
/**
|
|
* Configuration for requesting file and folder resources to be shown as completions.
|
|
*
|
|
* When a provider indicates that it wants file/folder resources, the terminal will surface completions for files and
|
|
* folders that match {@link globPattern} from the provided {@link cwd}.
|
|
*/
|
|
export interface TerminalCompletionResourceOptions {
|
|
/**
|
|
* Show files as completion items.
|
|
*/
|
|
showFiles: boolean;
|
|
/**
|
|
* Show folders as completion items.
|
|
*/
|
|
showDirectories: boolean;
|
|
/**
|
|
* A glob pattern string that controls which files suggest should surface. Note that this will only apply if {@param showFiles} or {@param showDirectories} is set to true.
|
|
*/
|
|
globPattern?: string;
|
|
/**
|
|
* The cwd from which to request resources.
|
|
*/
|
|
cwd: Uri;
|
|
}
|
|
|
|
export namespace window {
|
|
/**
|
|
* Register a completion provider for terminals.
|
|
* @param provider The completion provider.
|
|
* @param triggerCharacters Optional characters that trigger completion. When any of these characters is typed,
|
|
* the completion provider will be invoked. For example, passing `'-'` would cause the provider to be invoked
|
|
* whenever the user types a dash character.
|
|
* @returns A {@link Disposable} that unregisters this provider when being disposed.
|
|
*
|
|
* @example <caption>Register a provider for an extension</caption>
|
|
* window.registerTerminalCompletionProvider({
|
|
* provideTerminalCompletions(terminal, context) {
|
|
* return new TerminalCompletionList([
|
|
* { label: '--version', replacementRange: [Math.max(0, context.cursorPosition - 2), context.cursorPosition] }
|
|
* ]);
|
|
* }
|
|
* });
|
|
*
|
|
* @example <caption>Register a provider with trigger characters</caption>
|
|
* window.registerTerminalCompletionProvider({
|
|
* provideTerminalCompletions(terminal, context) {
|
|
* return new TerminalCompletionList([
|
|
* { label: '--help', replacementRange: [Math.max(0, context.cursorPosition - 2), context.cursorPosition] }
|
|
* ]);
|
|
* }
|
|
* }, '-');
|
|
*/
|
|
export function registerTerminalCompletionProvider<T extends TerminalCompletionItem>(provider: TerminalCompletionProvider<T>, ...triggerCharacters: string[]): Disposable;
|
|
}
|
|
}
|
|
|