|
2 | 2 | // Licensed under the MIT License. |
3 | 3 |
|
4 | 4 | import vscode = require("vscode"); |
5 | | -import { NotificationType } from "vscode-languageclient"; |
| 5 | +import { RequestType } from "vscode-languageclient"; |
6 | 6 | import type { LanguageClient } from "vscode-languageclient/node"; |
7 | 7 | import { LanguageClientConsumer } from "../languageClientConsumer"; |
8 | 8 |
|
9 | | -interface IShowHelpNotificationArguments {} |
| 9 | +export interface IShowHelpArguments { |
| 10 | + text: string; |
| 11 | +} |
| 12 | + |
| 13 | +export interface IShowHelpResult { |
| 14 | + helpText: string; |
| 15 | +} |
| 16 | + |
| 17 | +export const ShowHelpRequestType = new RequestType< |
| 18 | + IShowHelpArguments, |
| 19 | + IShowHelpResult, |
| 20 | + void |
| 21 | +>("powerShell/showHelp"); |
| 22 | + |
| 23 | +// Serves Get-Help output as read-only virtual documents (scheme "powershell-help"), |
| 24 | +// so help opens in an editor pane that is searchable and copyable but never marked |
| 25 | +// dirty (no save/discard prompt). The command name is carried in the URI path. |
| 26 | +class ShowHelpContentProvider implements vscode.TextDocumentContentProvider { |
| 27 | + private readonly onDidChangeEmitter = new vscode.EventEmitter<vscode.Uri>(); |
| 28 | + public readonly onDidChange = this.onDidChangeEmitter.event; |
| 29 | + |
| 30 | + public refresh(uri: vscode.Uri): void { |
| 31 | + this.onDidChangeEmitter.fire(uri); |
| 32 | + } |
10 | 33 |
|
11 | | -export const ShowHelpNotificationType = |
12 | | - new NotificationType<IShowHelpNotificationArguments>("powerShell/showHelp"); |
| 34 | + public async provideTextDocumentContent(uri: vscode.Uri): Promise<string> { |
| 35 | + const commandName = uri.path; |
| 36 | + const client = await LanguageClientConsumer.getLanguageClient(); |
| 37 | + const result = await client.sendRequest(ShowHelpRequestType, { |
| 38 | + text: commandName, |
| 39 | + }); |
| 40 | + return result.helpText || `No help found for '${commandName}'.`; |
| 41 | + } |
| 42 | + |
| 43 | + public dispose(): void { |
| 44 | + this.onDidChangeEmitter.dispose(); |
| 45 | + } |
| 46 | +} |
13 | 47 |
|
14 | 48 | export class ShowHelpFeature extends LanguageClientConsumer { |
| 49 | + public static readonly scheme = "powershell-help"; |
| 50 | + |
15 | 51 | private command: vscode.Disposable; |
| 52 | + private contentProvider: ShowHelpContentProvider; |
| 53 | + private providerRegistration: vscode.Disposable; |
16 | 54 |
|
17 | 55 | constructor() { |
18 | 56 | super(); |
| 57 | + this.contentProvider = new ShowHelpContentProvider(); |
| 58 | + this.providerRegistration = |
| 59 | + vscode.workspace.registerTextDocumentContentProvider( |
| 60 | + ShowHelpFeature.scheme, |
| 61 | + this.contentProvider, |
| 62 | + ); |
| 63 | + |
19 | 64 | this.command = vscode.commands.registerCommand( |
20 | 65 | "PowerShell.ShowHelp", |
21 | 66 | async (item?) => { |
22 | | - if (!item?.Name) { |
23 | | - const editor = vscode.window.activeTextEditor; |
24 | | - if (editor === undefined) { |
25 | | - return; |
26 | | - } |
27 | | - |
28 | | - const selection = editor.selection; |
29 | | - const doc = editor.document; |
30 | | - const cwr = doc.getWordRangeAtPosition(selection.active); |
31 | | - const text = doc.getText(cwr); |
32 | | - |
33 | | - const client = |
34 | | - await LanguageClientConsumer.getLanguageClient(); |
35 | | - await client.sendNotification(ShowHelpNotificationType, { |
36 | | - text, |
37 | | - }); |
38 | | - } else { |
39 | | - const client = |
40 | | - await LanguageClientConsumer.getLanguageClient(); |
41 | | - await client.sendNotification(ShowHelpNotificationType, { |
42 | | - text: item.Name, |
43 | | - }); |
| 67 | + const text = ShowHelpFeature.resolveCommandName(item); |
| 68 | + if (text === undefined) { |
| 69 | + return; |
44 | 70 | } |
| 71 | + |
| 72 | + await this.showHelp(text); |
45 | 73 | }, |
46 | 74 | ); |
47 | 75 | } |
48 | 76 |
|
| 77 | + // Determines the command to show help for: an explicit item, the current |
| 78 | + // selection, or the word under the cursor. Returns undefined (and surfaces a |
| 79 | + // hint) when there's nothing to look up, rather than falling back to the |
| 80 | + // entire document. |
| 81 | + private static resolveCommandName(item?: { |
| 82 | + Name?: string; |
| 83 | + }): string | undefined { |
| 84 | + if (item?.Name) { |
| 85 | + return item.Name; |
| 86 | + } |
| 87 | + |
| 88 | + const editor = vscode.window.activeTextEditor; |
| 89 | + if (editor === undefined) { |
| 90 | + return undefined; |
| 91 | + } |
| 92 | + |
| 93 | + const document = editor.document; |
| 94 | + const selection = editor.selection; |
| 95 | + |
| 96 | + if (!selection.isEmpty) { |
| 97 | + return document.getText(selection); |
| 98 | + } |
| 99 | + |
| 100 | + const wordRange = document.getWordRangeAtPosition(selection.active); |
| 101 | + if (wordRange === undefined) { |
| 102 | + void vscode.window.showInformationMessage( |
| 103 | + "Place the cursor on a PowerShell command to show its help.", |
| 104 | + ); |
| 105 | + return undefined; |
| 106 | + } |
| 107 | + |
| 108 | + return document.getText(wordRange); |
| 109 | + } |
| 110 | + |
| 111 | + private async showHelp(commandName: string): Promise<void> { |
| 112 | + const uri = vscode.Uri.from({ |
| 113 | + scheme: ShowHelpFeature.scheme, |
| 114 | + path: commandName, |
| 115 | + }); |
| 116 | + |
| 117 | + // Re-fetch in case the help changed since this document was last opened. |
| 118 | + this.contentProvider.refresh(uri); |
| 119 | + |
| 120 | + // If this command's help is already open, reuse that editor's column so |
| 121 | + // repeated clicks focus the existing pane instead of stacking duplicates. |
| 122 | + const existingColumn = vscode.window.tabGroups.all |
| 123 | + .flatMap((group) => group.tabs) |
| 124 | + .find( |
| 125 | + (tab) => |
| 126 | + tab.input instanceof vscode.TabInputText && |
| 127 | + tab.input.uri.toString() === uri.toString(), |
| 128 | + )?.group.viewColumn; |
| 129 | + |
| 130 | + const document = await vscode.workspace.openTextDocument(uri); |
| 131 | + await vscode.window.showTextDocument(document, { |
| 132 | + preview: true, |
| 133 | + viewColumn: existingColumn ?? vscode.ViewColumn.Beside, |
| 134 | + }); |
| 135 | + } |
| 136 | + |
49 | 137 | public override onLanguageClientSet( |
50 | 138 | _languageClient: LanguageClient, |
51 | 139 | // eslint-disable-next-line @typescript-eslint/no-empty-function |
52 | 140 | ): void {} |
53 | 141 |
|
54 | 142 | public dispose(): void { |
55 | 143 | this.command.dispose(); |
| 144 | + this.providerRegistration.dispose(); |
| 145 | + this.contentProvider.dispose(); |
56 | 146 | } |
57 | 147 | } |
0 commit comments