diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 2d385b2e..acef4893 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -7,7 +7,9 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - - uses: krdlab/setup-haxe@v1.1.4 + - uses: krdlab/setup-haxe@v1.5.1 + with: + haxe-version: 4.3.6 - run: | haxelib install hxnodejs haxelib git dox https://github.com/HaxeFoundation/dox diff --git a/.haxerc b/.haxerc new file mode 100644 index 00000000..ef431268 --- /dev/null +++ b/.haxerc @@ -0,0 +1,4 @@ +{ + "version": "4.3.6", + "resolveLibs": "scoped" +} \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json index f352f481..d7eb6aa6 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -3,7 +3,8 @@ "editor.formatOnSave": true, "editor.formatOnPaste": true, "editor.codeActionsOnSave": { - "source.sortImports": true + "source.sortImports": "explicit" } - } + }, + "explorer.autoReveal": true } \ No newline at end of file diff --git a/README.md b/README.md index e7297979..0f2ce56d 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,9 @@ This extern library makes it possible to write extensions for [Visual Studio Code](https://code.visualstudio.com/) using [Haxe](https://haxe.org/). -VS Code API version: **1.60** +VS Code API version: **1.97** -**NOTE**: Requires Haxe 4 or later +**NOTE**: Requires Haxe 4.3 or later ## Usage @@ -18,13 +18,14 @@ Global functions and variables from the `vscode` namespace are available through while types defined in `vscode` namespace are located in the `vscode` package. The node.js API externs are provided by the [hxnodejs](https://github.com/HaxeFoundation/hxnodejs) library. -The current "proposed" APIs are provided are provided via `VscodeProposed` top-level class for the `vscode` namespace -and the `vscode.proposed` package. +~~The current "proposed" APIs are provided via `VscodeProposed` top-level class for the `vscode` namespace +and the `vscode.proposed` package.~~ VS Code expects a .js module that exports the `activate` function that will be called upon extension activation. In Haxe this is done using the `@:expose` metdata. Example: + ```haxe class HelloHaxe { @:expose("activate") diff --git a/haxelib.json b/haxelib.json index 33940bbf..81199e08 100644 --- a/haxelib.json +++ b/haxelib.json @@ -3,8 +3,8 @@ "description": "Visual Studio Code extern library", "url": "https://github.com/vshaxe/vscode-extern", "license": "MIT", - "version": "1.60.0", - "releasenote": "Update to VSCode 1.60", + "version": "1.97.0", + "releasenote": "Update to VSCode 1.97", "classPath": "src", "contributors": ["nadako", "Gama11"], "dependencies": { diff --git a/src/Vscode.hx b/src/Vscode.hx index d7908cdc..9c2a84a4 100644 --- a/src/Vscode.hx +++ b/src/Vscode.hx @@ -178,6 +178,9 @@ extern class Vscode { static var tests(default, null):VscodeTests; } +/** + * Namespace describing the environment the editor runs in. + */ extern class VscodeEnv { /** * The application name of the editor, like 'VS Code'. @@ -193,7 +196,10 @@ extern class VscodeEnv { var appRoot(default, null):String; /** - * The environment in which the app is hosted in. i.e. 'desktop', 'codespaces', 'web'. + * The hosted location of the application + * On desktop this is 'desktop' + * In the web this is the specified embedder i.e. 'github.dev', 'codespaces', or 'web' if the embedder + * does not provide that information */ var appHost(default, null):String; @@ -241,6 +247,21 @@ extern class VscodeEnv { */ var onDidChangeTelemetryEnabled(default, null):Event; + /** + * An {@link Event} which fires when the default shell changes. This fires with the new + * shell path. + */ + var onDidChangeShell(default, null):Event; + + /** + * Creates a new {@link TelemetryLogger telemetry logger}. + * + * @param sender The telemetry sender that is used by the telemetry logger. + * @param options Options for the telemetry logger. + * @returns A new telemetry logger + */ + function createTelemetryLogger(sender:TelemetrySender, ?options:TelemetryLoggerOptions):TelemetryLogger; + /** * The name of a remote. Defined by extensions, popular samples are `wsl` for the Windows * Subsystem for Linux or `ssh-remote` for remotes using a secure shell. @@ -254,7 +275,7 @@ extern class VscodeEnv { /** * The detected default shell for the extension host, this is overridden by the - * `terminal.integrated.shell` setting for the extension host's platform. Note that in + * `terminal.integrated.defaultProfile` setting for the extension host's platform. Note that in * environments that do not support a shell the value is the empty string. */ var shell(default, null):String; @@ -319,12 +340,12 @@ extern class VscodeEnv { * } * }); * - * const callableUri = await vscode.env.asExternalUri(vscode.Uri.parse(`${vscode.env.uriScheme}://my.extension/did-authenticate`)); + * const callableUri = await vscode.env.asExternalUri(vscode.Uri.parse(vscode.env.uriScheme + '://my.extension/did-authenticate')); * await vscode.env.openExternal(callableUri); * ``` * * *Note* that extensions should not cache the result of `asExternalUri` as the resolved uri may become invalid due to - * a system or user action — for example, in remote cases, a user may close a port forwarding tunnel that was opened by + * a system or user action — for example, in remote cases, a user may close a port forwarding tunnel that was opened by * `asExternalUri`. * * #### Any other scheme @@ -332,11 +353,57 @@ extern class VscodeEnv { * Any other scheme will be handled as if the provided URI is a workspace URI. In that case, the method will return * a URI which, when handled, will make the editor open the workspace. * - * @return A uri that can be used on the client machine. + * @returns A uri that can be used on the client machine. */ function asExternalUri(target:Uri):Thenable; + + /** + * The current log level of the editor. + */ + var logLevel(default, null):LogLevel; + + /** + * An {@link Event} which fires when the log level of the editor changes. + */ + var onDidChangeLogLevel(default, null):Event; } +/** + * Namespace for dealing with commands. In short, a command is a function with a + * unique identifier. The function is sometimes also called _command handler_. + * + * Commands can be added to the editor using the {@link commands.registerCommand registerCommand} + * and {@link commands.registerTextEditorCommand registerTextEditorCommand} functions. Commands + * can be executed {@link commands.executeCommand manually} or from a UI gesture. Those are: + * + * * palette - Use the `commands`-section in `package.json` to make a command show in + * the [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette). + * * keybinding - Use the `keybindings`-section in `package.json` to enable + * [keybindings](https://code.visualstudio.com/docs/getstarted/keybindings#_advanced-customization) + * for your extension. + * + * Commands from other extensions and from the editor itself are accessible to an extension. However, + * when invoking an editor command not all argument types are supported. + * + * This is a sample that registers a command handler and adds an entry for that command to the palette. First + * register a command handler with the identifier `extension.sayHello`. + * ```javascript + * commands.registerCommand('extension.sayHello', () => { + * window.showInformationMessage('Hello World!'); + * }); + * ``` + * Second, bind the command identifier to a title under which it will show in the palette (`package.json`). + * ```json + * { + * "contributes": { + * "commands": [{ + * "command": "extension.sayHello", + * "title": "Hello World" + * }] + * } + * } + * ``` + */ extern class VscodeCommands { /** * Registers a command that can be invoked via a keyboard shortcut, @@ -348,7 +415,7 @@ extern class VscodeCommands { * @param command A unique identifier for the command. * @param callback A command handler function. * @param thisArg The `this` context used when invoking the handler function. - * @return Disposable which unregisters this command on disposal. + * @returns Disposable which unregisters this command on disposal. */ function registerCommand(command:String, callback:Function, ?thisArg:Any):Disposable; @@ -365,7 +432,7 @@ extern class VscodeCommands { * @param command A unique identifier for the command. * @param callback A command handler function with access to an {@link TextEditor editor} and an {@link TextEditorEdit edit}. * @param thisArg The `this` context used when invoking the handler function. - * @return Disposable which unregisters this command on disposal. + * @returns Disposable which unregisters this command on disposal. */ // TODO callback should receive Rest really function registerTextEditorCommand(command:String, callback:TextEditor->TextEditorEdit->Void, ?thisArg:Any):Disposable; @@ -381,22 +448,27 @@ extern class VscodeCommands { * * @param command Identifier of the command to execute. * @param rest Parameters passed to the command function. - * @return A thenable that resolves to the returned value of the given command. `undefined` when + * @returns A thenable that resolves to the returned value of the given command. Returns `undefined` when * the command handler function doesn't return anything. */ - function executeCommand(command:String, rest:Rest):Thenable>; + function executeCommand(command:String, rest:Rest):Thenable; /** * Retrieve the list of all available commands. Commands starting with an underscore are * treated as internal commands. * * @param filterInternal Set `true` to not see internal commands (starting with an underscore) - * @return Thenable that resolves to a list of command ids. + * @returns Thenable that resolves to a list of command ids. */ function getCommands(?filterInternal:Bool):Thenable>; } extern class VscodeWindow { + /** + * Represents the grid widget within the main editor area + */ + var tabGroups(default, null):TabGroups; + /** * The currently active editor or `undefined`. The active editor is the one * that currently has focus or, when none has focus, the one that has changed @@ -407,7 +479,7 @@ extern class VscodeWindow { /** * The currently visible editors or an empty array. */ - var visibleTextEditors:Array; + var visibleTextEditors:ReadOnlyArray; /** * An {@link Event} which fires when the {@link window.activeTextEditor active editor} @@ -420,7 +492,7 @@ extern class VscodeWindow { * An {@link Event} which fires when the array of {@link window.visibleTextEditors visible editors} * has changed. */ - var onDidChangeVisibleTextEditors(default, null):Event>; + var onDidChangeVisibleTextEditors(default, null):Event>; /** * An {@link Event} which fires when the selection in an editor has changed. @@ -442,6 +514,43 @@ extern class VscodeWindow { */ var onDidChangeTextEditorViewColumn(default, null):Event; + /** + * The currently visible {@link NotebookEditor notebook editors} or an empty array. + */ + var visibleNotebookEditors(default, null):ReadOnlyArray; + + /** + * An {@link Event} which fires when the {@link window.visibleNotebookEditors visible notebook editors} + * has changed. + */ + var onDidChangeVisibleNotebookEditors(default, null):Event>; + + /** + * The currently active {@link NotebookEditor notebook editor} or `undefined`. The active editor is the one + * that currently has focus or, when none has focus, the one that has changed + * input most recently. + */ + var activeNotebookEditor(default, null):Null; + + /** + * An {@link Event} which fires when the {@link window.activeNotebookEditor active notebook editor} + * has changed. *Note* that the event also fires when the active editor changes + * to `undefined`. + */ + var onDidChangeActiveNotebookEditor(default, null):Event>; + + /** + * An {@link Event} which fires when the {@link NotebookEditor.selections notebook editor selections} + * have changed. + */ + var onDidChangeNotebookEditorSelection(default, null):Event; + + /** + * An {@link Event} which fires when the {@link NotebookEditor.visibleRanges notebook editor visible ranges} + * have changed. + */ + var onDidChangeNotebookEditorVisibleRanges(default, null):Event; + /** * The currently opened terminals or an empty array. */ @@ -471,13 +580,37 @@ extern class VscodeWindow { */ var onDidCloseTerminal(default, null):Event; + /** + * An {@link Event} which fires when a {@link Terminal.state terminal's state} has changed. + */ + var onDidChangeTerminalState(default, null):Event; + + /** + * Fires when shell integration activates or one of its properties changes in a terminal. + */ + var onDidChangeTerminalShellIntegration(default, null):Event; + + /** + * This will be fired when a terminal command is started. This event will fire only when + * [shell integration](https://code.visualstudio.com/docs/terminal/shell-integration) is + * activated for the terminal. + */ + var onDidStartTerminalShellExecution(default, null):Event; + + /** + * This will be fired when a terminal command is ended. This event will fire only when + * [shell integration](https://code.visualstudio.com/docs/terminal/shell-integration) is + * activated for the terminal. + */ + var onDidEndTerminalShellExecution(default, null):Event; + /** * Represents the current window's state. */ var state(default, null):WindowState; /** - * An {@link Event} which fires when the focus state of the current window + * An {@link Event} which fires when the focus or activity state of the current window * changes. The value of the event represents whether the window is focused. */ var onDidChangeWindowState(default, null):Event; @@ -487,56 +620,104 @@ extern class VscodeWindow { * to control where the editor is being shown. Might change the {@link window.activeTextEditor active editor}. * * @param document A text document to be shown. - * @param column A view column in which the {@link TextEditor editor} should be shown. The default is the {@link ViewColumn.Active active}, other values - * are adjusted to be `Min(column, columnCount + 1)`, the {@link ViewColumn.Active active}-column is not adjusted. Use {@linkcode ViewColumn.Beside} + * @param column A view column in which the {@link TextEditor editor} should be shown. The default is the {@link ViewColumn.Active active}. + * Columns that do not exist will be created as needed up to the maximum of {@linkcode ViewColumn.Nine}. Use {@linkcode ViewColumn.Beside} * to open the editor to the side of the currently active one. * @param preserveFocus When `true` the editor will not take focus. - * @return A promise that resolves to an {@link TextEditor editor}. + * @returns A promise that resolves to an {@link TextEditor editor}. */ - @:overload(function(uri:Uri, ?options:TextDocumentShowOptions):Thenable {}) - @:overload(function(document:TextDocument, ?options:TextDocumentShowOptions):Thenable {}) - function showTextDocument(document:TextDocument, ?column:ViewColumn, ?preserveFocus:Bool):Thenable; + overload function showTextDocument(document:TextDocument, ?column:ViewColumn, ?preserveFocus:Bool):Thenable; + + /** + * A short-hand for `openTextDocument(uri).then(document => showTextDocument(document, options))`. + * + * @see {@link workspace.openTextDocument} + * + * @param uri A resource identifier. + * @param options {@link TextDocumentShowOptions Editor options} to configure the behavior of showing the {@link TextEditor editor}. + * @returns A promise that resolves to an {@link TextEditor editor}. + */ + overload function showTextDocument(uri:Uri, ?options:TextDocumentShowOptions):Thenable; + + /** + * Show the given document in a text editor. {@link TextDocumentShowOptions Options} can be provided + * to control options of the editor is being shown. Might change the {@link window.activeTextEditor active editor}. + * + * @param document A text document to be shown. + * @param options {@link TextDocumentShowOptions Editor options} to configure the behavior of showing the {@link TextEditor editor}. + * @returns A promise that resolves to an {@link TextEditor editor}. + */ + overload function showTextDocument(document:TextDocument, ?options:TextDocumentShowOptions):Thenable; + + /** + * Show the given {@link NotebookDocument} in a {@link NotebookEditor notebook editor}. + * + * @param document A text document to be shown. + * @param options {@link NotebookDocumentShowOptions Editor options} to configure the behavior of showing the {@link NotebookEditor notebook editor}. + * + * @returns A promise that resolves to an {@link NotebookEditor notebook editor}. + */ + function showNotebookDocument(document:NotebookDocument, ?options:NotebookDocumentShowOptions):Thenable; /** * Create a TextEditorDecorationType that can be used to add decorations to text editors. * * @param options Rendering options for the decoration type. - * @return A new decoration type instance. + * @returns A new decoration type instance. */ function createTextEditorDecorationType(options:DecorationRenderOptions):TextEditorDecorationType; + /** - * Show an information message. - * - * @see {@link window.showInformationMessage showInformationMessage} + * Show an information message to users. Optionally provide an array of items which will be presented as + * clickable buttons. * * @param message The message to show. * @param items A set of items that will be rendered as actions in the message. - * @param options Configures the behaviour of the message. - * @return A thenable that resolves to the selected item or `undefined` when being dismissed. + * @returns A thenable that resolves to the selected item or `undefined` when being dismissed. */ - // TODO overload plox // /** - // * Show an information message to users. Optionally provide an array of items which will be presented as - // * clickable buttons. + // * Show an information message. + // * + // * @see {@link window.showInformationMessage showInformationMessage} // * // * @param message The message to show. // * @param items A set of items that will be rendered as actions in the message. - // * @return A thenable that resolves to the selected item or `undefined` when being dismissed. + // * @returns A thenable that resolves to the selected item or `undefined` when being dismissed. // */ + overload function showInformationMessage>(message:String, items:Rest):Thenable>; + + /** + * Show an information message to users. Optionally provide an array of items which will be presented as + * clickable buttons. + * + * @param message The message to show. + * @param options Configures the behaviour of the message. + * @param items A set of items that will be rendered as actions in the message. + * @returns A thenable that resolves to the selected item or `undefined` when being dismissed. + */ // /** - // * Show an information message to users. Optionally provide an array of items which will be presented as - // * clickable buttons. + // * Show an information message. + // * + // * @see {@link window.showInformationMessage showInformationMessage} // * // * @param message The message to show. // * @param options Configures the behaviour of the message. // * @param items A set of items that will be rendered as actions in the message. - // * @return A thenable that resolves to the selected item or `undefined` when being dismissed. + // * @returns A thenable that resolves to the selected item or `undefined` when being dismissed. // */ - @:overload(function(message:String, items:Rest):Thenable> {}) - @:overload(function(message:String, options:MessageOptions, items:Rest):Thenable> {}) - @:overload(function(message:String, items:Rest):Thenable> {}) - function showInformationMessage(message:String, options:MessageOptions, items:Rest):Thenable>; + overload function showInformationMessage>(message:String, options:MessageOptions, items:Rest):Thenable>; + + /** + * Show a warning message. + * + * @see {@link window.showInformationMessage showInformationMessage} + * + * @param message The message to show. + * @param items A set of items that will be rendered as actions in the message. + * @returns A thenable that resolves to the selected item or `undefined` when being dismissed. + */ + overload function showWarningMessage(message:String, items:Rest):Thenable>; /** * Show a warning message. @@ -546,12 +727,43 @@ extern class VscodeWindow { * @param message The message to show. * @param options Configures the behaviour of the message. * @param items A set of items that will be rendered as actions in the message. - * @return A thenable that resolves to the selected item or `undefined` when being dismissed. + * @returns A thenable that resolves to the selected item or `undefined` when being dismissed. + */ + overload function showWarningMessage(message:String, options:MessageOptions, items:Rest):Thenable>; + + /** + * Show a warning message. + * + * @see {@link window.showInformationMessage showInformationMessage} + * + * @param message The message to show. + * @param items A set of items that will be rendered as actions in the message. + * @returns A thenable that resolves to the selected item or `undefined` when being dismissed. */ - @:overload(function(message:String, items:Rest):Thenable> {}) - @:overload(function(message:String, options:MessageOptions, items:Rest):Thenable> {}) - @:overload(function(message:String, items:Rest):Thenable> {}) - function showWarningMessage(message:String, options:MessageOptions, items:Rest):Thenable>; + overload function showWarningMessage(message:String, items:Rest):Thenable>; + + /** + * Show a warning message. + * + * @see {@link window.showInformationMessage showInformationMessage} + * + * @param message The message to show. + * @param options Configures the behaviour of the message. + * @param items A set of items that will be rendered as actions in the message. + * @returns A thenable that resolves to the selected item or `undefined` when being dismissed. + */ + overload function showWarningMessage(message:String, options:MessageOptions, items:Rest):Thenable>; + + /** + * Show an error message. + * + * @see {@link window.showInformationMessage showInformationMessage} + * + * @param message The message to show. + * @param items A set of items that will be rendered as actions in the message. + * @returns A thenable that resolves to the selected item or `undefined` when being dismissed. + */ + overload function showErrorMessage(message:String, items:Rest):Thenable>; /** * Show an error message. @@ -561,24 +773,53 @@ extern class VscodeWindow { * @param message The message to show. * @param options Configures the behaviour of the message. * @param items A set of items that will be rendered as actions in the message. - * @return A thenable that resolves to the selected item or `undefined` when being dismissed. + * @returns A thenable that resolves to the selected item or `undefined` when being dismissed. */ - @:overload(function(message:String, items:Rest):Thenable> {}) - @:overload(function(message:String, options:MessageOptions, items:Rest):Thenable> {}) - @:overload(function(message:String, items:Rest):Thenable> {}) - function showErrorMessage(message:String, options:MessageOptions, items:Rest):Thenable>; + overload function showErrorMessage(message:String, options:MessageOptions, items:Rest):Thenable>; /** - * Shows a selection list. + * Show an error message. + * + * @see {@link window.showInformationMessage showInformationMessage} + * + * @param message The message to show. + * @param items A set of items that will be rendered as actions in the message. + * @returns A thenable that resolves to the selected item or `undefined` when being dismissed. + */ + overload function showErrorMessage(message:String, items:Rest):Thenable>; + + /** + * Show an error message. + * + * @see {@link window.showInformationMessage showInformationMessage} + * + * @param message The message to show. + * @param options Configures the behaviour of the message. + * @param items A set of items that will be rendered as actions in the message. + * @returns A thenable that resolves to the selected item or `undefined` when being dismissed. + */ + overload function showErrorMessage(message:String, options:MessageOptions, items:Rest):Thenable>; + + /** + * Shows a selection list allowing multiple selections. * * @param items An array of strings, or a promise that resolves to an array of strings. * @param options Configures the behavior of the selection list. * @param token A token that can be used to signal cancellation. - * @return A promise that resolves to the selection or `undefined`. + * @returns A promise that resolves to the selected items or `undefined`. + */ + overload function showQuickPick(items:EitherType, Thenable>>, ?options:QuickPickOptions, + ?token:CancellationToken):Thenable>; + + /** + * Shows a selection list allowing multiple selections. + * + * @param items An array of items, or a promise that resolves to an array of items. + * @param options Configures the behavior of the selection list. + * @param token A token that can be used to signal cancellation. + * @returns A promise that resolves to the selected items or `undefined`. */ - @:overload(function(items:EitherType, Thenable>>, ?options:QuickPickOptions, - ?token:CancellationToken):Thenable> {}) - function showQuickPick(items:EitherType, Thenable>>, ?options:QuickPickOptions, + overload function showQuickPick(items:EitherType, Thenable>>, ?options:QuickPickOptions, ?token:CancellationToken):Thenable>; /** @@ -587,7 +828,7 @@ extern class VscodeWindow { * @param items An array of items, or a promise that resolves to an array of items. * @param options Configures the behavior of the selection list. * @param token A token that can be used to signal cancellation. - * @return A promise that resolves to the selected items or `undefined`. + * @returns A promise that resolves to the selected items or `undefined`. */ // see #13 for details on why this is needed extern inline function showQuickPickMany(items:EitherType, Thenable>>, ?options:QuickPickOptions, @@ -604,7 +845,7 @@ extern class VscodeWindow { * Returns `undefined` if no folder is open. * * @param options Configures the behavior of the workspace folder list. - * @return A promise that resolves to the workspace folder or `undefined`. + * @returns A promise that resolves to the workspace folder or `undefined`. */ function showWorkspaceFolderPick(?options:WorkspaceFolderPickOptions):Thenable>; @@ -635,7 +876,7 @@ extern class VscodeWindow { * * @param options Configures the behavior of the input box. * @param token A token that can be used to signal cancellation. - * @return A promise that resolves to a string the user provided or to `undefined` in case of dismissal. + * @returns A promise that resolves to a string the user provided or to `undefined` in case of dismissal. */ function showInputBox(?options:InputBoxOptions, ?token:CancellationToken):Thenable>; @@ -647,7 +888,7 @@ extern class VscodeWindow { * is easier to use. {@link window.createQuickPick} should be used * when {@link window.showQuickPick} does not offer the required flexibility. * - * @return A new {@link QuickPick}. + * @returns A new {@link QuickPick}. */ function createQuickPick():QuickPick; @@ -658,16 +899,31 @@ extern class VscodeWindow { * is easier to use. {@link window.createInputBox} should be used * when {@link window.showInputBox} does not offer the required flexibility. * - * @return A new {@link InputBox}. + * @returns A new {@link InputBox}. */ function createInputBox():InputBox; /** - * Creates a new {@link OutputChannel output channel} with the given name. + * Creates a new {@link OutputChannel output channel} with the given name and language id + * If language id is not provided, then **Log** is used as default language id. + * + * You can access the visible or active output channel as a {@link TextDocument text document} from {@link window.visibleTextEditors visible editors} or {@link window.activeTextEditor active editor} + * and use the language id to contribute language features like syntax coloring, code lens etc., + * + * @param name Human-readable string which will be used to represent the channel in the UI. + * @param languageId The identifier of the language associated with the channel. + * @returns A new output channel. + */ + overload function createOutputChannel(name:String, ?languageId:String):OutputChannel; + + /** + * Creates a new {@link LogOutputChannel log output channel} with the given name. * * @param name Human-readable string which will be used to represent the channel in the UI. + * @param options Options for the log output channel. + * @returns A new log output channel. */ - function createOutputChannel(name:String):OutputChannel; + overload function createOutputChannel(name:String, options:{/** literal-type defines return type */ log:Bool}):LogOutputChannel; /** * Create and show a new webview panel. @@ -677,26 +933,50 @@ extern class VscodeWindow { * @param showOptions Where to show the webview in the editor. If preserveFocus is set, the new webview will not take focus. * @param options Settings for the new panel. * - * @return New webview panel. + * @returns New webview panel. */ - function createWebviewPanel(viewType:String, title:String, showOptions:EitherType, - ?options:WebviewPanelOptions & WebviewOptions):WebviewPanel; + function createWebviewPanel(viewType:String, title:String, showOptions:EitherType, ?options:WebviewPanelOptions & WebviewOptions):WebviewPanel; /** * Set a message to the status bar. This is a short hand for the more powerful * status bar {@link window.createStatusBarItem items}. * - * *Note* that status bar messages without hide arguments stack and that they must be disposed when no - * longer used. - * * @param text The message to show, supports icon substitution as in status bar {@link StatusBarItem.text items}. * @param hideAfterTimeout Timeout in milliseconds after which the message will be disposed. + * @returns A disposable which hides the status bar message. + */ + overload function setStatusBarMessage(text:String, hideAfterTimeout:Float):Disposable; + + /** + * Set a message to the status bar. This is a short hand for the more powerful + * status bar {@link window.createStatusBarItem items}. + * + * @param text The message to show, supports icon substitution as in status bar {@link StatusBarItem.text items}. * @param hideWhenDone Thenable on which completion (resolve or reject) the message will be disposed. - * @return A disposable which hides the status bar message. + * @returns A disposable which hides the status bar message. + */ + overload function setStatusBarMessage(text:String, hideWhenDone:Thenable):Disposable; + + /** + * Set a message to the status bar. This is a short hand for the more powerful + * status bar {@link window.createStatusBarItem items}. + * + * *Note* that status bar messages stack and that they must be disposed when no + * longer used. + * + * @param text The message to show, supports icon substitution as in status bar {@link StatusBarItem.text items}. + * @returns A disposable which hides the status bar message. */ - @:overload(function(text:String, hideAfterTimeout:Float):Disposable {}) - @:overload(function(text:String, hideWhenDone:Thenable):Disposable {}) - function setStatusBarMessage(text:String):Disposable; + overload function setStatusBarMessage(text:String):Disposable; /** * Show progress in the Source Control viewlet while running the given callback and while @@ -706,7 +986,7 @@ extern class VscodeWindow { * * @param task A callback returning a promise. Progress increments can be reported with * the provided {@link Progress}-object. - * @return The thenable the task did return. + * @returns The thenable the task did return. */ @:deprecated("Use `withProgress` instead.") function withScmProgress(task:Progress->Thenable):Thenable; @@ -716,6 +996,7 @@ extern class VscodeWindow { * and while the promise it returned isn't resolved nor rejected. The location at which * progress should show (and other details) is defined via the passed {@linkcode ProgressOptions}. * + * @param options A {@linkcode ProgressOptions}-object describing the options to use for showing progress, like its location * @param task A callback returning a promise. Progress state can be reported with * the provided {@link Progress}-object. * @@ -728,20 +1009,38 @@ extern class VscodeWindow { * Note that currently only `ProgressLocation.Notification` is supporting to show a cancel button to cancel the * long running operation. * - * @return The thenable the task-callback returned. + * @returns The thenable the task-callback returned. + */ + function withProgress(options:ProgressOptions, task:Progress<{ + /** + * A progress message that represents a chunk of work + */ + ?message:String, + /** + * An increment for discrete progress. Increments will be summed up until 100% is reached + */ + ?increment:Float + }>->CancellationToken->Thenable):Thenable; + + /** + * Creates a status bar {@link StatusBarItem item}. + * + * @param id The identifier of the item. Must be unique within the extension. + * @param alignment The alignment of the item. + * @param priority The priority of the item. Higher values mean the item should be shown more to the left. + * @returns A new status bar item. */ - function withProgress(options:ProgressOptions, task:Progress<{?message:String, ?increment:Float}>->CancellationToken->Thenable):Thenable; + overload function createStatusBarItem(id:String, ?alignment:StatusBarAlignment, ?priority:Float):StatusBarItem; /** * Creates a status bar {@link StatusBarItem item}. * - * @param id The unique identifier of the item. + * @see {@link createStatusBarItem} for creating a status bar item with an identifier. * @param alignment The alignment of the item. * @param priority The priority of the item. Higher values mean the item should be shown more to the left. - * @return A new status bar item. + * @returns A new status bar item. */ - @:overload(function(id:String, ?alignment:StatusBarAlignment, ?priority:Float):StatusBarItem {}) - function createStatusBarItem(?alignment:StatusBarAlignment, ?priority:Float):StatusBarItem; + overload function createStatusBarItem(?alignment:StatusBarAlignment, ?priority:Float):StatusBarItem; /** * Creates a {@link Terminal} with a backing shell process. The cwd of the terminal will be the workspace @@ -752,15 +1051,28 @@ extern class VscodeWindow { * @param shellArgs Optional args for the custom shell executable. A string can be used on Windows only which * allows specifying shell args in * [command-line format](https://msdn.microsoft.com/en-au/08dfcab2-eb6e-49a4-80eb-87d4076c98c6). + * @returns A new Terminal. + * @throws When running in an environment where a new process cannot be started. + */ + overload function createTerminal(?name:String, ?shellPath:String, ?shellArgs:EitherType, String>):Terminal; + + /** + * Creates a {@link Terminal} with a backing shell process. + * * @param options A TerminalOptions object describing the characteristics of the new terminal. + * @returns A new Terminal. + * @throws When running in an environment where a new process cannot be started. + */ + overload function createTerminal(options:TerminalOptions):Terminal; + + /** + * Creates a {@link Terminal} where an extension controls its input and output. + * * @param options An {@link ExtensionTerminalOptions} object describing * the characteristics of the new terminal. - * @return A new Terminal. - * @throws When running in an environment where a new process cannot be started. + * @returns A new Terminal. */ - @:overload(function(options:TerminalOptions):Terminal {}) - @:overload(function(options:ExtensionTerminalOptions):Terminal {}) - function createTerminal(?name:String, ?shellPath:String, ?shellArgs:EitherType, String>):Terminal; + overload function createTerminal(options:ExtensionTerminalOptions):Terminal; /** * Register a {@link TreeDataProvider} for the view contributed using the extension point `views`. @@ -770,6 +1082,7 @@ extern class VscodeWindow { * * @param viewId Id of the view contributed using the extension point `views`. * @param treeDataProvider A {@link TreeDataProvider} that provides tree data for the view + * @returns A {@link Disposable disposable} that unregisters the {@link TreeDataProvider}. */ function registerTreeDataProvider(viewId:String, treeDataProvider:TreeDataProvider):Disposable; @@ -801,6 +1114,7 @@ extern class VscodeWindow { * the current extension is about to be handled. * * @param handler The uri handler to register for this extension. + * @returns A {@link Disposable disposable} that unregisters the handler. */ function registerUriHandler(handler:UriHandler):Disposable; @@ -808,12 +1122,13 @@ extern class VscodeWindow { * Registers a webview panel serializer. * * Extensions that support reviving should have an `"onWebviewPanel:viewType"` activation event and - * make sure that {@link registerWebviewPanelSerializer} is called during activation. + * make sure that `registerWebviewPanelSerializer` is called during activation. * * Only a single serializer may be registered at a time for a given `viewType`. * * @param viewType Type of the webview panel that can be serialized. * @param serializer Webview serializer. + * @returns A {@link Disposable disposable} that unregisters the serializer. */ function registerWebviewPanelSerializer(viewType:String, serializer:WebviewPanelSerializer):Disposable; @@ -824,7 +1139,7 @@ extern class VscodeWindow { * `views` contribution in the package.json. * @param provider Provider for the webview views. * - * @return Disposable that unregisters the provider. + * @returns Disposable that unregisters the provider. */ function registerWebviewViewProvider(viewId:String, provider:WebviewViewProvider, ?options:{ /** @@ -863,7 +1178,7 @@ extern class VscodeWindow { * @param provider Provider that resolves custom editors. * @param options Options for the provider. * - * @return Disposable that unregisters the provider. + * @returns Disposable that unregisters the provider. */ function registerCustomEditorProvider(viewType:String, provider:EitherType, CustomEditorProvider>>, ?options:{ @@ -871,7 +1186,6 @@ extern class VscodeWindow { * Content settings for the webview panels created for this custom editor. */ final ?webviewOptions:WebviewPanelOptions; - /** * Only applies to `CustomReadonlyEditorProvider | CustomEditorProvider`. * @@ -892,14 +1206,16 @@ extern class VscodeWindow { /** * Register provider that enables the detection and handling of links within the terminal. * @param provider The provider that provides the terminal links. - * @return Disposable that unregisters the provider. + * @returns Disposable that unregisters the provider. */ function registerTerminalLinkProvider(provider:TerminalLinkProvider):Disposable; /** * Registers a provider for a contributed terminal profile. + * * @param id The ID of the contributed terminal profile. * @param provider The terminal profile provider. + * @returns A {@link Disposable disposable} that unregisters the provider. */ function registerTerminalProfileProvider(id:String, provider:TerminalProfileProvider):Disposable; @@ -907,7 +1223,7 @@ extern class VscodeWindow { * Register a file decoration provider. * * @param provider A {@link FileDecorationProvider}. - * @return A {@link Disposable} that unregisters the provider. + * @returns A {@link Disposable} that unregisters the provider. */ function registerFileDecorationProvider(provider:FileDecorationProvider):Disposable; @@ -928,7 +1244,7 @@ extern class VscodeExtensions { * Get an extension by its full identifier in the form of: `publisher.name`. * * @param extensionId An extension identifier. - * @return An extension or `undefined`. + * @returns An extension or `undefined`. */ function getExtension(extensionId:String):Null>; @@ -944,6 +1260,9 @@ extern class VscodeExtensions { var onDidChange(default, null):Event; } +/** + * Namespace for source control mangement. + */ extern class VscodeScm { /** * The {@link SourceControlInputBox input box} for the last source control @@ -960,7 +1279,7 @@ extern class VscodeScm { * @param id An `id` for the source control. Something short, e.g.: `git`. * @param label A human-readable string for the source control. E.g.: `Git`. * @param rootUri An optional Uri of the root of the source control. E.g.: `Uri.parse(workspaceRoot)`. - * @return An instance of {@link SourceControl source control}. + * @returns An instance of {@link SourceControl source control}. */ function createSourceControl(id:String, label:String, ?rootUri:Uri):SourceControl; } @@ -968,7 +1287,7 @@ extern class VscodeScm { extern class VscodeLanguages { /** * Return the identifiers of all known languages. - * @return Promise resolving to an array of identifier strings. + * @returns Promise resolving to an array of identifier strings. */ function getLanguages():Thenable>; @@ -993,10 +1312,10 @@ extern class VscodeLanguages { * 1. When {@linkcode DocumentSelector} is an array, compute the match for each contained `DocumentFilter` or language identifier and take the maximum value. * 2. A string will be desugared to become the `language`-part of a {@linkcode DocumentFilter}, so `"fooLang"` is like `{ language: "fooLang" }`. * 3. A {@linkcode DocumentFilter} will be matched against the document by comparing its parts with the document. The following rules apply: - * 1. When the `DocumentFilter` is empty (`{}`) the result is `0` - * 2. When `scheme`, `language`, or `pattern` are defined but one doesn’t match, the result is `0` - * 3. Matching against `*` gives a score of `5`, matching via equality or via a glob-pattern gives a score of `10` - * 4. The result is the maximum value of each match + * 1. When the `DocumentFilter` is empty (`{}`) the result is `0` + * 2. When `scheme`, `language`, `pattern`, or `notebook` are defined but one doesn't match, the result is `0` + * 3. Matching against `*` gives a score of `5`, matching via equality or via a glob-pattern gives a score of `10` + * 4. The result is the maximum value of each match * * Samples: * ```js @@ -1004,8 +1323,8 @@ extern class VscodeLanguages { * doc.uri; //'file:///my/file.js' * doc.languageId; // 'javascript' * match('javascript', doc); // 10; - * match({language: 'javascript'}, doc); // 10; - * match({language: 'javascript', scheme: 'file'}, doc); // 10; + * match({ language: 'javascript' }, doc); // 10; + * match({ language: 'javascript', scheme: 'file' }, doc); // 10; * match('*', doc); // 5 * match('fooLang', doc); // 0 * match(['fooLang', '*'], doc); // 5 @@ -1014,13 +1333,21 @@ extern class VscodeLanguages { * doc.uri; // 'git:/my/file.js' * doc.languageId; // 'javascript' * match('javascript', doc); // 10; - * match({language: 'javascript', scheme: 'git'}, doc); // 10; + * match({ language: 'javascript', scheme: 'git' }, doc); // 10; * match('*', doc); // 5 + * + * // notebook cell document + * doc.uri; // `vscode-notebook-cell:///my/notebook.ipynb#gl65s2pmha`; + * doc.languageId; // 'python' + * match({ notebookType: 'jupyter-notebook' }, doc) // 10 + * match({ notebookType: 'fooNotebook', language: 'python' }, doc) // 0 + * match({ language: 'python' }, doc) // 10 + * match({ notebookType: '*' }, doc) // 5 * ``` * * @param selector A document selector. * @param document A text document. - * @return A number `>0` when the selector matches and `0` when the selector does not match. + * @returns A number `>0` when the selector matches and `0` when the selector does not match. */ function match(selector:DocumentSelector, document:TextDocument):Float; @@ -1035,24 +1362,33 @@ extern class VscodeLanguages { * * @param resource A resource * @returns An array of {@link Diagnostic diagnostics} objects or an empty array. - * - * OR - * + */ + overload function getDiagnostics(resource:Uri):Array; + + /** * Get all diagnostics. * * @returns An array of uri-diagnostics tuples or an empty array. */ - @:overload(function(resource:Uri):Array {}) - function getDiagnostics():Array; + overload function getDiagnostics():Array; /** * Create a diagnostics collection. * * @param name The {@link DiagnosticCollection.name name} of the collection. - * @return A new diagnostic collection. + * @returns A new diagnostic collection. */ function createDiagnosticCollection(?name:String):DiagnosticCollection; + /** + * Creates a new {@link LanguageStatusItem language status item}. + * + * @param id The identifier of the item. + * @param selector The document selector that defines for what editors the item shows. + * @returns A new language status item. + */ + function createLanguageStatusItem(id:String, selector:DocumentSelector):LanguageStatusItem; + /** * Register a completion provider. * @@ -1070,11 +1406,24 @@ extern class VscodeLanguages { * @param selector A selector that defines the documents this provider is applicable to. * @param provider A completion provider. * @param triggerCharacters Trigger completion when the user types one of the characters. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerCompletionItemProvider(selector:DocumentSelector, provider:CompletionItemProvider, triggerCharacters:Rest):Disposable; + /** + * Registers an inline completion provider. + * + * Multiple providers can be registered for a language. In that case providers are asked in + * parallel and the results are merged. A failing provider (rejected promise or exception) will + * not cause a failure of the whole operation. + * + * @param selector A selector that defines the documents this provider is applicable to. + * @param provider An inline completion provider. + * @returns A {@link Disposable} that unregisters this provider when being disposed. + */ + function registerInlineCompletionItemProvider(selector:DocumentSelector, provider:InlineCompletionItemProvider):Disposable; + /** * Register a code action provider. * @@ -1085,7 +1434,7 @@ extern class VscodeLanguages { * @param selector A selector that defines the documents this provider is applicable to. * @param provider A code action provider. * @param metadata Metadata about the kind of code actions the provider provides. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerCodeActionsProvider(selector:DocumentSelector, provider:CodeActionProvider, ?metadata:CodeActionProviderMetadata):Disposable; @@ -1099,7 +1448,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A code lens provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerCodeLensProvider(selector:DocumentSelector, provider:CodeLensProvider):Disposable; @@ -1112,7 +1461,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A definition provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerDefinitionProvider(selector:DocumentSelector, provider:DefinitionProvider):Disposable; @@ -1125,7 +1474,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider An implementation provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerImplementationProvider(selector:DocumentSelector, provider:ImplementationProvider):Disposable; @@ -1138,7 +1487,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A type definition provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerTypeDefinitionProvider(selector:DocumentSelector, provider:TypeDefinitionProvider):Disposable; @@ -1151,7 +1500,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A declaration provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerDeclarationProvider(selector:DocumentSelector, provider:DeclarationProvider):Disposable; @@ -1164,7 +1513,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A hover provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerHoverProvider(selector:DocumentSelector, provider:HoverProvider):Disposable; @@ -1176,7 +1525,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider An evaluatable expression provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerEvaluatableExpressionProvider(selector:DocumentSelector, provider:EvaluatableExpressionProvider):Disposable; @@ -1191,7 +1540,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider An inline values provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerInlineValuesProvider(selector:DocumentSelector, provider:InlineValuesProvider):Disposable; @@ -1204,7 +1553,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A document highlight provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerDocumentHighlightProvider(selector:DocumentSelector, provider:DocumentHighlightProvider):Disposable; @@ -1218,7 +1567,7 @@ extern class VscodeLanguages { * @param selector A selector that defines the documents this provider is applicable to. * @param provider A document symbol provider. * @param metaData metadata about the provider - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerDocumentSymbolProvider(selector:DocumentSelector, provider:DocumentSymbolProvider, ?metaData:DocumentSymbolProviderMetadata):Disposable; @@ -1230,7 +1579,7 @@ extern class VscodeLanguages { * a failure of the whole operation. * * @param provider A workspace symbol provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerWorkspaceSymbolProvider(provider:WorkspaceSymbolProvider):Disposable; @@ -1243,7 +1592,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A reference provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerReferenceProvider(selector:DocumentSelector, provider:ReferenceProvider):Disposable; @@ -1256,7 +1605,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A rename provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerRenameProvider(selector:DocumentSelector, provider:RenameProvider):Disposable; @@ -1269,10 +1618,9 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A document semantic tokens provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ - function registerDocumentSemanticTokensProvider(selector:DocumentSelector, provider:DocumentSemanticTokensProvider, - legend:SemanticTokensLegend):Disposable; + function registerDocumentSemanticTokensProvider(selector:DocumentSelector, provider:DocumentSemanticTokensProvider, legend:SemanticTokensLegend):Disposable; /** * Register a semantic tokens provider for a document range. @@ -1289,7 +1637,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A document range semantic tokens provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerDocumentRangeSemanticTokensProvider(selector:DocumentSelector, provider:DocumentRangeSemanticTokensProvider, legend:SemanticTokensLegend):Disposable; @@ -1303,7 +1651,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A document formatting edit provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerDocumentFormattingEditProvider(selector:DocumentSelector, provider:DocumentFormattingEditProvider):Disposable; @@ -1320,7 +1668,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A document range formatting edit provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerDocumentRangeFormattingEditProvider(selector:DocumentSelector, provider:DocumentRangeFormattingEditProvider):Disposable; @@ -1335,7 +1683,7 @@ extern class VscodeLanguages { * @param provider An on type formatting edit provider. * @param firstTriggerCharacter A character on which formatting should be triggered, like `}`. * @param moreTriggerCharacter More trigger characters. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerOnTypeFormattingEditProvider(selector:DocumentSelector, provider:OnTypeFormattingEditProvider, firstTriggerCharacter:String, moreTriggerCharacter:Rest):Disposable; @@ -1350,11 +1698,20 @@ extern class VscodeLanguages { * @param selector A selector that defines the documents this provider is applicable to. * @param provider A signature help provider. * @param triggerCharacters Trigger signature help when the user types one of the characters, like `,` or `(`. + * @returns A {@link Disposable} that unregisters this provider when being disposed. + */ + overload function registerSignatureHelpProvider(selector:DocumentSelector, provider:SignatureHelpProvider, triggerCharacters:Rest):Disposable; + + /** + * @see {@link languages.registerSignatureHelpProvider} + * + * @param selector A selector that defines the documents this provider is applicable to. + * @param provider A signature help provider. * @param metadata Information about the provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ - @:overload(function(selector:DocumentSelector, provider:SignatureHelpProvider, triggerCharacters:Rest):Disposable {}) - function registerSignatureHelpProvider(selector:DocumentSelector, provider:SignatureHelpProvider, metadata:SignatureHelpProviderMetadata):Disposable; + overload function registerSignatureHelpProvider(selector:DocumentSelector, provider:SignatureHelpProvider, + metadata:SignatureHelpProviderMetadata):Disposable; /** * Register a document link provider. @@ -1365,7 +1722,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A document link provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerDocumentLinkProvider(selector:DocumentSelector, provider:DocumentLinkProvider):Disposable; @@ -1378,10 +1735,23 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A color provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerColorProvider(selector:DocumentSelector, provider:DocumentColorProvider):Disposable; + /** + * Register a inlay hints provider. + * + * Multiple providers can be registered for a language. In that case providers are asked in + * parallel and the results are merged. A failing provider (rejected promise or exception) will + * not cause a failure of the whole operation. + * + * @param selector A selector that defines the documents this provider is applicable to. + * @param provider An inlay hints provider. + * @returns A {@link Disposable} that unregisters this provider when being disposed. + */ + function registerInlayHintsProvider(selector:DocumentSelector, provider:InlayHintsProvider):Disposable; + /** * Register a folding range provider. * @@ -1395,7 +1765,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A folding range provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerFoldingRangeProvider(selector:DocumentSelector, provider:FoldingRangeProvider):Disposable; @@ -1408,7 +1778,7 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A selection range provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerSelectionRangeProvider(selector:DocumentSelector, provider:SelectionRangeProvider):Disposable; @@ -1417,10 +1787,19 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A call hierarchy provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerCallHierarchyProvider(selector:DocumentSelector, provider:CallHierarchyProvider):Disposable; + /** + * Register a type hierarchy provider. + * + * @param selector A selector that defines the documents this provider is applicable to. + * @param provider A type hierarchy provider. + * @returns A {@link Disposable} that unregisters this provider when being disposed. + */ + function registerTypeHierarchyProvider(selector:DocumentSelector, provider:TypeHierarchyProvider):Disposable; + /** * Register a linked editing range provider. * @@ -1430,16 +1809,26 @@ extern class VscodeLanguages { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A linked editing range provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerLinkedEditingRangeProvider(selector:DocumentSelector, provider:LinkedEditingRangeProvider):Disposable; + /** + * Registers a new {@link DocumentDropEditProvider}. + * + * @param selector A selector that defines the documents this provider applies to. + * @param provider A drop provider. + * + * @returns A {@link Disposable} that unregisters this provider when disposed of. + */ + function registerDocumentDropEditProvider(selector:DocumentSelector, provider:DocumentDropEditProvider):Disposable; + /** * Set a {@link LanguageConfiguration language configuration} for a language. * * @param language A language identifier like `typescript`. * @param configuration Language configuration. - * @return A {@link Disposable} that unsets this configuration. + * @returns A {@link Disposable} that unsets this configuration. */ function setLanguageConfiguration(language:String, configuration:LanguageConfiguration):Disposable; } @@ -1519,6 +1908,11 @@ extern class VscodeWorkspace { /** * An event that is emitted when a workspace folder is added or removed. + * + * **Note:** this event will not fire if the first workspace folder is added, removed or changed, + * because in that case the currently executing extensions (including the one that listens to this + * event) will be terminated and restarted so that the (deprecated) `rootPath` property is updated + * to point to the first workspace folder. */ var onDidChangeWorkspaceFolders(default, null):Event; @@ -1528,7 +1922,7 @@ extern class VscodeWorkspace { * * returns the *input* when the given uri is a workspace folder itself * * @param uri An uri. - * @return A workspace folder or `undefined` + * @returns A workspace folder or `undefined` */ function getWorkspaceFolder(uri:Uri):Null; @@ -1542,7 +1936,7 @@ extern class VscodeWorkspace { * @param includeWorkspaceFolder When `true` and when the given path is contained inside a * workspace folder the name of the workspace is prepended. Defaults to `true` when there are * multiple workspace folders and `false` otherwise. - * @return A path relative to the root or the input. + * @returns A path relative to the root or the input. */ function asRelativePath(pathOrUri:EitherType, ?includeWorkspaceFolder:Bool):String; @@ -1551,9 +1945,11 @@ extern class VscodeWorkspace { * by an optional set of `workspaceFoldersToAdd` on the `vscode.workspace.workspaceFolders` array. This "splice" * behavior can be used to add, remove and change workspace folders in a single operation. * - * If the first workspace folder is added, removed or changed, the currently executing extensions (including the - * one that called this method) will be terminated and restarted so that the (deprecated) `rootPath` property is - * updated to point to the first workspace folder. + * **Note:** in some cases calling this method may result in the currently executing extensions (including the + * one that called this method) to be terminated and restarted. For example when the first workspace folder is + * added, removed or changed the (deprecated) `rootPath` property is updated to point to the first workspace + * folder. Another case is when transitioning from an empty or single-folder workspace into a multi-folder + * workspace (see also: https://code.visualstudio.com/docs/editor/workspaces). * * Use the {@linkcode onDidChangeWorkspaceFolders onDidChangeWorkspaceFolders()} event to get notified when the * workspace folders have been updated. @@ -1584,27 +1980,123 @@ extern class VscodeWorkspace { * @param deleteCount the optional number of workspace folders to remove. * @param workspaceFoldersToAdd the optional variable set of workspace folders to add in place of the deleted ones. * Each workspace is identified with a mandatory URI and an optional name. - * @return true if the operation was successfully started and false otherwise if arguments were used that would result + * @returns true if the operation was successfully started and false otherwise if arguments were used that would result * in invalid workspace folder state (e.g. 2 folders with the same URI). */ - function updateWorkspaceFolders(start:Int, deleteCount:Null, workspaceFoldersToAdd:Rest<{uri:Uri, ?name:String}>):Bool; + function updateWorkspaceFolders(start:Int, deleteCount:Null, workspaceFoldersToAdd:Rest<{ + /** + * The uri of a workspace folder that's to be added. + */ + uri:Uri, + /** + * The name of a workspace folder that's to be added. + */ + ?name:String + }>):Bool; /** - * Creates a file system watcher. + * Creates a file system watcher that is notified on file events (create, change, delete) + * depending on the parameters provided. + * + * By default, all opened {@link workspace.workspaceFolders workspace folders} will be watched + * for file changes recursively. * - * A glob pattern that filters the file events on their absolute path must be provided. Optionally, - * flags to ignore certain kinds of events can be provided. To stop listening to events the watcher must be disposed. + * Additional paths can be added for file watching by providing a {@link RelativePattern} with + * a `base` path to watch. If the path is a folder and the `pattern` is complex (e.g. contains + * `**` or path segments), it will be watched recursively and otherwise will be watched + * non-recursively (i.e. only changes to the first level of the path will be reported). * - * *Note* that only files within the current {@link workspace.workspaceFolders workspace folders} can be watched. - * *Note* that when watching for file changes such as '**​/*.js', notifications will not be sent when a parent folder is - * moved or deleted (this is a known limitation of the current implementation and may change in the future). + * *Note* that paths that do not exist in the file system will be monitored with a delay until + * created and then watched depending on the parameters provided. If a watched path is deleted, + * the watcher will suspend and not report any events until the path is created again. + * + * If possible, keep the use of recursive watchers to a minimum because recursive file watching + * is quite resource intense. + * + * Providing a `string` as `globPattern` acts as convenience method for watching file events in + * all opened workspace folders. It cannot be used to add more folders for file watching, nor will + * it report any file events from folders that are not part of the opened workspace folders. + * + * Optionally, flags to ignore certain kinds of events can be provided. + * + * To stop listening to events the watcher must be disposed. + * + * *Note* that file events from recursive file watchers may be excluded based on user configuration. + * The setting `files.watcherExclude` helps to reduce the overhead of file events from folders + * that are known to produce many file changes at once (such as `.git` folders). As such, + * it is highly recommended to watch with simple patterns that do not require recursive watchers + * where the exclude settings are ignored and you have full control over the events. + * + * *Note* that symbolic links are not automatically followed for file watching unless the path to + * watch itself is a symbolic link. + * + * *Note* that the file paths that are reported for having changed may have a different path casing + * compared to the actual casing on disk on case-insensitive platforms (typically macOS and Windows + * but not Linux). We allow a user to open a workspace folder with any desired path casing and try + * to preserve that. This means: + * * if the path is within any of the workspace folders, the path will match the casing of the + * workspace folder up to that portion of the path and match the casing on disk for children + * * if the path is outside of any of the workspace folders, the casing will match the case of the + * path that was provided for watching + * In the same way, symbolic links are preserved, i.e. the file event will report the path of the + * symbolic link as it was provided for watching and not the target. + * + * ### Examples + * + * The basic anatomy of a file watcher is as follows: + * + * ```ts + * const watcher = vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(, )); + * + * watcher.onDidChange(uri => { ... }); // listen to files being changed + * watcher.onDidCreate(uri => { ... }); // listen to files/folders being created + * watcher.onDidDelete(uri => { ... }); // listen to files/folders getting deleted + * + * watcher.dispose(); // dispose after usage + * ``` * - * @param globPattern A {@link GlobPattern glob pattern} that is applied to the absolute paths of created, changed, - * and deleted files. Use a {@link RelativePattern relative pattern} to limit events to a certain {@link WorkspaceFolder workspace folder}. + * #### Workspace file watching + * + * If you only care about file events in a specific workspace folder: + * + * ```ts + * vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(vscode.workspace.workspaceFolders[0], '**​/*.js')); + * ``` + * + * If you want to monitor file events across all opened workspace folders: + * + * ```ts + * vscode.workspace.createFileSystemWatcher('**​/*.js'); + * ``` + * + * *Note:* the array of workspace folders can be empty if no workspace is opened (empty window). + * + * #### Out of workspace file watching + * + * To watch a folder for changes to *.js files outside the workspace (non recursively), pass in a `Uri` to such + * a folder: + * + * ```ts + * vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(vscode.Uri.file(), '*.js')); + * ``` + * + * And use a complex glob pattern to watch recursively: + * + * ```ts + * vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(vscode.Uri.file(), '**​/*.js')); + * ``` + * + * Here is an example for watching the active editor for file changes: + * + * ```ts + * vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(vscode.window.activeTextEditor.document.uri, '*')); + * ``` + * + * @param globPattern A {@link GlobPattern glob pattern} that controls which file events the watcher should report. * @param ignoreCreateEvents Ignore when files have been created. * @param ignoreChangeEvents Ignore when files have been changed. * @param ignoreDeleteEvents Ignore when files have been deleted. - * @return A new file system watcher instance. + * @returns A new file system watcher instance. Must be disposed when no longer needed. */ function createFileSystemWatcher(globPattern:GlobPattern, ?ignoreCreateEvents:Bool, ?ignoreChangeEvents:Bool, ?ignoreDeleteEvents:Bool):FileSystemWatcher; @@ -1618,20 +2110,44 @@ extern class VscodeWorkspace { * will be matched against the file paths of resulting matches relative to their workspace. Use a {@link RelativePattern relative pattern} * to restrict the search results to a {@link WorkspaceFolder workspace folder}. * @param exclude A {@link GlobPattern glob pattern} that defines files and folders to exclude. The glob pattern - * will be matched against the file paths of resulting matches relative to their workspace. When `undefined`, default excludes and the user's - * configured excludes will apply. When `null`, no excludes will apply. + * will be matched against the file paths of resulting matches relative to their workspace. When `undefined`, default file-excludes (e.g. the `files.exclude`-setting + * but not `search.exclude`) will apply. When `null`, no excludes will apply. * @param maxResults An upper-bound for the result. * @param token A token that can be used to signal cancellation to the underlying search engine. - * @return A thenable that resolves to an array of resource identifiers. Will return no results if no + * @returns A thenable that resolves to an array of resource identifiers. Will return no results if no * {@link workspace.workspaceFolders workspace folders} are opened. */ function findFiles(include:GlobPattern, ?exclude:Null, ?maxResults:Int, ?token:CancellationToken):Thenable>; + /** + * Saves the editor identified by the given resource and returns the resulting resource or `undefined` + * if save was not successful or no editor with the given resource was found. + * + * **Note** that an editor with the provided resource must be opened in order to be saved. + * + * @param uri the associated uri for the opened editor to save. + * @returns A thenable that resolves when the save operation has finished. + */ + function save(uri:Uri):Thenable>; + + /** + * Saves the editor identified by the given resource to a new file name as provided by the user and + * returns the resulting resource or `undefined` if save was not successful or cancelled or no editor + * with the given resource was found. + * + * **Note** that an editor with the provided resource must be opened in order to be saved as. + * + * @param uri the associated uri for the opened editor to save as. + * @returns A thenable that resolves when the save-as operation has finished. + */ + function saveAs(uri:Uri):Thenable>; + /** * Save all dirty files. * * @param includeUntitled Also save files that have been created during this session. - * @return A thenable that resolves when the files have been saved. + * @returns A thenable that resolves when the files have been saved. Will return `false` + * for any file that failed to save. */ function saveAll(?includeUntitled:Bool):Thenable; @@ -1649,9 +2165,10 @@ extern class VscodeWorkspace { * not be attempted, when a single edit fails. * * @param edit A workspace edit. - * @return A thenable that resolves when the edit could be applied. + * @param metadata Optional {@link WorkspaceEditMetadata metadata} for the edit. + * @returns A thenable that resolves when the edit could be applied. */ - function applyEdit(edit:WorkspaceEdit):Thenable; + function applyEdit(edit:WorkspaceEdit, ?metadata:WorkspaceEditMetadata):Thenable; /** * All text documents currently known to the editor. @@ -1674,24 +2191,38 @@ extern class VscodeWorkspace { * *Note* that the lifecycle of the returned document is owned by the editor and not by the extension. That means an * {@linkcode workspace.onDidCloseTextDocument onDidClose}-event can occur at any time after opening it. * - * --- - * - * A short-hand for `openTextDocument(Uri.file(fileName))`. - * - * --- + * @param uri Identifies the resource to open. + * @returns A promise that resolves to a {@link TextDocument document}. + */ + overload function openTextDocument(uri:Uri):Thenable; + + /** + * A short-hand for `openTextDocument(Uri.file(path))`. * + * @see {@link workspace.openTextDocument} + * @param path A path of a file on disk. + * @returns A promise that resolves to a {@link TextDocument document}. + */ + overload function openTextDocument(path:String):Thenable; + + /** * Opens an untitled text document. The editor will prompt the user for a file * path when the document is to be saved. The `options` parameter allows to * specify the *language* and/or the *content* of the document. * - * @param uri Identifies the resource to open. - * @param fileName A name of a file on disk. * @param options Options to control how the document will be created. - * @return A promise that resolves to a {@link TextDocument document}. + * @returns A promise that resolves to a {@link TextDocument document}. */ - @:overload(function(?options:{?language:String, ?content:String}):Thenable {}) - @:overload(function(fileName:String):Thenable {}) - function openTextDocument(uri:Uri):Thenable; + overload function openTextDocument(?options:{ + /** + * The {@link TextDocument.languageId language} of the document. + */ + ?language:String, + /** + * The initial contents of the document. + */ + ?content:String + }):Thenable; /** * Register a text document content provider. @@ -1700,7 +2231,7 @@ extern class VscodeWorkspace { * * @param scheme The uri-scheme to register for. * @param provider A content provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerTextDocumentContentProvider(scheme:String, provider:TextDocumentContentProvider):Disposable; @@ -1763,27 +2294,55 @@ extern class VscodeWorkspace { var notebookDocuments(default, null):ReadOnlyArray; /** - * Open a notebook. Will return early if this notebook is already {@link notebook.notebookDocuments loaded}. Otherwise - * the notebook is loaded and the {@linkcode notebook.onDidOpenNotebookDocument onDidOpenNotebookDocument}-event fires. + * Open a notebook. Will return early if this notebook is already {@link notebookDocuments loaded}. Otherwise + * the notebook is loaded and the {@linkcode onDidOpenNotebookDocument}-event fires. * * *Note* that the lifecycle of the returned notebook is owned by the editor and not by the extension. That means an - * {@linkcode notebook.onDidCloseNotebookDocument onDidCloseNotebookDocument}-event can occur at any time after. + * {@linkcode onDidCloseNotebookDocument}-event can occur at any time after. * * *Note* that opening a notebook does not show a notebook editor. This function only returns a notebook document which - * can be showns in a notebook editor but it can also be used for other things. - * - * --- + * can be shown in a notebook editor but it can also be used for other things. * + * @param uri The resource to open. + * @returns A promise that resolves to a {@link NotebookDocument notebook} + */ + overload function openNotebookDocument(uri:Uri):Thenable; + + /** * Open an untitled notebook. The editor will prompt the user for a file * path when the document is to be saved. * - * @param uri The resource to open. + * @see {@link workspace.openNotebookDocument} * @param notebookType The notebook type that should be used. * @param content The initial contents of the notebook. - * @returns A promise that resolves to a {@link NotebookDocument notebook} + * @returns A promise that resolves to a {@link NotebookDocument notebook}. + */ + overload function openNotebookDocument(notebookType:String, ?content:NotebookData):Thenable; + + /** + * An event that is emitted when a {@link NotebookDocument notebook} has changed. + */ + final onDidChangeNotebookDocument:Event; + + /** + * An event that is emitted when a {@link NotebookDocument notebook document} will be saved to disk. + * + * *Note 1:* Subscribers can delay saving by registering asynchronous work. For the sake of data integrity the editor + * might save without firing this event. For instance when shutting down with dirty files. + * + * *Note 2:* Subscribers are called sequentially and they can {@link NotebookDocumentWillSaveEvent.waitUntil delay} saving + * by registering asynchronous work. Protection against misbehaving listeners is implemented as such: + * * there is an overall time budget that all listeners share and if that is exhausted no further listener is called + * * listeners that take a long time or produce errors frequently will not be called anymore + * + * The current thresholds are 1.5 seconds as overall time budget and a listener can misbehave 3 times before being ignored. */ - @:overload(function(notebookType:String, ?content:NotebookData):Thenable {}) - function openNotebookDocument(uri:Uri):Thenable; + final onWillSaveNotebookDocument:Event; + + /** + * An event that is emitted when a {@link NotebookDocument notebook} is saved. + */ + final onDidSaveNotebookDocument:Event; /** * Register a {@link NotebookSerializer notebook serializer}. @@ -1794,7 +2353,7 @@ extern class VscodeWorkspace { * @param notebookType A notebook. * @param serializer A notebook serialzier. * @param options Optional context options that define what parts of a notebook should be persisted - * @return A {@link Disposable} that unregisters this serializer when being disposed. + * @returns A {@link Disposable} that unregisters this serializer when being disposed. */ function registerNotebookSerializer(notebookType:String, serializer:NotebookSerializer, ?options:NotebookDocumentContentOptions):Disposable; @@ -1894,7 +2453,7 @@ extern class VscodeWorkspace { * * @param section A dot-separated identifier. * @param scope A scope for which the configuration is asked for. - * @return The full configuration or a subset. + * @returns The full configuration or a subset. */ function getConfiguration(?section:String, ?scope:Null):WorkspaceConfiguration; @@ -1910,7 +2469,7 @@ extern class VscodeWorkspace { * * @param type The task kind type this provider is registered for. * @param provider A task provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ @:deprecated("Use the corresponding function on the `tasks` namespace instead") function registerTaskProvider(type:String, provider:TaskProvider):Disposable; @@ -1924,10 +2483,19 @@ extern class VscodeWorkspace { * @param scheme The uri-{@link Uri.scheme scheme} the provider registers for. * @param provider The filesystem provider. * @param options Immutable metadata about the provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ - function registerFileSystemProvider(scheme:String, provider:FileSystemProvider, - options:{var ?isCaseSensitive(default, null):Bool; var ?isReadonly(default, null):Bool;}):Disposable; + function registerFileSystemProvider(scheme:String, provider:FileSystemProvider, options:{ + /** + * Whether the file system provider use case sensitive compare for {@link Uri.path paths} + */ + var ?isCaseSensitive(default, null):Bool; + /** + * Whether the file system provider is readonly, no modifications like write, delete, create are possible. + * If a {@link MarkdownString} is given, it will be shown as the reason why the file system is readonly. + */ + var ?isReadonly(default, null):Bool; + }):Disposable; /** * When true, the user has explicitly trusted the contents of the workspace. @@ -1940,6 +2508,9 @@ extern class VscodeWorkspace { var onDidGrantWorkspaceTrust(default, null):Event; } +/** + * Namespace for debug functionality. + */ extern class VscodeDebug { /** * The currently active {@link DebugSession debug session} or `undefined`. The active debug session is the one @@ -1957,7 +2528,7 @@ extern class VscodeDebug { /** * List of breakpoints. */ - var breakpoints:Array; + var breakpoints:ReadOnlyArray; /** * An {@link Event} which fires when the {@link debug.activeDebugSession active debug session} @@ -1986,6 +2557,19 @@ extern class VscodeDebug { */ var onDidChangeBreakpoints(default, null):Event; + /** + * The currently focused thread or stack frame, or `undefined` if no + * thread or stack is focused. A thread can be focused any time there is + * an active debug session, while a stack frame can only be focused when + * a session is paused and the call stack has been retrieved. + */ + var activeStackItem:Null>; + + /** + * An event which fires when the {@link debug.activeStackItem} has changed. + */ + var onDidChangeActiveStackItem:Event>>; + /** * Register a {@link DebugConfigurationProvider debug configuration provider} for a specific debug type. * The optional {@link DebugConfigurationProviderTriggerKind triggerKind} can be used to specify when the `provideDebugConfigurations` method of the provider is triggered. @@ -1995,10 +2579,10 @@ extern class VscodeDebug { * Registering a single provider with resolve methods for different trigger kinds, results in the same resolve methods called multiple times. * More than one provider can be registered for the same type. * - * @param type The debug type for which the provider is registered. + * @param debugType The debug type for which the provider is registered. * @param provider The {@link DebugConfigurationProvider debug configuration provider} to register. - * @param triggerKind The {@link DebugConfigurationProviderTrigger trigger} for which the 'provideDebugConfiguration' method of the provider is registered. If `triggerKind` is missing, the value `DebugConfigurationProviderTriggerKind.Initial` is assumed. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @param triggerKind The {@link DebugConfigurationProviderTriggerKind trigger} for which the 'provideDebugConfiguration' method of the provider is registered. If `triggerKind` is missing, the value `DebugConfigurationProviderTriggerKind.Initial` is assumed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerDebugConfigurationProvider(debugType:String, provider:DebugConfigurationProvider, ?triggerKind:DebugConfigurationProviderTriggerKind):Disposable; @@ -2010,7 +2594,7 @@ extern class VscodeDebug { * * @param debugType The debug type for which the factory is registered. * @param factory The {@link DebugAdapterDescriptorFactory debug adapter descriptor factory} to register. - * @return A {@link Disposable} that unregisters this factory when being disposed. + * @returns A {@link Disposable} that unregisters this factory when being disposed. */ function registerDebugAdapterDescriptorFactory(debugType:String, factory:DebugAdapterDescriptorFactory):Disposable; @@ -2019,7 +2603,7 @@ extern class VscodeDebug { * * @param debugType The debug type for which the factory is registered or '*' for matching all debug types. * @param factory The {@link DebugAdapterTrackerFactory debug adapter tracker factory} to register. - * @return A {@link Disposable} that unregisters this factory when being disposed. + * @returns A {@link Disposable} that unregisters this factory when being disposed. */ function registerDebugAdapterTrackerFactory(debugType:String, factory:DebugAdapterTrackerFactory):Disposable; @@ -2032,14 +2616,16 @@ extern class VscodeDebug { * @param folder The {@link WorkspaceFolder workspace folder} for looking up named configurations and resolving variables or `undefined` for a non-folder setup. * @param nameOrConfiguration Either the name of a debug or compound configuration or a {@link DebugConfiguration} object. * @param parentSessionOrOptions Debug session options. When passed a parent {@link DebugSession debug session}, assumes options with just this parent session. - * @return A thenable that resolves when debugging could be successfully started. + * @returns A thenable that resolves when debugging could be successfully started. */ function startDebugging(folder:Null, nameOrConfiguration:EitherType, ?parentSessionOrOptions:EitherType):Thenable; /** * Stop the given debug session or stop all debug sessions if session is omitted. + * * @param session The {@link DebugSession debug session} to stop; if omitted all sessions are stopped. + * @returns A thenable that resolves when the session(s) have been stopped. */ function stopDebugging(?session:DebugSession):Thenable; @@ -2064,7 +2650,7 @@ extern class VscodeDebug { * * @param source An object conforming to the [Source](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source) type defined in the Debug Adapter Protocol. * @param session An optional debug session that will be used when the source descriptor uses a reference number to load the contents from an active debug session. - * @return A uri that can be used to load the contents of the source. + * @returns A uri that can be used to load the contents of the source. */ function asDebugSourceUri(source:DebugProtocolSource, ?session:DebugSession):Uri; } @@ -2085,13 +2671,16 @@ abstract VscodeLanguagesGetDiagnosticsReturn(Array) { return this[1]; } +/** + * Namespace for tasks functionality. + */ extern class VscodeTasks { /** * Register a task provider. * * @param type The task kind type this provider is registered for. * @param provider A task provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerTaskProvider(type:String, provider:TaskProvider):Disposable; @@ -2101,6 +2690,7 @@ extern class VscodeTasks { * contributed through extensions. * * @param filter Optional filter to select tasks of a certain type or version. + * @returns A thenable that resolves to an array of tasks. */ function fetchTasks(?filter:TaskFilter):Thenable>; @@ -2113,6 +2703,7 @@ extern class VscodeTasks { * In such an environment, only CustomExecution tasks can be run. * * @param task the task to execute + * @returns A thenable that resolves to a task execution. */ function executeTask(task:Task):Thenable; @@ -2146,13 +2737,16 @@ extern class VscodeTasks { var onDidEndTaskProcess(default, null):Event; } +/** + * Namespace for authentication. + */ extern class VscodeComments { /** * Creates a new {@link CommentController comment controller} instance. * * @param id An `id` for the comment controller. * @param label A human-readable string for the comment controller. - * @return An instance of {@link CommentController comment controller}. + * @returns An instance of {@link CommentController comment controller}. */ function createCommentController(id:String, label:String):CommentController; } @@ -2168,12 +2762,25 @@ extern class VscodeAuthentication { * to the editor that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'. * @param providerId The id of the provider to use * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider - * @param options The {@link GetSessionOptions} to use - * @returns A thenable that resolves to an authentication session + * @param options The {@link AuthenticationGetSessionOptions} to use + * @returns A thenable that resolves to an authentication session if available, or undefined if there are no sessions + */ + overload function getSession(providerId:String, scopes:ReadOnlyArray, + ?options:AuthenticationGetSessionOptions):Thenable>; + + /** + * Get all accounts that the user is logged in to for the specified provider. + * Use this paired with {@link getSession} in order to get an authentication session for a specific account. + * + * Currently, there are only two authentication providers that are contributed from built in extensions + * to the editor that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'. + * + * Note: Getting accounts does not imply that your extension has access to that account or its authentication sessions. You can verify access to the account by calling {@link getSession}. + * + * @param providerId The id of the provider to use + * @returns A thenable that resolves to a readonly array of authentication accounts. */ - @:overload(function(providerId:String, scopes:ReadOnlyArray, ?options:AuthenticationGetSessionOptions):Thenable> {}) - function getSession(providerId:String, scopes:ReadOnlyArray, - options:AuthenticationGetSessionOptions & {createIfNone:Bool}):Thenable; + function getAccounts(providerId:String):Thenable>; /** * An {@link Event} which fires when the authentication sessions of an authentication provider have @@ -2190,12 +2797,107 @@ extern class VscodeAuthentication { * @param id The unique identifier of the provider. * @param label The human-readable name of the provider. * @param provider The authentication provider provider. - * @params options Additional options for the provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @param options Additional options for the provider. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerAuthenticationProvider(id:String, label:String, provider:AuthenticationProvider, ?options:AuthenticationProviderOptions):Disposable; } +/** + * Namespace for localization-related functionality in the extension API. To use this properly, + * you must have `l10n` defined in your extension manifest and have bundle.l10n..json files. + * For more information on how to generate bundle.l10n..json files, check out the + * [vscode-l10n repo](https://github.com/microsoft/vscode-l10n). + * + * Note: Built-in extensions (for example, Git, TypeScript Language Features, GitHub Authentication) + * are excluded from the `l10n` property requirement. In other words, they do not need to specify + * a `l10n` in the extension manifest because their translated strings come from Language Packs. + */ +extern class VscodeL10n { + /** + * Marks a string for localization. If a localized bundle is available for the language specified by + * {@link env.language} and the bundle has a localized value for this message, then that localized + * value will be returned (with injected {@link args} values for any templated values). + * + * @param message - The message to localize. Supports index templating where strings like `{0}` and `{1}` are + * replaced by the item at that index in the {@link args} array. + * @param args - The arguments to be used in the localized string. The index of the argument is used to + * match the template placeholder in the localized string. + * @returns localized string with injected arguments. + * + * @example + * l10n.t('Hello {0}!', 'World'); + */ + overload function t(message:String, ...args:Array>>>):String; + + /** + * Marks a string for localization. If a localized bundle is available for the language specified by + * {@link env.language} and the bundle has a localized value for this message, then that localized + * value will be returned (with injected {@link args} values for any templated values). + * + * @param message The message to localize. Supports named templating where strings like `{foo}` and `{bar}` are + * replaced by the value in the Record for that key (foo, bar, etc). + * @param args The arguments to be used in the localized string. The name of the key in the record is used to + * match the template placeholder in the localized string. + * @returns localized string with injected arguments. + * + * @example + * l10n.t('Hello {name}', { name: 'Erich' }); + */ + overload function t(message:String, args:Record):String; + + /** + * Marks a string for localization. If a localized bundle is available for the language specified by + * {@link env.language} and the bundle has a localized value for this message, then that localized + * value will be returned (with injected args values for any templated values). + * + * @param options The options to use when localizing the message. + * @returns localized string with injected arguments. + */ + overload function t(options:{ + /** + * The message to localize. If {@link options.args args} is an array, this message supports index templating where strings like + * `{0}` and `{1}` are replaced by the item at that index in the {@link options.args args} array. If `args` is a `Record`, + * this supports named templating where strings like `{foo}` and `{bar}` are replaced by the value in + * the Record for that key (foo, bar, etc). + */ + message:String, + /** + * The arguments to be used in the localized string. As an array, the index of the argument is used to + * match the template placeholder in the localized string. As a Record, the key is used to match the template + * placeholder in the localized string. + */ + ?args:EitherType>>>, Record>, + /** + * A comment to help translators understand the context of the message. + */ + comment:EitherType> + }):String; + + /** + * The bundle of localized strings that have been loaded for the extension. + * It's undefined if no bundle has been loaded. The bundle is typically not loaded if + * there was no bundle found or when we are running with the default language. + */ + final bundle:Null>; + + /** + * The URI of the localization bundle that has been loaded for the extension. + * It's undefined if no bundle has been loaded. The bundle is typically not loaded if + * there was no bundle found or when we are running with the default language. + */ + final uri:Null; +} + +/** + * Namespace for notebooks. + * + * The notebooks functionality is composed of three loosely coupled components: + * + * 1. {@link NotebookSerializer} enable the editor to open, show, and save notebooks + * 2. {@link NotebookController} own the execution of notebooks, e.g they create output from code cells. + * 3. NotebookRenderer present notebook output in the editor. They run in a separate context. + */ extern class VscodeNotebooks { /** * Creates a new notebook controller. @@ -2204,6 +2906,7 @@ extern class VscodeNotebooks { * @param notebookType A notebook type for which this controller is for. * @param label The label of the controller. * @param handler The execute-handler of the controller. + * @returns A new notebook controller. */ function createNotebookController(id:String, notebookType:String, label:String, ?handler:(cells:Array, notebook:NotebookDocument, controller:NotebookController) -> Thenable):NotebookController; @@ -2213,7 +2916,7 @@ extern class VscodeNotebooks { * * @param notebookType The notebook type to register for. * @param provider A cell status bar provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. + * @returns A {@link Disposable} that unregisters this provider when being disposed. */ function registerNotebookCellStatusBarItemProvider(notebookType:String, provider:NotebookCellStatusBarItemProvider):Disposable; @@ -2230,6 +2933,12 @@ extern class VscodeNotebooks { function createRendererMessaging(rendererId:String):NotebookRendererMessaging; } +/** + * Namespace for testing functionality. Tests are published by registering + * {@link TestController} instances, then adding {@link TestItem TestItems}. + * Controllers may also describe how to run tests by creating one or more + * {@link TestRunProfile} instances. + */ extern class VscodeTests { /** * Creates a new test controller. @@ -2240,3 +2949,100 @@ extern class VscodeTests { */ function createTestController(id:String, label:String):TestController; } + +/** + * Namespace for chat functionality. Users interact with chat participants by sending messages + * to them in the chat view. Chat participants can respond with markdown or other types of content + * via the {@link ChatResponseStream}. + */ +extern class VscodeChat { + /** + * Create a new {@link ChatParticipant chat participant} instance. + * + * @param id A unique identifier for the participant. + * @param handler A request handler for the participant. + * @returns A new chat participant + */ + function createChatParticipant(id:String, handler:ChatRequestHandler):ChatParticipant; +} + +/** + * Namespace for language model related functionality. + */ +extern class VscodeLm { + /** + * An event that is fired when the set of available chat models changes. + */ + var onDidChangeChatModels:Event; + + /** + * Select chat models by a {@link LanguageModelChatSelector selector}. This can yield multiple or no chat models and + * extensions must handle these cases, esp. when no chat model exists, gracefully. + * + * ```ts + * const models = await vscode.lm.selectChatModels({ family: 'gpt-3.5-turbo' }); + * if (models.length > 0) { + * const [first] = models; + * const response = await first.sendRequest(...) + * // ... + * } else { + * // NO chat models available + * } + * ``` + * + * A selector can be written to broadly match all models of a given vendor or family, or it can narrowly select one model by ID. + * Keep in mind that the available set of models will change over time, but also that prompts may perform differently in + * different models. + * + * *Note* that extensions can hold on to the results returned by this function and use them later. However, when the + * {@link onDidChangeChatModels}-event is fired the list of chat models might have changed and extensions should re-query. + * + * @param selector A chat model selector. When omitted all chat models are returned. + * @returns An array of chat models, can be empty! + */ + function selectChatModels(?selector:LanguageModelChatSelector):Thenable>; + + /** + * Register a LanguageModelTool. The tool must also be registered in the package.json `languageModelTools` contribution + * point. A registered tool is available in the {@link lm.tools} list for any extension to see. But in order for it to + * be seen by a language model, it must be passed in the list of available tools in {@link LanguageModelChatRequestOptions.tools}. + * @returns A {@link Disposable} that unregisters the tool when disposed. + */ + function registerTool(name:String, tool:LanguageModelTool):Disposable; + + /** + * A list of all available tools that were registered by all extensions using {@link lm.registerTool}. They can be called + * with {@link lm.invokeTool} with input that match their declared `inputSchema`. + */ + var tools:ReadOnlyArray; + + /** + * Invoke a tool listed in {@link lm.tools} by name with the given input. The input will be validated against + * the schema declared by the tool + * + * A tool can be invoked by a chat participant, in the context of handling a chat request, or globally by any extension in + * any custom flow. + * + * In the former case, the caller shall pass the + * {@link LanguageModelToolInvocationOptions.toolInvocationToken toolInvocationToken}, which comes with the a + * {@link ChatRequest.toolInvocationToken chat request}. This makes sure the chat UI shows the tool invocation for the + * correct conversation. + * + * A tool {@link LanguageModelToolResult result} is an array of {@link LanguageModelTextPart text-} and + * {@link LanguageModelPromptTsxPart prompt-tsx}-parts. If the tool caller is using `@vscode/prompt-tsx`, it can + * incorporate the response parts into its prompt using a `ToolResult`. If not, the parts can be passed along to the + * {@link LanguageModelChat} via a user message with a {@link LanguageModelToolResultPart}. + * + * If a chat participant wants to preserve tool results for requests across multiple turns, it can store tool results in + * the {@link ChatResult.metadata} returned from the handler and retrieve them on the next turn from + * {@link ChatResponseTurn.result}. + * + * @param name The name of the tool to call. + * @param options The options to use when invoking the tool. + * @param token A cancellation token. See {@link CancellationTokenSource} for how to create one. + * @returns The result of the tool invocation. + */ + function invokeTool(name:String, options:LanguageModelToolInvocationOptions<{}>, ?token:CancellationToken):Thenable; +} + +typedef Record = Map; diff --git a/src/import.hx b/src/import.hx index 8c5c4267..9c08f25d 100644 --- a/src/import.hx +++ b/src/import.hx @@ -4,5 +4,6 @@ import haxe.ds.ReadOnlyArray; import haxe.extern.EitherType; import haxe.extern.Rest; import js.lib.Error; +import js.lib.Iterator.AsyncIterator; import js.lib.Promise; import js.lib.RegExp; diff --git a/src/vscode/AccessibilityInformation.hx b/src/vscode/AccessibilityInformation.hx index 50bbfc51..f40034df 100644 --- a/src/vscode/AccessibilityInformation.hx +++ b/src/vscode/AccessibilityInformation.hx @@ -7,7 +7,7 @@ typedef AccessibilityInformation = { /** * Label to be read out by a screen reader once the item has focus. */ - var label:String; + var label(default, null):String; /** * Role of the widget which defines how a screen reader interacts with it. @@ -15,5 +15,5 @@ typedef AccessibilityInformation = { * If role is not specified the editor will pick the appropriate role automatically. * More about aria roles can be found here https://w3c.github.io/aria/#widget_roles */ - var ?role:String; + var ?role(default, null):String; } diff --git a/src/vscode/AuthenticationForceNewSessionOptions.hx b/src/vscode/AuthenticationForceNewSessionOptions.hx new file mode 100644 index 00000000..e3f85728 --- /dev/null +++ b/src/vscode/AuthenticationForceNewSessionOptions.hx @@ -0,0 +1,14 @@ +package vscode; + +import vscode.CommentOptions; + +/** + * Optional options to be used when calling {@link authentication.getSession} with the flag `forceNewSession`. + */ +typedef AuthenticationForceNewSessionOptions = { + /** + * An optional message that will be displayed to the user when we ask to re-authenticate. Providing additional context + * as to why you are asking a user to re-authenticate can help increase the odds that they will accept. + */ + var ?detail:String; +} diff --git a/src/vscode/AuthenticationGetSessionOptions.hx b/src/vscode/AuthenticationGetSessionOptions.hx index 7c949508..c5577e2b 100644 --- a/src/vscode/AuthenticationGetSessionOptions.hx +++ b/src/vscode/AuthenticationGetSessionOptions.hx @@ -4,6 +4,24 @@ package vscode; * Options to be used when getting an {@link AuthenticationSession} from an {@link AuthenticationProvider}. */ typedef AuthenticationGetSessionOptions = { + /** + * Whether the existing session preference should be cleared. + * + * For authentication providers that support being signed into multiple accounts at once, the user will be + * prompted to select an account to use when {@link authentication.getSession getSession} is called. This preference + * is remembered until {@link authentication.getSession getSession} is called with this flag. + * + * Note: + * The preference is extension specific. So if one extension calls {@link authentication.getSession getSession}, it will not + * affect the session preference for another extension calling {@link authentication.getSession getSession}. Additionally, + * the preference is set for the current workspace and also globally. This means that new workspaces will use the "global" + * value at first and then when this flag is provided, a new value can be set for that workspace. This also means + * that pre-existing workspaces will not lose their preference if a new workspace sets this flag. + * + * Defaults to false. + */ + var ?clearSessionPreference:Bool; + /** * Whether login should be performed if there is no matching session. * @@ -15,17 +33,38 @@ typedef AuthenticationGetSessionOptions = { * will also result in an immediate modal dialog, and false will add a numbered badge to the accounts icon. * * Defaults to false. + * + * Note: you cannot use this option with {@link AuthenticationGetSessionOptions.silent silent}. */ var ?createIfNone:Bool; /** - * Whether the existing user session preference should be cleared. + * Whether we should attempt to reauthenticate even if there is already a session available. * - * For authentication providers that support being signed into multiple accounts at once, the user will be - * prompted to select an account to use when {@link authentication.getSession getSession} is called. This preference - * is remembered until {@link authentication.getSession getSession} is called with this flag. + * If true, a modal dialog will be shown asking the user to sign in again. This is mostly used for scenarios + * where the token needs to be re minted because it has lost some authorization. + * + * If there are no existing sessions and forceNewSession is true, it will behave identically to + * {@link AuthenticationGetSessionOptions.createIfNone createIfNone}. + * + * This defaults to false. + */ + var ?forceNewSession:EitherType; + + /** + * Whether we should show the indication to sign in in the Accounts menu. + * + * If false, the user will be shown a badge on the Accounts menu with an option to sign in for the extension. + * If true, no indication will be shown. * * Defaults to false. + * + * Note: you cannot use this option with any other options that prompt the user like {@link AuthenticationGetSessionOptions.createIfNone createIfNone}. */ - var ?clearSessionPreference:Bool; + var ?silent:Bool; + + /** + * The account that you would like to get a session for. This is passed down to the Authentication Provider to be used for creating the correct session. + */ + var ?account:AuthenticationSessionAccountInformation; } diff --git a/src/vscode/AuthenticationProvider.hx b/src/vscode/AuthenticationProvider.hx index 632342cb..95dff75a 100644 --- a/src/vscode/AuthenticationProvider.hx +++ b/src/vscode/AuthenticationProvider.hx @@ -14,9 +14,10 @@ typedef AuthenticationProvider = { * Get a list of sessions. * @param scopes An optional list of scopes. If provided, the sessions returned should match * these permissions, otherwise all sessions should be returned. + * @param options Additional options for getting sessions. * @returns A promise that resolves to an array of authentication sessions. */ - function getSessions(?scopes:ReadOnlyArray):Thenable>; + function getSessions(scopes:Null>, options:AuthenticationProviderSessionOptions):Thenable>; /** * Prompts a user to login. @@ -29,9 +30,10 @@ typedef AuthenticationProvider = { * then this should never be called if there is already an existing session matching these * scopes. * @param scopes A list of scopes, permissions, that the new session should be created with. + * @param options Additional options for creating a session. * @returns A promise that resolves to an authentication session. */ - function createSession(scopes:ReadOnlyArray):Thenable; + function createSession(scopes:ReadOnlyArray, options:AuthenticationProviderSessionOptions):Thenable; /** * Removes the session corresponding to session id. diff --git a/src/vscode/AuthenticationProviderAuthenticationSessionsChangeEvent.hx b/src/vscode/AuthenticationProviderAuthenticationSessionsChangeEvent.hx index df8ec7dc..c4aa6693 100644 --- a/src/vscode/AuthenticationProviderAuthenticationSessionsChangeEvent.hx +++ b/src/vscode/AuthenticationProviderAuthenticationSessionsChangeEvent.hx @@ -5,19 +5,19 @@ package vscode; */ typedef AuthenticationProviderAuthenticationSessionsChangeEvent = { /** - * The {@link AuthenticationSession}s of the {@link AuthenticationProvider} that have been added. + * The {@link AuthenticationSession AuthenticationSessions} of the {@link AuthenticationProvider} that have been added. */ - var ?added(default, null):ReadOnlyArray; + var added(default, null):Null>; /** - * The {@link AuthenticationSession}s of the {@link AuthenticationProvider} that have been removed. + * The {@link AuthenticationSession AuthenticationSessions} of the {@link AuthenticationProvider} that have been removed. */ - var ?removed(default, null):ReadOnlyArray; + var removed(default, null):Null>; /** - * The {@link AuthenticationSession}s of the {@link AuthenticationProvider} that have been changed. + * The {@link AuthenticationSession AuthenticationSessions} of the {@link AuthenticationProvider} that have been changed. * A session changes when its data excluding the id are updated. An example of this is a session refresh that results in a new * access token being set for the session. */ - var ?changed(default, null):ReadOnlyArray; + var changed(default, null):Null>; } diff --git a/src/vscode/AuthenticationProviderSessionOptions.hx b/src/vscode/AuthenticationProviderSessionOptions.hx new file mode 100644 index 00000000..0a25f4db --- /dev/null +++ b/src/vscode/AuthenticationProviderSessionOptions.hx @@ -0,0 +1,13 @@ +package vscode; + +/** + * The options passed in to the {@link AuthenticationProvider.getSessions} and + * {@link AuthenticationProvider.createSession} call. + */ +typedef AuthenticationProviderSessionOptions = { + /** + * The account that is being asked about. If this is passed in, the provider should + * attempt to return the sessions that are only related to this account. + */ + var ?account:AuthenticationSessionAccountInformation; +} diff --git a/src/vscode/AutoClosingPair.hx b/src/vscode/AutoClosingPair.hx new file mode 100644 index 00000000..cdec9643 --- /dev/null +++ b/src/vscode/AutoClosingPair.hx @@ -0,0 +1,21 @@ +package vscode; + +/** + * Describes pairs of strings where the close string will be automatically inserted when typing the opening string. + */ +typedef AutoClosingPair = { + /** + * The string that will trigger the automatic insertion of the closing string. + */ + var open:String; + + /** + * The closing string that will be automatically inserted when typing the opening string. + */ + var close:String; + + /** + * A set of tokens where the pair should not be auto closed. + */ + var ?notIn:Array; +} diff --git a/src/vscode/BranchCoverage.hx b/src/vscode/BranchCoverage.hx new file mode 100644 index 00000000..2f9fa162 --- /dev/null +++ b/src/vscode/BranchCoverage.hx @@ -0,0 +1,33 @@ +package vscode; + +/** + * Contains coverage information for a branch of a {@link StatementCoverage}. + */ +@:jsRequire("vscode", "BranchCoverage") +extern class BranchCoverage { + /** + * The number of times this branch was executed, or a boolean indicating + * whether it was executed if the exact count is unknown. If zero or false, + * the branch will be marked as un-covered. + */ + var executed:EitherType; + + /** + * Branch location. + */ + var location:Null>; + + /** + * Label for the branch, used in the context of "the ${label} branch was + * not taken," for example. + */ + var label:Null; + + /** + * @param executed The number of times this branch was executed, or a + * boolean indicating whether it was executed if the exact count is + * unknown. If zero or false, the branch will be marked as un-covered. + * @param location The branch position. + */ + function new(executed:EitherType, ?location:EitherType, ?label:String); +} diff --git a/src/vscode/Breakpoint.hx b/src/vscode/Breakpoint.hx index 050fbebb..2ef7abb2 100644 --- a/src/vscode/Breakpoint.hx +++ b/src/vscode/Breakpoint.hx @@ -30,5 +30,13 @@ extern class Breakpoint { */ var logMessage(default, never):Null; + /** + * Creates a new breakpoint + * + * @param enabled Is breakpoint enabled. + * @param condition Expression for conditional breakpoints + * @param hitCondition Expression that controls how many hits of the breakpoint are ignored + * @param logMessage Log message to display when breakpoint is hit + */ private function new(?enabled:Bool, ?condition:String, ?hitCondition:String, ?logMessage:String); } diff --git a/src/vscode/CallHierarchyProvider.hx b/src/vscode/CallHierarchyProvider.hx index 37498288..ae58eeab 100644 --- a/src/vscode/CallHierarchyProvider.hx +++ b/src/vscode/CallHierarchyProvider.hx @@ -16,8 +16,8 @@ typedef CallHierarchyProvider = { * @param document The document in which the command was invoked. * @param position The position at which the command was invoked. * @param token A cancellation token. - * @returns A call hierarchy item or a thenable that resolves to such. The lack of a result can be - * signaled by returning `undefined` or `null`. + * @returns One or multiple call hierarchy items or a thenable that resolves to such. The lack of a result can be + * signaled by returning `undefined`, `null`, or an empty array. */ function prepareCallHierarchy(document:TextDocument, position:Position, token:CancellationToken):ProviderResult>>>; diff --git a/src/vscode/ChatContext.hx b/src/vscode/ChatContext.hx new file mode 100644 index 00000000..613f8692 --- /dev/null +++ b/src/vscode/ChatContext.hx @@ -0,0 +1,11 @@ +package vscode; + +/** + * Extra context passed to a participant. + */ +typedef ChatContext = { + /** + * All of the chat messages so far in the current chat session. Currently, only chat messages for the current participant are included. + */ + var history(default, null):ReadOnlyArray>; +} diff --git a/src/vscode/ChatErrorDetails.hx b/src/vscode/ChatErrorDetails.hx new file mode 100644 index 00000000..be60437e --- /dev/null +++ b/src/vscode/ChatErrorDetails.hx @@ -0,0 +1,16 @@ +package vscode; + +/** + * Represents an error result from a chat request. + */ +typedef ChatErrorDetails = { + /** + * An error message that is shown to the user. + */ + var message:String; + + /** + * If set to true, the response will be partly blurred out. + */ + var ?responseIsFiltered:Bool; +} diff --git a/src/vscode/ChatFollowup.hx b/src/vscode/ChatFollowup.hx new file mode 100644 index 00000000..f0d30029 --- /dev/null +++ b/src/vscode/ChatFollowup.hx @@ -0,0 +1,27 @@ +package vscode; + +/** + * A followup question suggested by the participant. + */ +typedef ChatFollowup = { + /** + * The message to send to the chat. + */ + var prompt:String; + + /** + * A title to show the user. The prompt will be shown by default, when this is unspecified. + */ + var ?label:String; + + /** + * By default, the followup goes to the same participant/command. But this property can be set to invoke a different participant by ID. + * Followups can only invoke a participant that was contributed by the same extension. + */ + var ?participant:String; + + /** + * By default, the followup goes to the same participant/command. But this property can be set to invoke a different command. + */ + var ?command:String; +} diff --git a/src/vscode/ChatFollowupProvider.hx b/src/vscode/ChatFollowupProvider.hx new file mode 100644 index 00000000..47dad4b2 --- /dev/null +++ b/src/vscode/ChatFollowupProvider.hx @@ -0,0 +1,15 @@ +package vscode; + +/** + * Will be invoked once after each request to get suggested followup questions to show the user. The user can click the followup to send it to the chat. + */ +typedef ChatFollowupProvider = { + /** + * Provide followups for the given result. + * + * @param result This object has the same properties as the result returned from the participant callback, including `metadata`, but is not the same instance. + * @param context Extra context passed to a participant. + * @param token A cancellation token. + */ + function provideFollowups(result:ChatResult, context:ChatContext, token:CancellationToken):ProviderResult>; +} diff --git a/src/vscode/ChatLanguageModelToolReference.hx b/src/vscode/ChatLanguageModelToolReference.hx new file mode 100644 index 00000000..e26b4612 --- /dev/null +++ b/src/vscode/ChatLanguageModelToolReference.hx @@ -0,0 +1,26 @@ +package vscode; + +import vscode.TerminalShellExecution.AsyncIterable; + +/** + * A reference to a tool that the user manually attached to their request, either using the `#`-syntax inline, or as an + * attachment via the paperclip button. + */ +typedef ChatLanguageModelToolReference = { + /** + * The tool name. Refers to a tool listed in {@link lm.tools}. + */ + var name(default, null):String; + + /** + * The start and end index of the reference in the {@link ChatRequest.prompt prompt}. When undefined, the reference was + * not part of the prompt text. + * + * *Note* that the indices take the leading `#`-character into account which means they can be used to modify the prompt + * as-is. + */ + var ?range(default, null):{ + start:Int, + end:Int + }; +} diff --git a/src/vscode/ChatParticipant.hx b/src/vscode/ChatParticipant.hx new file mode 100644 index 00000000..40fbd08f --- /dev/null +++ b/src/vscode/ChatParticipant.hx @@ -0,0 +1,41 @@ +package vscode; + +/** + * A chat participant can be invoked by the user in a chat session, using the `@` prefix. When it is invoked, it handles the chat request and is solely + * responsible for providing a response to the user. A ChatParticipant is created using {@link chat.createChatParticipant}. + */ +typedef ChatParticipant = { + /** + * A unique ID for this participant. + */ + var id(default, null):String; + + /** + * An icon for the participant shown in UI. + */ + var ?iconPath:IconPath; + + /** + * The handler for requests to this participant. + */ + var requestHandler:ChatRequestHandler; + + /** + * This provider will be called once after each request to retrieve suggested followup questions. + */ + var ?followupProvider:ChatFollowupProvider; + + /** + * An event that fires whenever feedback for a result is received, e.g. when a user up- or down-votes + * a result. + * + * The passed {@link ChatResultFeedback.result result} is guaranteed to have the same properties as the result that was + * previously returned from this chat participant's handler. + */ + var onDidReceiveFeedback:Event; + + /** + * Dispose this participant and free resources. + */ + function dispose():Void; +} diff --git a/src/vscode/ChatParticipantToolToken.hx b/src/vscode/ChatParticipantToolToken.hx new file mode 100644 index 00000000..e2cb74f0 --- /dev/null +++ b/src/vscode/ChatParticipantToolToken.hx @@ -0,0 +1,3 @@ +package vscode; + +typedef ChatParticipantToolToken = Void; diff --git a/src/vscode/ChatPromptReference.hx b/src/vscode/ChatPromptReference.hx new file mode 100644 index 00000000..bee4a5ee --- /dev/null +++ b/src/vscode/ChatPromptReference.hx @@ -0,0 +1,32 @@ +package vscode; + +/** + * A reference to a value that the user added to their chat request. + */ +typedef ChatPromptReference = { + /** + * A unique identifier for this kind of reference. + */ + var id(default, null):String; + + /** + * The start and end index of the reference in the {@link ChatRequest.prompt prompt}. When undefined, the reference was not part of the prompt text. + * + * *Note* that the indices take the leading `#`-character into account which means they can + * used to modify the prompt as-is. + */ + var ?range(default, null):{ + start:Int, + end:Int + }; + + /** + * A description of this value that could be used in an LLM prompt. + */ + var ?modelDescription(default, null):String; + + /** + * The value of this reference. The `string | Uri | Location` types are used today, but this could expand in the future. + */ + var value(default, null):Null>>; +} diff --git a/src/vscode/ChatRequest.hx b/src/vscode/ChatRequest.hx new file mode 100644 index 00000000..fe74d55a --- /dev/null +++ b/src/vscode/ChatRequest.hx @@ -0,0 +1,54 @@ +package vscode; + +/** + * A request to a chat participant. + */ +typedef ChatRequest = { + /** + * The prompt as entered by the user. + * + * Information about references used in this request is stored in {@link ChatRequest.references}. + * + * *Note* that the {@link ChatParticipant.name name} of the participant and the {@link ChatCommand.name command} + * are not part of the prompt. + */ + var prompt(default, null):String; + + /** + * The name of the {@link ChatCommand command} that was selected for this request. + */ + var command(default, null):Null; + + /** + * The list of references and their values that are referenced in the prompt. + * + * *Note* that the prompt contains references as authored and that it is up to the participant + * to further modify the prompt, for instance by inlining reference values or creating links to + * headings which contain the resolved values. References are sorted in reverse by their range + * in the prompt. That means the last reference in the prompt is the first in this list. This simplifies + * string-manipulation of the prompt. + */ + var references(default, null):ReadOnlyArray; + + /** + * The list of tools that the user attached to their request. + * + * When a tool reference is present, the chat participant should make a chat request using + * {@link LanguageModelChatToolMode.Required} to force the language model to generate input for the tool. Then, the + * participant can use {@link lm.invokeTool} to use the tool attach the result to its request for the user's prompt. The + * tool may contribute useful extra context for the user's request. + */ + var toolReferences(default, null):ReadOnlyArray; + + /** + * A token that can be passed to {@link lm.invokeTool} when invoking a tool inside the context of handling a chat request. + * This associates the tool invocation to a chat session. + */ + var toolInvocationToken(default, null):ChatParticipantToolToken; + + /** + * This is the model that is currently selected in the UI. Extensions can use this or use {@link chat.selectChatModels} to + * pick another model. Don't hold onto this past the lifetime of the request. + */ + var model(default, null):LanguageModelChat; +} diff --git a/src/vscode/ChatRequestHandler.hx b/src/vscode/ChatRequestHandler.hx new file mode 100644 index 00000000..78b5b043 --- /dev/null +++ b/src/vscode/ChatRequestHandler.hx @@ -0,0 +1,4 @@ +package vscode; + +typedef ChatRequestHandler = (request:ChatRequest, context:ChatContext, response:ChatResponseStream, + token:CancellationToken) -> ProviderResult>; diff --git a/src/vscode/ChatRequestTurn.hx b/src/vscode/ChatRequestTurn.hx new file mode 100644 index 00000000..d8ffdaa2 --- /dev/null +++ b/src/vscode/ChatRequestTurn.hx @@ -0,0 +1,43 @@ +package vscode; + +/** + * Represents a user request in chat history. + */ +@:jsRequire("vscode", "ChatRequestTurn") +extern class ChatRequestTurn { + /** + * The prompt as entered by the user. + * + * Information about references used in this request is stored in {@link ChatRequestTurn.references}. + * + * *Note* that the {@link ChatParticipant.name name} of the participant and the {@link ChatCommand.name command} + * are not part of the prompt. + */ + var prompt(default, null):String; + + /** + * The id of the chat participant to which this request was directed. + */ + var participant(default, null):String; + + /** + * The name of the {@link ChatCommand command} that was selected for this request. + */ + var command(default, null):Null; + + /** + * The references that were used in this message. + */ + var references(default, null):Array; + + /** + * The list of tools were attached to this request. + */ + var toolReferences(default, null):ReadOnlyArray; + + /** + * @hidden + */ + private function new(prompt:String, command:Null, references:Array, participant:String, + toolReferences:Array); +} diff --git a/src/vscode/ChatResponseAnchorPart.hx b/src/vscode/ChatResponseAnchorPart.hx new file mode 100644 index 00000000..72e6152a --- /dev/null +++ b/src/vscode/ChatResponseAnchorPart.hx @@ -0,0 +1,24 @@ +package vscode; + +/** + * Represents a part of a chat response that is an anchor, that is rendered as a link to a target. + */ +@:jsRequire("vscode", "ChatResponseAnchorPart") +extern class ChatResponseAnchorPart { + /** + * The target of this anchor. + */ + var value:EitherType; + + /** + * An optional title that is rendered with value. + */ + var title:Null; + + /** + * Create a new ChatResponseAnchorPart. + * @param value A uri or location. + * @param title An optional title that is rendered with value. + */ + function new(value:EitherType, ?title:String); +} diff --git a/src/vscode/ChatResponseCommandButtonPart.hx b/src/vscode/ChatResponseCommandButtonPart.hx new file mode 100644 index 00000000..37d6cf70 --- /dev/null +++ b/src/vscode/ChatResponseCommandButtonPart.hx @@ -0,0 +1,18 @@ +package vscode; + +/** + * Represents a part of a chat response that is a button that executes a command. + */ +@:jsRequire("vscode", "ChatResponseCommandButtonPart") +extern class ChatResponseCommandButtonPart { + /** + * The command that will be executed when the button is clicked. + */ + var value:Command; + + /** + * Create a new ChatResponseCommandButtonPart. + * @param value A Command that will be executed when the button is clicked. + */ + function new(value:Command); +} diff --git a/src/vscode/ChatResponseFileTree.hx b/src/vscode/ChatResponseFileTree.hx new file mode 100644 index 00000000..b48386da --- /dev/null +++ b/src/vscode/ChatResponseFileTree.hx @@ -0,0 +1,16 @@ +package vscode; + +/** + * Represents a file tree structure in a chat response. + */ +typedef ChatResponseFileTree = { + /** + * The name of the file or directory. + */ + var name:String; + + /** + * An array of child file trees, if the current file tree is a directory. + */ + var ?children:Array; +} diff --git a/src/vscode/ChatResponseFileTreePart.hx b/src/vscode/ChatResponseFileTreePart.hx new file mode 100644 index 00000000..6efe7608 --- /dev/null +++ b/src/vscode/ChatResponseFileTreePart.hx @@ -0,0 +1,24 @@ +package vscode; + +/** + * Represents a part of a chat response that is a file tree. + */ +@:jsRequire("vscode", "ChatResponseFileTreePart") +extern class ChatResponseFileTreePart { + /** + * File tree data. + */ + var value:Array; + + /** + * The base uri to which this file tree is relative + */ + var baseUri:Uri; + + /** + * Create a new ChatResponseFileTreePart. + * @param value File tree data. + * @param baseUri The base uri to which this file tree is relative. + */ + function new(value:Array, baseUri:Uri); +} diff --git a/src/vscode/ChatResponseMarkdownPart.hx b/src/vscode/ChatResponseMarkdownPart.hx new file mode 100644 index 00000000..20792a14 --- /dev/null +++ b/src/vscode/ChatResponseMarkdownPart.hx @@ -0,0 +1,19 @@ +package vscode; + +/** + * Represents a part of a chat response that is formatted as Markdown. + */ +@:jsRequire("vscode", "ChatResponseMarkdownPart") +extern class ChatResponseMarkdownPart { + /** + * A markdown string or a string that should be interpreted as markdown. + */ + var value:MarkdownString; + + /** + * Create a new ChatResponseMarkdownPart. + * + * @param value A markdown string or a string that should be interpreted as markdown. The boolean form of {@link MarkdownString.isTrusted} is NOT supported. + */ + function new(value:EitherType); +} diff --git a/src/vscode/ChatResponsePart.hx b/src/vscode/ChatResponsePart.hx new file mode 100644 index 00000000..d85d0e90 --- /dev/null +++ b/src/vscode/ChatResponsePart.hx @@ -0,0 +1,5 @@ +package vscode; + +typedef ChatResponsePart = EitherType>>>>; diff --git a/src/vscode/ChatResponseProgressPart.hx b/src/vscode/ChatResponseProgressPart.hx new file mode 100644 index 00000000..97625f73 --- /dev/null +++ b/src/vscode/ChatResponseProgressPart.hx @@ -0,0 +1,18 @@ +package vscode; + +/** + * Represents a part of a chat response that is a progress message. + */ +@:jsRequire("vscode", "ChatResponseProgressPart") +extern class ChatResponseProgressPart { + /** + * The progress message + */ + var value:String; + + /** + * Create a new ChatResponseProgressPart. + * @param value A progress message + */ + function new(value:String); +} diff --git a/src/vscode/ChatResponseReferencePart.hx b/src/vscode/ChatResponseReferencePart.hx new file mode 100644 index 00000000..f31f2247 --- /dev/null +++ b/src/vscode/ChatResponseReferencePart.hx @@ -0,0 +1,24 @@ +package vscode; + +/** + * Represents a part of a chat response that is a reference, rendered separately from the content. + */ +@:jsRequire("vscode", "ChatResponseReferencePart") +extern class ChatResponseReferencePart { + /** + * The reference target. + */ + var value:EitherType; + + /** + * The icon for the reference. + */ + var iconPath:Null; + + /** + * Create a new ChatResponseReferencePart. + * @param value A uri or location + * @param iconPath Icon for the reference shown in UI + */ + function new(value:EitherType, ?iconPath:IconPath); +} diff --git a/src/vscode/ChatResponseStream.hx b/src/vscode/ChatResponseStream.hx new file mode 100644 index 00000000..5fe89605 --- /dev/null +++ b/src/vscode/ChatResponseStream.hx @@ -0,0 +1,70 @@ +package vscode; + +/** + * The ChatResponseStream is how a participant is able to return content to the chat view. It provides several methods for streaming different types of content + * which will be rendered in an appropriate way in the chat view. A participant can use the helper method for the type of content it wants to return, or it + * can instantiate a {@link ChatResponsePart} and use the generic {@link ChatResponseStream.push} method to return it. + */ +typedef ChatResponseStream = { + /** + * Push a markdown part to this stream. Short-hand for + * `push(new ChatResponseMarkdownPart(value))`. + * + * @see {@link ChatResponseStream.push} + * @param value A markdown string or a string that should be interpreted as markdown. The boolean form of {@link MarkdownString.isTrusted} is NOT supported. + */ + function markdown(value:EitherType):Void; + + /** + * Push an anchor part to this stream. Short-hand for + * `push(new ChatResponseAnchorPart(value, title))`. + * An anchor is an inline reference to some type of resource. + * + * @param value A uri or location. + * @param title An optional title that is rendered with value. + */ + function anchor(value:EitherType, ?title:String):Void; + + /** + * Push a command button part to this stream. Short-hand for + * `push(new ChatResponseCommandButtonPart(value, title))`. + * + * @param command A Command that will be executed when the button is clicked. + */ + function button(command:Command):Void; + + /** + * Push a filetree part to this stream. Short-hand for + * `push(new ChatResponseFileTreePart(value))`. + * + * @param value File tree data. + * @param baseUri The base uri to which this file tree is relative. + */ + function filetree(value:Array, baseUri:Uri):Void; + + /** + * Push a progress part to this stream. Short-hand for + * `push(new ChatResponseProgressPart(value))`. + * + * @param value A progress message + */ + function progress(value:String):Void; + + /** + * Push a reference to this stream. Short-hand for + * `push(new ChatResponseReferencePart(value))`. + * + * *Note* that the reference is not rendered inline with the response. + * + * @param value A uri or location + * @param iconPath Icon for the reference shown in UI + */ + function reference(value:EitherType, ?iconPath:IconPath):Void; + + /** + * Pushes a part to this stream. + * + * @param part A response part, rendered or metadata + */ + function push(part:ChatResponsePart):Void; +} diff --git a/src/vscode/ChatResponseTurn.hx b/src/vscode/ChatResponseTurn.hx new file mode 100644 index 00000000..15011528 --- /dev/null +++ b/src/vscode/ChatResponseTurn.hx @@ -0,0 +1,36 @@ +package vscode; + +/** + * Represents a chat participant's response in chat history. + */ +@:jsRequire("vscode", "ChatResponseTurn") +extern class ChatResponseTurn { + /** + * The content that was received from the chat participant. Only the stream parts that represent actual content (not metadata) are represented. + */ + var response(default, + null):ReadOnlyArray>>>; + + /** + * The result that was received from the chat participant. + */ + var result(default, null):ChatResult; + + /** + * The id of the chat participant that this response came from. + */ + var participant(default, null):String; + + /** + * The name of the command that this response came from. + */ + var command(default, null):Null; + + /** + * @hidden + */ + private function new(response:ReadOnlyArray>>>, + result:ChatResult, participant:String); +} diff --git a/src/vscode/ChatResult.hx b/src/vscode/ChatResult.hx new file mode 100644 index 00000000..e9a83b22 --- /dev/null +++ b/src/vscode/ChatResult.hx @@ -0,0 +1,16 @@ +package vscode; + +/** + * The result of a chat request. + */ +typedef ChatResult = { + /** + * If the request resulted in an error, this property defines the error details. + */ + var ?errorDetails:ChatErrorDetails; + + /** + * Arbitrary metadata for this result. Can be anything, but must be JSON-stringifyable. + */ + var ?metadata:DynamicAccess; +} diff --git a/src/vscode/ChatResultFeedback.hx b/src/vscode/ChatResultFeedback.hx new file mode 100644 index 00000000..c382f44b --- /dev/null +++ b/src/vscode/ChatResultFeedback.hx @@ -0,0 +1,17 @@ +package vscode; + +/** + * Represents user feedback for a result. + */ +typedef ChatResultFeedback = { + /** + * The ChatResult for which the user is providing feedback. + * This object has the same properties as the result returned from the participant callback, including `metadata`, but is not the same instance. + */ + var result(default, null):ChatResult; + + /** + * The kind of feedback that was received. + */ + var kind(default, null):ChatResultFeedbackKind; +} diff --git a/src/vscode/ChatResultFeedbackKind.hx b/src/vscode/ChatResultFeedbackKind.hx new file mode 100644 index 00000000..7a06675a --- /dev/null +++ b/src/vscode/ChatResultFeedbackKind.hx @@ -0,0 +1,17 @@ +package vscode; + +/** + * Represents the type of user feedback received. + */ +@:jsRequire("vscode", "ChatResultFeedbackKind") +extern enum abstract ChatResultFeedbackKind(Int) { + /** + * The user marked the result as unhelpful. + */ + var Unhelpful; + + /** + * The user marked the result as helpful. + */ + var Helpful; +} diff --git a/src/vscode/CodeActionContext.hx b/src/vscode/CodeActionContext.hx index 974d2c7f..c833e775 100644 --- a/src/vscode/CodeActionContext.hx +++ b/src/vscode/CodeActionContext.hx @@ -20,5 +20,5 @@ typedef CodeActionContext = { * * Actions not of this kind are filtered out before being shown by the [lightbulb](https://code.visualstudio.com/docs/editor/editingevolved#_code-action). */ - var ?only(default, null):CodeActionKind; + var only(default, null):Null; } diff --git a/src/vscode/CodeActionKind.hx b/src/vscode/CodeActionKind.hx index 993664b6..f0ad0524 100644 --- a/src/vscode/CodeActionKind.hx +++ b/src/vscode/CodeActionKind.hx @@ -54,6 +54,18 @@ extern class CodeActionKind { */ static var RefactorInline(default, null):CodeActionKind; + /** + * Base kind for refactoring move actions: `refactor.move` + * + * Example move actions: + * + * - Move a function to a new file + * - Move a property between classes + * - Move method to base class + * - ... + */ + static var RefactorMove(default, null):CodeActionKind; + /** * Base kind for refactoring rewrite actions: `refactor.rewrite` * @@ -63,7 +75,6 @@ extern class CodeActionKind { * - Add or remove parameter * - Encapsulate field * - Make method static - * - Move method to base class * - ... */ static var RefactorRewrite(default, null):CodeActionKind; @@ -90,6 +101,29 @@ extern class CodeActionKind { */ static var SourceFixAll(default, null):CodeActionKind; + /** + * Base kind for all code actions applying to the entire notebook's scope. CodeActionKinds using + * this should always begin with `notebook.` + * + * This requires that new CodeActions be created for it and contributed via extensions. + * Pre-existing kinds can not just have the new `notebook.` prefix added to them, as the functionality + * is unique to the full-notebook scope. + * + * Notebook CodeActionKinds can be initialized as either of the following (both resulting in `notebook.source.xyz`): + * - `const newKind = CodeActionKind.Notebook.append(CodeActionKind.Source.append('xyz').value)` + * - `const newKind = CodeActionKind.Notebook.append('source.xyz')` + * + * Example Kinds/Actions: + * - `notebook.source.organizeImports` (might move all imports to a new top cell) + * - `notebook.source.normalizeVariableNames` (might rename all variables to a standardized casing format) + */ + static var Notebook(default, null):CodeActionKind; + + /** + * Private constructor, use static `CodeActionKind.XYZ` to derive from an existing code action kind. + * + * @param value The value of the kind, such as `refactor.extract.function`. + */ private function new(value:String); /** @@ -107,7 +141,7 @@ extern class CodeActionKind { /** * Checks if this code action kind intersects `other`. * - * The kind `"refactor.extract"` for example intersects `refactor`, `"refactor.extract"` and ``"refactor.extract.function"`, + * The kind `"refactor.extract"` for example intersects `refactor`, `"refactor.extract"` and `"refactor.extract.function"`, * but not `"unicorn.refactor.extract"`, or `"refactor.extractAll"`. * * @param other Kind to check. diff --git a/src/vscode/CodeActionProvider.hx b/src/vscode/CodeActionProvider.hx index fd1dcd78..5a382292 100644 --- a/src/vscode/CodeActionProvider.hx +++ b/src/vscode/CodeActionProvider.hx @@ -1,22 +1,35 @@ package vscode; /** - * The code action interface defines the contract between extensions and - * the [lightbulb](https://code.visualstudio.com/docs/editor/editingevolved#_code-action) feature. + * Provides contextual actions for code. Code actions typically either fix problems or beautify/refactor code. * - * A code action can be any command that is {@link commands.getCommands known} to the system. + * Code actions are surfaced to users in a few different ways: + * + * - The [lightbulb](https://code.visualstudio.com/docs/editor/editingevolved#_code-action) feature, which shows + * a list of code actions at the current cursor position. The lightbulb's list of actions includes both quick fixes + * and refactorings. + * - As commands that users can run, such as `Refactor`. Users can run these from the command palette or with keybindings. + * - As source actions, such `Organize Imports`. + * - {@link CodeActionKind.QuickFix Quick fixes} are shown in the problems view. + * - Change applied on save by the `editor.codeActionsOnSave` setting. */ typedef CodeActionProvider = { /** - * Provide commands for the given document and range. + * Get code actions for a given range in a document. + * + * Only return code actions that are relevant to user for the requested range. Also keep in mind how the + * returned code actions will appear in the UI. The lightbulb widget and `Refactor` commands for instance show + * returned code actions as a list, so do not return a large number of code actions that will overwhelm the user. * * @param document The document in which the command was invoked. - * @param range The selector or range for which the command was invoked. This will always be a selection if - * there is a currently active editor. - * @param context Context carrying additional information. + * @param range The selector or range for which the command was invoked. This will always be a + * {@link Selection selection} if the actions are being requested in the currently active editor. + * @param context Provides additional information about what code actions are being requested. You can use this + * to see what specific type of code actions are being requested by the editor in order to return more relevant + * actions and avoid returning irrelevant code actions that the editor will discard. * @param token A cancellation token. * - * @return An array of code actions, such as quick fixes or refactorings. The lack of a result can be signaled + * @returns An array of code actions, such as quick fixes or refactorings. The lack of a result can be signaled * by returning `undefined`, `null`, or an empty array. * * We also support returning `Command` for legacy reasons, however all new extensions should return @@ -36,7 +49,7 @@ typedef CodeActionProvider = { * * @param codeAction A code action. * @param token A cancellation token. - * @return The resolved code action or a thenable that resolves to such. It is OK to return the given + * @returns The resolved code action or a thenable that resolves to such. It is OK to return the given * `item`. When no result is returned, the given `item` will be used. */ @:optional function resolveCodeAction(codeAction:T, token:CancellationToken):ProviderResult; diff --git a/src/vscode/CodeLensProvider.hx b/src/vscode/CodeLensProvider.hx index 3a9b34a4..5f53a9a7 100644 --- a/src/vscode/CodeLensProvider.hx +++ b/src/vscode/CodeLensProvider.hx @@ -17,7 +17,7 @@ typedef CodeLensProvider = { * * @param document The document in which the command was invoked. * @param token A cancellation token. - * @return An array of code lenses or a thenable that resolves to such. The lack of a result can be + * @returns An array of code lenses or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined`, `null`, or an empty array. */ function provideCodeLenses(document:TextDocument, token:CancellationToken):ProviderResult>; @@ -28,7 +28,7 @@ typedef CodeLensProvider = { * * @param codeLens Code lens that must be resolved. * @param token A cancellation token. - * @return The given, resolved code lens or thenable that resolves to such. + * @returns The given, resolved code lens or thenable that resolves to such. */ @:optional function resolveCodeLens(codeLens:T, token:CancellationToken):ProviderResult; } diff --git a/src/vscode/Color.hx b/src/vscode/Color.hx index ea0e0bb1..e7095ecc 100644 --- a/src/vscode/Color.hx +++ b/src/vscode/Color.hx @@ -6,22 +6,22 @@ package vscode; @:jsRequire("vscode", "Color") extern class Color { /** - * The red component of this color in the range [0-1]. + * The red component of this color in the range `[0-1]`. */ var red(default, null):Float; /** - * The green component of this color in the range [0-1]. + * The green component of this color in the range `[0-1]`. */ var green(default, null):Float; /** - * The blue component of this color in the range [0-1]. + * The blue component of this color in the range `[0-1]`. */ var blue(default, null):Float; /** - * The alpha component of this color in the range [0-1]. + * The alpha component of this color in the range `[0-1]`. */ var alpha(default, null):Float; diff --git a/src/vscode/ColorInformation.hx b/src/vscode/ColorInformation.hx index 5a0977a7..18c8a46e 100644 --- a/src/vscode/ColorInformation.hx +++ b/src/vscode/ColorInformation.hx @@ -20,7 +20,6 @@ extern class ColorInformation { * * @param range The range the color appears in. Must not be empty. * @param color The value of the color. - * @param format The format in which this color is currently formatted. */ function new(range:Range, color:Color); } diff --git a/src/vscode/ColorTheme.hx b/src/vscode/ColorTheme.hx index b4161333..2ad5ba52 100644 --- a/src/vscode/ColorTheme.hx +++ b/src/vscode/ColorTheme.hx @@ -5,7 +5,7 @@ package vscode; */ typedef ColorTheme = { /** - * The kind of this color theme: light, dark or high contrast. + * The kind of this color theme: light, dark, high contrast dark and high contrast light. */ var kind(default, null):ColorThemeKind; } diff --git a/src/vscode/ColorThemeKind.hx b/src/vscode/ColorThemeKind.hx index 83b5eb98..8c99bc45 100644 --- a/src/vscode/ColorThemeKind.hx +++ b/src/vscode/ColorThemeKind.hx @@ -5,7 +5,23 @@ package vscode; */ @:jsRequire("vscode", "ColorThemeKind") extern enum abstract ColorThemeKind(Int) { + /** + * A light color theme. + */ var Light; + + /** + * A dark color theme. + */ var Dark; + + /** + * A dark high contrast color theme. + */ var HighContrast; + + /** + * A light high contrast color theme. + */ + var HighContrastLight; } diff --git a/src/vscode/Comment.hx b/src/vscode/Comment.hx index d6a6c33f..9429c606 100644 --- a/src/vscode/Comment.hx +++ b/src/vscode/Comment.hx @@ -49,4 +49,10 @@ typedef Comment = { * Label will be rendered next to authorName if exists. */ var ?label:String; + + /** + * Optional timestamp that will be displayed in comments. + * The date will be formatted according to the user's locale and settings. + */ + var ?timestamp:Date; } diff --git a/src/vscode/CommentController.hx b/src/vscode/CommentController.hx index 3a52695e..992a8a7c 100644 --- a/src/vscode/CommentController.hx +++ b/src/vscode/CommentController.hx @@ -25,7 +25,7 @@ typedef CommentController = { /** * Optional commenting range provider. Provide a list {@link Range ranges} which support commenting to any given resource uri. * - * If not provided, users can leave comments in any document opened in the editor. + * If not provided, users cannot leave any comments. */ var ?commentingRangeProvider:CommentingRangeProvider; diff --git a/src/vscode/CommentReaction.hx b/src/vscode/CommentReaction.hx index e62c1b80..6f46622c 100644 --- a/src/vscode/CommentReaction.hx +++ b/src/vscode/CommentReaction.hx @@ -20,7 +20,7 @@ typedef CommentReaction = { var count(default, null):Int; /** - * Whether the [author](CommentAuthorInformation) of the comment has reacted to this reaction + * Whether the {@link CommentAuthorInformation author} of the comment has reacted to this reaction */ var authorHasReacted(default, null):Bool; } diff --git a/src/vscode/CommentThread.hx b/src/vscode/CommentThread.hx index 48d60e1c..37965630 100644 --- a/src/vscode/CommentThread.hx +++ b/src/vscode/CommentThread.hx @@ -11,9 +11,10 @@ typedef CommentThread = { /** * The range the comment thread is located within the document. The thread icon will be shown - * at the first line of the range. + * at the last line of the range. When set to undefined, the comment will be associated with the + * file, and not a specific range. */ - var range:Range; + var range:Null; /** * The ordered comments of the thread. @@ -36,17 +37,17 @@ typedef CommentThread = { * Context value of the comment thread. This can be used to contribute thread specific actions. * For example, a comment thread is given a context value as `editable`. When contributing actions to `comments/commentThread/title` * using `menus` extension point, you can specify context value for key `commentThread` in `when` expression like `commentThread == editable`. - * ``` - * "contributes": { - * "menus": { - * "comments/commentThread/title": [ - * { - * "command": "extension.deleteCommentThread", - * "when": "commentThread == editable" - * } - * ] - * } - * } + * ```json + * "contributes": { + * "menus": { + * "comments/commentThread/title": [ + * { + * "command": "extension.deleteCommentThread", + * "when": "commentThread == editable" + * } + * ] + * } + * } * ``` * This will show action `extension.deleteCommentThread` only for comment threads with `contextValue` is `editable`. */ @@ -57,6 +58,11 @@ typedef CommentThread = { */ var ?label:String; + /** + * The optional state of a comment thread, which may affect how the comment is displayed. + */ + var ?state:CommentThreadState; + /** * Dispose this comment thread. * diff --git a/src/vscode/CommentThreadState.hx b/src/vscode/CommentThreadState.hx new file mode 100644 index 00000000..3fa4366b --- /dev/null +++ b/src/vscode/CommentThreadState.hx @@ -0,0 +1,17 @@ +package vscode; + +/** + * The state of a comment thread. + */ +@:jsRequire("vscode", "CommentThreadState") +extern enum abstract CommentThreadState(Int) { + /** + * Unresolved thread state + */ + var Unresolved; + + /** + * Resolved thread state + */ + var Resolved; +} diff --git a/src/vscode/CommentingRangeProvider.hx b/src/vscode/CommentingRangeProvider.hx index 4bd0d6b9..d15f4c03 100644 --- a/src/vscode/CommentingRangeProvider.hx +++ b/src/vscode/CommentingRangeProvider.hx @@ -7,5 +7,5 @@ typedef CommentingRangeProvider = { /** * Provide a list of ranges which allow new comment threads creation or null for a given document */ - function provideCommentingRanges(document:TextDocument, token:CancellationToken):ProviderResult>; + function provideCommentingRanges(document:TextDocument, token:CancellationToken):ProviderResult, CommentingRanges>>; } diff --git a/src/vscode/CommentingRanges.hx b/src/vscode/CommentingRanges.hx new file mode 100644 index 00000000..f433328b --- /dev/null +++ b/src/vscode/CommentingRanges.hx @@ -0,0 +1,16 @@ +package vscode; + +/** + * The ranges a CommentingRangeProvider enables commenting on. + */ +typedef CommentingRanges = { + /** + * Enables comments to be added to a file without a specific range. + */ + var enableFileComments:Bool; + + /** + * The ranges which allow new comment threads creation. + */ + var ?ranges:Array; +} diff --git a/src/vscode/CompletionContext.hx b/src/vscode/CompletionContext.hx index cdeed7e8..5cf65de1 100644 --- a/src/vscode/CompletionContext.hx +++ b/src/vscode/CompletionContext.hx @@ -13,9 +13,9 @@ typedef CompletionContext = { /** * Character that triggered the completion item provider. * - * `undefined` if provider was not triggered by a character. + * `undefined` if the provider was not triggered by a character. * * The trigger character is already in the document when the completion provider is triggered. */ - var ?triggerCharacter(default, null):String; + var triggerCharacter(default, null):Null; } diff --git a/src/vscode/CompletionItem.hx b/src/vscode/CompletionItem.hx index 5e2b74c4..b8b87cca 100644 --- a/src/vscode/CompletionItem.hx +++ b/src/vscode/CompletionItem.hx @@ -95,7 +95,16 @@ extern class CompletionItem { * {@link Range.contains contain} the position at which completion has been {@link CompletionItemProvider.provideCompletionItems requested}. * *Note 2:* A insert range must be a prefix of a replace range, that means it must be contained and starting at the same position. */ - var range:Null>; + var range:Null>; /** * An optional set of characters that when pressed while this completion is active will accept it first and diff --git a/src/vscode/CompletionItemKind.hx b/src/vscode/CompletionItemKind.hx index cb4bf77f..0012df50 100644 --- a/src/vscode/CompletionItemKind.hx +++ b/src/vscode/CompletionItemKind.hx @@ -5,31 +5,138 @@ package vscode; */ @:jsRequire("vscode", "CompletionItemKind") extern enum abstract CompletionItemKind(Int) { + /** + * The `Text` completion item kind. + */ var Text; + + /** + * The `Method` completion item kind. + */ var Method; + + /** + * The `Function` completion item kind. + */ var Function; + + /** + * The `Constructor` completion item kind. + */ var Constructor; + + /** + * The `Field` completion item kind. + */ var Field; + + /** + * The `Variable` completion item kind. + */ var Variable; + + /** + * The `Class` completion item kind. + */ var Class; + + /** + * The `Interface` completion item kind. + */ var Interface; + + /** + * The `Module` completion item kind. + */ var Module; + + /** + * The `Property` completion item kind. + */ var Property; + + /** + * The `Unit` completion item kind. + */ var Unit; + + /** + * The `Value` completion item kind. + */ var Value; + + /** + * The `Enum` completion item kind. + */ var Enum; + + /** + * The `Keyword` completion item kind. + */ var Keyword; + + /** + * The `Snippet` completion item kind. + */ var Snippet; + + /** + * The `Color` completion item kind. + */ var Color; + + /** + * The `Reference` completion item kind. + */ var Reference; + + /** + * The `File` completion item kind. + */ var File; + + /** + * The `Folder` completion item kind. + */ var Folder; + + /** + * The `EnumMember` completion item kind. + */ var EnumMember; + + /** + * The `Constant` completion item kind. + */ var Constant; + + /** + * The `Struct` completion item kind. + */ var Struct; + + /** + * The `Event` completion item kind. + */ var Event; + + /** + * The `Operator` completion item kind. + */ var Operator; + + /** + * The `TypeParameter` completion item kind. + */ var TypeParameter; + + /** + * The `User` completion item kind. + */ var User; + + /** + * The `Issue` completion item kind. + */ var Issue; } diff --git a/src/vscode/CompletionItemProvider.hx b/src/vscode/CompletionItemProvider.hx index e8edb3c5..d4f0b19d 100644 --- a/src/vscode/CompletionItemProvider.hx +++ b/src/vscode/CompletionItemProvider.hx @@ -22,7 +22,7 @@ typedef CompletionItemProvider = { * @param token A cancellation token. * @param context How the completion was triggered. * - * @return An array of completions, a {@link CompletionList completion list}, or a thenable that resolves to either. + * @returns An array of completions, a {@link CompletionList completion list}, or a thenable that resolves to either. * The lack of a result can be signaled by returning `undefined`, `null`, or an empty array. */ function provideCompletionItems(document:TextDocument, position:Position, token:CancellationToken, @@ -44,7 +44,7 @@ typedef CompletionItemProvider = { * * @param item A completion item currently active in the UI. * @param token A cancellation token. - * @return The resolved completion item or a thenable that resolves to of such. It is OK to return the given + * @returns The resolved completion item or a thenable that resolves to of such. It is OK to return the given * `item`. When no result is returned, the given `item` will be used. */ @:optional function resolveCompletionItem(item:T, token:CancellationToken):ProviderResult; diff --git a/src/vscode/ConfigurationChangeEvent.hx b/src/vscode/ConfigurationChangeEvent.hx index 72f7e4c0..2ddb0e3c 100644 --- a/src/vscode/ConfigurationChangeEvent.hx +++ b/src/vscode/ConfigurationChangeEvent.hx @@ -10,7 +10,7 @@ typedef ConfigurationChangeEvent = { * * @param section Configuration name, supports _dotted_ names. * @param scope A scope in which to check. - * @return `true` if the given section has changed. + * @returns `true` if the given section has changed. */ function affectsConfiguration(section:String, ?scope:ConfigurationScope):Bool; } diff --git a/src/vscode/ConfigurationScope.hx b/src/vscode/ConfigurationScope.hx index 93355479..09647268 100644 --- a/src/vscode/ConfigurationScope.hx +++ b/src/vscode/ConfigurationScope.hx @@ -6,4 +6,14 @@ package vscode; * a '{@link TextDocument}' or * a '{@link WorkspaceFolder}' */ -typedef ConfigurationScope = EitherType>>; +typedef ConfigurationScope = EitherType>>; diff --git a/src/vscode/CustomDocumentBackupContext.hx b/src/vscode/CustomDocumentBackupContext.hx index 223f5ccb..a71e1b65 100644 --- a/src/vscode/CustomDocumentBackupContext.hx +++ b/src/vscode/CustomDocumentBackupContext.hx @@ -1,7 +1,7 @@ package vscode; /** - * Additional information used to implement {@linkcode CustomEditableDocument.backup}. + * Additional information used to implement {@linkcode CustomDocumentBackup}. */ typedef CustomDocumentBackupContext = { /** diff --git a/src/vscode/CustomDocumentOpenContext.hx b/src/vscode/CustomDocumentOpenContext.hx index 65f23104..dda79088 100644 --- a/src/vscode/CustomDocumentOpenContext.hx +++ b/src/vscode/CustomDocumentOpenContext.hx @@ -12,12 +12,12 @@ typedef CustomDocumentOpenContext = { * If this is provided, your extension should restore the editor from the backup instead of reading the file * from the user's workspace. */ - final ?backupId:String; + final backupId:Null; /** * If the URI is an untitled file, this will be populated with the byte data of that file * * If this is provided, your extension should utilize this byte data rather than executing fs APIs on the URI passed in */ - var ?untitledDocumentData(default, null):Uint8Array; + var untitledDocumentData(default, null):Null; } diff --git a/src/vscode/CustomEditorProvider.hx b/src/vscode/CustomEditorProvider.hx index 53c50033..8b10c6f5 100644 --- a/src/vscode/CustomEditorProvider.hx +++ b/src/vscode/CustomEditorProvider.hx @@ -47,7 +47,7 @@ typedef CustomEditorProvider = CustomReadonlyEditorProvider * @param document Document to save. * @param cancellation Token that signals the save is no longer required (for example, if another save was triggered). * - * @return Thenable signaling that saving has completed. + * @returns Thenable signaling that saving has completed. */ function saveCustomDocument(document:T, cancellation:CancellationToken):Thenable; @@ -63,7 +63,7 @@ typedef CustomEditorProvider = CustomReadonlyEditorProvider * @param destination Location to save to. * @param cancellation Token that signals the save is no longer required. * - * @return Thenable signaling that saving has completed. + * @returns Thenable signaling that saving has completed. */ function saveCustomDocumentAs(document:T, destination:Uri, cancellation:CancellationToken):Thenable; @@ -80,7 +80,7 @@ typedef CustomEditorProvider = CustomReadonlyEditorProvider * @param document Document to revert. * @param cancellation Token that signals the revert is no longer required. * - * @return Thenable signaling that the change has completed. + * @returns Thenable signaling that the change has completed. */ function revertCustomDocument(document:T, cancellation:CancellationToken):Thenable; diff --git a/src/vscode/CustomReadonlyEditorProvider.hx b/src/vscode/CustomReadonlyEditorProvider.hx index b6068161..9b78f897 100644 --- a/src/vscode/CustomReadonlyEditorProvider.hx +++ b/src/vscode/CustomReadonlyEditorProvider.hx @@ -25,7 +25,7 @@ typedef CustomReadonlyEditorProvider = { * @param openContext Additional information about the opening custom document. * @param token A cancellation token that indicates the result is no longer needed. * - * @return The custom document. + * @returns The custom document. */ function openCustomDocument(uri:Uri, openContext:CustomDocumentOpenContext, token:CancellationToken):EitherType, T>; @@ -44,7 +44,7 @@ typedef CustomReadonlyEditorProvider = { * * @param token A cancellation token that indicates the result is no longer needed. * - * @return Optional thenable indicating that the custom editor has been resolved. + * @returns Optional thenable indicating that the custom editor has been resolved. */ function resolveCustomEditor(document:T, webviewPanel:WebviewPanel, token:CancellationToken):EitherType, Void>; } diff --git a/src/vscode/CustomTextEditorProvider.hx b/src/vscode/CustomTextEditorProvider.hx index bcd13319..5d39e0e1 100644 --- a/src/vscode/CustomTextEditorProvider.hx +++ b/src/vscode/CustomTextEditorProvider.hx @@ -25,7 +25,7 @@ typedef CustomTextEditorProvider = { * * @param token A cancellation token that indicates the result is no longer needed. * - * @return Thenable indicating that the custom editor has been resolved. + * @returns Thenable indicating that the custom editor has been resolved. */ function resolveCustomTextEditor(document:TextDocument, webviewPanel:WebviewPanel, token:CancellationToken):EitherType, Void>; } diff --git a/src/vscode/DataTransfer.hx b/src/vscode/DataTransfer.hx new file mode 100644 index 00000000..46e6a4e9 --- /dev/null +++ b/src/vscode/DataTransfer.hx @@ -0,0 +1,45 @@ +package vscode; + +/** + * A map containing a mapping of the mime type of the corresponding transferred data. + * + * Drag and drop controllers that implement {@link TreeDragAndDropController.handleDrag `handleDrag`} can add additional mime types to the + * data transfer. These additional mime types will only be included in the `handleDrop` when the the drag was initiated from + * an element in the same drag and drop controller. + */ +@:jsRequire("vscode", "DataTransfer") +extern class DataTransfer { // implements Iterable<[mimeType: string, item: DataTransferItem]> { + + /** + * Retrieves the data transfer item for a given mime type. + * + * @param mimeType The mime type to get the data transfer item for, such as `text/plain` or `image/png`. + * Mimes type look ups are case-insensitive. + * + * Special mime types: + * - `text/uri-list` — A string with `toString()`ed Uris separated by `\r\n`. To specify a cursor position in the file, + * set the Uri's fragment to `L3,5`, where 3 is the line number and 5 is the column number. + */ + function get(mimeType:String):Null; + + /** + * Sets a mime type to data transfer item mapping. + * + * @param mimeType The mime type to set the data for. Mimes types stored in lower case, with case-insensitive looks up. + * @param value The data transfer item for the given mime type. + */ + function set(mimeType:String, value:DataTransferItem):Void; + + /** + * Allows iteration through the data transfer items. + * + * @param callbackfn Callback for iteration through the data transfer items. + * @param thisArg The `this` context used when invoking the handler function. + */ + function forEach(callbackfn:(item:DataTransferItem, mimeType:String, dataTransfer:DataTransfer) -> Void, ?thisArg:Any):Void; + + /** + * Get a new iterator with the `[mime, item]` pairs for each element in this data transfer. + */ + // [Symbol.iterator](): IterableIterator<[mimeType: string, item: DataTransferItem]>; +} diff --git a/src/vscode/DataTransferFile.hx b/src/vscode/DataTransferFile.hx new file mode 100644 index 00000000..b7bd9f3f --- /dev/null +++ b/src/vscode/DataTransferFile.hx @@ -0,0 +1,27 @@ +package vscode; + +import js.lib.Uint8Array; + +/** + * A file associated with a {@linkcode DataTransferItem}. + * + * Instances of this type can only be created by the editor and not by extensions. + */ +typedef DataTransferFile = { + /** + * The name of the file. + */ + var name(default, null):String; + + /** + * The full file path of the file. + * + * May be `undefined` on web. + */ + var ?uri(default, null):Uri; + + /** + * The full file contents of the file. + */ + function data():Thenable; +} diff --git a/src/vscode/DataTransferItem.hx b/src/vscode/DataTransferItem.hx new file mode 100644 index 00000000..b25a8a02 --- /dev/null +++ b/src/vscode/DataTransferItem.hx @@ -0,0 +1,37 @@ +package vscode; + +/** + * Encapsulates data transferred during drag and drop operations. + */ +@:jsRequire("vscode", "DataTransferItem") +extern class DataTransferItem { + /** + * Get a string representation of this item. + * + * If {@linkcode DataTransferItem.value} is an object, this returns the result of json stringifying {@linkcode DataTransferItem.value} value. + */ + function asString():Thenable; + + /** + * Try getting the {@link DataTransferFile file} associated with this data transfer item. + * + * Note that the file object is only valid for the scope of the drag and drop operation. + * + * @returns The file for the data transfer or `undefined` if the item is either not a file or the + * file data cannot be accessed. + */ + function asFile():Null; + + /** + * Custom data stored on this item. + * + * You can use `value` to share data across operations. The original object can be retrieved so long as the extension that + * created the `DataTransferItem` runs in the same extension host. + */ + var value(default, null):Any; + + /** + * @param value Custom data stored on this item. Can be retrieved using {@linkcode DataTransferItem.value}. + */ + function new(value:Any); +} diff --git a/src/vscode/DebugAdapterDescriptor.hx b/src/vscode/DebugAdapterDescriptor.hx index 9682c2c2..16abb7b8 100644 --- a/src/vscode/DebugAdapterDescriptor.hx +++ b/src/vscode/DebugAdapterDescriptor.hx @@ -1,4 +1,7 @@ package vscode; +/** + * Represents the different types of debug adapters + */ typedef DebugAdapterDescriptor = EitherType>>; diff --git a/src/vscode/DebugAdapterDescriptorFactory.hx b/src/vscode/DebugAdapterDescriptorFactory.hx index ca5ef727..3beff6fb 100644 --- a/src/vscode/DebugAdapterDescriptorFactory.hx +++ b/src/vscode/DebugAdapterDescriptorFactory.hx @@ -1,5 +1,8 @@ package vscode; +/** + * A debug adaper factory that creates {@link DebugAdapterDescriptor debug adapter descriptors}. + */ typedef DebugAdapterDescriptorFactory = { /** * 'createDebugAdapterDescriptor' is called at the start of a debug session to provide details about the debug adapter to use. @@ -16,7 +19,7 @@ typedef DebugAdapterDescriptorFactory = { * } * @param session The {@link DebugSession debug session} for which the debug adapter will be used. * @param executable The debug adapter's executable information as specified in the package.json (or undefined if no such information exists). - * @return a {@link DebugAdapterDescriptor debug adapter descriptor} or undefined. + * @returns a {@link DebugAdapterDescriptor debug adapter descriptor} or undefined. */ function createDebugAdapterDescriptor(session:DebugSession, ?executable:DebugAdapterExecutable):ProviderResult; } diff --git a/src/vscode/DebugAdapterTrackerFactory.hx b/src/vscode/DebugAdapterTrackerFactory.hx index f74dc9ba..7183da92 100644 --- a/src/vscode/DebugAdapterTrackerFactory.hx +++ b/src/vscode/DebugAdapterTrackerFactory.hx @@ -1,12 +1,15 @@ package vscode; +/** + * A debug adaper factory that creates {@link DebugAdapterTracker debug adapter trackers}. + */ typedef DebugAdapterTrackerFactory = { /** * The method 'createDebugAdapterTracker' is called at the start of a debug session in order * to return a "tracker" object that provides read-access to the communication between the editor and a debug adapter. * * @param session The {@link DebugSession debug session} for which the debug adapter tracker will be used. - * @return A {@link DebugAdapterTracker debug adapter tracker} or undefined. + * @returns A {@link DebugAdapterTracker debug adapter tracker} or undefined. */ function createDebugAdapterTracker(session:DebugSession):ProviderResult; } diff --git a/src/vscode/DebugConfigurationProvider.hx b/src/vscode/DebugConfigurationProvider.hx index 3c1e87a6..1fee7617 100644 --- a/src/vscode/DebugConfigurationProvider.hx +++ b/src/vscode/DebugConfigurationProvider.hx @@ -12,7 +12,7 @@ typedef DebugConfigurationProvider = { * * @param folder The workspace folder for which the configurations are used or `undefined` for a folderless setup. * @param token A cancellation token. - * @return An array of {@link DebugConfiguration debug configurations}. + * @returns An array of {@link DebugConfiguration debug configurations}. */ @:optional function provideDebugConfigurations(folder:Null, ?token:CancellationToken):ProviderResult>; @@ -26,7 +26,7 @@ typedef DebugConfigurationProvider = { * @param folder The workspace folder from which the configuration originates from or `undefined` for a folderless setup. * @param debugConfiguration The {@link DebugConfiguration debug configuration} to resolve. * @param token A cancellation token. - * @return The resolved debug configuration or undefined or null. + * @returns The resolved debug configuration or undefined or null. */ @:optional function resolveDebugConfiguration(folder:Null, debugConfiguration:DebugConfiguration, ?token:CancellationToken):ProviderResult; @@ -42,7 +42,7 @@ typedef DebugConfigurationProvider = { * @param folder The workspace folder from which the configuration originates from or `undefined` for a folderless setup. * @param debugConfiguration The {@link DebugConfiguration debug configuration} to resolve. * @param token A cancellation token. - * @return The resolved debug configuration or undefined or null. + * @returns The resolved debug configuration or undefined or null. */ @:optional function resolveDebugConfigurationWithSubstitutedVariables(folder:Null, debugConfiguration:DebugConfiguration, ?token:CancellationToken):ProviderResult; diff --git a/src/vscode/DebugProtocolBreakpoint.hx b/src/vscode/DebugProtocolBreakpoint.hx index 2b243130..68952375 100644 --- a/src/vscode/DebugProtocolBreakpoint.hx +++ b/src/vscode/DebugProtocolBreakpoint.hx @@ -4,5 +4,5 @@ package vscode; * A DebugProtocolBreakpoint is an opaque stand-in type for the [Breakpoint](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Breakpoint) type defined in the Debug Adapter Protocol. */ typedef DebugProtocolBreakpoint = { - // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Breakpoint). + // Properties: see [Breakpoint details](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Breakpoint). } diff --git a/src/vscode/DebugProtocolMessage.hx b/src/vscode/DebugProtocolMessage.hx index b2356cbb..57b67a9e 100644 --- a/src/vscode/DebugProtocolMessage.hx +++ b/src/vscode/DebugProtocolMessage.hx @@ -4,5 +4,5 @@ package vscode; * A DebugProtocolMessage is an opaque stand-in type for the [ProtocolMessage](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_ProtocolMessage) type defined in the Debug Adapter Protocol. */ typedef DebugProtocolMessage = { - // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_ProtocolMessage). + // Properties: see [ProtocolMessage details](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_ProtocolMessage). } diff --git a/src/vscode/DebugProtocolSource.hx b/src/vscode/DebugProtocolSource.hx index efb560a6..11b3db1f 100644 --- a/src/vscode/DebugProtocolSource.hx +++ b/src/vscode/DebugProtocolSource.hx @@ -4,5 +4,5 @@ package vscode; * A DebugProtocolSource is an opaque stand-in type for the [Source](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source) type defined in the Debug Adapter Protocol. */ typedef DebugProtocolSource = { - // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source). + // Properties: see [Source details](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source). } diff --git a/src/vscode/DebugSession.hx b/src/vscode/DebugSession.hx index f7e0ae9a..75d57aa1 100644 --- a/src/vscode/DebugSession.hx +++ b/src/vscode/DebugSession.hx @@ -49,7 +49,7 @@ typedef DebugSession = { * If no DAP breakpoint exists (either because the editor breakpoint was not yet registered or because the debug adapter is not interested in the breakpoint), the value `undefined` is returned. * * @param breakpoint A {@link Breakpoint} in the editor. - * @return A promise that resolves to the Debug Adapter Protocol breakpoint or `undefined`. + * @returns A promise that resolves to the Debug Adapter Protocol breakpoint or `undefined`. */ function getDebugProtocolBreakpoint(breakpoint:Breakpoint):Thenable>; } diff --git a/src/vscode/DebugSessionCustomEvent.hx b/src/vscode/DebugSessionCustomEvent.hx index 1d6b99ff..e241851a 100644 --- a/src/vscode/DebugSessionCustomEvent.hx +++ b/src/vscode/DebugSessionCustomEvent.hx @@ -17,5 +17,5 @@ typedef DebugSessionCustomEvent = { /** * Event specific information. */ - var ?body(default, null):Any; + var body(default, null):Any; } diff --git a/src/vscode/DebugSessionOptions.hx b/src/vscode/DebugSessionOptions.hx index a0859c1e..6869ef49 100644 --- a/src/vscode/DebugSessionOptions.hx +++ b/src/vscode/DebugSessionOptions.hx @@ -36,4 +36,31 @@ typedef DebugSessionOptions = { * If compact is true, debug sessions with a single child are hidden in the CALL STACK view to make the tree more compact. */ var ?compact:Bool; + + /** + * When true, a save will not be triggered for open editors when starting a debug session, regardless of the value of the `debug.saveBeforeStart` setting. + */ + var ?suppressSaveBeforeStart:Bool; + + /** + * When true, the debug toolbar will not be shown for this session. + */ + var ?suppressDebugToolbar:Bool; + + /** + * When true, the window statusbar color will not be changed for this session. + */ + var ?suppressDebugStatusbar:Bool; + + /** + * When true, the debug viewlet will not be automatically revealed for this session. + */ + var ?suppressDebugView:Bool; + + /** + * Signals to the editor that the debug session was started from a test run + * request. This is used to link the lifecycle of the debug session and + * test run in UI actions. + */ + var ?testRun:TestRun; } diff --git a/src/vscode/DebugStackFrame.hx b/src/vscode/DebugStackFrame.hx new file mode 100644 index 00000000..5b41d4d9 --- /dev/null +++ b/src/vscode/DebugStackFrame.hx @@ -0,0 +1,27 @@ +package vscode; + +/** + * Represents a stack frame in a debug session. + */ +@:jsRequire("vscode", "DebugStackFrame") +extern class DebugStackFrame { + /** + * Debug session for thread. + */ + var session(default, null):DebugSession; + + /** + * ID of the associated thread in the debug protocol. + */ + var threadId(default, null):Int; + + /** + * ID of the stack frame in the debug protocol. + */ + var frameId(default, null):Int; + + /** + * @hidden + */ + private function new(session:DebugSession, threadId:Int, frameId:Int); +} diff --git a/src/vscode/DebugThread.hx b/src/vscode/DebugThread.hx new file mode 100644 index 00000000..117d1338 --- /dev/null +++ b/src/vscode/DebugThread.hx @@ -0,0 +1,22 @@ +package vscode; + +/** + * Represents a thread in a debug session. + */ +@:jsRequire("vscode", "DebugThread") +extern class DebugThread { + /** + * Debug session for thread. + */ + var session(default, null):DebugSession; + + /** + * ID of the associated thread in the debug protocol. + */ + var threadId(default, null):Int; + + /** + * @hidden + */ + private function new(session:DebugSession, threadId:Int); +} diff --git a/src/vscode/DeclarationCoverage.hx b/src/vscode/DeclarationCoverage.hx new file mode 100644 index 00000000..e7cf3fe2 --- /dev/null +++ b/src/vscode/DeclarationCoverage.hx @@ -0,0 +1,33 @@ +package vscode; + +/** + * Contains coverage information for a declaration. Depending on the reporter + * and language, this may be types such as functions, methods, or namespaces. + */ +@:jsRequire("vscode", "DeclarationCoverage") +extern class DeclarationCoverage { + /** + * Name of the declaration. + */ + var name:String; + + /** + * The number of times this declaration was executed, or a boolean + * indicating whether it was executed if the exact count is unknown. If + * zero or false, the declaration will be marked as un-covered. + */ + var executed:EitherType; + + /** + * Declaration location. + */ + var location:EitherType; + + /** + * @param executed The number of times this declaration was executed, or a + * boolean indicating whether it was executed if the exact count is + * unknown. If zero or false, the declaration will be marked as un-covered. + * @param location The declaration position. + */ + function new(name:String, executed:EitherType, location:EitherType); +} diff --git a/src/vscode/DeclarationProvider.hx b/src/vscode/DeclarationProvider.hx index e867aba4..7d951855 100644 --- a/src/vscode/DeclarationProvider.hx +++ b/src/vscode/DeclarationProvider.hx @@ -11,7 +11,7 @@ typedef DeclarationProvider = { * @param document The document in which the command was invoked. * @param position The position at which the command was invoked. * @param token A cancellation token. - * @return A declaration or a thenable that resolves to such. The lack of a result can be + * @returns A declaration or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined` or `null`. */ function provideDeclaration(document:TextDocument, position:Position, token:CancellationToken):ProviderResult; diff --git a/src/vscode/DecorationInstanceRenderOptions.hx b/src/vscode/DecorationInstanceRenderOptions.hx index 223be983..563b2d4b 100644 --- a/src/vscode/DecorationInstanceRenderOptions.hx +++ b/src/vscode/DecorationInstanceRenderOptions.hx @@ -1,5 +1,8 @@ package vscode; +/** + * Represents render options for decoration instances. See {@link DecorationOptions.renderOptions}. + */ typedef DecorationInstanceRenderOptions = ThemableDecorationInstanceRenderOptions & { /** * Overwrite options for light themes. diff --git a/src/vscode/DecorationRangeBehavior.hx b/src/vscode/DecorationRangeBehavior.hx index cba0879c..eb3fe86d 100644 --- a/src/vscode/DecorationRangeBehavior.hx +++ b/src/vscode/DecorationRangeBehavior.hx @@ -11,7 +11,7 @@ extern enum abstract DecorationRangeBehavior(Int) { var OpenOpen; /** - * The decoration's range will not widen when edits occur at the start of end. + * The decoration's range will not widen when edits occur at the start or end. */ var ClosedClosed; diff --git a/src/vscode/DefinitionProvider.hx b/src/vscode/DefinitionProvider.hx index f44ee28e..7272be0c 100644 --- a/src/vscode/DefinitionProvider.hx +++ b/src/vscode/DefinitionProvider.hx @@ -12,9 +12,8 @@ typedef DefinitionProvider = { * @param document The document in which the command was invoked. * @param position The position at which the command was invoked. * @param token A cancellation token. - * @return A definition or a thenable that resolves to such. The lack of a result can be + * @returns A definition or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined` or `null`. */ - function provideDefinition(document:TextDocument, position:Position, - token:CancellationToken):ProviderResult>>; + function provideDefinition(document:TextDocument, position:Position, token:CancellationToken):ProviderResult>>; } diff --git a/src/vscode/DiagnosticCollection.hx b/src/vscode/DiagnosticCollection.hx index f1527438..fdf0d937 100644 --- a/src/vscode/DiagnosticCollection.hx +++ b/src/vscode/DiagnosticCollection.hx @@ -8,7 +8,9 @@ package vscode; * To get an instance of a `DiagnosticCollection` use * {@link languages.createDiagnosticCollection createDiagnosticCollection}. */ -typedef DiagnosticCollection = { +@:jsRequire("vscode", "DiagnosticCollection") +extern class DiagnosticCollection { // extends Iterable<{uri:Uri, diagnostics:ReadOnlyArray}> { + /** * The name of this diagnostic collection, for instance `typescript`. Every diagnostic * from this collection will be associated with this name. Also, the task framework uses this @@ -23,19 +25,19 @@ typedef DiagnosticCollection = { * @param uri A resource identifier. * @param diagnostics Array of diagnostics or `undefined` */ - // TODO overload plox - // /** - // * Replace diagnostics for multiple resources in this collection. - // * - // * _Note_ that multiple tuples of the same uri will be merged, e.g - // * `[[file1, [d1]], [file1, [d2]]]` is equivalent to `[[file1, [d1, d2]]]`. - // * If a diagnostics item is `undefined` as in `[file1, undefined]` - // * all previous but not subsequent diagnostics are removed. - // * - // * @param entries An array of tuples, like `[[file1, [d1, d2]], [file2, [d3, d4, d5]]]`, or `undefined`. - // */ - @:overload(function(entries:ReadOnlyArray>):Void {}) - function set(uri:Uri, diagnostics:Null>):Void; + overload function set(uri:Uri, diagnostics:Null>):Void; + + /** + * Replace diagnostics for multiple resources in this collection. + * + * _Note_ that multiple tuples of the same uri will be merged, e.g + * `[[file1, [d1]], [file1, [d2]]]` is equivalent to `[[file1, [d1, d2]]]`. + * If a diagnostics item is `undefined` as in `[file1, undefined]` + * all previous but not subsequent diagnostics are removed. + * + * @param entries An array of tuples, like `[[file1, [d1, d2]], [file2, [d3, d4, d5]]]`, or `undefined`. + */ + overload function set(entries:ReadOnlyArray>):Void; /** * Remove all diagnostics from this collection that belong diff --git a/src/vscode/Disposable.hx b/src/vscode/Disposable.hx index 54e2f135..8ceba16e 100644 --- a/src/vscode/Disposable.hx +++ b/src/vscode/Disposable.hx @@ -7,22 +7,30 @@ package vscode; @:jsRequire("vscode", "Disposable") extern class Disposable { /** - * Combine many disposable-likes into one. Use this method - * when having objects with a dispose function which are not - * instances of Disposable. + * Combine many disposable-likes into one. You can use this method when having objects with + * a dispose function which aren't instances of `Disposable`. * - * @param disposableLikes Objects that have at least a `dispose`-function member. - * @return Returns a new disposable which, upon dispose, will + * @param disposableLikes Objects that have at least a `dispose`-function member. Note that asynchronous + * dispose-functions aren't awaited. + * @returns Returns a new disposable which, upon dispose, will * dispose all provided disposables. */ - static function from(disposableLikes:Rest<{function dispose():Void;}>):Disposable; + static function from(disposableLikes:Rest<{ + /** + * Function to clean up resources. + */ + function dispose():Void; + }>):Disposable; /** - * Creates a new Disposable calling the provided function + * Creates a new disposable that calls the provided function * on dispose. + * + * *Note* that an asynchronous function is not awaited. + * * @param callOnDispose Function that disposes something. */ - function new(callOnDispose:Function):Void; + function new(callOnDispose:() -> Any):Void; /** * Dispose this object. diff --git a/src/vscode/DocumentColorProvider.hx b/src/vscode/DocumentColorProvider.hx index 6d438787..5acf42f2 100644 --- a/src/vscode/DocumentColorProvider.hx +++ b/src/vscode/DocumentColorProvider.hx @@ -10,7 +10,7 @@ typedef DocumentColorProvider = { * * @param document The document in which the command was invoked. * @param token A cancellation token. - * @return An array of {@link ColorInformation color information} or a thenable that resolves to such. The lack of a result + * @returns An array of {@link ColorInformation color information} or a thenable that resolves to such. The lack of a result * can be signaled by returning `undefined`, `null`, or an empty array. */ function provideDocumentColors(document:TextDocument, token:CancellationToken):ProviderResult>; @@ -21,9 +21,17 @@ typedef DocumentColorProvider = { * @param color The color to show and insert. * @param context A context object with additional information * @param token A cancellation token. - * @return An array of color presentations or a thenable that resolves to such. The lack of a result + * @returns An array of color presentations or a thenable that resolves to such. The lack of a result * can be signaled by returning `undefined`, `null`, or an empty array. */ - function provideColorPresentations(color:Color, context:{document:TextDocument, range:Range}, - token:CancellationToken):ProviderResult>; + function provideColorPresentations(color:Color, context:{ + /** + * The text document that contains the color + */ + document:TextDocument, + /** + * The range in the document where the color is located. + */ + range:Range + }, token:CancellationToken):ProviderResult>; } diff --git a/src/vscode/DocumentDropEdit.hx b/src/vscode/DocumentDropEdit.hx new file mode 100644 index 00000000..44823e2a --- /dev/null +++ b/src/vscode/DocumentDropEdit.hx @@ -0,0 +1,22 @@ +package vscode; + +/** + * An edit operation applied {@link DocumentDropEditProvider on drop}. + */ +@:jsRequire("vscode", "DocumentDropEdit") +extern class DocumentDropEdit { + /** + * The text or snippet to insert at the drop location. + */ + var insertText:EitherType; + + /** + * An optional additional edit to apply on drop. + */ + var additionalEdit:Null; + + /** + * @param insertText The text or snippet to insert at the drop location. + */ + function new(insertText:EitherType); +} diff --git a/src/vscode/DocumentDropEditProvider.hx b/src/vscode/DocumentDropEditProvider.hx new file mode 100644 index 00000000..0a4eda4d --- /dev/null +++ b/src/vscode/DocumentDropEditProvider.hx @@ -0,0 +1,24 @@ +package vscode; + +/** + * Provider which handles dropping of resources into a text editor. + * + * This allows users to drag and drop resources (including resources from external apps) into the editor. While dragging + * and dropping files, users can hold down `shift` to drop the file into the editor instead of opening it. + * Requires `editor.dropIntoEditor.enabled` to be on. + */ +typedef DocumentDropEditProvider = { + /** + * Provide edits which inserts the content being dragged and dropped into the document. + * + * @param document The document in which the drop occurred. + * @param position The position in the document where the drop occurred. + * @param dataTransfer A {@link DataTransfer} object that holds data about what is being dragged and dropped. + * @param token A cancellation token. + * + * @returns A {@link DocumentDropEdit} or a thenable that resolves to such. The lack of a result can be + * signaled by returning `undefined` or `null`. + */ + function provideDocumentDropEdits(document:TextDocument, position:Position, dataTransfer:DataTransfer, + token:CancellationToken):ProviderResult; +} diff --git a/src/vscode/DocumentFilter.hx b/src/vscode/DocumentFilter.hx index 3e6fa74a..48e53893 100644 --- a/src/vscode/DocumentFilter.hx +++ b/src/vscode/DocumentFilter.hx @@ -15,7 +15,19 @@ typedef DocumentFilter = { /** * A language id, like `typescript`. */ - final ?language:String; + var ?language(default, null):String; + + /** + * The {@link NotebookDocument.notebookType type} of a notebook, like `jupyter-notebook`. This allows + * to narrow down on the type of a notebook that a {@link NotebookCell.document cell document} belongs to. + * + * *Note* that setting the `notebookType`-property changes how `scheme` and `pattern` are interpreted. When set + * they are evaluated against the {@link NotebookDocument.uri notebook uri}, not the document uri. + * + * @example Match python document inside jupyter notebook that aren't stored yet (`untitled`) + * { language: 'python', notebookType: 'jupyter-notebook', scheme: 'untitled' } + */ + var ?notebookType(default, null):String; /** * A Uri {@link Uri.scheme scheme}, like `file` or `untitled`. diff --git a/src/vscode/DocumentFormattingEditProvider.hx b/src/vscode/DocumentFormattingEditProvider.hx index 4f6fdbcf..7f0c63fa 100644 --- a/src/vscode/DocumentFormattingEditProvider.hx +++ b/src/vscode/DocumentFormattingEditProvider.hx @@ -11,7 +11,7 @@ typedef DocumentFormattingEditProvider = { * @param document The document in which the command was invoked. * @param options Options controlling formatting. * @param token A cancellation token. - * @return A set of text edits or a thenable that resolves to such. The lack of a result can be + * @returns A set of text edits or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined`, `null`, or an empty array. */ function provideDocumentFormattingEdits(document:TextDocument, options:FormattingOptions, token:CancellationToken):ProviderResult>; diff --git a/src/vscode/DocumentHighlightProvider.hx b/src/vscode/DocumentHighlightProvider.hx index 0ed42d6c..83c8cdf9 100644 --- a/src/vscode/DocumentHighlightProvider.hx +++ b/src/vscode/DocumentHighlightProvider.hx @@ -12,7 +12,7 @@ typedef DocumentHighlightProvider = { * @param document The document in which the command was invoked. * @param position The position at which the command was invoked. * @param token A cancellation token. - * @return An array of document highlights or a thenable that resolves to such. The lack of a result can be + * @returns An array of document highlights or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined`, `null`, or an empty array. */ function provideDocumentHighlights(document:TextDocument, position:Position, token:CancellationToken):ProviderResult>; diff --git a/src/vscode/DocumentLinkProvider.hx b/src/vscode/DocumentLinkProvider.hx index 8d1219bc..ce36110e 100644 --- a/src/vscode/DocumentLinkProvider.hx +++ b/src/vscode/DocumentLinkProvider.hx @@ -11,7 +11,7 @@ typedef DocumentLinkProvider = { * * @param document The document in which the command was invoked. * @param token A cancellation token. - * @return An array of {@link DocumentLink document links} or a thenable that resolves to such. The lack of a result + * @returns An array of {@link DocumentLink document links} or a thenable that resolves to such. The lack of a result * can be signaled by returning `undefined`, `null`, or an empty array. */ function provideDocumentLinks(document:TextDocument, token:CancellationToken):ProviderResult>; diff --git a/src/vscode/DocumentRangeFormattingEditProvider.hx b/src/vscode/DocumentRangeFormattingEditProvider.hx index 1eadd414..86cd6e02 100644 --- a/src/vscode/DocumentRangeFormattingEditProvider.hx +++ b/src/vscode/DocumentRangeFormattingEditProvider.hx @@ -16,9 +16,29 @@ typedef DocumentRangeFormattingEditProvider = { * @param range The range which should be formatted. * @param options Options controlling formatting. * @param token A cancellation token. - * @return A set of text edits or a thenable that resolves to such. The lack of a result can be + * @returns A set of text edits or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined`, `null`, or an empty array. */ function provideDocumentRangeFormattingEdits(document:TextDocument, range:Range, options:FormattingOptions, token:CancellationToken):ProviderResult>; + + /** + * Provide formatting edits for multiple ranges in a document. + * + * This function is optional but allows a formatter to perform faster when formatting only modified ranges or when + * formatting a large number of selections. + * + * The given ranges are hints and providers can decide to format a smaller + * or larger range. Often this is done by adjusting the start and end + * of the range to full syntax nodes. + * + * @param document The document in which the command was invoked. + * @param ranges The ranges which should be formatted. + * @param options Options controlling formatting. + * @param token A cancellation token. + * @returns A set of text edits or a thenable that resolves to such. The lack of a result can be + * signaled by returning `undefined`, `null`, or an empty array. + */ + @:optional function provideDocumentRangesFormattingEdits(document:TextDocument, ranges:Array, options:FormattingOptions, + token:CancellationToken):ProviderResult>; } diff --git a/src/vscode/DocumentSymbolProvider.hx b/src/vscode/DocumentSymbolProvider.hx index aab22608..13fd942a 100644 --- a/src/vscode/DocumentSymbolProvider.hx +++ b/src/vscode/DocumentSymbolProvider.hx @@ -10,9 +10,8 @@ typedef DocumentSymbolProvider = { * * @param document The document in which the command was invoked. * @param token A cancellation token. - * @return An array of document highlights or a thenable that resolves to such. The lack of a result can be + * @returns An array of document highlights or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined`, `null`, or an empty array. */ - function provideDocumentSymbols(document:TextDocument, - token:CancellationToken):ProviderResult, Array>>; + function provideDocumentSymbols(document:TextDocument, token:CancellationToken):ProviderResult, Array>>; } diff --git a/src/vscode/EnvironmentVariableCollection.hx b/src/vscode/EnvironmentVariableCollection.hx index bf8e77dd..4be885b9 100644 --- a/src/vscode/EnvironmentVariableCollection.hx +++ b/src/vscode/EnvironmentVariableCollection.hx @@ -21,6 +21,8 @@ typedef EnvironmentVariableCollection = { * * @param variable The variable to replace. * @param value The value to replace the variable with. + * @param options Options applied to the mutator, when no options are provided this will + * default to `{ applyAtProcessCreation: true }`. */ function replace(variable:String, value:String):Void; @@ -32,6 +34,8 @@ typedef EnvironmentVariableCollection = { * * @param variable The variable to append to. * @param value The value to append to the variable. + * @param options Options applied to the mutator, when no options are provided this will + * default to `{ applyAtProcessCreation: true }`. */ function append(variable:String, value:String):Void; @@ -43,6 +47,8 @@ typedef EnvironmentVariableCollection = { * * @param variable The variable to prepend. * @param value The value to prepend to the variable. + * @param options Options applied to the mutator, when no options are provided this will + * default to `{ applyAtProcessCreation: true }`. */ function prepend(variable:String, value:String):Void; diff --git a/src/vscode/EnvironmentVariableMutator.hx b/src/vscode/EnvironmentVariableMutator.hx index 9850c935..9ac1c135 100644 --- a/src/vscode/EnvironmentVariableMutator.hx +++ b/src/vscode/EnvironmentVariableMutator.hx @@ -13,4 +13,9 @@ typedef EnvironmentVariableMutator = { * The value to use for the variable. */ final value:String; + + /** + * Options applied to the mutator. + */ + final options:EnvironmentVariableMutatorOptions; } diff --git a/src/vscode/EnvironmentVariableMutatorOptions.hx b/src/vscode/EnvironmentVariableMutatorOptions.hx new file mode 100644 index 00000000..a413c703 --- /dev/null +++ b/src/vscode/EnvironmentVariableMutatorOptions.hx @@ -0,0 +1,18 @@ +package vscode; + +/** + * Options applied to the mutator. + */ +typedef EnvironmentVariableMutatorOptions = { + /** + * Apply to the environment just before the process is created. Defaults to false. + */ + var ?applyAtProcessCreation:Bool; + + /** + * Apply to the environment in the shell integration script. Note that this _will not_ apply + * the mutator if shell integration is disabled or not working for some reason. Defaults to + * false. + */ + var ?applyAtShellIntegration:Bool; +} diff --git a/src/vscode/EnvironmentVariableScope.hx b/src/vscode/EnvironmentVariableScope.hx new file mode 100644 index 00000000..78512753 --- /dev/null +++ b/src/vscode/EnvironmentVariableScope.hx @@ -0,0 +1,11 @@ +package vscode; + +/** + * The scope object to which the environment variable collection applies. + */ +typedef EnvironmentVariableScope = { + /** + * Any specific workspace folder to get collection for. + */ + var ?workspaceFolder:WorkspaceFolder; +} diff --git a/src/vscode/EvaluatableExpressionProvider.hx b/src/vscode/EvaluatableExpressionProvider.hx index 3e936bbf..5cd67694 100644 --- a/src/vscode/EvaluatableExpressionProvider.hx +++ b/src/vscode/EvaluatableExpressionProvider.hx @@ -14,7 +14,7 @@ typedef EvaluatableExpressionProvider = { * @param document The document for which the debug hover is about to appear. * @param position The line and character position in the document where the debug hover is about to appear. * @param token A cancellation token. - * @return An EvaluatableExpression or a thenable that resolves to such. The lack of a result can be + * @returns An EvaluatableExpression or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined` or `null`. */ function provideEvaluatableExpression(document:TextDocument, position:Position, token:CancellationToken):ProviderResult; diff --git a/src/vscode/Event.hx b/src/vscode/Event.hx index 066a544d..542c7fa9 100644 --- a/src/vscode/Event.hx +++ b/src/vscode/Event.hx @@ -9,7 +9,7 @@ package vscode; * @param listener The listener function will be called when the event happens. * @param thisArgs The `this`-argument which will be used when calling the event listener. * @param disposables An array to which a {@link Disposable} will be added. - * @return A disposable which unsubscribes the event listener. + * @returns A disposable which unsubscribes the event listener. * * @example * item.onDidChange(function(event) { console.log("Event happened: " + event); }); diff --git a/src/vscode/Extension.hx b/src/vscode/Extension.hx index 62f564b6..7165eb3c 100644 --- a/src/vscode/Extension.hx +++ b/src/vscode/Extension.hx @@ -42,15 +42,15 @@ typedef Extension = { var extensionKind:ExtensionKind; /** - * The public API exported by this extension. It is an invalid action - * to access this field before this extension has been activated. + * The public API exported by this extension (return value of `activate`). + * It is an invalid action to access this field before this extension has been activated. */ var exports:T; /** * Activates this extension and returns its public API. * - * @return A promise that will resolve when this extension has been activated. + * @returns A promise that will resolve when this extension has been activated. */ function activate():Thenable; } diff --git a/src/vscode/ExtensionContext.hx b/src/vscode/ExtensionContext.hx index e6ddb226..305e2fb7 100644 --- a/src/vscode/ExtensionContext.hx +++ b/src/vscode/ExtensionContext.hx @@ -11,8 +11,15 @@ typedef ExtensionContext = { /** * An array to which disposables can be added. When this * extension is deactivated the disposables will be disposed. + * + * *Note* that asynchronous dispose-functions aren't awaited. */ - var subscriptions(default, null):Array<{function dispose():Void;}>; + var subscriptions(default, null):Array<{ + /** + * Function to clean up resources. + */ + function dispose():Void; + }>; /** * A memento object that stores state in the context @@ -24,27 +31,11 @@ typedef ExtensionContext = { * A memento object that stores state independent * of the current opened {@link workspace.workspaceFolders workspace}. */ - var globalState(default, null):Memento & { - - /** - * Set the keys whose values should be synchronized across devices when synchronizing user-data - * like configuration, extensions, and mementos. - * - * Note that this function defines the whole set of keys whose values are synchronized: - * - calling it with an empty array stops synchronization for this memento - * - calling it with a non-empty array replaces all keys whose values are synchronized - * - * For any given set of keys this function needs to be called only once but there is no harm in - * repeatedly calling it. - * - * @param keys The set of keys whose values are synced. - */ - function setKeysForSync(keys:ReadOnlyArray):Void; - }; + var globalState(default, null):MementoKeysForSync; /** - * A storage utility for secrets. Secrets are persisted across reloads and are independent of the - * current opened {@link workspace.workspaceFolders workspace}. + * A secret storage object that stores state independent + * of the current opened {@link workspace.workspaceFolders workspace}. */ var secrets(default, null):SecretStorage; @@ -60,10 +51,10 @@ typedef ExtensionContext = { var extensionPath(default, null):String; /** - * Gets the extension's environment variable collection for this workspace, enabling changes - * to be applied to terminal environment variables. + * Gets the extension's global environment variable collection for this workspace, enabling changes to be + * applied to terminal environment variables. */ - var environmentVariableCollection(default, null):EnvironmentVariableCollection; + var environmentVariableCollection(default, null):GlobalEnvironmentVariableCollection; /** * Get the absolute path of a resource contained in the extension. @@ -72,7 +63,7 @@ typedef ExtensionContext = { * {@linkcode ExtensionContext.extensionUri extensionUri}, e.g. `vscode.Uri.joinPath(context.extensionUri, relativePath);` * * @param relativePath A relative path to a resource contained in the extension. - * @return The absolute path of the resource. + * @returns The absolute path of the resource. */ function asAbsolutePath(relativePath:String):String; @@ -148,9 +139,8 @@ typedef ExtensionContext = { var logPath(default, null):String; /** - * The mode the extension is running in. This is specific to the current - * extension. One extension may be in `ExtensionMode.Development` while - * other extensions in the host run in `ExtensionMode.Release`. + * The mode the extension is running in. See {@link ExtensionMode} + * for possible values and scenarios. */ var extensionMode(default, null):ExtensionMode; @@ -158,4 +148,28 @@ typedef ExtensionContext = { * The current `Extension` instance. */ var extension(default, null):Extension; + + /** + * An object that keeps information about how this extension can use language models. + * + * @see {@link LanguageModelChat.sendRequest} + */ + var languageModelAccessInformation(default, null):LanguageModelAccessInformation; +} + +abstract class MementoKeysForSync extends Memento { + /** + * Set the keys whose values should be synchronized across devices when synchronizing user-data + * like configuration, extensions, and mementos. + * + * Note that this function defines the whole set of keys whose values are synchronized: + * - calling it with an empty array stops synchronization for this memento + * - calling it with a non-empty array replaces all keys whose values are synchronized + * + * For any given set of keys this function needs to be called only once but there is no harm in + * repeatedly calling it. + * + * @param keys The set of keys whose values are synced. + */ + abstract function setKeysForSync(keys:ReadOnlyArray):Void; } diff --git a/src/vscode/ExtensionTerminalOptions.hx b/src/vscode/ExtensionTerminalOptions.hx index a04af186..41873012 100644 --- a/src/vscode/ExtensionTerminalOptions.hx +++ b/src/vscode/ExtensionTerminalOptions.hx @@ -18,7 +18,7 @@ typedef ExtensionTerminalOptions = { /** * The icon path or {@link ThemeIcon} for the terminal. */ - var ?iconPath:EitherType>; + var ?iconPath:IconPath; /** * The icon {@link ThemeColor} for the terminal. @@ -26,4 +26,15 @@ typedef ExtensionTerminalOptions = { * recommended for the best contrast and consistency across themes. */ var ?color:ThemeColor; + + /** + * The {@link TerminalLocation} or {@link TerminalEditorLocationOptions} or {@link TerminalSplitLocationOptions} for the terminal. + */ + var ?location:EitherType>; + + /** + * Opt-out of the default terminal persistence on restart and reload. + * This will only take effect when `terminal.integrated.enablePersistentSessions` is enabled. + */ + var ?isTransient:Bool; } diff --git a/src/vscode/FileCoverage.hx b/src/vscode/FileCoverage.hx new file mode 100644 index 00000000..03d51ad2 --- /dev/null +++ b/src/vscode/FileCoverage.hx @@ -0,0 +1,56 @@ +package vscode; + +/** + * Contains coverage metadata for a file. + */ +@:jsRequire("vscode", "FileCoverage") +extern class FileCoverage { + /** + * File URI. + */ + var uri(default, null):Uri; + + /** + * Statement coverage information. If the reporter does not provide statement + * coverage information, this can instead be used to represent line coverage. + */ + var statementCoverage:TestCoverageCount; + + /** + * Branch coverage information. + */ + var branchCoverage:Null; + + /** + * Declaration coverage information. Depending on the reporter and + * language, this may be types such as functions, methods, or namespaces. + */ + var declarationCoverage:Null; + + /** + * A list of {@link TestItem test cases} that generated coverage in this + * file. If set, then {@link TestRunProfile.loadDetailedCoverageForTest} + * should also be defined in order to retrieve detailed coverage information. + */ + var includesTests:Null>; + + /** + * Creates a {@link FileCoverage} instance with counts filled in from + * the coverage details. + * @param uri Covered file URI + * @param detailed Detailed coverage information + */ + static function fromDetails(uri:Uri, details:ReadOnlyArray):FileCoverage; + + /** + * @param uri Covered file URI + * @param statementCoverage Statement coverage information. If the reporter + * does not provide statement coverage information, this can instead be + * used to represent line coverage. + * @param branchCoverage Branch coverage information + * @param declarationCoverage Declaration coverage information + * @param includesTests Test cases included in this coverage report, see {@link includesTests} + */ + function new(uri:Uri, statementCoverage:TestCoverageCount, ?branchCoverage:TestCoverageCount, ?declarationCoverage:TestCoverageCount, + ?includesTests:Array); +} diff --git a/src/vscode/FileCoverageDetail.hx b/src/vscode/FileCoverageDetail.hx new file mode 100644 index 00000000..bec77593 --- /dev/null +++ b/src/vscode/FileCoverageDetail.hx @@ -0,0 +1,3 @@ +package vscode; + +typedef FileCoverageDetail = EitherType; diff --git a/src/vscode/FilePermission.hx b/src/vscode/FilePermission.hx new file mode 100644 index 00000000..9b4471a4 --- /dev/null +++ b/src/vscode/FilePermission.hx @@ -0,0 +1,17 @@ +package vscode; + +/** + * Permissions of a file. + */ +@:jsRequire("vscode", "FilePermission") +extern enum abstract FilePermission(Int) { + /** + * The file is readonly. + * + * *Note:* All `FileStat` from a `FileSystemProvider` that is registered with + * the option `isReadonly: true` will be implicitly handled as if `FilePermission.Readonly` + * is set. As a consequence, it is not possible to have a readonly file system provider + * registered where some `FileStat` are not readonly. + */ + var Readonly; +} diff --git a/src/vscode/FileRenameEvent.hx b/src/vscode/FileRenameEvent.hx index f82627bd..67208e18 100644 --- a/src/vscode/FileRenameEvent.hx +++ b/src/vscode/FileRenameEvent.hx @@ -7,5 +7,14 @@ typedef FileRenameEvent = { /** * The files that got renamed. */ - var files(default, never):ReadOnlyArray<{final oldUri:Uri; final newUri:Uri;}>; + var files(default, never):ReadOnlyArray<{ + /** + * The old uri of a file. + */ + final oldUri:Uri; + /** + * The new uri of a file. + */ + final newUri:Uri; + }>; } diff --git a/src/vscode/FileStat.hx b/src/vscode/FileStat.hx index 0a8f2896..cbf6313e 100644 --- a/src/vscode/FileStat.hx +++ b/src/vscode/FileStat.hx @@ -34,4 +34,11 @@ typedef FileStat = { * example. */ var size:Int; + + /** + * The permissions of the file, e.g. whether the file is readonly. + * + * *Note:* This value might be a bitmask, e.g. `FilePermission.Readonly | FilePermission.Other`. + */ + var ?permissions:FilePermission; } diff --git a/src/vscode/FileSystem.hx b/src/vscode/FileSystem.hx index 2ed1aa19..d485bad3 100644 --- a/src/vscode/FileSystem.hx +++ b/src/vscode/FileSystem.hx @@ -15,7 +15,7 @@ typedef FileSystem = { * Retrieve metadata about a file. * * @param uri The uri of the file to retrieve metadata about. - * @return The file metadata about the file. + * @returns The file metadata about the file. */ function stat(uri:Uri):Thenable; @@ -23,7 +23,7 @@ typedef FileSystem = { * Retrieve all entries of a {@link FileType.Directory directory}. * * @param uri The uri of the folder. - * @return An array of name/type-tuples or a thenable that resolves to such. + * @returns An array of name/type-tuples or a thenable that resolves to such. */ function readDirectory(uri:Uri):Thenable>; @@ -41,7 +41,7 @@ typedef FileSystem = { * Read the entire contents of a file. * * @param uri The uri of the file. - * @return An array of bytes or a thenable that resolves to such. + * @returns An array of bytes or a thenable that resolves to such. */ function readFile(uri:Uri):Thenable; @@ -59,25 +59,44 @@ typedef FileSystem = { * @param uri The resource that is to be deleted. * @param options Defines if trash can should be used and if deletion of folders is recursive */ - function delete(uri:Uri, ?options:{?recursive:Bool, ?useTrash:Bool}):Thenable; + function delete(uri:Uri, ?options:{ + /** + * Delete the content recursively if a folder is denoted. + */ + ?recursive:Bool, + /** + * Use the os's trashcan instead of permanently deleting files whenever possible. + */ + ?useTrash:Bool + }):Thenable; /** * Rename a file or folder. * - * @param oldUri The existing file. - * @param newUri The new location. + * @param source The existing file. + * @param target The new location. * @param options Defines if existing files should be overwritten. */ - function rename(source:Uri, target:Uri, ?options:{?overwrite:Bool}):Thenable; + function rename(source:Uri, target:Uri, ?options:{ + /** + * Overwrite the file if it does exist. + */ + ?overwrite:Bool + }):Thenable; /** * Copy files or folders. * * @param source The existing file. - * @param destination The destination location. + * @param target The destination location. * @param options Defines if existing files should be overwritten. */ - function copy(source:Uri, target:Uri, ?options:{?overwrite:Bool}):Thenable; + function copy(source:Uri, target:Uri, ?options:{ + /** + * Overwrite the file if it does exist. + */ + ?overwrite:Bool + }):Thenable; /** * Check if a given file system supports writing files. @@ -88,7 +107,7 @@ typedef FileSystem = { * * @param scheme The scheme of the filesystem, for example `file` or `git`. * - * @return `true` if the file system supports writing, `false` if it does not + * @returns `true` if the file system supports writing, `false` if it does not * support writing (i.e. it is readonly), and `undefined` if the editor does not * know about the filesystem. */ diff --git a/src/vscode/FileSystemProvider.hx b/src/vscode/FileSystemProvider.hx index 5f101de8..af3b627f 100644 --- a/src/vscode/FileSystemProvider.hx +++ b/src/vscode/FileSystemProvider.hx @@ -29,17 +29,36 @@ typedef FileSystemProvider = { var onDidChangeFile(default, null):Event>; /** - * Subscribe to events in the file or folder denoted by `uri`. + * Subscribes to file change events in the file or folder denoted by `uri`. For folders, + * the option `recursive` indicates whether subfolders, sub-subfolders, etc. should + * be watched for file changes as well. With `recursive: false`, only changes to the + * files that are direct children of the folder should trigger an event. * - * The editor will call this function for files and folders. In the latter case, the - * options differ from defaults, e.g. what files/folders to exclude from watching - * and if subfolders, sub-subfolder, etc. should be watched (`recursive`). + * The `excludes` array is used to indicate paths that should be excluded from file + * watching. It is typically derived from the `files.watcherExclude` setting that + * is configurable by the user. Each entry can be be: + * - the absolute path to exclude + * - a relative path to exclude (for example `build/output`) + * - a simple glob pattern (for example `**​/build`, `output/**`) * - * @param uri The uri of the file to be watched. + * It is the file system provider's job to call {@linkcode FileSystemProvider.onDidChangeFile onDidChangeFile} + * for every change given these rules. No event should be emitted for files that match any of the provided + * excludes. + * + * @param uri The uri of the file or folder to be watched. * @param options Configures the watch. * @returns A disposable that tells the provider to stop watching the `uri`. */ - function watch(uri:Uri, options:{recursive:Bool, excludes:Array}):Disposable; + function watch(uri:Uri, options:{ + /** + * When enabled also watch subfolders. + */ + recursive:Bool, + /** + * A list of paths and pattern to exclude from watching. + */ + excludes:Array + }):Disposable; /** * Retrieve metadata about a file. @@ -49,7 +68,7 @@ typedef FileSystemProvider = { * `FileType.SymbolicLink | FileType.Directory`. * * @param uri The uri of the file to retrieve metadata about. - * @return The file metadata about the file. + * @returns The file metadata about the file. * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when `uri` doesn't exist. */ function stat(uri:Uri):EitherType>; @@ -58,7 +77,7 @@ typedef FileSystemProvider = { * Retrieve all entries of a {@link FileType.Directory directory}. * * @param uri The uri of the folder. - * @return An array of name/type-tuples or a thenable that resolves to such. + * @returns An array of name/type-tuples or a thenable that resolves to such. * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when `uri` doesn't exist. */ function readDirectory(uri:Uri):EitherType, Thenable>>; @@ -77,7 +96,7 @@ typedef FileSystemProvider = { * Read the entire contents of a file. * * @param uri The uri of the file. - * @return An array of bytes or a thenable that resolves to such. + * @returns An array of bytes or a thenable that resolves to such. * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when `uri` doesn't exist. */ function readFile(uri:Uri):EitherType>; @@ -93,7 +112,16 @@ typedef FileSystemProvider = { * @throws {@linkcode FileSystemError.FileExists FileExists} when `uri` already exists, `create` is set but `overwrite` is not set. * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient. */ - function writeFile(uri:Uri, content:Uint8Array, options:{create:Bool, overwrite:Bool}):EitherType>; + function writeFile(uri:Uri, content:Uint8Array, options:{ + /** + * Create the file if it does not exist already. + */ + create:Bool, + /** + * Overwrite the file if it does exist. + */ + overwrite:Bool + }):EitherType>; /** * Delete a file. @@ -103,7 +131,12 @@ typedef FileSystemProvider = { * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when `uri` doesn't exist. * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient. */ - function delete(uri:Uri, options:{recursive:Bool}):EitherType>; + function delete(uri:Uri, options:{ + /** + * Delete the content recursively if a folder is denoted. + */ + recursive:Bool + }):EitherType>; /** * Rename a file or folder. @@ -116,7 +149,12 @@ typedef FileSystemProvider = { * @throws {@linkcode FileSystemError.FileExists FileExists} when `newUri` exists and when the `overwrite` option is not `true`. * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient. */ - function rename(oldUri:Uri, newUri:Uri, options:{overwrite:Bool}):EitherType>; + function rename(oldUri:Uri, newUri:Uri, options:{ + /** + * Overwrite the file if it does exist. + */ + overwrite:Bool + }):EitherType>; /** * Copy files or folders. Implementing this function is optional but it will speedup @@ -130,5 +168,10 @@ typedef FileSystemProvider = { * @throws {@linkcode FileSystemError.FileExists FileExists} when `destination` exists and when the `overwrite` option is not `true`. * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient. */ - var ?copy:(source:Uri, destination:Uri, options:{overwrite:Bool}) -> EitherType>; + var ?copy:(source:Uri, destination:Uri, options:{ + /** + * Overwrite the file if it does exist. + */ + overwrite:Bool + }) -> EitherType>; } diff --git a/src/vscode/FileSystemWatcher.hx b/src/vscode/FileSystemWatcher.hx index fe05269c..f2146219 100644 --- a/src/vscode/FileSystemWatcher.hx +++ b/src/vscode/FileSystemWatcher.hx @@ -13,32 +13,32 @@ extern class FileSystemWatcher extends Disposable { * true if this file system watcher has been created such that * it ignores creation file system events. */ - var ignoreCreateEvents:Bool; + var ignoreCreateEvents(default, null):Bool; /** * true if this file system watcher has been created such that * it ignores change file system events. */ - var ignoreChangeEvents:Bool; + var ignoreChangeEvents(default, null):Bool; /** * true if this file system watcher has been created such that * it ignores delete file system events. */ - var ignoreDeleteEvents:Bool; + var ignoreDeleteEvents(default, null):Bool; /** * An event which fires on file/folder creation. */ - var onDidCreate:Event; + var onDidCreate(default, null):Event; /** * An event which fires on file/folder change. */ - var onDidChange:Event; + var onDidChange(default, null):Event; /** * An event which fires on file/folder deletion. */ - var onDidDelete:Event; + var onDidDelete(default, null):Event; } diff --git a/src/vscode/FileWillCreateEvent.hx b/src/vscode/FileWillCreateEvent.hx index 3dde4efe..711eb580 100644 --- a/src/vscode/FileWillCreateEvent.hx +++ b/src/vscode/FileWillCreateEvent.hx @@ -7,7 +7,13 @@ package vscode; * call the {@linkcode FileWillCreateEvent.waitUntil waitUntil}-function with a * thenable that resolves to a {@link WorkspaceEdit workspace edit}. */ -typedef FileWillCreateEvent = { +@:jsRequire("vscode", "FileWillCreateEvent") +extern class FileWillCreateEvent { + /** + * A cancellation token. + */ + var token(default, null):CancellationToken; + /** * The files that are going to be created. */ @@ -31,6 +37,14 @@ typedef FileWillCreateEvent = { * * @param thenable A thenable that delays saving. */ - @:overload(function(thenable:Thenable):Void {}) - function waitUntil(thenable:Thenable):Void; + overload function waitUntil(thenable:Thenable):Void; + + /** + * Allows to pause the event until the provided thenable resolves. + * + * *Note:* This function can only be called during event dispatch. + * + * @param thenable A thenable that delays saving. + */ + overload function waitUntil(thenable:Thenable):Void; } diff --git a/src/vscode/FileWillDeleteEvent.hx b/src/vscode/FileWillDeleteEvent.hx index d1888957..5cc7d35b 100644 --- a/src/vscode/FileWillDeleteEvent.hx +++ b/src/vscode/FileWillDeleteEvent.hx @@ -4,10 +4,16 @@ package vscode; * An event that is fired when files are going to be deleted. * * To make modifications to the workspace before the files are deleted, - * call the {@link FileWillCreateEvent.waitUntil `waitUntil}-function with a + * call the {@link FileWillCreateEvent.waitUntil `waitUntil`}-function with a * thenable that resolves to a {@link WorkspaceEdit workspace edit}. */ -typedef FileWillDeleteEvent = { +@:jsRequire("vscode", "FileWillDeleteEvent") +extern class FileWillDeleteEvent { + /** + * A cancellation token. + */ + var token(default, null):CancellationToken; + /** * The files that are going to be deleted. */ @@ -31,6 +37,14 @@ typedef FileWillDeleteEvent = { * * @param thenable A thenable that delays saving. */ - @:overload(function(thenable:Thenable):Void {}) - function waitUntil(thenable:Thenable):Void; + overload function waitUntil(thenable:Thenable):Void; + + /** + * Allows to pause the event until the provided thenable resolves. + * + * *Note:* This function can only be called during event dispatch. + * + * @param thenable A thenable that delays saving. + */ + overload function waitUntil(thenable:Thenable):Void; } diff --git a/src/vscode/FileWillRenameEvent.hx b/src/vscode/FileWillRenameEvent.hx index cfda4fea..f3e167c1 100644 --- a/src/vscode/FileWillRenameEvent.hx +++ b/src/vscode/FileWillRenameEvent.hx @@ -4,14 +4,29 @@ package vscode; * An event that is fired when files are going to be renamed. * * To make modifications to the workspace before the files are renamed, - * call the {@link FileWillCreateEvent.waitUntil `waitUntil}-function with a + * call the {@link FileWillCreateEvent.waitUntil `waitUntil`}-function with a * thenable that resolves to a {@link WorkspaceEdit workspace edit}. */ -typedef FileWillRenameEvent = { +@:jsRequire("vscode", "FileWillRenameEvent") +extern class FileWillRenameEvent { + /** + * A cancellation token. + */ + var token(default, null):CancellationToken; + /** * The files that are going to be renamed. */ - var files(default, never):ReadOnlyArray<{final oldUri:Uri; final newUri:Uri;}>; + var files(default, never):ReadOnlyArray<{ + /** + * The old uri of a file. + */ + final oldUri:Uri; + /** + * The new uri of a file. + */ + final newUri:Uri; + }>; /** * Allows to pause the event and to apply a {@link WorkspaceEdit workspace edit}. @@ -31,6 +46,14 @@ typedef FileWillRenameEvent = { * * @param thenable A thenable that delays saving. */ - @:overload(function(thenable:Thenable):Void {}) - function waitUntil(thenable:Thenable):Void; + overload function waitUntil(thenable:Thenable):Void; + + /** + * Allows to pause the event until the provided thenable resolves. + * + * *Note:* This function can only be called during event dispatch. + * + * @param thenable A thenable that delays saving. + */ + overload function waitUntil(thenable:Thenable):Void; } diff --git a/src/vscode/GlobPattern.hx b/src/vscode/GlobPattern.hx index eefa9934..db162b81 100644 --- a/src/vscode/GlobPattern.hx +++ b/src/vscode/GlobPattern.hx @@ -5,7 +5,7 @@ package vscode; * (like `**​/*.{ts,js}` or `*.{ts,js}`) or a {@link RelativePattern relative pattern}. * * Glob patterns can have the following syntax: - * * `*` to match one or more characters in a path segment + * * `*` to match zero or more characters in a path segment * * `?` to match on one character in a path segment * * `**` to match any number of path segments, including none * * `{}` to group conditions (e.g. `**​/*.{ts,js}` matches all TypeScript and JavaScript files) diff --git a/src/vscode/GlobalEnvironmentVariableCollection.hx b/src/vscode/GlobalEnvironmentVariableCollection.hx new file mode 100644 index 00000000..f8fbddd8 --- /dev/null +++ b/src/vscode/GlobalEnvironmentVariableCollection.hx @@ -0,0 +1,24 @@ +package vscode; + +/** + * Value-object describing what options formatting should use. + */ +typedef GlobalEnvironmentVariableCollection = EnvironmentVariableCollection & { + /** + * Gets scope-specific environment variable collection for the extension. This enables alterations to + * terminal environment variables solely within the designated scope, and is applied in addition to (and + * after) the global collection. + * + * Each object obtained through this method is isolated and does not impact objects for other scopes, + * including the global collection. + * + * @param scope The scope to which the environment variable collection applies to. + * + * If a scope parameter is omitted, collection applicable to all relevant scopes for that parameter is + * returned. For instance, if the 'workspaceFolder' parameter is not specified, the collection that applies + * across all workspace folders will be returned. + * + * @returns Environment variable collection for the passed in scope. + */ + function getScoped(scope:EnvironmentVariableScope):EnvironmentVariableCollection; +} diff --git a/src/vscode/HoverProvider.hx b/src/vscode/HoverProvider.hx index e510c5d7..d41a8b19 100644 --- a/src/vscode/HoverProvider.hx +++ b/src/vscode/HoverProvider.hx @@ -13,7 +13,7 @@ typedef HoverProvider = { * @param document The document in which the command was invoked. * @param position The position at which the command was invoked. * @param token A cancellation token. - * @return A hover or a thenable that resolves to such. The lack of a result can be + * @returns A hover or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined` or `null`. */ function provideHover(document:TextDocument, position:Position, token:CancellationToken):ProviderResult; diff --git a/src/vscode/IconPath.hx b/src/vscode/IconPath.hx new file mode 100644 index 00000000..d008baa1 --- /dev/null +++ b/src/vscode/IconPath.hx @@ -0,0 +1,17 @@ +package vscode; + +/** + * Represents an icon in the UI. This is either an uri, separate uris for the light- and dark-themes, + * or a {@link ThemeIcon theme icon}. + */ +typedef IconPath = EitherType>; diff --git a/src/vscode/ImplementationProvider.hx b/src/vscode/ImplementationProvider.hx index b717acc0..8651f828 100644 --- a/src/vscode/ImplementationProvider.hx +++ b/src/vscode/ImplementationProvider.hx @@ -11,7 +11,7 @@ typedef ImplementationProvider = { * @param document The document in which the command was invoked. * @param position The position at which the command was invoked. * @param token A cancellation token. - * @return A definition or a thenable that resolves to such. The lack of a result can be + * @returns A definition or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined` or `null`. */ function provideImplementation(document:TextDocument, position:Position, diff --git a/src/vscode/InlayHint.hx b/src/vscode/InlayHint.hx new file mode 100644 index 00000000..198f0a40 --- /dev/null +++ b/src/vscode/InlayHint.hx @@ -0,0 +1,67 @@ +package vscode; + +/** + * Inlay hint information. + */ +@:jsRequire("vscode", "InlayHint") +extern class InlayHint { + /** + * The position of this hint. + */ + var position:Position; + + /** + * The label of this hint. A human readable string or an array of {@link InlayHintLabelPart label parts}. + * + * *Note* that neither the string nor the label part can be empty. + */ + var label:EitherType>; + + /** + * The tooltip text when you hover over this item. + * + * *Note* that this property can be set late during + * {@link InlayHintsProvider.resolveInlayHint resolving} of inlay hints. + */ + var tooltip:Null>; + + /** + * The kind of this hint. The inlay hint kind defines the appearance of this inlay hint. + */ + var kind:Null; + + /** + * Optional {@link TextEdit text edits} that are performed when accepting this inlay hint. The default + * gesture for accepting an inlay hint is the double click. + * + * *Note* that edits are expected to change the document so that the inlay hint (or its nearest variant) is + * now part of the document and the inlay hint itself is now obsolete. + * + * *Note* that this property can be set late during + * {@link InlayHintsProvider.resolveInlayHint resolving} of inlay hints. + */ + var textEdits:Null>; + + /** + * Render padding before the hint. Padding will use the editor's background color, + * not the background color of the hint itself. That means padding can be used to visually + * align/separate an inlay hint. + */ + var paddingLeft:Null; + + /** + * Render padding after the hint. Padding will use the editor's background color, + * not the background color of the hint itself. That means padding can be used to visually + * align/separate an inlay hint. + */ + var paddingRight:Null; + + /** + * Creates a new inlay hint. + * + * @param position The position of the hint. + * @param label The label of the hint. + * @param kind The {@link InlayHintKind kind} of the hint. + */ + function new(position:Position, label:EitherType>, ?kind:InlayHintKind); +} diff --git a/src/vscode/InlayHintKind.hx b/src/vscode/InlayHintKind.hx new file mode 100644 index 00000000..9896dc30 --- /dev/null +++ b/src/vscode/InlayHintKind.hx @@ -0,0 +1,20 @@ +package vscode; + +/** + * Inlay hint kinds. + * + * The kind of an inline hint defines its appearance, e.g the corresponding foreground and background colors are being + * used. + */ +@:jsRequire("vscode", "InlayHintKind") +extern enum abstract InlayHintKind(Int) { + /** + * An inlay hint that for a type annotation. + */ + var Type; + + /** + * An inlay hint that is for a parameter. + */ + var Parameter; +} diff --git a/src/vscode/InlayHintLabelPart.hx b/src/vscode/InlayHintLabelPart.hx new file mode 100644 index 00000000..a52440a7 --- /dev/null +++ b/src/vscode/InlayHintLabelPart.hx @@ -0,0 +1,52 @@ +package vscode; + +/** + * An inlay hint label part allows for interactive and composite labels of inlay hints. + */ +@:jsRequire("vscode", "InlayHintLabelPart") +extern class InlayHintLabelPart { + /** + * The value of this label part. + */ + var value:String; + + /** + * The tooltip text when you hover over this label part. + * + * *Note* that this property can be set late during + * {@link InlayHintsProvider.resolveInlayHint resolving} of inlay hints. + */ + var tooltip:Null>; + + /** + * An optional {@link Location source code location} that represents this label + * part. + * + * The editor will use this location for the hover and for code navigation features: This + * part will become a clickable link that resolves to the definition of the symbol at the + * given location (not necessarily the location itself), it shows the hover that shows at + * the given location, and it shows a context menu with further code navigation commands. + * + * *Note* that this property can be set late during + * {@link InlayHintsProvider.resolveInlayHint resolving} of inlay hints. + */ + var location:Null; + + /** + * An optional command for this label part. + * + * The editor renders parts with commands as clickable links. The command is added to the context menu + * when a label part defines {@link InlayHintLabelPart.location location} and {@link InlayHintLabelPart.command command} . + * + * *Note* that this property can be set late during + * {@link InlayHintsProvider.resolveInlayHint resolving} of inlay hints. + */ + var command:Null; + + /** + * Creates a new inlay hint label part. + * + * @param value The value of the part. + */ + function new(value:String); +} diff --git a/src/vscode/InlayHintsProvider.hx b/src/vscode/InlayHintsProvider.hx new file mode 100644 index 00000000..ba2b880a --- /dev/null +++ b/src/vscode/InlayHintsProvider.hx @@ -0,0 +1,36 @@ +package vscode; + +/** + * The inlay hints provider interface defines the contract between extensions and + * the inlay hints feature. + */ +typedef InlayHintsProvider = { + /** + * An optional event to signal that inlay hints from this provider have changed. + */ + var ?onDidChangeInlayHints:Event; + + /** + * Provide inlay hints for the given range and document. + * + * *Note* that inlay hints that are not {@link Range.contains contained} by the given range are ignored. + * + * @param document The document in which the command was invoked. + * @param range The range for which inlay hints should be computed. + * @param token A cancellation token. + * @returns An array of inlay hints or a thenable that resolves to such. + */ + function provideInlayHints(document:TextDocument, range:Range, token:CancellationToken):ProviderResult>; + + /** + * Given an inlay hint fill in {@link InlayHint.tooltip tooltip}, {@link InlayHint.textEdits text edits}, + * or complete label {@link InlayHintLabelPart parts}. + * + * *Note* that the editor will resolve an inlay hint at most once. + * + * @param hint An inlay hint. + * @param token A cancellation token. + * @returns The resolved inlay hint or a thenable that resolves to such. It is OK to return the given `item`. When no result is returned, the given `item` will be used. + */ + function resolveInlayHint(hint:T, token:CancellationToken):ProviderResult; +} diff --git a/src/vscode/InlineCompletionContext.hx b/src/vscode/InlineCompletionContext.hx new file mode 100644 index 00000000..e7958be0 --- /dev/null +++ b/src/vscode/InlineCompletionContext.hx @@ -0,0 +1,23 @@ +package vscode; + +/** + * Provides information about the context in which an inline completion was requested. + */ +typedef InlineCompletionContext = { + /** + * Describes how the inline completion was triggered. + */ + var triggerKind(default, null):InlineCompletionTriggerKind; + + /** + * Provides information about the currently selected item in the autocomplete widget if it is visible. + * + * If set, provided inline completions must extend the text of the selected item + * and use the same range, otherwise they are not shown as preview. + * As an example, if the document text is `console.` and the selected item is `.log` replacing the `.` in the document, + * the inline completion must also replace `.` and start with `.log`, for example `.log()`. + * + * Inline completion providers are requested again whenever the selected item changes. + */ + var selectedCompletionInfo(default, null):Null; +} diff --git a/src/vscode/InlineCompletionItem.hx b/src/vscode/InlineCompletionItem.hx new file mode 100644 index 00000000..6399d40b --- /dev/null +++ b/src/vscode/InlineCompletionItem.hx @@ -0,0 +1,45 @@ +package vscode; + +/** + * An inline completion item represents a text snippet that is proposed inline to complete text that is being typed. + * + * @see {@link InlineCompletionItemProvider.provideInlineCompletionItems} + */ +@:jsRequire("vscode", "InlineCompletionItem") +extern class InlineCompletionItem { + /** + * The text to replace the range with. Must be set. + * Is used both for the preview and the accept operation. + */ + var insertText:EitherType; + + /** + * A text that is used to decide if this inline completion should be shown. When `falsy` + * the {@link InlineCompletionItem.insertText} is used. + * + * An inline completion is shown if the text to replace is a prefix of the filter text. + */ + var filterText:Null; + + /** + * The range to replace. + * Must begin and end on the same line. + * + * Prefer replacements over insertions to provide a better experience when the user deletes typed text. + */ + var range:Null; + + /** + * An optional {@link Command} that is executed *after* inserting this completion. + */ + var command:Null; + + /** + * Creates a new inline completion item. + * + * @param insertText The text to replace the range with. + * @param range The range to replace. If not set, the word at the requested position will be used. + * @param command An optional {@link Command} that is executed *after* inserting this completion. + */ + function new(insertText:EitherType, ?range:Range, ?command:Command); +} diff --git a/src/vscode/InlineCompletionItemProvider.hx b/src/vscode/InlineCompletionItemProvider.hx new file mode 100644 index 00000000..663b862e --- /dev/null +++ b/src/vscode/InlineCompletionItemProvider.hx @@ -0,0 +1,25 @@ +package vscode; + +/** + * The inline completion item provider interface defines the contract between extensions and + * the inline completion feature. + * + * Providers are asked for completions either explicitly by a user gesture or implicitly when typing. + */ +typedef InlineCompletionItemProvider = { + /** + * Provides inline completion items for the given position and document. + * If inline completions are enabled, this method will be called whenever the user stopped typing. + * It will also be called when the user explicitly triggers inline completions or explicitly asks for the next or previous inline completion. + * In that case, all available inline completions should be returned. + * `context.triggerKind` can be used to distinguish between these scenarios. + * + * @param document The document inline completions are requested for. + * @param position The position inline completions are requested for. + * @param context A context object with additional information. + * @param token A cancellation token. + * @returns An array of completion items or a thenable that resolves to an array of completion items. + */ + function provideInlineCompletionItems(document:TextDocument, position:Position, context:InlineCompletionContext, + token:CancellationToken):ProviderResult, InlineCompletionList>>; +} diff --git a/src/vscode/InlineCompletionList.hx b/src/vscode/InlineCompletionList.hx new file mode 100644 index 00000000..fb6f754b --- /dev/null +++ b/src/vscode/InlineCompletionList.hx @@ -0,0 +1,18 @@ +package vscode; + +/** + * Represents a collection of {@link InlineCompletionItem inline completion items} to be presented + * in the editor. + */ +@:jsRequire("vscode", "InlineCompletionList") +extern class InlineCompletionList { + /** + * The inline completion items. + */ + var items:Array; + + /** + * Creates a new list of inline completion items. + */ + function new(items:Array); +} diff --git a/src/vscode/InlineCompletionTriggerKind.hx b/src/vscode/InlineCompletionTriggerKind.hx new file mode 100644 index 00000000..7da52889 --- /dev/null +++ b/src/vscode/InlineCompletionTriggerKind.hx @@ -0,0 +1,19 @@ +package vscode; + +/** + * Describes how an {@link InlineCompletionItemProvider inline completion provider} was triggered. + */ +@:jsRequire("vscode", "InlineCompletionTriggerKind") +extern enum abstract InlineCompletionTriggerKind(Int) { + /** + * Completion was triggered explicitly by a user gesture. + * Return multiple completion items to enable cycling through them. + */ + var Invoke; + + /** + * Completion was triggered automatically while editing. + * It is sufficient to return a single completion item in this case. + */ + var Automatic; +} diff --git a/src/vscode/InlineValuesProvider.hx b/src/vscode/InlineValuesProvider.hx index 5a02e9f5..8bcfbd94 100644 --- a/src/vscode/InlineValuesProvider.hx +++ b/src/vscode/InlineValuesProvider.hx @@ -21,9 +21,8 @@ typedef InlineValuesProvider = { * @param viewPort The visible document range for which inline values should be computed. * @param context A bag containing contextual information like the current location. * @param token A cancellation token. - * @return An array of InlineValueDescriptors or a thenable that resolves to such. The lack of a result can be + * @returns An array of InlineValueDescriptors or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined` or `null`. */ - function provideInlineValues(document:TextDocument, viewPort:Range, context:InlineValueContext, - token:CancellationToken):ProviderResult>; + function provideInlineValues(document:TextDocument, viewPort:Range, context:InlineValueContext, token:CancellationToken):ProviderResult>; } diff --git a/src/vscode/InputBox.hx b/src/vscode/InputBox.hx index ee14c85f..7f67b7f2 100644 --- a/src/vscode/InputBox.hx +++ b/src/vscode/InputBox.hx @@ -13,6 +13,17 @@ typedef InputBox = QuickInput & { */ var value:String; + /** + * Selection range in the input value. Defined as tuple of two number where the + * first is the inclusive start index and the second the exclusive end index. When `undefined` the whole + * pre-filled value will be selected, when empty (start equals end) only the cursor will be set, + * otherwise the defined range will be selected. + * + * This property does not get updated when the user types or makes a selection, + * but it can be updated by the extension. + */ + var valueSelection:Null>>; + /** * Optional placeholder in the filter text. */ @@ -50,6 +61,8 @@ typedef InputBox = QuickInput & { /** * An optional validation message indicating a problem with the current input value. + * By returning a string, the InputBox will use a default {@link InputBoxValidationSeverity} of Error. + * Returning undefined clears the validation message. */ - var ?validationMessage:String; + var validationMessage:Null>; } diff --git a/src/vscode/InputBoxOptions.hx b/src/vscode/InputBoxOptions.hx index 70895839..6af50cb3 100644 --- a/src/vscode/InputBoxOptions.hx +++ b/src/vscode/InputBoxOptions.hx @@ -10,14 +10,14 @@ typedef InputBoxOptions = { var ?title:String; /** - * The value to prefill in the input box. + * The value to pre-fill in the input box. */ var ?value:String; /** - * Selection of the prefilled {@linkcode InputBoxOptions.value value}. Defined as tuple of two number where the + * Selection of the pre-filled {@linkcode InputBoxOptions.value value}. Defined as tuple of two number where the * first is the inclusive start index and the second the exclusive end index. When `undefined` the whole - * word will be selected, when empty (start equals end) only the cursor will be set, + * pre-filled value will be selected, when empty (start equals end) only the cursor will be set, * otherwise the defined range will be selected. */ var ?valueSelection:Array; @@ -48,8 +48,8 @@ typedef InputBoxOptions = { * to the user. * * @param value The current value of the input box. - * @return A human-readable string which is presented as diagnostic message. - * Return `undefined`, `null`, or the empty string when 'value' is valid. + * @returns Either a human-readable string which is presented as an error message or an {@link InputBoxValidationMessage} + * which can provide a specific message severity. Return `undefined`, `null`, or the empty string when 'value' is valid. */ - var ?validateInput:String->ProviderResult>; + var ?validateInput:String->EitherType, Thenable>>; } diff --git a/src/vscode/InputBoxValidationMessage.hx b/src/vscode/InputBoxValidationMessage.hx new file mode 100644 index 00000000..c64f6c4f --- /dev/null +++ b/src/vscode/InputBoxValidationMessage.hx @@ -0,0 +1,18 @@ +package vscode; + +/** + * Object to configure the behavior of the validation message. + */ +typedef InputBoxValidationMessage = { + /** + * The validation message to display. + */ + var message(default, null):String; + + /** + * The severity of the validation message. + * NOTE: When using `InputBoxValidationSeverity.Error`, the user will not be allowed to accept (hit ENTER) the input. + * `Info` and `Warning` will still allow the InputBox to accept the input. + */ + var severity(default, null):InputBoxValidationSeverity; +} diff --git a/src/vscode/InputBoxValidationSeverity.hx b/src/vscode/InputBoxValidationSeverity.hx new file mode 100644 index 00000000..2422b53a --- /dev/null +++ b/src/vscode/InputBoxValidationSeverity.hx @@ -0,0 +1,25 @@ +package vscode; + +/** + * Impacts the behavior and appearance of the validation message. + */ +/** + * The severity level for input box validation. + */ +@:jsRequire("vscode", "InputBoxValidationSeverity") +extern enum abstract InputBoxValidationSeverity(Int) { + /** + * Informational severity level. + */ + var Info; + + /** + * Warning severity level. + */ + var Warning; + + /** + * Error severity level. + */ + var Error; +} diff --git a/src/vscode/LanguageConfiguration.hx b/src/vscode/LanguageConfiguration.hx index ab495504..d3169e65 100644 --- a/src/vscode/LanguageConfiguration.hx +++ b/src/vscode/LanguageConfiguration.hx @@ -23,7 +23,9 @@ typedef LanguageConfiguration = { * If the language supports Unicode identifiers (e.g. JavaScript), it is preferable * to provide a word definition that uses exclusion of known separators. * e.g.: A regex that matches anything except known separators (and dot is allowed to occur in a floating point number): - * /(-?\d*\.\d\w*)|([^\`\~\!\@\#\%\^\&\*\(\)\-\=\+\[\{\]\}\\\|\;\:\'\"\,\.\<\>\/\?\s]+)/g + * ``` + * /(-?\d*\.\d\w*)|([^\`\~\!\@\#\%\^\&\*\(\)\-\=\+\[\{\]\}\\\|\;\:\'\"\,\.\<\>\/\?\s]+)/g + * ``` */ var ?wordPattern:RegExp; @@ -37,6 +39,11 @@ typedef LanguageConfiguration = { */ var ?onEnterRules:Array; + /** + * The language's auto closing pairs. + */ + var ?autoClosingPairs:Array; + /** * **Deprecated** Do not use. * @@ -50,7 +57,6 @@ typedef LanguageConfiguration = { * @deprecated */ @:deprecated var ?brackets:Any; - /** * This property is deprecated and not fully supported anymore by * the editor (scope and lineStart are ignored). @@ -58,9 +64,21 @@ typedef LanguageConfiguration = { * @deprecated */ @:deprecated var ?docComment:{ + /** + * @deprecated + */ var scope:String; + /** + * @deprecated + */ var open:String; + /** + * @deprecated + */ var lineStart:String; + /** + * @deprecated + */ var ?close:String; }; }; @@ -72,6 +90,22 @@ typedef LanguageConfiguration = { */ @:deprecated("Use the autoClosingPairs property in the language configuration file instead.") var ?__characterPairSupport:{ - var autoClosingPairs:Array<{open:String, close:String, ?notIn:Array}>; + /** + * @deprecated + */ + var autoClosingPairs:Array<{ + /** + * @deprecated + */ + open:String, + /** + * @deprecated + */ + close:String, + /** + * @deprecated + */ + ?notIn:Array + }>; }; } diff --git a/src/vscode/LanguageModelAccessInformation.hx b/src/vscode/LanguageModelAccessInformation.hx new file mode 100644 index 00000000..b317f293 --- /dev/null +++ b/src/vscode/LanguageModelAccessInformation.hx @@ -0,0 +1,24 @@ +package vscode; + +import vscode.TerminalShellExecution.AsyncIterable; + +/** + * Represents extension specific information about the access to language models. + */ +typedef LanguageModelAccessInformation = { + /** + * An event that fires when access information changes. + */ + var onDidChange:Event; + + /** + * Checks if a request can be made to a language model. + * + * *Note* that calling this function will not trigger a consent UI but just checks for a persisted state. + * + * @param chat A language model chat object. + * @return `true` if a request can be made, `false` if not, `undefined` if the language + * model does not exist or consent hasn't been asked for. + */ + function canSendRequest(chat:LanguageModelChat):Null; +} diff --git a/src/vscode/LanguageModelChat.hx b/src/vscode/LanguageModelChat.hx new file mode 100644 index 00000000..cf099237 --- /dev/null +++ b/src/vscode/LanguageModelChat.hx @@ -0,0 +1,78 @@ +package vscode; + +/** + * Represents a language model for making chat requests. + * + * @see {@link lm.selectChatModels} + */ +typedef LanguageModelChat = { + /** + * Human-readable name of the language model. + */ + var name(default, null):String; + + /** + * Opaque identifier of the language model. + */ + var id(default, null):String; + + /** + * A well-known identifier of the vendor of the language model. An example is `copilot`, but + * values are defined by extensions contributing chat models and need to be looked up with them. + */ + var vendor(default, null):String; + + /** + * Opaque family-name of the language model. Values might be `gpt-3.5-turbo`, `gpt4`, `phi2`, or `llama` + * but they are defined by extensions contributing languages and subject to change. + */ + var family(default, null):String; + + /** + * Opaque version string of the model. This is defined by the extension contributing the language model + * and subject to change. + */ + var version(default, null):String; + + /** + * The maximum number of tokens that can be sent to the model in a single request. + */ + var maxInputTokens(default, null):Int; + + /** + * Make a chat request using a language model. + * + * *Note* that language model use may be subject to access restrictions and user consent. Calling this function + * for the first time (for an extension) will show a consent dialog to the user and because of that this function + * must _only be called in response to a user action!_ Extensions can use {@link LanguageModelAccessInformation.canSendRequest} + * to check if they have the necessary permissions to make a request. + * + * This function will return a rejected promise if making a request to the language model is not + * possible. Reasons for this can be: + * + * - user consent not given, see {@link LanguageModelError.NoPermissions `NoPermissions`} + * - model does not exist anymore, see {@link LanguageModelError.NotFound `NotFound`} + * - quota limits exceeded, see {@link LanguageModelError.Blocked `Blocked`} + * - other issues in which case extension must check {@link LanguageModelError.cause `LanguageModelError.cause`} + * + * An extension can make use of language model tool calling by passing a set of tools to + * {@link LanguageModelChatRequestOptions.tools}. The language model will return a {@link LanguageModelToolCallPart} and + * the extension can invoke the tool and make another request with the result. + * + * @param messages An array of message instances. + * @param options Options that control the request. + * @param token A cancellation token which controls the request. See {@link CancellationTokenSource} for how to create one. + * @returns A thenable that resolves to a {@link LanguageModelChatResponse}. The promise will reject when the request couldn't be made. + */ + function sendRequest(messages:Array, ?options:LanguageModelChatRequestOptions, + ?token:CancellationToken):Thenable; + + /** + * Count the number of tokens in a message using the model specific tokenizer-logic. + + * @param text A string or a message instance. + * @param token Optional cancellation token. See {@link CancellationTokenSource} for how to create one. + * @returns A thenable that resolves to the number of tokens. + */ + function countTokens(text:EitherType, ?token:CancellationToken):Thenable; +} diff --git a/src/vscode/LanguageModelChatMessage.hx b/src/vscode/LanguageModelChatMessage.hx new file mode 100644 index 00000000..723e6c43 --- /dev/null +++ b/src/vscode/LanguageModelChatMessage.hx @@ -0,0 +1,51 @@ +package vscode; + +/** + * Represents a message in a chat. Can assume different roles, like user or assistant. + */ +@:jsRequire("vscode", "LanguageModelChatMessage") +extern class LanguageModelChatMessage { + /** + * Utility to create a new user message. + * + * @param content The content of the message. + * @param name The optional name of a user for the message. + */ + static function User(content:EitherType>>, + ?name:String):LanguageModelChatMessage; + + /** + * Utility to create a new assistant message. + * + * @param content The content of the message. + * @param name The optional name of a user for the message. + */ + static function Assistant(content:EitherType>>, + ?name:String):LanguageModelChatMessage; + + /** + * The role of this message. + */ + var role:LanguageModelChatMessageRole; + + /** + * A string or heterogeneous array of things that a message can contain as content. Some parts may be message-type + * specific for some models. + */ + var content:Array>>; + + /** + * The optional name of a user for this message. + */ + var name:Null; + + /** + * Create a new user message. + * + * @param role The role of the message. + * @param content The content of the message. + * @param name The optional name of a user for the message. + */ + function new(role:LanguageModelChatMessageRole, + content:EitherType>>>, ?name:String); +} diff --git a/src/vscode/LanguageModelChatMessageRole.hx b/src/vscode/LanguageModelChatMessageRole.hx new file mode 100644 index 00000000..d03c3ce0 --- /dev/null +++ b/src/vscode/LanguageModelChatMessageRole.hx @@ -0,0 +1,17 @@ +package vscode; + +/** + * Represents the role of a chat message. This is either the user or the assistant. + */ +@:jsRequire("vscode", "LanguageModelChatMessageRole") +extern enum abstract LanguageModelChatMessageRole(Int) { + /** + * The user role, e.g the human interacting with a language model. + */ + var User; + + /** + * The assistant role, e.g. the language model generating responses. + */ + var Assistant; +} diff --git a/src/vscode/LanguageModelChatRequestOptions.hx b/src/vscode/LanguageModelChatRequestOptions.hx new file mode 100644 index 00000000..a287d356 --- /dev/null +++ b/src/vscode/LanguageModelChatRequestOptions.hx @@ -0,0 +1,37 @@ +package vscode; + +/** + * Options for making a chat request using a language model. + * + * @see {@link LanguageModelChat.sendRequest} + */ +typedef LanguageModelChatRequestOptions = { + /** + * A human-readable message that explains why access to a language model is needed and what feature is enabled by it. + */ + var ?justification:String; + + /** + * A set of options that control the behavior of the language model. These options are specific to the language model + * and need to be lookup in the respective documentation. + */ + var ?modelOptions:DynamicAccess; + + /** + * An optional list of tools that are available to the language model. These could be registered tools available via + * {@link lm.tools}, or private tools that are just implemented within the calling extension. + * + * If the LLM requests to call one of these tools, it will return a {@link LanguageModelToolCallPart} in + * {@link LanguageModelChatResponse.stream}. It's the caller's responsibility to invoke the tool. If it's a tool + * registered in {@link lm.tools}, that means calling {@link lm.invokeTool}. + * + * Then, the tool result can be provided to the LLM by creating an Assistant-type {@link LanguageModelChatMessage} with a + * {@link LanguageModelToolCallPart}, followed by a User-type message with a {@link LanguageModelToolResultPart}. + */ + var ?tools:Array; + + /** + * The tool-selecting mode to use. {@link LanguageModelChatToolMode.Auto} by default. + */ + var ?toolMode:LanguageModelChatToolMode; +} diff --git a/src/vscode/LanguageModelChatResponse.hx b/src/vscode/LanguageModelChatResponse.hx new file mode 100644 index 00000000..6b8fe82b --- /dev/null +++ b/src/vscode/LanguageModelChatResponse.hx @@ -0,0 +1,50 @@ +package vscode; + +import vscode.TerminalShellExecution.AsyncIterable; + +/** + * Represents a language model response. + * + * @see {@link LanguageModelAccess.chatRequest} + */ +typedef LanguageModelChatResponse = { + /** + * An async iterable that is a stream of text and tool-call parts forming the overall response. A + * {@link LanguageModelTextPart} is part of the assistant's response to be shown to the user. A + * {@link LanguageModelToolCallPart} is a request from the language model to call a tool. The latter will + * only be returned if tools were passed in the request via {@link LanguageModelChatRequestOptions.tools}. The + * `unknown`-type is used as a placeholder for future parts, like image data parts. + * + * *Note* that this stream will error when during data receiving an error occurs. Consumers of the stream should handle + * the errors accordingly. + * + * To cancel the stream, the consumer can {@link CancellationTokenSource.cancel cancel} the token that was used to make + * the request or break from the for-loop. + * + * @example + * ```ts + * try { + * // consume stream + * for await (const chunk of response.stream) { + * if (chunk instanceof LanguageModelTextPart) { + * console.log("TEXT", chunk); + * } else if (chunk instanceof LanguageModelToolCallPart) { + * console.log("TOOL CALL", chunk); + * } + * } + * + * } catch(e) { + * // stream ended with an error + * console.error(e); + * } + * ``` + */ + var stream:AsyncIterable>; + + /** + * This is equivalent to filtering everything except for text parts from a {@link LanguageModelChatResponse.stream}. + * + * @see {@link LanguageModelChatResponse.stream} + */ + var text:AsyncIterable; +} diff --git a/src/vscode/LanguageModelChatSelector.hx b/src/vscode/LanguageModelChatSelector.hx new file mode 100644 index 00000000..bfe08a83 --- /dev/null +++ b/src/vscode/LanguageModelChatSelector.hx @@ -0,0 +1,32 @@ +package vscode; + +/** + * Describes how to select language models for chat requests. + * + * @see {@link lm.selectChatModels} + */ +typedef LanguageModelChatSelector = { + /** + * A vendor of language models. + * @see {@link LanguageModelChat.vendor} + */ + var ?vendor:String; + + /** + * A family of language models. + * @see {@link LanguageModelChat.family} + */ + var ?family:String; + + /** + * The version of a language model. + * @see {@link LanguageModelChat.version} + */ + var ?version:String; + + /** + * The identifier of a language model. + * @see {@link LanguageModelChat.id} + */ + var ?id:String; +} diff --git a/src/vscode/LanguageModelChatTool.hx b/src/vscode/LanguageModelChatTool.hx new file mode 100644 index 00000000..7ac24891 --- /dev/null +++ b/src/vscode/LanguageModelChatTool.hx @@ -0,0 +1,24 @@ +package vscode; + +import vscode.TerminalShellExecution.AsyncIterable; + +/** + * A tool that is available to the language model via {@link LanguageModelChatRequestOptions}. A language model uses all the + * properties of this interface to decide which tool to call, and how to call it. + */ +typedef LanguageModelChatTool = { + /** + * The name of the tool. + */ + var name:String; + + /** + * The description of the tool. + */ + var description:String; + + /** + * A JSON schema for the input this tool accepts. + */ + var inputSchema:{} +} diff --git a/src/vscode/LanguageModelChatToolMode.hx b/src/vscode/LanguageModelChatToolMode.hx new file mode 100644 index 00000000..a71e6a10 --- /dev/null +++ b/src/vscode/LanguageModelChatToolMode.hx @@ -0,0 +1,18 @@ +package vscode; + +/** + * A tool-calling mode for the language model to use. + */ +@:jsRequire("vscode", "LanguageModelChatToolMode") +extern enum abstract LanguageModelChatToolMode(Int) { + /** + * The language model can choose to call a tool or generate a message. Is the default. + */ + var Auto; + + /** + * The language model must call one of the provided tools. Note- some models only support a single tool when using this + * mode. + */ + var Required; +} diff --git a/src/vscode/LanguageModelError.hx b/src/vscode/LanguageModelError.hx new file mode 100644 index 00000000..0e5c909e --- /dev/null +++ b/src/vscode/LanguageModelError.hx @@ -0,0 +1,37 @@ +package vscode; + +/** + * An error type for language model specific errors. + * + * Consumers of language models should check the code property to determine specific + * failure causes, like `if(someError.code === vscode.LanguageModelError.NotFound.name) {...}` + * for the case of referring to an unknown language model. For unspecified errors the `cause`-property + * will contain the actual error. + */ +@:jsRequire("vscode", "LanguageModelError") +extern class LanguageModelError extends Error { + /** + * The requestor does not have permissions to use this + * language model + */ + static function NoPermissions(?message:String):LanguageModelError; + + /** + * The requestor is blocked from using this language model. + */ + static function Blocked(?message:String):LanguageModelError; + + /** + * The language model does not exist. + */ + static function NotFound(?message:String):LanguageModelError; + + /** + * A code that identifies this error. + * + * Possible values are names of errors, like {@linkcode LanguageModelError.NotFound NotFound}, + * or `Unknown` for unspecified errors from the language model itself. In the latter case the + * `cause`-property will contain the actual error. + */ + var code(default, null):String; +} diff --git a/src/vscode/LanguageModelPromptTsxPart.hx b/src/vscode/LanguageModelPromptTsxPart.hx new file mode 100644 index 00000000..ccdf3cff --- /dev/null +++ b/src/vscode/LanguageModelPromptTsxPart.hx @@ -0,0 +1,19 @@ +package vscode; + +/** + * A language model response part containing a PromptElementJSON from `@vscode/prompt-tsx`. + * @see {@link LanguageModelToolResult} + */ +@:jsRequire("vscode", "LanguageModelPromptTsxPart") +extern class LanguageModelPromptTsxPart { + /** + * The value of the part. + */ + var value:Any; + + /** + * Construct a prompt-tsx part with the given content. + * @param value The value of the part, the result of `renderPromptElementJSON` from `@vscode/prompt-tsx`. + */ + function new(value:Any); +} diff --git a/src/vscode/LanguageModelTextPart.hx b/src/vscode/LanguageModelTextPart.hx new file mode 100644 index 00000000..f7cbe1a7 --- /dev/null +++ b/src/vscode/LanguageModelTextPart.hx @@ -0,0 +1,18 @@ +package vscode; + +/** + * A language model response part containing a piece of text, returned from a {@link LanguageModelChatResponse}. + */ +@:jsRequire("vscode", "LanguageModelTextPart") +extern class LanguageModelTextPart { + /** + * The text content of the part. + */ + var value:String; + + /** + * Construct a text part with the given content. + * @param value The text content of the part. + */ + function new(value:String); +} diff --git a/src/vscode/LanguageModelTool.hx b/src/vscode/LanguageModelTool.hx new file mode 100644 index 00000000..7e46f30d --- /dev/null +++ b/src/vscode/LanguageModelTool.hx @@ -0,0 +1,25 @@ +package vscode; + +import vscode.TerminalShellExecution.AsyncIterable; + +/** + * A tool that can be invoked by a call to a {@link LanguageModelChat}. + */ +typedef LanguageModelTool = { + /** + * Invoke the tool with the given input and return a result. + * + * The provided {@link LanguageModelToolInvocationOptions.input} has been validated against the declared schema. + */ + function invoke(options:LanguageModelToolInvocationOptions, token:CancellationToken):ProviderResult; + + /** + * Called once before a tool is invoked. It's recommended to implement this to customize the progress message that appears + * while the tool is running, and to provide a more useful message with context from the invocation input. Can also + * signal that a tool needs user confirmation before running, if appropriate. + * + * * *Note 1:* Must be free of side-effects. + * * *Note 2:* A call to `prepareInvocation` is not necessarily followed by a call to `invoke`. + */ + function prepareInvocation(options:LanguageModelToolInvocationPrepareOptions, token:CancellationToken):ProviderResult; +} diff --git a/src/vscode/LanguageModelToolCallPart.hx b/src/vscode/LanguageModelToolCallPart.hx new file mode 100644 index 00000000..0d34ed77 --- /dev/null +++ b/src/vscode/LanguageModelToolCallPart.hx @@ -0,0 +1,32 @@ +package vscode; + +/** + * A language model response part indicating a tool call, returned from a {@link LanguageModelChatResponse}, and also can be + * included as a content part on a {@link LanguageModelChatMessage}, to represent a previous tool call in a chat request. + */ +@:jsRequire("vscode", "LanguageModelToolCallPart") +extern class LanguageModelToolCallPart { + /** + * The ID of the tool call. This is a unique identifier for the tool call within the chat request. + */ + var callId:String; + + /** + * The name of the tool to call. + */ + var name:String; + + /** + * The input with which to call the tool. + */ + var input:{}; + + /** + * Create a new LanguageModelToolCallPart. + * + * @param callId The ID of the tool call. + * @param name The name of the tool to call. + * @param input The input with which to call the tool. + */ + function new(callId:String, name:String, input:{}); +} diff --git a/src/vscode/LanguageModelToolConfirmationMessages.hx b/src/vscode/LanguageModelToolConfirmationMessages.hx new file mode 100644 index 00000000..3ebad938 --- /dev/null +++ b/src/vscode/LanguageModelToolConfirmationMessages.hx @@ -0,0 +1,19 @@ +package vscode; + +import vscode.TerminalShellExecution.AsyncIterable; + +/** + * When this is returned in {@link PreparedToolInvocation}, the user will be asked to confirm before running the tool. These + * messages will be shown with buttons that say "Continue" and "Cancel". + */ +typedef LanguageModelToolConfirmationMessages = { + /** + * The title of the confirmation message. + */ + var title:String; + + /** + * The body of the confirmation message. + */ + var message:EitherType; +} diff --git a/src/vscode/LanguageModelToolInformation.hx b/src/vscode/LanguageModelToolInformation.hx new file mode 100644 index 00000000..5092a045 --- /dev/null +++ b/src/vscode/LanguageModelToolInformation.hx @@ -0,0 +1,29 @@ +package vscode; + +import vscode.TerminalShellExecution.AsyncIterable; + +/** + * Information about a registered tool available in {@link lm.tools}. + */ +typedef LanguageModelToolInformation = { + /** + * A unique name for the tool. + */ + var name(default, null):String; + + /** + * A description of this tool that may be passed to a language model. + */ + var description(default, null):String; + + /** + * A JSON schema for the input this tool accepts. + */ + var inputSchema(default, null):Null<{}>; + + /** + * A set of tags, declared by the tool, that roughly describe the tool's capabilities. A tool user may use these to filter + * the set of tools to just ones that are relevant for the task at hand. + */ + var tags(default, null):ReadOnlyArray; +} diff --git a/src/vscode/LanguageModelToolInvocationOptions.hx b/src/vscode/LanguageModelToolInvocationOptions.hx new file mode 100644 index 00000000..44c48730 --- /dev/null +++ b/src/vscode/LanguageModelToolInvocationOptions.hx @@ -0,0 +1,34 @@ +package vscode; + +import vscode.TerminalShellExecution.AsyncIterable; + +/** + * Options provided for tool invocation. + */ +typedef LanguageModelToolInvocationOptions = { + /** + * An opaque object that ties a tool invocation to a chat request from a {@link ChatParticipant chat participant}. + * + * The _only_ way to get a valid tool invocation token is using the provided {@link ChatRequest.toolInvocationToken toolInvocationToken} + * from a chat request. In that case, a progress bar will be automatically shown for the tool invocation in the chat response view, and if + * the tool requires user confirmation, it will show up inline in the chat view. + * + * If the tool is being invoked outside of a chat request, `undefined` should be passed instead, and no special UI except for + * confirmations will be shown. + * + * *Note* that a tool that invokes another tool during its invocation, can pass along the `toolInvocationToken` that it received. + */ + var toolInvocationToken:Null; + + /** + * The input with which to invoke the tool. The input must match the schema defined in + * {@link LanguageModelToolInformation.inputSchema} + */ + var input:T; + + /** + * Options to hint at how many tokens the tool should return in its response, and enable the tool to count tokens + * accurately. + */ + var ?tokenizationOptions:LanguageModelToolTokenizationOptions; +} diff --git a/src/vscode/LanguageModelToolInvocationPrepareOptions.hx b/src/vscode/LanguageModelToolInvocationPrepareOptions.hx new file mode 100644 index 00000000..fea94a72 --- /dev/null +++ b/src/vscode/LanguageModelToolInvocationPrepareOptions.hx @@ -0,0 +1,13 @@ +package vscode; + +import vscode.TerminalShellExecution.AsyncIterable; + +/** + * Options for {@link LanguageModelTool.prepareInvocation}. + */ +typedef LanguageModelToolInvocationPrepareOptions = { + /** + * The input that the tool is being invoked with. + */ + var input:T; +} diff --git a/src/vscode/LanguageModelToolResult.hx b/src/vscode/LanguageModelToolResult.hx new file mode 100644 index 00000000..05e69de2 --- /dev/null +++ b/src/vscode/LanguageModelToolResult.hx @@ -0,0 +1,20 @@ +package vscode; + +/** + * A result returned from a tool invocation. If using `@vscode/prompt-tsx`, this result may be rendered using a `ToolResult`. + */ +@:jsRequire("vscode", "LanguageModelToolResult") +extern class LanguageModelToolResult { + /** + * A list of tool result content parts. Includes `unknown` becauses this list may be extended with new content types in + * the future. + * @see {@link lm.invokeTool}. + */ + var content:Array>; + + /** + * Create a LanguageModelToolResult + * @param content A list of tool result content parts + */ + function new(content:Array>); +} diff --git a/src/vscode/LanguageModelToolResultPart.hx b/src/vscode/LanguageModelToolResultPart.hx new file mode 100644 index 00000000..c3cc9b05 --- /dev/null +++ b/src/vscode/LanguageModelToolResultPart.hx @@ -0,0 +1,26 @@ +package vscode; + +/** + * The result of a tool call. This is the counterpart of a {@link LanguageModelToolCallPart tool call} and + * it can only be included in the content of a User message + */ +@:jsRequire("vscode", "LanguageModelToolResultPart") +extern class LanguageModelToolResultPart { + /** + * The ID of the tool call. + * + * *Note* that this should match the {@link LanguageModelToolCallPart.callId callId} of a tool call part. + */ + var callId:String; + + /** + * The value of the tool result. + */ + var content:Array>; + + /** + * @param callId The ID of the tool call. + * @param content The content of the tool result. + */ + function new(callId:String, content:Array>); +} diff --git a/src/vscode/LanguageModelToolTokenizationOptions.hx b/src/vscode/LanguageModelToolTokenizationOptions.hx new file mode 100644 index 00000000..ac43169a --- /dev/null +++ b/src/vscode/LanguageModelToolTokenizationOptions.hx @@ -0,0 +1,21 @@ +package vscode; + +import vscode.TerminalShellExecution.AsyncIterable; + +/** + * Options related to tokenization for a tool invocation. + */ +typedef LanguageModelToolTokenizationOptions = { + /** + * If known, the maximum number of tokens the tool should emit in its result. + */ + var tokenBudget:Int; + + /** + * Count the number of tokens in a message using the model specific tokenizer-logic. + * @param text A string. + * @param token Optional cancellation token. See {@link CancellationTokenSource} for how to create one. + * @returns A thenable that resolves to the number of tokens. + */ + function countTokens(text:String, ?token:CancellationToken):Thenable; +} diff --git a/src/vscode/LanguageStatusItem.hx b/src/vscode/LanguageStatusItem.hx new file mode 100644 index 00000000..52e51649 --- /dev/null +++ b/src/vscode/LanguageStatusItem.hx @@ -0,0 +1,67 @@ +package vscode; + +/** + * A language status item is the preferred way to present language status reports for the active text editors, + * such as selected linter or notifying about a configuration problem. + */ +typedef LanguageStatusItem = { + /** + * The identifier of this item. + */ + var id(default, null):String; + + /** + * The short name of this item, like 'Java Language Status', etc. + */ + var name:Null; + + /** + * A {@link DocumentSelector selector} that defines for what editors + * this item shows. + */ + var selector:DocumentSelector; + + /** + * The severity of this item. + * + * Defaults to {@link LanguageStatusSeverity.Information information}. You can use this property to + * signal to users that there is a problem that needs attention, like a missing executable or an + * invalid configuration. + */ + var severity:LanguageStatusSeverity; + + /** + * The text to show for the entry. You can embed icons in the text by leveraging the syntax: + * + * `My text $(icon-name) contains icons like $(icon-name) this one.` + * + * Where the icon-name is taken from the ThemeIcon [icon set](https://code.visualstudio.com/api/references/icons-in-labels#icon-listing), e.g. + * `light-bulb`, `thumbsup`, `zap` etc. + */ + var text:String; + + /** + * Optional, human-readable details for this item. + */ + var ?detail:String; + + /** + * Controls whether the item is shown as "busy". Defaults to `false`. + */ + var busy:Bool; + + /** + * A {@linkcode Command command} for this item. + */ + var command:Null; + + /** + * Accessibility information used when a screen reader interacts with this item + */ + var ?accessibilityInformation:AccessibilityInformation; + + /** + * Dispose and free associated resources. + */ + function dispose():Void; +} diff --git a/src/vscode/LanguageStatusSeverity.hx b/src/vscode/LanguageStatusSeverity.hx new file mode 100644 index 00000000..92a20cd4 --- /dev/null +++ b/src/vscode/LanguageStatusSeverity.hx @@ -0,0 +1,25 @@ +package vscode; + +/** + * Represents the severity of a language status item. + */ +/** + * Represents the severity level of a language status. + */ +@:jsRequire("vscode", "LanguageStatusSeverity") +extern enum abstract LanguageStatusSeverity(Int) { + /** + * Informational severity level. + */ + var Information; + + /** + * Warning severity level. + */ + var Warning; + + /** + * Error severity level. + */ + var Error; +} diff --git a/src/vscode/LinkedEditingRangeProvider.hx b/src/vscode/LinkedEditingRangeProvider.hx index 98b28894..ee4c7a16 100644 --- a/src/vscode/LinkedEditingRangeProvider.hx +++ b/src/vscode/LinkedEditingRangeProvider.hx @@ -14,7 +14,7 @@ typedef LinkedEditingRangeProvider = { * @param document The document in which the provider was invoked. * @param position The position at which the provider was invoked. * @param token A cancellation token. - * @return A list of ranges that can be edited together + * @returns A list of ranges that can be edited together */ function provideLinkedEditingRanges(document:TextDocument, position:Position, token:CancellationToken):ProviderResult; } diff --git a/src/vscode/LogLevel.hx b/src/vscode/LogLevel.hx new file mode 100644 index 00000000..ed736515 --- /dev/null +++ b/src/vscode/LogLevel.hx @@ -0,0 +1,40 @@ +package vscode; + +/** + * Represents the severity of a language status item. + */ +/** + * Represents the severity level of a language status. + */ +@:jsRequire("vscode", "LogLevel") +extern enum abstract LogLevel(Int) { + /** + * No messages are logged with this level. + */ + var Off; + + /** + * All messages are logged with this level. + */ + var Trace; + + /** + * Messages with debug and higher log level are logged with this level. + */ + var Debug; + + /** + * Messages with info and higher log level are logged with this level. + */ + var Info; + + /** + * Messages with warning and higher log level are logged with this level. + */ + var Warning; + + /** + * Only error messages are logged with this level. + */ + var Error; +} diff --git a/src/vscode/LogOutputChannel.hx b/src/vscode/LogOutputChannel.hx new file mode 100644 index 00000000..d5c05016 --- /dev/null +++ b/src/vscode/LogOutputChannel.hx @@ -0,0 +1,65 @@ +package vscode; + +/** + * A channel for containing log output. + * + * To get an instance of a `LogOutputChannel` use + * {@link window.createOutputChannel createOutputChannel}. + */ +@:jsRequire("vscode", "OutputChannel") +extern class LogOutputChannel extends OutputChannel { + /** + * The current log level of the channel. Defaults to {@link env.logLevel editor log level}. + */ + var logLevel(default, null):LogLevel; + + /** + * An {@link Event} which fires when the log level of the channel changes. + */ + var onDidChangeLogLevel(default, null):Event; + + /** + * Outputs the given trace message to the channel. Use this method to log verbose information. + * + * The message is only logged if the channel is configured to display {@link LogLevel.Trace trace} log level. + * + * @param message trace message to log + */ + function trace(message:String, ...args:Any):Void; + + /** + * Outputs the given debug message to the channel. + * + * The message is only logged if the channel is configured to display {@link LogLevel.Debug debug} log level or lower. + * + * @param message debug message to log + */ + function debug(message:String, ...args:Any):Void; + + /** + * Outputs the given information message to the channel. + * + * The message is only logged if the channel is configured to display {@link LogLevel.Info info} log level or lower. + * + * @param message info message to log + */ + function info(message:String, ...args:Any):Void; + + /** + * Outputs the given warning message to the channel. + * + * The message is only logged if the channel is configured to display {@link LogLevel.Warning warning} log level or lower. + * + * @param message warning message to log + */ + function warn(message:String, ...args:Any):Void; + + /** + * Outputs the given error or error message to the channel. + * + * The message is only logged if the channel is configured to display {@link LogLevel.Error error} log level or lower. + * + * @param error Error or error message to log + */ + function error(error:EitherType, ...args:Any):Void; +} diff --git a/src/vscode/MarkdownString.hx b/src/vscode/MarkdownString.hx index ca698946..e820f078 100644 --- a/src/vscode/MarkdownString.hx +++ b/src/vscode/MarkdownString.hx @@ -1,11 +1,12 @@ package vscode; /** - * The MarkdownString represents human-readable text that supports formatting via the - * markdown syntax. Standard markdown is supported, also tables, but no embedded html. + * Human-readable text that supports formatting via the [markdown syntax](https://commonmark.org). * * Rendering of {@link ThemeIcon theme icons} via the `$()`-syntax is supported - * when the {@linkcode MarkdownString.supportThemeIcons supportThemeIcons} is set to `true`. + * when the {@linkcode supportThemeIcons} is set to `true`. + * + * Rendering of embedded html is supported when {@linkcode supportHtml} is set to `true`. */ @:jsRequire("vscode", "MarkdownString") extern class MarkdownString { @@ -17,14 +18,54 @@ extern class MarkdownString { /** * Indicates that this markdown string is from a trusted source. Only *trusted* * markdown supports links that execute commands, e.g. `[Run it](command:myCommandId)`. + * + * Defaults to `false` (commands are disabled). */ - var isTrusted:Null; + var isTrusted:Null; + }>>; /** * Indicates that this markdown string can contain {@link ThemeIcon ThemeIcons}, e.g. `$(zap)`. */ var supportThemeIcons:Null; + /** + * Indicates that this markdown string can contain raw html tags. Defaults to `false`. + * + * When `supportHtml` is false, the markdown renderer will strip out any raw html tags + * that appear in the markdown text. This means you can only use markdown syntax for rendering. + * + * When `supportHtml` is true, the markdown render will also allow a safe subset of html tags + * and attributes to be rendered. See https://github.com/microsoft/vscode/blob/6d2920473c6f13759c978dd89104c4270a83422d/src/vs/base/browser/markdownRenderer.ts#L296 + * for a list of all supported tags and attributes. + */ + var supportHtml:Null; + + /** + * Uri that relative paths are resolved relative to. + * + * If the `baseUri` ends with `/`, it is considered a directory and relative paths in the markdown are resolved relative to that directory: + * + * ```ts + * const md = new vscode.MarkdownString(`[link](./file.js)`); + * md.baseUri = vscode.Uri.file('/path/to/dir/'); + * // Here 'link' in the rendered markdown resolves to '/path/to/dir/file.js' + * ``` + * + * If the `baseUri` is a file, relative paths in the markdown are resolved relative to the parent dir of that file: + * + * ```ts + * const md = new vscode.MarkdownString(`[link](./file.js)`); + * md.baseUri = vscode.Uri.file('/path/to/otherFile.js'); + * // Here 'link' in the rendered markdown resolves to '/path/to/file.js' + * ``` + */ + var baseUri:Null; + /** * Creates a new markdown string with the given value. * diff --git a/src/vscode/MarkedString.hx b/src/vscode/MarkedString.hx index 25a91710..4525acc1 100644 --- a/src/vscode/MarkedString.hx +++ b/src/vscode/MarkedString.hx @@ -7,4 +7,16 @@ package vscode; * * @deprecated This type is deprecated, please use {@linkcode MarkdownString} instead. */ -typedef MarkedString = EitherType; +typedef MarkedString = EitherType; diff --git a/src/vscode/Memento.hx b/src/vscode/Memento.hx index 0fa44094..e5114a7d 100644 --- a/src/vscode/Memento.hx +++ b/src/vscode/Memento.hx @@ -4,28 +4,39 @@ package vscode; * A memento represents a storage utility. It can store and retrieve * values. */ -typedef Memento = { +@:jsRequire("vscode", "Memento") +extern class Memento { /** * Returns the stored keys. * - * @return The stored keys. + * @returns The stored keys. */ function keys():ReadOnlyArray; + /** + * Return a value. + * + * @param key A string. + * @returns The stored value or `undefined`. + */ + overload function get(key:String):Null; + /** * Return a value. * * @param key A string. * @param defaultValue A value that should be returned when there is no * value (`undefined`) with the given key. - * @return The stored value, `undefined`, or the defaultValue. + * @returns The stored value or the defaultValue. */ - @:overload(function(key:String, defaultValue:T):T {}) - function get(key:String):Null; + overload function get(key:String, defaultValue:T):T; /** * Store a value. The value must be JSON-stringifyable. * + * *Note* that using `undefined` as value removes the key from the underlying + * storage. + * * @param key A string. * @param value A value. MUST not contain cyclic references. */ diff --git a/src/vscode/NotebookCell.hx b/src/vscode/NotebookCell.hx index 3ef05b81..f7b7ee3d 100644 --- a/src/vscode/NotebookCell.hx +++ b/src/vscode/NotebookCell.hx @@ -42,5 +42,5 @@ typedef NotebookCell = { /** * The most recent {@link NotebookCellExecutionSummary execution summary} for this cell. */ - final ?executionSummary:NotebookCellExecutionSummary; + final executionSummary:Null; } diff --git a/src/vscode/NotebookCellExecution.hx b/src/vscode/NotebookCellExecution.hx index 81349b8a..2bbfc7d9 100644 --- a/src/vscode/NotebookCellExecution.hx +++ b/src/vscode/NotebookCellExecution.hx @@ -51,7 +51,7 @@ typedef NotebookCellExecution = { * * @param cell Cell for which output is cleared. Defaults to the {@link NotebookCellExecution.cell cell} of * this execution. - * @return A thenable that resolves when the operation finished. + * @returns A thenable that resolves when the operation finished. */ function clearOutput(?cell:NotebookCell):Thenable; @@ -61,9 +61,9 @@ typedef NotebookCellExecution = { * @param out Output that replaces the current output. * @param cell Cell for which output is cleared. Defaults to the {@link NotebookCellExecution.cell cell} of * this execution. - * @return A thenable that resolves when the operation finished. + * @returns A thenable that resolves when the operation finished. */ - function replaceOutput(out:EitherType>, ?cell:NotebookCell):Thenable; + function replaceOutput(out:EitherType>, ?cell:NotebookCell):Thenable; /** * Append to the output of the cell that is executing or to another cell that is affected by this execution. @@ -71,25 +71,25 @@ typedef NotebookCellExecution = { * @param out Output that is appended to the current output. * @param cell Cell for which output is cleared. Defaults to the {@link NotebookCellExecution.cell cell} of * this execution. - * @return A thenable that resolves when the operation finished. + * @returns A thenable that resolves when the operation finished. */ - function appendOutput(out:EitherType>, ?cell:NotebookCell):Thenable; + function appendOutput(out:EitherType>, ?cell:NotebookCell):Thenable; /** * Replace all output items of existing cell output. * * @param items Output items that replace the items of existing output. * @param output Output object that already exists. - * @return A thenable that resolves when the operation finished. + * @returns A thenable that resolves when the operation finished. */ - function replaceOutputItems(items:EitherType>, output:NotebookCellOutput):Thenable; + function replaceOutputItems(items:EitherType>, output:NotebookCellOutput):Thenable; /** * Append output items to existing cell output. * * @param items Output items that are append to existing output. * @param output Output object that already exists. - * @return A thenable that resolves when the operation finished. + * @returns A thenable that resolves when the operation finished. */ - function appendOutputItems(items:EitherType>, output:NotebookCellOutput):Thenable; + function appendOutputItems(items:EitherType>, output:NotebookCellOutput):Thenable; } diff --git a/src/vscode/NotebookCellExecutionSummary.hx b/src/vscode/NotebookCellExecutionSummary.hx index 4fb7f152..6ca84eae 100644 --- a/src/vscode/NotebookCellExecutionSummary.hx +++ b/src/vscode/NotebookCellExecutionSummary.hx @@ -17,5 +17,14 @@ typedef NotebookCellExecutionSummary = { /** * The times at which execution started and ended, as unix timestamps */ - var ?timing(default, null):{startTime:Float, endTime:Float}; + var ?timing(default, null):{ + /** + * Execution start time. + */ + startTime:Float, + /** + * Execution end time. + */ + endTime:Float + }; } diff --git a/src/vscode/NotebookCellStatusBarItemProvider.hx b/src/vscode/NotebookCellStatusBarItemProvider.hx index 83fcc8ce..9e225c5d 100644 --- a/src/vscode/NotebookCellStatusBarItemProvider.hx +++ b/src/vscode/NotebookCellStatusBarItemProvider.hx @@ -13,7 +13,7 @@ typedef NotebookCellStatusBarItemProvider = { * The provider will be called when the cell scrolls into view, when its content, outputs, language, or metadata change, and when it changes execution state. * @param cell The cell for which to return items. * @param token A token triggered if this request should be cancelled. - * @return One or more {@link NotebookCellStatusBarItem cell statusbar items} + * @returns One or more {@link NotebookCellStatusBarItem cell statusbar items} */ function provideCellStatusBarItems(cell:NotebookCell, token:CancellationToken):ProviderResult>>; diff --git a/src/vscode/NotebookController.hx b/src/vscode/NotebookController.hx index f1dd89f5..b1dfc787 100644 --- a/src/vscode/NotebookController.hx +++ b/src/vscode/NotebookController.hx @@ -110,7 +110,16 @@ typedef NotebookController = { * _Note_ that controller selection is persisted (by the controllers {@link NotebookController.id id}) and restored as soon as a * controller is re-created or as a notebook is {@link workspace.onDidOpenNotebookDocument opened}. */ - var onDidChangeSelectedNotebooks(default, null):Event<{notebook:NotebookDocument, selected:Bool}>; + var onDidChangeSelectedNotebooks(default, null):Event<{ + /** + * The notebook for which the controller has been selected or un-selected. + */ + notebook:NotebookDocument, + /** + * Whether the controller has been selected or un-selected. + */ + selected:Bool + }>; /** * A controller can set affinities for specific notebook documents. This allows a controller diff --git a/src/vscode/NotebookDocument.hx b/src/vscode/NotebookDocument.hx index 478959ca..11be712a 100644 --- a/src/vscode/NotebookDocument.hx +++ b/src/vscode/NotebookDocument.hx @@ -56,7 +56,7 @@ typedef NotebookDocument = { * Return the cell at the specified index. The index will be adjusted to the notebook. * * @param index - The index of the cell to retrieve. - * @return A {@link NotebookCell cell}. + * @returns A {@link NotebookCell cell}. */ function cellAt(index:Int):NotebookCell; @@ -72,7 +72,7 @@ typedef NotebookDocument = { /** * Save the document. The saving will be handled by the corresponding {@link NotebookSerializer serializer}. * - * @return A promise that will resolve to true when the document + * @returns A promise that will resolve to true when the document * has been saved. Will return false if the file was not dirty or when save failed. */ function save():Thenable; diff --git a/src/vscode/NotebookDocumentCellChange.hx b/src/vscode/NotebookDocumentCellChange.hx new file mode 100644 index 00000000..b3553467 --- /dev/null +++ b/src/vscode/NotebookDocumentCellChange.hx @@ -0,0 +1,36 @@ +package vscode; + +/** + * Describes a change to a notebook cell. + * + * @see {@link NotebookDocumentChangeEvent} + */ +typedef NotebookDocumentCellChange = { + /** + * The affected cell. + */ + var cell(default, null):NotebookCell; + + /** + * The document of the cell or `undefined` when it did not change. + * + * *Note* that you should use the {@link workspace.onDidChangeTextDocument onDidChangeTextDocument}-event + * for detailed change information, like what edits have been performed. + */ + var document(default, null):Null; + + /** + * The new metadata of the cell or `undefined` when it did not change. + */ + var metadata(default, null):Null>; + + /** + * The new outputs of the cell or `undefined` when they did not change. + */ + var outputs(default, null):Null>; + + /** + * The new execution summary of the cell or `undefined` when it did not change. + */ + var executionSummary(default, null):Null; +} diff --git a/src/vscode/NotebookDocumentChangeEvent.hx b/src/vscode/NotebookDocumentChangeEvent.hx new file mode 100644 index 00000000..c02f2286 --- /dev/null +++ b/src/vscode/NotebookDocumentChangeEvent.hx @@ -0,0 +1,26 @@ +package vscode; + +/** + * An event describing a transactional {@link NotebookDocument notebook} change. + */ +typedef NotebookDocumentChangeEvent = { + /** + * The affected notebook. + */ + var notebook(default, null):NotebookDocument; + + /** + * The new metadata of the notebook or `undefined` when it did not change. + */ + var metadata(default, null):Null>; + + /** + * An array of content changes describing added or removed {@link NotebookCell cells}. + */ + var contentChanges(default, null):ReadOnlyArray; + + /** + * An array of {@link NotebookDocumentCellChange cell changes}. + */ + var cellChanges(default, null):ReadOnlyArray; +} diff --git a/src/vscode/NotebookDocumentContentChange.hx b/src/vscode/NotebookDocumentContentChange.hx new file mode 100644 index 00000000..cb0ba575 --- /dev/null +++ b/src/vscode/NotebookDocumentContentChange.hx @@ -0,0 +1,26 @@ +package vscode; + +/** + * Describes a structural change to a notebook document, e.g newly added and removed cells. + * + * @see {@link NotebookDocumentChangeEvent} + */ +typedef NotebookDocumentContentChange = { + /** + * The range at which cells have been either added or removed. + * + * Note that no cells have been {@link NotebookDocumentContentChange.removedCells removed} + * when this range is {@link NotebookRange.isEmpty empty}. + */ + var range(default, null):NotebookRange; + + /** + * Cells that have been added to the document. + */ + var addedCells(default, null):ReadOnlyArray; + + /** + * Cells that have been removed from the document. + */ + var removedCells(default, null):ReadOnlyArray; +} diff --git a/src/vscode/NotebookDocumentContentOptions.hx b/src/vscode/NotebookDocumentContentOptions.hx index 2e95e30d..38fad62b 100644 --- a/src/vscode/NotebookDocumentContentOptions.hx +++ b/src/vscode/NotebookDocumentContentOptions.hx @@ -8,20 +8,25 @@ package vscode; */ typedef NotebookDocumentContentOptions = { /** - * Controls if outputs change will trigger notebook document content change and if it will be used in the diff editor - * Default to false. If the content provider doesn't persisit the outputs in the file document, this should be set to true. + * Controls if output change events will trigger notebook document content change events and + * if it will be used in the diff editor, defaults to false. If the content provider doesn't + * persist the outputs in the file document, this should be set to true. */ var ?transientOutputs:Bool; /** - * Controls if a cell metadata property change will trigger notebook document content change and if it will be used in the diff editor - * Default to false. If the content provider doesn't persisit a metadata property in the file document, it should be set to true. + * Controls if a cell metadata property change event will trigger notebook document content + * change events and if it will be used in the diff editor, defaults to false. If the + * content provider doesn't persist a metadata property in the file document, it should be + * set to true. */ var ?transientCellMetadata:DynamicAccess>; /** - * Controls if a document metadata property change will trigger notebook document content change and if it will be used in the diff editor - * Default to false. If the content provider doesn't persisit a metadata property in the file document, it should be set to true. + * Controls if a document metadata property change event will trigger notebook document + * content change event and if it will be used in the diff editor, defaults to false. If the + * content provider doesn't persist a metadata property in the file document, it should be + * set to true. */ var ?transientDocumentMetadata:DynamicAccess>; } diff --git a/src/vscode/NotebookDocumentShowOptions.hx b/src/vscode/NotebookDocumentShowOptions.hx new file mode 100644 index 00000000..21a34fa9 --- /dev/null +++ b/src/vscode/NotebookDocumentShowOptions.hx @@ -0,0 +1,32 @@ +package vscode; + +/** + * Represents options to configure the behavior of showing a {@link NotebookDocument notebook document} in an {@link NotebookEditor notebook editor}. + */ +typedef NotebookDocumentShowOptions = { + /** + * An optional view column in which the {@link NotebookEditor notebook editor} should be shown. + * The default is the {@link ViewColumn.Active active}. Columns that do not exist + * will be created as needed up to the maximum of {@linkcode ViewColumn.Nine}. + * Use {@linkcode ViewColumn.Beside} to open the editor to the side of the currently + * active one. + */ + var ?viewColumn(default, null):ViewColumn; + + /** + * An optional flag that when `true` will stop the {@link NotebookEditor notebook editor} from taking focus. + */ + var ?preserveFocus(default, null):Bool; + + /** + * An optional flag that controls if an {@link NotebookEditor notebook editor}-tab shows as preview. Preview tabs will + * be replaced and reused until set to stay - either explicitly or through editing. The default behaviour depends + * on the `workbench.editor.enablePreview`-setting. + */ + var ?preview(default, null):Bool; + + /** + * An optional selection to apply for the document in the {@link NotebookEditor notebook editor}. + */ + var ?selections(default, null):ReadOnlyArray; +} diff --git a/src/vscode/NotebookDocumentWillSaveEvent.hx b/src/vscode/NotebookDocumentWillSaveEvent.hx new file mode 100644 index 00000000..172ee381 --- /dev/null +++ b/src/vscode/NotebookDocumentWillSaveEvent.hx @@ -0,0 +1,57 @@ +package vscode; + +/** + * An event that is fired when a {@link NotebookDocument notebook document} will be saved. + * + * To make modifications to the document before it is being saved, call the + * {@linkcode NotebookDocumentWillSaveEvent.waitUntil waitUntil}-function with a thenable + * that resolves to a {@link WorkspaceEdit workspace edit}. + */ +@:jsRequire("vscode", "NotebookDocumentWillSaveEvent") +extern class NotebookDocumentWillSaveEvent { + /** + * A cancellation token. + */ + var token(default, null):CancellationToken; + + /** + * The {@link NotebookDocument notebook document} that will be saved. + */ + var notebook(default, null):NotebookDocument; + + /** + * The reason why save was triggered. + */ + var reason(default, null):TextDocumentSaveReason; + + /** + * Allows to pause the event loop and to apply {@link WorkspaceEdit workspace edit}. + * Edits of subsequent calls to this function will be applied in order. The + * edits will be *ignored* if concurrent modifications of the notebook document happened. + * + * *Note:* This function can only be called during event dispatch and not + * in an asynchronous manner: + * + * ```ts + * workspace.onWillSaveNotebookDocument(event => { + * // async, will *throw* an error + * setTimeout(() => event.waitUntil(promise)); + * + * // sync, OK + * event.waitUntil(promise); + * }) + * ``` + * + * @param thenable A thenable that resolves to {@link WorkspaceEdit workspace edit}. + */ + overload function waitUntil(thenable:Thenable):Void; + + /** + * Allows to pause the event loop until the provided thenable resolved. + * + * *Note:* This function can only be called during event dispatch. + * + * @param thenable A thenable that delays saving. + */ + overload function waitUntil(thenable:Thenable):Void; +} diff --git a/src/vscode/NotebookEdit.hx b/src/vscode/NotebookEdit.hx new file mode 100644 index 00000000..4ee82363 --- /dev/null +++ b/src/vscode/NotebookEdit.hx @@ -0,0 +1,73 @@ +package vscode; + +/** + * A notebook edit represents edits that should be applied to the contents of a notebook. + */ +@:jsRequire("vscode", "NotebookEdit") +extern class NotebookEdit { + /** + * Utility to create a edit that replaces cells in a notebook. + * + * @param range The range of cells to replace + * @param newCells The new notebook cells. + */ + static function replaceCells(range:NotebookRange, newCells:Array):NotebookEdit; + + /** + * Utility to create an edit that replaces cells in a notebook. + * + * @param index The index to insert cells at. + * @param newCells The new notebook cells. + */ + static function insertCells(index:Int, newCells:Array):NotebookEdit; + + /** + * Utility to create an edit that deletes cells in a notebook. + * + * @param range The range of cells to delete. + */ + static function deleteCells(range:NotebookRange):NotebookEdit; + + /** + * Utility to create an edit that update a cell's metadata. + * + * @param index The index of the cell to update. + * @param newCellMetadata The new metadata for the cell. + */ + static function updateCellMetadata(index:Int, newCellMetadata:DynamicAccess):NotebookEdit; + + /** + * Utility to create an edit that updates the notebook's metadata. + * + * @param newNotebookMetadata The new metadata for the notebook. + */ + static function updateNotebookMetadata(newNotebookMetadata:DynamicAccess):NotebookEdit; + + /** + * Range of the cells being edited. May be empty. + */ + var range:NotebookRange; + + /** + * New cells being inserted. May be empty. + */ + var newCells:Array; + + /** + * Optional new metadata for the cells. + */ + var newCellMetadata:Null>; + + /** + * Optional new metadata for the notebook. + */ + var newNotebookMetadata:Null>; + + /** + * Create a new notebook edit. + * + * @param range A notebook range. + * @param newCells An array of new cell data. + */ + function new(range:NotebookRange, newCells:Array); +} diff --git a/src/vscode/NotebookEditor.hx b/src/vscode/NotebookEditor.hx index 00c7c2a5..b5e0e959 100644 --- a/src/vscode/NotebookEditor.hx +++ b/src/vscode/NotebookEditor.hx @@ -5,4 +5,39 @@ package vscode; * Additional properties of the NotebookEditor are available in the proposed * API, which will be finalized later. */ -typedef NotebookEditor = {} +typedef NotebookEditor = { + /** + * The {@link NotebookDocument notebook document} associated with this notebook editor. + */ + var notebook(default, null):NotebookDocument; + + /** + * The primary selection in this notebook editor. + */ + var selection:NotebookRange; + + /** + * All selections in this notebook editor. + * + * The primary selection (or focused range) is `selections[0]`. When the document has no cells, the primary selection is empty `{ start: 0, end: 0 }`; + */ + var selections:ReadOnlyArray; + + /** + * The current visible ranges in the editor (vertically). + */ + var visibleRanges(default, null):ReadOnlyArray; + + /** + * The column in which this editor shows. + */ + var ?viewColumn(default, null):ViewColumn; + + /** + * Scroll as indicated by `revealType` in order to reveal the given range. + * + * @param range A range. + * @param revealType The scrolling strategy for revealing `range`. + */ + function revealRange(range:NotebookRange, ?revealType:NotebookEditorRevealType):Void; +} diff --git a/src/vscode/NotebookEditorRevealType.hx b/src/vscode/NotebookEditorRevealType.hx new file mode 100644 index 00000000..c772e049 --- /dev/null +++ b/src/vscode/NotebookEditorRevealType.hx @@ -0,0 +1,28 @@ +package vscode; + +/** + * Represents a notebook editor that is attached to a {@link NotebookDocument notebook}. + */ +@:jsRequire("vscode", "NotebookEditorRevealType") +extern enum abstract NotebookEditorRevealType(Int) { + /** + * The range will be revealed with as little scrolling as possible. + */ + var Default; + + /** + * The range will always be revealed in the center of the viewport. + */ + var InCenter; + + /** + * If the range is outside the viewport, it will be revealed in the center of the viewport. + * Otherwise, it will be revealed with as little scrolling as possible. + */ + var InCenterIfOutsideViewport; + + /** + * The range will always be revealed at the top of the viewport. + */ + var AtTop; +} diff --git a/src/vscode/NotebookEditorSelectionChangeEvent.hx b/src/vscode/NotebookEditorSelectionChangeEvent.hx new file mode 100644 index 00000000..36809ab7 --- /dev/null +++ b/src/vscode/NotebookEditorSelectionChangeEvent.hx @@ -0,0 +1,16 @@ +package vscode; + +/** + * Represents an event describing the change in a {@link NotebookEditor.selections notebook editor's selections}. + */ +typedef NotebookEditorSelectionChangeEvent = { + /** + * The {@link NotebookEditor notebook editor} for which the selections have changed. + */ + var notebookEditor(default, null):NotebookEditor; + + /** + * The new value for the {@link NotebookEditor.selections notebook editor's selections}. + */ + var selections(default, null):ReadOnlyArray; +} diff --git a/src/vscode/NotebookEditorVisibleRangesChangeEvent.hx b/src/vscode/NotebookEditorVisibleRangesChangeEvent.hx new file mode 100644 index 00000000..f37a79a5 --- /dev/null +++ b/src/vscode/NotebookEditorVisibleRangesChangeEvent.hx @@ -0,0 +1,16 @@ +package vscode; + +/** + * Represents an event describing the change in a {@link NotebookEditor.visibleRanges notebook editor's visibleRanges}. + */ +typedef NotebookEditorVisibleRangesChangeEvent = { + /** + * The {@link NotebookEditor notebook editor} for which the visible ranges have changed. + */ + var notebookEditor(default, null):NotebookEditor; + + /** + * The new value for the {@link NotebookEditor.visibleRanges notebook editor's visibleRanges}. + */ + var visibleRanges(default, null):ReadOnlyArray; +} diff --git a/src/vscode/NotebookRange.hx b/src/vscode/NotebookRange.hx index 9d31d45a..92d1108e 100644 --- a/src/vscode/NotebookRange.hx +++ b/src/vscode/NotebookRange.hx @@ -34,8 +34,17 @@ extern class NotebookRange { * Derive a new range for this range. * * @param change An object that describes a change to this range. - * @return A range that reflects the given change. Will return `this` range if the change + * @returns A range that reflects the given change. Will return `this` range if the change * is not changing anything. */ - function with(change:{?start:Int, ?end:Int}):NotebookRange; + function with(change:{ + /** + * New start index, defaults to `this.start`. + */ + ?start:Int, + /** + * New end index, defaults to `this.end`. + */ + ?end:Int + }):NotebookRange; } diff --git a/src/vscode/NotebookRendererMessaging.hx b/src/vscode/NotebookRendererMessaging.hx index 3743a9d5..4770e6ad 100644 --- a/src/vscode/NotebookRendererMessaging.hx +++ b/src/vscode/NotebookRendererMessaging.hx @@ -8,7 +8,13 @@ typedef NotebookRendererMessaging = { * An event that fires when a message is received from a renderer. */ var onDidReceiveMessage(default, null):Event<{ + /** + * The {@link NotebookEditor editor} that sent the message. + */ final editor:NotebookEditor; + /** + * The actual message. + */ final message:Any; }>; diff --git a/src/vscode/NotebookSerializer.hx b/src/vscode/NotebookSerializer.hx index 6501b7d3..78c69c7d 100644 --- a/src/vscode/NotebookSerializer.hx +++ b/src/vscode/NotebookSerializer.hx @@ -16,7 +16,7 @@ typedef NotebookSerializer = { * * @param content Contents of a notebook file. * @param token A cancellation token. - * @return Notebook data or a thenable that resolves to such. + * @returns Notebook data or a thenable that resolves to such. */ function deserializeNotebook(content:Uint8Array, token:CancellationToken):EitherType>; diff --git a/src/vscode/OnTypeFormattingEditProvider.hx b/src/vscode/OnTypeFormattingEditProvider.hx index 3cdeb066..3600e1cb 100644 --- a/src/vscode/OnTypeFormattingEditProvider.hx +++ b/src/vscode/OnTypeFormattingEditProvider.hx @@ -17,7 +17,7 @@ typedef OnTypeFormattingEditProvider = { * @param ch The character that has been typed. * @param options Options controlling formatting. * @param token A cancellation token. - * @return A set of text edits or a thenable that resolves to such. The lack of a result can be + * @returns A set of text edits or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined`, `null`, or an empty array. */ function provideOnTypeFormattingEdits(document:TextDocument, position:Position, ch:String, options:FormattingOptions, diff --git a/src/vscode/OpenDialogOptions.hx b/src/vscode/OpenDialogOptions.hx index a45a5208..ed44f4fa 100644 --- a/src/vscode/OpenDialogOptions.hx +++ b/src/vscode/OpenDialogOptions.hx @@ -36,10 +36,10 @@ typedef OpenDialogOptions = { /** * A set of file filters that are used by the dialog. Each entry is a human-readable label, - * like "TypeScript", and an array of extensions, e.g. + * like "TypeScript", and an array of extensions, for example: * ```ts * { - * 'Images': ['png', 'jpg'] + * 'Images': ['png', 'jpg'], * 'TypeScript': ['ts', 'tsx'] * } * ``` diff --git a/src/vscode/OutputChannel.hx b/src/vscode/OutputChannel.hx index 04e95561..97074e8a 100644 --- a/src/vscode/OutputChannel.hx +++ b/src/vscode/OutputChannel.hx @@ -6,7 +6,8 @@ package vscode; * To get an instance of an `OutputChannel` use * {@link window.createOutputChannel createOutputChannel}. */ -typedef OutputChannel = { +@:jsRequire("vscode", "OutputChannel") +extern class OutputChannel { /** * The human-readable name of this output channel. */ @@ -27,6 +28,13 @@ typedef OutputChannel = { */ function appendLine(value:String):Void; + /** + * Replaces all output from the channel with the given value. + * + * @param value A string, falsy values will not be printed. + */ + function replace(value:String):Void; + /** * Removes all output from the channel. */ @@ -37,8 +45,17 @@ typedef OutputChannel = { * * @param preserveFocus When `true` the channel will not take focus. */ - @:overload(function(?column:ViewColumn, ?preservceFocus:Bool):Void {}) - function show(?preserveFocus:Bool):Void; + overload function show(?preserveFocus:Bool):Void; + + /** + * Reveal this channel in the UI. + * + * @deprecated Use the overload with just one parameter (`show(preserveFocus?: boolean): void`). + * + * @param column This argument is **deprecated** and will be ignored. + * @param preserveFocus When `true` the channel will not take focus. + */ + overload function show(?column:ViewColumn, ?preservceFocus:Bool):Void; /** * Hide this channel from the UI. diff --git a/src/vscode/OverviewRulerLane.hx b/src/vscode/OverviewRulerLane.hx index 01a2ef02..a5ea2228 100644 --- a/src/vscode/OverviewRulerLane.hx +++ b/src/vscode/OverviewRulerLane.hx @@ -6,8 +6,23 @@ package vscode; */ @:jsRequire("vscode", "OverviewRulerLane") extern enum abstract OverviewRulerLane(Int) { + /** + * The left lane of the overview ruler. + */ var Left; + + /** + * The center lane of the overview ruler. + */ var Center; + + /** + * The right lane of the overview ruler. + */ var Right; + + /** + * All lanes of the overview ruler. + */ var Full; } diff --git a/src/vscode/Position.hx b/src/vscode/Position.hx index e7852fe3..4d742d11 100644 --- a/src/vscode/Position.hx +++ b/src/vscode/Position.hx @@ -30,7 +30,7 @@ extern class Position { * Check if this position is before `other`. * * @param other A position. - * @return `true` if position is on a smaller line + * @returns `true` if position is on a smaller line * or on the same line on a smaller character. */ function isBefore(other:Position):Bool; @@ -39,7 +39,7 @@ extern class Position { * Check if this position is before or equal to `other`. * * @param other A position. - * @return `true` if position is on a smaller line + * @returns `true` if position is on a smaller line * or on the same line on a smaller or equal character. */ function isBeforeOrEqual(other:Position):Bool; @@ -48,7 +48,7 @@ extern class Position { * Check if this position is after `other`. * * @param other A position. - * @return `true` if position is on a greater line + * @returns `true` if position is on a greater line * or on the same line on a greater character. */ function isAfter(other:Position):Bool; @@ -57,7 +57,7 @@ extern class Position { * Check if this position is after or equal to `other`. * * @param other A position. - * @return `true` if position is on a greater line + * @returns `true` if position is on a greater line * or on the same line on a greater or equal character. */ function isAfterOrEqual(other:Position):Bool; @@ -66,7 +66,7 @@ extern class Position { * Check if this position is equal to `other`. * * @param other A position. - * @return `true` if the line and character of the given position are equal to + * @returns `true` if the line and character of the given position are equal to * the line and character of this position. */ function isEqual(other:Position):Bool; @@ -75,7 +75,7 @@ extern class Position { * Compare this to `other`. * * @param other A position. - * @return A number smaller than zero if this position is before the given position, + * @returns A number smaller than zero if this position is before the given position, * a number greater than zero if this position is after the given position, or zero when * this and the given position are equal. */ @@ -86,27 +86,53 @@ extern class Position { * * @param lineDelta Delta value for the line value, default is `0`. * @param characterDelta Delta value for the character value, default is `0`. - * @return A position which line and character is the sum of the current line and + * @returns A position which line and character is the sum of the current line and * character and the corresponding deltas. */ - // TODO overload plox - // /** - // * Derived a new position relative to this position. - // * - // * @param change An object that describes a delta to this position. - // * @return A position that reflects the given delta. Will return `this` position if the change - // * is not changing anything. - // */ - @:overload(function(change:{?lineDelta:Int, ?characterDelta:Int}):Position {}) - function translate(?lineDelta:Int, ?characterDelta:Int):Position; + overload function translate(?lineDelta:Int, ?characterDelta:Int):Position; + + /** + * Derived a new position relative to this position. + * + * @param change An object that describes a delta to this position. + * @returns A position that reflects the given delta. Will return `this` position if the change + * is not changing anything. + */ + overload function translate(change:{ + /** + * Delta value for the line value, default is `0`. + */ + ?lineDelta:Int, + /** + * Delta value for the character value, default is `0`. + */ + ?characterDelta:Int + }):Position; /** * Create a new position derived from this position. * * @param line Value that should be used as line value, default is the {@link Position.line existing value} * @param character Value that should be used as character value, default is the {@link Position.character existing value} - * @return A position where line and character are replaced by the given values. + * @returns A position where line and character are replaced by the given values. + */ + overload function with(?line:Int, ?character:Int):Position; + + /** + * Derived a new position from this position. + * + * @param change An object that describes a change to this position. + * @returns A position that reflects the given change. Will return `this` position if the change + * is not changing anything. */ - @:overload(function(change:{?line:Int, ?character:Int}):Position {}) - function with(?line:Int, ?character:Int):Position; + overload function with(change:{ + /** + * New line value, defaults the line value of `this`. + */ + ?line:Int, + /** + * New character value, defaults the character value of `this`. + */ + ?character:Int + }):Position; } diff --git a/src/vscode/PreparedToolInvocation.hx b/src/vscode/PreparedToolInvocation.hx new file mode 100644 index 00000000..d4301e75 --- /dev/null +++ b/src/vscode/PreparedToolInvocation.hx @@ -0,0 +1,19 @@ +package vscode; + +import vscode.TerminalShellExecution.AsyncIterable; + +/** + * The result of a call to {@link LanguageModelTool.prepareInvocation}. + */ +typedef PreparedToolInvocation = { + /** + * A customized progress message to show while the tool runs. + */ + var ?invocationMessage:EitherType; + + /** + * The presence of this property indicates that the user should be asked to confirm before running the tool. The user + * should be asked for confirmation for any tool that has a side-effect or may potentially be dangerous. + */ + var ?confirmationMessages:LanguageModelToolConfirmationMessages; +} diff --git a/src/vscode/ProgressLocation.hx b/src/vscode/ProgressLocation.hx index 6723405f..3d2289bc 100644 --- a/src/vscode/ProgressLocation.hx +++ b/src/vscode/ProgressLocation.hx @@ -8,17 +8,20 @@ package vscode; extern enum abstract ProgressLocation(Int) { /** * Show progress for the source control viewlet, as overlay for the icon and as progress bar - * inside the viewlet (when visible). Neither supports cancellation nor discrete progress. + * inside the viewlet (when visible). Neither supports cancellation nor discrete progress nor + * a label to describe the operation. */ var SourceControl; /** * Show progress in the status bar of the editor. Neither supports cancellation nor discrete progress. + * Supports rendering of {@link ThemeIcon theme icons} via the `$()`-syntax in the progress label. */ var Window; /** - * Show progress as notification with an optional cancel button. Supports to show infinite and discrete progress. + * Show progress as notification with an optional cancel button. Supports to show infinite and discrete + * progress but does not support rendering of icons. */ var Notification; } diff --git a/src/vscode/ProgressOptions.hx b/src/vscode/ProgressOptions.hx index 7aee917b..dfe18934 100644 --- a/src/vscode/ProgressOptions.hx +++ b/src/vscode/ProgressOptions.hx @@ -7,7 +7,12 @@ typedef ProgressOptions = { /** * The location at which progress should show. */ - var location:EitherType; + var location:EitherType; /** * A human-readable string which will be used to describe the diff --git a/src/vscode/Pseudoterminal.hx b/src/vscode/Pseudoterminal.hx index 1dcf5b9a..eddf1b2f 100644 --- a/src/vscode/Pseudoterminal.hx +++ b/src/vscode/Pseudoterminal.hx @@ -13,6 +13,8 @@ typedef Pseudoterminal = { * Note writing `\n` will just move the cursor down 1 row, you need to write `\r` as well * to move the cursor to the left-most cell. * + * Events fired before {@link Pseudoterminal.open} is called will be be ignored. + * * **Example:** Write red text to the terminal * ```typescript * const writeEmitter = new vscode.EventEmitter(); @@ -38,6 +40,8 @@ typedef Pseudoterminal = { * bar). Set to `undefined` for the terminal to go back to the regular dimensions (fit to * the size of the panel). * + * Events fired before {@link Pseudoterminal.open} is called will be be ignored. + * * **Example:** Override the dimensions of a terminal to 20 columns and 10 rows * ```typescript * const dimensionsEmitter = new vscode.EventEmitter(); @@ -60,6 +64,8 @@ typedef Pseudoterminal = { /** * An event that when fired will signal that the pty is closed and dispose of the terminal. * + * Events fired before {@link Pseudoterminal.open} is called will be be ignored. + * * A number can be used to provide an exit code for the terminal. Exit codes must be * positive and a non-zero exit codes signals failure which shows a notification for a * regular terminal and allows dependent tasks to proceed when used with the @@ -68,7 +74,7 @@ typedef Pseudoterminal = { * **Example:** Exit the terminal when "y" is pressed, otherwise show a notification. * ```typescript * const writeEmitter = new vscode.EventEmitter(); - * const closeEmitter = new vscode.EventEmitter(); + * const closeEmitter = new vscode.EventEmitter(); * const pty: vscode.Pseudoterminal = { * onDidWrite: writeEmitter.event, * onDidClose: closeEmitter.event, @@ -81,7 +87,8 @@ typedef Pseudoterminal = { * closeEmitter.fire(); * } * }; - * vscode.window.createTerminal({ name: 'Exit example', pty }); + * const terminal = vscode.window.createTerminal({ name: 'Exit example', pty }); + * terminal.show(true); * ``` */ var ?onDidClose:Event>; diff --git a/src/vscode/QuickDiffProvider.hx b/src/vscode/QuickDiffProvider.hx index 1c9b58a3..650ce409 100644 --- a/src/vscode/QuickDiffProvider.hx +++ b/src/vscode/QuickDiffProvider.hx @@ -1,12 +1,17 @@ package vscode; +/** + * A quick diff provider provides a {@link Uri uri} to the original state of a + * modified resource. The editor will use this information to render ad'hoc diffs + * within the text. + */ typedef QuickDiffProvider = { /** * Provide a {@link Uri} to the original resource of any given resource uri. * * @param uri The uri of the resource open in a text editor. * @param token A cancellation token. - * @return A thenable that resolves to uri of the matching original resource. + * @returns A thenable that resolves to uri of the matching original resource. */ @:optional function provideOriginalResource(uri:Uri, token:CancellationToken):ProviderResult; } diff --git a/src/vscode/QuickInputButton.hx b/src/vscode/QuickInputButton.hx index 46261e3c..b182f590 100644 --- a/src/vscode/QuickInputButton.hx +++ b/src/vscode/QuickInputButton.hx @@ -7,7 +7,7 @@ typedef QuickInputButton = { /** * Icon for the button. */ - var iconPath(default, null):EitherType>; + var iconPath(default, null):IconPath; /** * An optional tooltip. diff --git a/src/vscode/QuickPick.hx b/src/vscode/QuickPick.hx index 9c4bf96c..d6a3a331 100644 --- a/src/vscode/QuickPick.hx +++ b/src/vscode/QuickPick.hx @@ -17,7 +17,7 @@ typedef QuickPick = QuickInput & { var value:String; /** - * Optional placeholder in the filter text. + * Optional placeholder shown in the filter textbox when no filter has been entered. */ var ?placeholder:String; @@ -37,11 +37,17 @@ typedef QuickPick = QuickInput & { var buttons:ReadOnlyArray; /** - * An event signaling when a button in the title bar was triggered. + * An event signaling when a top level button (buttons stored in {@link buttons}) was triggered. * This event does not fire for buttons on a {@link QuickPickItem}. */ var onDidTriggerButton(default, null):Event; + /** + * An event signaling when a button in a particular {@link QuickPickItem} was triggered. + * This event does not fire for buttons in the title bar. + */ + var onDidTriggerItemButton(default, null):Event>; + /** * Items to pick from. This can be read and updated by the extension. */ @@ -62,6 +68,11 @@ typedef QuickPick = QuickInput & { */ var matchOnDetail:Bool; + /** + * An optional flag to maintain the scroll position of the quick pick when the quick pick items are updated. Defaults to false. + */ + var ?keepScrollPosition:Bool; + /** * Active items. This can be read and updated by the extension. */ diff --git a/src/vscode/QuickPickItem.hx b/src/vscode/QuickPickItem.hx index 341f84b4..41d64f64 100644 --- a/src/vscode/QuickPickItem.hx +++ b/src/vscode/QuickPickItem.hx @@ -11,28 +11,60 @@ typedef QuickPickItem = { */ var label:String; + /** + * The kind of QuickPickItem that will determine how this item is rendered in the quick pick. When not specified, + * the default is {@link QuickPickItemKind.Default}. + */ + var ?kind:QuickPickItemKind; + + /** + * The icon path or {@link ThemeIcon} for the QuickPickItem. + */ + var ?iconPath:IconPath; + /** * A human-readable string which is rendered less prominent in the same line. Supports rendering of * {@link ThemeIcon theme icons} via the `$()`-syntax. + * + * Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator} */ var ?description:String; /** * A human-readable string which is rendered less prominent in a separate line. Supports rendering of * {@link ThemeIcon theme icons} via the `$()`-syntax. + * + * Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator} */ var ?detail:String; /** - * Optional flag indicating if this item is picked initially. - * (Only honored when the picker allows multiple selections.) + * Optional flag indicating if this item is picked initially. This is only honored when using + * the {@link window.showQuickPick showQuickPick()} API. To do the same thing with + * the {@link window.createQuickPick createQuickPick()} API, simply set the {@link QuickPick.selectedItems} + * to the items you want picked initially. + * (*Note:* This is only honored when the picker allows multiple selections.) * * @see {@link QuickPickOptions.canPickMany} + * + * Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator} */ var ?picked:Bool; /** * Always show this item. + * + * Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator} */ var ?alwaysShow:Bool; + + /** + * Optional buttons that will be rendered on this particular item. These buttons will trigger + * an {@link QuickPickItemButtonEvent} when clicked. Buttons are only rendered when using a quickpick + * created by the {@link window.createQuickPick createQuickPick()} API. Buttons are not rendered when using + * the {@link window.showQuickPick showQuickPick()} API. + * + * Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator} + */ + var ?buttons:ReadOnlyArray; } diff --git a/src/vscode/QuickPickItemButtonEvent.hx b/src/vscode/QuickPickItemButtonEvent.hx new file mode 100644 index 00000000..18c8ee29 --- /dev/null +++ b/src/vscode/QuickPickItemButtonEvent.hx @@ -0,0 +1,17 @@ +package vscode; + +/** + * An event signaling when a button in a particular {@link QuickPickItem} was triggered. + * This event does not fire for buttons in the title bar. + */ +typedef QuickPickItemButtonEvent = { + /** + * The button that was clicked. + */ + var button(default, null):QuickInputButton; + + /** + * The item that the button belongs to. + */ + var item:T; +} diff --git a/src/vscode/QuickPickItemKind.hx b/src/vscode/QuickPickItemKind.hx new file mode 100644 index 00000000..297b0dad --- /dev/null +++ b/src/vscode/QuickPickItemKind.hx @@ -0,0 +1,18 @@ +package vscode; + +/** + * The kind of {@link QuickPickItem quick pick item}. + */ +@:jsRequire("vscode", "QuickPickItemKind") +extern enum abstract QuickPickItemKind(Int) { + /** + * When a {@link QuickPickItem} has a kind of {@link Separator}, the item is just a visual separator and does not represent a real item. + * The only property that applies is {@link QuickPickItem.label label }. All other properties on {@link QuickPickItem} will be ignored and have no effect. + */ + var Separator; + + /** + * The default {@link QuickPickItem.kind} is an item that can be selected in the quick pick. + */ + var Default; +} diff --git a/src/vscode/Range.hx b/src/vscode/Range.hx index d9867619..8955b195 100644 --- a/src/vscode/Range.hx +++ b/src/vscode/Range.hx @@ -54,7 +54,7 @@ extern class Range { * Check if a position or a range is contained in this range. * * @param positionOrRange A position or a range. - * @return `true` if the position or range is inside or equal + * @returns `true` if the position or range is inside or equal * to this range. */ function contains(positionOrRange:EitherType):Bool; @@ -63,7 +63,7 @@ extern class Range { * Check if `other` equals this range. * * @param other A range. - * @return `true` when start and end are {@link Position.isEqual equal} to + * @returns `true` when start and end are {@link Position.isEqual equal} to * start and end of this range. */ function isEqual(other:Range):Bool; @@ -73,7 +73,7 @@ extern class Range { * if the ranges have no overlap. * * @param range A range. - * @return A range of the greater start and smaller end positions. Will + * @returns A range of the greater start and smaller end positions. Will * return undefined when there is no overlap. */ function intersection(range:Range):Null; @@ -82,7 +82,7 @@ extern class Range { * Compute the union of `other` with this range. * * @param other A range. - * @return A range of smaller start position and the greater end position. + * @returns A range of smaller start position and the greater end position. */ function union(other:Range):Range; @@ -91,17 +91,26 @@ extern class Range { * * @param start A position that should be used as start. The default value is the {@link Range.start current start}. * @param end A position that should be used as end. The default value is the {@link Range.end current end}. - * @return A range derived from this range with the given start and end position. + * @returns A range derived from this range with the given start and end position. * If start and end are not different `this` range will be returned. */ - // TODO overload plox - // /** - // * Derived a new range from this range. - // * - // * @param change An object that describes a change to this range. - // * @return A range that reflects the given change. Will return `this` range if the change - // * is not changing anything. - // */ - @:overload(function(change:{?start:Position, ?end:Position}):Range {}) - function with(?start:Position, ?end:Position):Range; + overload function with(?start:Position, ?end:Position):Range; + + /** + * Derived a new range from this range. + * + * @param change An object that describes a change to this range. + * @returns A range that reflects the given change. Will return `this` range if the change + * is not changing anything. + */ + overload function with(change:{ + /** + * New start position, defaults to {@link Range.start current start} + */ + ?start:Position, + /** + * New end position, defaults to {@link Range.end current end} + */ + ?end:Position + }):Range; } diff --git a/src/vscode/ReferenceContext.hx b/src/vscode/ReferenceContext.hx index 83cc7b44..fb2ba4cf 100644 --- a/src/vscode/ReferenceContext.hx +++ b/src/vscode/ReferenceContext.hx @@ -8,5 +8,5 @@ typedef ReferenceContext = { /** * Include the declaration of the current symbol. */ - var includeDeclaration:Bool; + var includeDeclaration(default, null):Bool; } diff --git a/src/vscode/ReferenceProvider.hx b/src/vscode/ReferenceProvider.hx index b0bce417..494264f3 100644 --- a/src/vscode/ReferenceProvider.hx +++ b/src/vscode/ReferenceProvider.hx @@ -10,9 +10,10 @@ typedef ReferenceProvider = { * * @param document The document in which the command was invoked. * @param position The position at which the command was invoked. + * @param context Additional information about the references request. * @param token A cancellation token. * - * @return An array of locations or a thenable that resolves to such. The lack of a result can be + * @returns An array of locations or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined`, `null`, or an empty array. */ function provideReferences(document:TextDocument, position:Position, context:ReferenceContext, token:CancellationToken):ProviderResult>; diff --git a/src/vscode/RelativePattern.hx b/src/vscode/RelativePattern.hx index cb201775..e2256e35 100644 --- a/src/vscode/RelativePattern.hx +++ b/src/vscode/RelativePattern.hx @@ -8,8 +8,22 @@ package vscode; */ @:jsRequire("vscode", "RelativePattern") extern class RelativePattern { + /** + * A base file path to which this pattern will be matched against relatively. The + * file path must be absolute, should not have any trailing path separators and + * not include any relative segments (`.` or `..`). + */ + var baseUri:Uri; + /** * A base file path to which this pattern will be matched against relatively. + * + * This matches the `fsPath` value of {@link RelativePattern.baseUri}. + * + * *Note:* updating this value will update {@link RelativePattern.baseUri} to + * be a uri with `file` scheme. + * + * @deprecated This property is deprecated, please use {@link RelativePattern.baseUri} instead. */ var base:String; diff --git a/src/vscode/RenameProvider.hx b/src/vscode/RenameProvider.hx index 04d4dc25..79750890 100644 --- a/src/vscode/RenameProvider.hx +++ b/src/vscode/RenameProvider.hx @@ -13,7 +13,7 @@ typedef RenameProvider = { * @param position The position at which the command was invoked. * @param newName The new name of the symbol. If the given name is not valid, the provider must return a rejected promise. * @param token A cancellation token. - * @return A workspace edit or a thenable that resolves to such. The lack of a result can be + * @returns A workspace edit or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined` or `null`. */ function provideRenameEdits(document:TextDocument, position:Position, newName:String, token:CancellationToken):ProviderResult; @@ -23,15 +23,24 @@ typedef RenameProvider = { * be a range or a range and a placeholder text. The placeholder text should be the identifier of the symbol * which is being renamed - when omitted the text in the returned range is used. * - * *Note: * This function should throw an error or return a rejected thenable when the provided location + * *Note:* This function should throw an error or return a rejected thenable when the provided location * doesn't allow for a rename. * * @param document The document in which rename will be invoked. * @param position The position at which rename will be invoked. * @param token A cancellation token. - * @return The range or range and placeholder text of the identifier that is to be renamed. The lack of a result can signaled by returning `undefined` or `null`. + * @returns The range or range and placeholder text of the identifier that is to be renamed. The lack of a result can signaled by returning `undefined` or `null`. */ - var ?prepareRename:TextDocument->Position->CancellationToken->ProviderResult>; + var ?prepareRename:TextDocument->Position->CancellationToken->ProviderResult>; // TODO: use Haxe 4 function types whenever we drop Haxe 3.4 support for the externs (lets us have argument names) // function prepareRename?(document: TextDocument, position: Position, token: CancellationToken): ProviderResult; diff --git a/src/vscode/SaveDialogOptions.hx b/src/vscode/SaveDialogOptions.hx index 2da1ee95..4d6f9a54 100644 --- a/src/vscode/SaveDialogOptions.hx +++ b/src/vscode/SaveDialogOptions.hx @@ -16,10 +16,10 @@ typedef SaveDialogOptions = { /** * A set of file filters that are used by the dialog. Each entry is a human-readable label, - * like "TypeScript", and an array of extensions, e.g. + * like "TypeScript", and an array of extensions, for example: * ```ts * { - * 'Images': ['png', 'jpg'] + * 'Images': ['png', 'jpg'], * 'TypeScript': ['ts', 'tsx'] * } * ``` diff --git a/src/vscode/SecretStorage.hx b/src/vscode/SecretStorage.hx index c3bbcc72..c93e043b 100644 --- a/src/vscode/SecretStorage.hx +++ b/src/vscode/SecretStorage.hx @@ -1,8 +1,10 @@ package vscode; /** - * Represents a storage utility for secrets, information that is - * sensitive. + * Represents a storage utility for secrets (or any information that is sensitive) + * that will be stored encrypted. The implementation of the secret storage will + * be different on each platform and the secrets will not be synced across + * machines. */ typedef SecretStorage = { /** diff --git a/src/vscode/SelectedCompletionInfo.hx b/src/vscode/SelectedCompletionInfo.hx new file mode 100644 index 00000000..99df8770 --- /dev/null +++ b/src/vscode/SelectedCompletionInfo.hx @@ -0,0 +1,16 @@ +package vscode; + +/** + * Describes the currently selected completion item. + */ +typedef SelectedCompletionInfo = { + /** + * The range that will be replaced if this completion item is accepted. + */ + var range(default, null):Range; + + /** + * The text the range will be replaced with if this completion is accepted. + */ + var text(default, null):String; +} diff --git a/src/vscode/SelectionRangeProvider.hx b/src/vscode/SelectionRangeProvider.hx index a2a218c6..42e88ec8 100644 --- a/src/vscode/SelectionRangeProvider.hx +++ b/src/vscode/SelectionRangeProvider.hx @@ -1,5 +1,8 @@ package vscode; +/** + * The selection range provider interface defines the contract between extensions and the "Expand and Shrink Selection" feature. + */ typedef SelectionRangeProvider = { /** * Provide selection ranges for the given positions. @@ -11,8 +14,8 @@ typedef SelectionRangeProvider = { * @param document The document in which the command was invoked. * @param positions The positions at which the command was invoked. * @param token A cancellation token. - * @return Selection ranges or a thenable that resolves to such. The lack of a result can be + * @returns Selection ranges or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined` or `null`. */ - function provideSelectionRanges(document:TextDocument, positions:Array, token:CancellationToken):ProviderResult>; + function provideSelectionRanges(document:TextDocument, positions:ReadOnlyArray, token:CancellationToken):ProviderResult>; } diff --git a/src/vscode/SemanticTokens.hx b/src/vscode/SemanticTokens.hx index 3b32b659..b7e8569c 100644 --- a/src/vscode/SemanticTokens.hx +++ b/src/vscode/SemanticTokens.hx @@ -22,5 +22,11 @@ extern class SemanticTokens { */ var data(default, null):Uint32Array; + /** + * Create new semantic tokens. + * + * @param data Token data. + * @param resultId Result identifier. + */ function new(data:Uint32Array, ?resultId:String); } diff --git a/src/vscode/SemanticTokensBuilder.hx b/src/vscode/SemanticTokensBuilder.hx index a311465c..e718db7b 100644 --- a/src/vscode/SemanticTokensBuilder.hx +++ b/src/vscode/SemanticTokensBuilder.hx @@ -6,6 +6,11 @@ package vscode; */ @:jsRequire("vscode", "SemanticTokensBuilder") extern class SemanticTokensBuilder { + /** + * Creates a semantic tokens builder. + * + * @param legend A semantic tokens legend. + */ function new(?legend:SemanticTokensLegend); /** @@ -17,8 +22,16 @@ extern class SemanticTokensBuilder { * @param tokenType The encoded token type. * @param tokenModifiers The encoded token modifiers. */ - @:overload(function(range:Range, tokenType:String, ?tokenModifiers:Array):Void {}) - function push(line:Int, char:Int, length:Int, tokenType:Int, ?tokenModifiers:Int):Void; + overload function push(line:Int, char:Int, length:Int, tokenType:Int, ?tokenModifiers:Int):Void; + + /** + * Add another token. Use only when providing a legend. + * + * @param range The range of the token. Must be single-line. + * @param tokenType The token type. + * @param tokenModifiers The token modifiers. + */ + overload function push(range:Range, tokenType:String, ?tokenModifiers:ReadOnlyArray):Void; /** * Finish and create a `SemanticTokens` instance. diff --git a/src/vscode/SemanticTokensEdit.hx b/src/vscode/SemanticTokensEdit.hx index eb753901..595e4696 100644 --- a/src/vscode/SemanticTokensEdit.hx +++ b/src/vscode/SemanticTokensEdit.hx @@ -23,5 +23,12 @@ extern class SemanticTokensEdit { */ var data(default, null):Null; + /** + * Create a semantic token edit. + * + * @param start Start offset + * @param deleteCount Number of elements to remove. + * @param data Elements to insert + */ function new(start:Int, deleteCount:Int, ?data:Uint32Array); } diff --git a/src/vscode/SemanticTokensEdits.hx b/src/vscode/SemanticTokensEdits.hx index 557a7693..0311bbba 100644 --- a/src/vscode/SemanticTokensEdits.hx +++ b/src/vscode/SemanticTokensEdits.hx @@ -19,5 +19,11 @@ extern class SemanticTokensEdits { */ var edits(default, null):Array; + /** + * Create new semantic tokens edits. + * + * @param edits An array of semantic token edits + * @param resultId Result identifier. + */ function new(edits:Array, ?resultId:String); } diff --git a/src/vscode/SemanticTokensLegend.hx b/src/vscode/SemanticTokensLegend.hx index 4e523038..4fac9a6a 100644 --- a/src/vscode/SemanticTokensLegend.hx +++ b/src/vscode/SemanticTokensLegend.hx @@ -16,5 +16,11 @@ extern class SemanticTokensLegend { */ var tokenModifiers(default, null):Array; + /** + * Creates a semantic tokens legend. + * + * @param tokenTypes An array of token types. + * @param tokenModifiers An array of token modifiers. + */ function new(tokenTypes:Array, ?tokenModifiers:Array); } diff --git a/src/vscode/ShellExecution.hx b/src/vscode/ShellExecution.hx index b65ca7c4..535e2c6f 100644 --- a/src/vscode/ShellExecution.hx +++ b/src/vscode/ShellExecution.hx @@ -1,5 +1,8 @@ package vscode; +/** + * Represents a task execution that happens inside a shell. + */ @:jsRequire("vscode", "ShellExecution") extern class ShellExecution { /** @@ -29,12 +32,12 @@ extern class ShellExecution { /** * The shell command. Is `undefined` if created with a full command line. */ - var command:EitherType; + var command:Null>; /** * The shell args. Is `undefined` if created with a full command line. */ - var args:Array>; + var args:Null>>; /** * The shell options used when the command line is executed in a shell. diff --git a/src/vscode/SignatureHelpContext.hx b/src/vscode/SignatureHelpContext.hx index 38f3382f..2af4cb56 100644 --- a/src/vscode/SignatureHelpContext.hx +++ b/src/vscode/SignatureHelpContext.hx @@ -16,7 +16,7 @@ typedef SignatureHelpContext = { * This is `undefined` when signature help is not triggered by typing, such as when manually invoking * signature help or when moving the cursor. */ - var ?triggerCharacter(default, null):String; + var triggerCharacter(default, null):Null; /** * `true` if signature help was already showing when it was triggered. @@ -29,8 +29,8 @@ typedef SignatureHelpContext = { /** * The currently active {@linkcode SignatureHelp}. * - * The `activeSignatureHelp` has its [`SignatureHelp.activeSignature`] field updated based on + * The `activeSignatureHelp` has its {@linkcode SignatureHelp.activeSignature activeSignature} field updated based on * the user arrowing through available signatures. */ - var ?activeSignatureHelp(default, null):SignatureHelp; + var activeSignatureHelp(default, null):Null; } diff --git a/src/vscode/SignatureHelpProvider.hx b/src/vscode/SignatureHelpProvider.hx index 3e76d58c..d8451eb6 100644 --- a/src/vscode/SignatureHelpProvider.hx +++ b/src/vscode/SignatureHelpProvider.hx @@ -13,7 +13,7 @@ typedef SignatureHelpProvider = { * @param token A cancellation token. * @param context Information about how signature help was triggered. * - * @return Signature help or a thenable that resolves to such. The lack of a result can be + * @returns Signature help or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined` or `null`. */ function provideSignatureHelp(document:TextDocument, position:Position, token:CancellationToken, diff --git a/src/vscode/SignatureInformation.hx b/src/vscode/SignatureInformation.hx index 913e15a9..8c6c2209 100644 --- a/src/vscode/SignatureInformation.hx +++ b/src/vscode/SignatureInformation.hx @@ -27,7 +27,7 @@ extern class SignatureInformation { /** * The index of the active parameter. * - * If provided, this is used in place of {@linkcode SignatureHelp.activeSignature}. + * If provided, this is used in place of {@linkcode SignatureHelp.activeParameter}. */ var activeParameter:Null; diff --git a/src/vscode/SnippetString.hx b/src/vscode/SnippetString.hx index e022250d..213a2fe1 100644 --- a/src/vscode/SnippetString.hx +++ b/src/vscode/SnippetString.hx @@ -7,8 +7,8 @@ package vscode; * A snippet can define tab stops and placeholders with `$1`, `$2` * and `${3:foo}`. `$0` defines the final tab stop, it defaults to * the end of the snippet. Variables are defined with `$name` and - * `${name:default value}`. The full snippet syntax is documented - * [here](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_creating-your-own-snippets). + * `${name:default value}`. Also see + * [the full snippet syntax](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_create-your-own-snippets). */ @:jsRequire("vscode", "SnippetString") extern class SnippetString { @@ -17,6 +17,11 @@ extern class SnippetString { */ var value:String; + /** + * Create a new snippet string. + * + * @param value A snippet string. + */ function new(?value:String); /** @@ -24,7 +29,7 @@ extern class SnippetString { * the {@linkcode SnippetString.value value} of this snippet string. * * @param string A value to append 'as given'. The string will be escaped. - * @return This snippet string. + * @returns This snippet string. */ function appendText(string:String):SnippetString; @@ -34,7 +39,7 @@ extern class SnippetString { * * @param number The number of this tabstop, defaults to an auto-increment * value starting at 1. - * @return This snippet string. + * @returns This snippet string. */ function appendTabstop(?number:Int):SnippetString; @@ -46,7 +51,7 @@ extern class SnippetString { * with which a nested snippet can be created. * @param number The number of this tabstop, defaults to an auto-increment * value starting at 1. - * @return This snippet string. + * @returns This snippet string. */ function appendPlaceholder(value:EitherTypeAny>, ?number:Int):SnippetString; @@ -57,9 +62,9 @@ extern class SnippetString { * @param values The values for choices - the array of strings * @param number The number of this tabstop, defaults to an auto-increment * value starting at 1. - * @return This snippet string. + * @returns This snippet string. */ - function appendChoice(values:Array, ?number:Int):SnippetString; + function appendChoice(values:ReadOnlyArray, ?number:Int):SnippetString; /** * Builder-function that appends a variable (`${VAR}`) to @@ -68,7 +73,7 @@ extern class SnippetString { * @param name The name of the variable - excluding the `$`. * @param defaultValue The default value which is used when the variable name cannot * be resolved - either a string or a function with which a nested snippet can be created. - * @return This snippet string. + * @returns This snippet string. */ function appendVariable(name:String, defaultValue:EitherTypeAny>):SnippetString; } diff --git a/src/vscode/SnippetTextEdit.hx b/src/vscode/SnippetTextEdit.hx new file mode 100644 index 00000000..d4386edd --- /dev/null +++ b/src/vscode/SnippetTextEdit.hx @@ -0,0 +1,49 @@ +package vscode; + +/** + * A snippet edit represents an interactive edit that is performed by + * the editor. + * + * *Note* that a snippet edit can always be performed as a normal {@link TextEdit text edit}. + * This will happen when no matching editor is open or when a {@link WorkspaceEdit workspace edit} + * contains snippet edits for multiple files. In that case only those that match the active editor + * will be performed as snippet edits and the others as normal text edits. + */ +@:jsRequire("vscode", "SnippetTextEdit") +extern class SnippetTextEdit { + /** + * Utility to create a replace snippet edit. + * + * @param range A range. + * @param snippet A snippet string. + * @returns A new snippet edit object. + */ + static function replace(range:Range, snippet:SnippetString):SnippetTextEdit; + + /** + * Utility to create an insert snippet edit. + * + * @param position A position, will become an empty range. + * @param snippet A snippet string. + * @returns A new snippet edit object. + */ + static function insert(position:Position, snippet:SnippetString):SnippetTextEdit; + + /** + * The range this edit applies to. + */ + var range:Range; + + /** + * The {@link SnippetString snippet} this edit will perform. + */ + var snippet:SnippetString; + + /** + * Create a new snippet edit. + * + * @param range A range. + * @param snippet A snippet string. + */ + function new(range:Range, snippet:SnippetString); +} diff --git a/src/vscode/SourceControl.hx b/src/vscode/SourceControl.hx index ea8ccbc8..bf93a16a 100644 --- a/src/vscode/SourceControl.hx +++ b/src/vscode/SourceControl.hx @@ -29,8 +29,9 @@ typedef SourceControl = { * The UI-visible count of {@link SourceControlResourceState resource states} of * this source control. * - * Equals to the total number of {@link SourceControlResourceState resource state} - * of this source control, if undefined. + * If undefined, this source control will + * - display its UI-visible count as zero, and + * - contribute the count of its {@link SourceControlResourceState resource states} to the UI-visible aggregated count for all source controls */ var ?count:Int; diff --git a/src/vscode/SourceControlInputBox.hx b/src/vscode/SourceControlInputBox.hx index 0fb0cf21..27119ee1 100644 --- a/src/vscode/SourceControlInputBox.hx +++ b/src/vscode/SourceControlInputBox.hx @@ -14,6 +14,11 @@ typedef SourceControlInputBox = { */ var placeholder:String; + /** + * Controls whether the input box is enabled (default is `true`). + */ + var enabled:Bool; + /** * Controls whether the input box is visible (default is `true`). */ diff --git a/src/vscode/SourceControlResourceState.hx b/src/vscode/SourceControlResourceState.hx index 87c1f488..0c57eef9 100644 --- a/src/vscode/SourceControlResourceState.hx +++ b/src/vscode/SourceControlResourceState.hx @@ -26,17 +26,17 @@ typedef SourceControlResourceState = { * Context value of the resource state. This can be used to contribute resource specific actions. * For example, if a resource is given a context value as `diffable`. When contributing actions to `scm/resourceState/context` * using `menus` extension point, you can specify context value for key `scmResourceState` in `when` expressions, like `scmResourceState == diffable`. - * ``` - * "contributes": { - * "menus": { - * "scm/resourceState/context": [ - * { - * "command": "extension.diff", - * "when": "scmResourceState == diffable" - * } - * ] - * } - * } + * ```json + * "contributes": { + * "menus": { + * "scm/resourceState/context": [ + * { + * "command": "extension.diff", + * "when": "scmResourceState == diffable" + * } + * ] + * } + * } * ``` * This will show action `extension.diff` only for resources with `contextValue` is `diffable`. */ diff --git a/src/vscode/StatementCoverage.hx b/src/vscode/StatementCoverage.hx new file mode 100644 index 00000000..67c7912f --- /dev/null +++ b/src/vscode/StatementCoverage.hx @@ -0,0 +1,35 @@ +package vscode; + +/** + * Contains coverage information for a single statement or line. + */ +@:jsRequire("vscode", "StatementCoverage") +extern class StatementCoverage { + /** + * The number of times this statement was executed, or a boolean indicating + * whether it was executed if the exact count is unknown. If zero or false, + * the statement will be marked as un-covered. + */ + var executed:EitherType; + + /** + * Statement location. + */ + var location:EitherType; + + /** + * Coverage from branches of this line or statement. If it's not a + * conditional, this will be empty. + */ + var branches:Array; + + /** + * @param location The statement position. + * @param executed The number of times this statement was executed, or a + * boolean indicating whether it was executed if the exact count is + * unknown. If zero or false, the statement will be marked as un-covered. + * @param branches Coverage from branches of this line. If it's not a + * conditional, this should be omitted. + */ + function new(executed:EitherType, location:EitherType, ?branches:Array); +} diff --git a/src/vscode/StatusBarItem.hx b/src/vscode/StatusBarItem.hx index b6e420a0..5f808936 100644 --- a/src/vscode/StatusBarItem.hx +++ b/src/vscode/StatusBarItem.hx @@ -22,7 +22,7 @@ typedef StatusBarItem = { * The priority of this item. Higher value means the item should * be shown more to the left. */ - var ?priority(default, null):Float; + var priority(default, null):Null; /** * The name of the entry, like 'Python Language Indicator', 'Git Status' etc. @@ -78,7 +78,7 @@ typedef StatusBarItem = { /** * Accessibility information used when a screen reader interacts with this StatusBar item */ - var ?accessibilityInformation:AccessibilityInformation; + var accessibilityInformation:Null; /** * Shows the entry in the status bar. diff --git a/src/vscode/SymbolKind.hx b/src/vscode/SymbolKind.hx index fdb8da8c..469918ea 100644 --- a/src/vscode/SymbolKind.hx +++ b/src/vscode/SymbolKind.hx @@ -5,30 +5,133 @@ package vscode; */ @:jsRequire("vscode", "SymbolKind") extern enum abstract SymbolKind(Int) { + /** + * The `File` symbol kind. + */ var File; + + /** + * The `Module` symbol kind. + */ var Module; + + /** + * The `Namespace` symbol kind. + */ var Namespace; + + /** + * The `Package` symbol kind. + */ var Package; + + /** + * The `Class` symbol kind. + */ var Class; + + /** + * The `Method` symbol kind. + */ var Method; + + /** + * The `Property` symbol kind. + */ var Property; + + /** + * The `Field` symbol kind. + */ var Field; + + /** + * The `Constructor` symbol kind. + */ var Constructor; + + /** + * The `Enum` symbol kind. + */ var Enum; + + /** + * The `Interface` symbol kind. + */ var Interface; + + /** + * The `Function` symbol kind. + */ var Function; + + /** + * The `Variable` symbol kind. + */ var Variable; + + /** + * The `Constant` symbol kind. + */ var Constant; + + /** + * The `String` symbol kind. + */ var String; + + /** + * The `Number` symbol kind. + */ var Number; + + /** + * The `Boolean` symbol kind. + */ var Boolean; + + /** + * The `Array` symbol kind. + */ var Array; + + /** + * The `Object` symbol kind. + */ var Object; + + /** + * The `Key` symbol kind. + */ var Key; + + /** + * The `Null` symbol kind. + */ var Null; + + /** + * The `EnumMember` symbol kind. + */ var EnumMember; + + /** + * The `Struct` symbol kind. + */ var Struct; + + /** + * The `Event` symbol kind. + */ var Event; + + /** + * The `Operator` symbol kind. + */ var Operator; + + /** + * The `TypeParameter` symbol kind. + */ var TypeParameter; } diff --git a/src/vscode/SyntaxTokenType.hx b/src/vscode/SyntaxTokenType.hx new file mode 100644 index 00000000..f13bae4a --- /dev/null +++ b/src/vscode/SyntaxTokenType.hx @@ -0,0 +1,27 @@ +package vscode; + +/** + * Enumeration of commonly encountered syntax token types. + */ +@:jsRequire("vscode", "SyntaxTokenType") +extern enum abstract SyntaxTokenType(Int) { + /** + * Everything except tokens that are part of comments, string literals and regular expressions. + */ + var Other; + + /** + * A comment. + */ + var Comment; + + /** + * A string literal. + */ + @:native("String") var StringLiteral; + + /** + * A regular expression. + */ + @:native("RegEx") var RegExLiteral; +} diff --git a/src/vscode/Tab.hx b/src/vscode/Tab.hx new file mode 100644 index 00000000..d3e07d6c --- /dev/null +++ b/src/vscode/Tab.hx @@ -0,0 +1,48 @@ +package vscode; + +/** + * Represents a tab within a {@link TabGroup group of tabs}. + * Tabs are merely the graphical representation within the editor area. + * A backing editor is not a guarantee. + */ +typedef Tab = { + /** + * The text displayed on the tab. + */ + var label(default, null):String; + + /** + * The group which the tab belongs to. + */ + var group(default, null):TabGroup; + + /** + * Defines the structure of the tab i.e. text, notebook, custom, etc. + * Resource and other useful properties are defined on the tab kind. + */ + var input(default, + null):Null>>>>>>; + + /** + * Whether or not the tab is currently active. + * This is dictated by being the selected tab in the group. + */ + var isActive(default, null):Bool; + + /** + * Whether or not the dirty indicator is present on the tab. + */ + var isDirty(default, null):Bool; + + /** + * Whether or not the tab is pinned (pin icon is present). + */ + var isPinned(default, null):Bool; + + /** + * Whether or not the tab is in preview mode. + */ + var isPreview(default, null):Bool; +} diff --git a/src/vscode/TabChangeEvent.hx b/src/vscode/TabChangeEvent.hx new file mode 100644 index 00000000..9ab4c925 --- /dev/null +++ b/src/vscode/TabChangeEvent.hx @@ -0,0 +1,22 @@ +package vscode; + +/** + * An event describing change to tabs. + */ +typedef TabChangeEvent = { + /** + * The tabs that have been opened. + */ + var opened(default, null):ReadOnlyArray; + + /** + * The tabs that have been closed. + */ + var closed(default, null):ReadOnlyArray; + + /** + * Tabs that have changed, e.g have changed + * their {@link Tab.isActive active} state. + */ + var changed(default, null):ReadOnlyArray; +} diff --git a/src/vscode/TabGroup.hx b/src/vscode/TabGroup.hx new file mode 100644 index 00000000..f0bd0fd8 --- /dev/null +++ b/src/vscode/TabGroup.hx @@ -0,0 +1,35 @@ +package vscode; + +/** + * Represents a group of tabs. A tab group itself consists of multiple tabs. + */ +typedef TabGroup = { + /** + * Whether or not the group is currently active. + * + * *Note* that only one tab group is active at a time, but that multiple tab + * groups can have an {@link activeTab active tab}. + * + * @see {@link Tab.isActive} + */ + var isActive(default, null):Bool; + + /** + * The view column of the group. + */ + var viewColumn(default, null):ViewColumn; + + /** + * The active {@link Tab tab} in the group. This is the tab whose contents are currently + * being rendered. + * + * *Note* that there can be one active tab per group but there can only be one {@link TabGroups.activeTabGroup active group}. + */ + var activeTab(default, null):Null; + + /** + * The list of tabs contained within the group. + * This can be empty if the group has no tabs open. + */ + var tabs(default, null):ReadOnlyArray; +} diff --git a/src/vscode/TabGroupChangeEvent.hx b/src/vscode/TabGroupChangeEvent.hx new file mode 100644 index 00000000..7d542829 --- /dev/null +++ b/src/vscode/TabGroupChangeEvent.hx @@ -0,0 +1,22 @@ +package vscode; + +/** + * An event describing changes to tab groups. + */ +typedef TabGroupChangeEvent = { + /** + * Tab groups that have been opened. + */ + var opened(default, null):ReadOnlyArray; + + /** + * Tab groups that have been closed. + */ + var closed(default, null):ReadOnlyArray; + + /** + * Tab groups that have changed, e.g have changed + * their {@link TabGroup.isActive active} state. + */ + var changed(default, null):ReadOnlyArray; +} diff --git a/src/vscode/TabGroups.hx b/src/vscode/TabGroups.hx new file mode 100644 index 00000000..b66ab460 --- /dev/null +++ b/src/vscode/TabGroups.hx @@ -0,0 +1,47 @@ +package vscode; + +/** + * Represents the main editor area which consists of multiple groups which contain tabs. + */ +@:jsRequire("vscode", "TabGroups") +extern class TabGroups { + /** + * All the groups within the group container. + */ + var all(default, null):ReadOnlyArray; + + /** + * The currently active group. + */ + var activeTabGroup(default, null):TabGroup; + + /** + * An {@link Event event} which fires when {@link TabGroup tab groups} have changed. + */ + var onDidChangeTabGroups(default, null):Event; + + /** + * An {@link Event event} which fires when {@link Tab tabs} have changed. + */ + var onDidChangeTabs(default, null):Event; + + /** + * Closes the tab. This makes the tab object invalid and the tab + * should no longer be used for further actions. + * Note: In the case of a dirty tab, a confirmation dialog will be shown which may be cancelled. If cancelled the tab is still valid + * + * @param tab The tab to close. + * @param preserveFocus When `true` focus will remain in its current position. If `false` it will jump to the next tab. + * @returns A promise that resolves to `true` when all tabs have been closed. + */ + overload function close(tab:EitherType>, ?preserveFocus:Bool):Thenable; + + /** + * Closes the tab group. This makes the tab group object invalid and the tab group + * should no longer be used for further actions. + * @param tabGroup The tab group to close. + * @param preserveFocus When `true` focus will remain in its current position. + * @returns A promise that resolves to `true` when all tab groups have been closed. + */ + overload function close(tabGroup:EitherType>, ?preserveFocus:Bool):Thenable; +} diff --git a/src/vscode/TabInputCustom.hx b/src/vscode/TabInputCustom.hx new file mode 100644 index 00000000..47147e0f --- /dev/null +++ b/src/vscode/TabInputCustom.hx @@ -0,0 +1,24 @@ +package vscode; + +/** + * The tab represents a custom editor. + */ +@:jsRequire("vscode", "TabInputCustom") +extern class TabInputCustom { + /** + * The uri that the tab is representing. + */ + var uri(default, null):Uri; + + /** + * The type of custom editor. + */ + var viewType(default, null):String; + + /** + * Constructs a custom editor tab input. + * @param uri The uri of the tab. + * @param viewType The viewtype of the custom editor. + */ + function new(uri:Uri, viewType:String); +} diff --git a/src/vscode/TabInputNotebook.hx b/src/vscode/TabInputNotebook.hx new file mode 100644 index 00000000..8311a54b --- /dev/null +++ b/src/vscode/TabInputNotebook.hx @@ -0,0 +1,24 @@ +package vscode; + +/** + * The tab represents a notebook. + */ +@:jsRequire("vscode", "TabInputNotebook") +extern class TabInputNotebook { + /** + * The uri that the tab is representing. + */ + var uri(default, null):Uri; + + /** + * The type of notebook. Maps to {@linkcode NotebookDocument.notebookType NotebookDocuments's notebookType} + */ + var notebookType(default, null):String; + + /** + * Constructs a new tab input for a notebook. + * @param uri The uri of the notebook. + * @param notebookType The type of notebook. Maps to {@linkcode NotebookDocument.notebookType NotebookDocuments's notebookType} + */ + function new(uri:Uri, notebookType:String); +} diff --git a/src/vscode/TabInputNotebookDiff.hx b/src/vscode/TabInputNotebookDiff.hx new file mode 100644 index 00000000..4d6f5df2 --- /dev/null +++ b/src/vscode/TabInputNotebookDiff.hx @@ -0,0 +1,30 @@ +package vscode; + +/** + * The tabs represents two notebooks in a diff configuration. + */ +@:jsRequire("vscode", "TabInputNotebookDiff") +extern class TabInputNotebookDiff { + /** + * The uri of the original notebook. + */ + var original(default, null):Uri; + + /** + * The uri of the modified notebook. + */ + var modified(default, null):Uri; + + /** + * The type of notebook. Maps to {@linkcode NotebookDocument.notebookType NotebookDocuments's notebookType} + */ + var notebookType(default, null):String; + + /** + * Constructs a notebook diff tab input. + * @param original The uri of the original unmodified notebook. + * @param modified The uri of the modified notebook. + * @param notebookType The type of notebook. Maps to {@linkcode NotebookDocument.notebookType NotebookDocuments's notebookType} + */ + function new(original:Uri, modified:Uri, notebookType:String); +} diff --git a/src/vscode/TabInputTerminal.hx b/src/vscode/TabInputTerminal.hx new file mode 100644 index 00000000..b59166a4 --- /dev/null +++ b/src/vscode/TabInputTerminal.hx @@ -0,0 +1,12 @@ +package vscode; + +/** + * The tab represents a terminal in the editor area. + */ +@:jsRequire("vscode", "TabInputTerminal") +extern class TabInputTerminal { + /** + * Constructs a terminal tab input. + */ + function new(); +} diff --git a/src/vscode/TabInputText.hx b/src/vscode/TabInputText.hx new file mode 100644 index 00000000..a55abdaf --- /dev/null +++ b/src/vscode/TabInputText.hx @@ -0,0 +1,18 @@ +package vscode; + +/** + * The tab represents a single text based resource. + */ +@:jsRequire("vscode", "TabInputText") +extern class TabInputText { + /** + * The uri represented by the tab. + */ + var uri(default, null):Uri; + + /** + * Constructs a text tab input with the given URI. + * @param uri The URI of the tab. + */ + function new(uri:Uri); +} diff --git a/src/vscode/TabInputTextDiff.hx b/src/vscode/TabInputTextDiff.hx new file mode 100644 index 00000000..2c17c112 --- /dev/null +++ b/src/vscode/TabInputTextDiff.hx @@ -0,0 +1,25 @@ +package vscode; + +/** + * The tab represents two text based resources + * being rendered as a diff. + */ +@:jsRequire("vscode", "TabInputTextDiff") +extern class TabInputTextDiff { + /** + * The uri of the original text resource. + */ + var original(default, null):Uri; + + /** + * The uri of the modified text resource. + */ + var modified(default, null):Uri; + + /** + * Constructs a new text diff tab input with the given URIs. + * @param original The uri of the original text resource. + * @param modified The uri of the modified text resource. + */ + function new(original:Uri, modified:Uri); +} diff --git a/src/vscode/TabInputWebview.hx b/src/vscode/TabInputWebview.hx new file mode 100644 index 00000000..b924799c --- /dev/null +++ b/src/vscode/TabInputWebview.hx @@ -0,0 +1,18 @@ +package vscode; + +/** + * The tab represents a webview. + */ +@:jsRequire("vscode", "TabInputWebview") +extern class TabInputWebview { + /** + * The type of webview. Maps to {@linkcode WebviewPanel.viewType WebviewPanel's viewType} + */ + var viewType(default, null):String; + + /** + * Constructs a webview tab input with the given view type. + * @param viewType The type of webview. Maps to {@linkcode WebviewPanel.viewType WebviewPanel's viewType} + */ + function new(viewType:String); +} diff --git a/src/vscode/Task.hx b/src/vscode/Task.hx index 6785151e..51c08500 100644 --- a/src/vscode/Task.hx +++ b/src/vscode/Task.hx @@ -8,7 +8,7 @@ extern class Task { /** * Creates a new task. * - * @param definition The task definition as defined in the taskDefinitions extension point. + * @param taskDefinition The task definition as defined in the taskDefinitions extension point. * @param scope Specifies the task's scope. It is either a global or a workspace task or a task for a specific workspace folder. Global tasks are currently not supported. * @param name The task's name. Is presented in the user interface. * @param source The task's source (e.g. 'gulp', 'npm', ...). Is presented in the user interface. @@ -17,6 +17,20 @@ extern class Task { * or '$eslint'. Problem matchers can be contributed by an extension using * the `problemMatchers` extension point. */ + // TODO overload plox + // /** + // * Creates a new task. + // * + // * @deprecated Use the new constructors that allow specifying a scope for the task. + // * + // * @param taskDefinition The task definition as defined in the taskDefinitions extension point. + // * @param name The task's name. Is presented in the user interface. + // * @param source The task's source (e.g. 'gulp', 'npm', ...). Is presented in the user interface. + // * @param execution The process or shell execution. + // * @param problemMatchers the names of problem matchers to use, like '$tsc' + // * or '$eslint'. Problem matchers can be contributed by an extension using + // * the `problemMatchers` extension point. + // */ @:overload(function(taskDefinition:TaskDefinition, name:String, source:String, ?execution:EitherType, ?problemMatchers:EitherType>):Void {}) // deprecated function new(taskDefinition:TaskDefinition, target:EitherType, name:String, source:String, diff --git a/src/vscode/TaskFilter.hx b/src/vscode/TaskFilter.hx index c4b500e4..d57bf01b 100644 --- a/src/vscode/TaskFilter.hx +++ b/src/vscode/TaskFilter.hx @@ -1,5 +1,8 @@ package vscode; +/** + * A task filter denotes tasks by their version and types + */ typedef TaskFilter = { /** * The task version as used in the tasks.json file. diff --git a/src/vscode/TaskGroup.hx b/src/vscode/TaskGroup.hx index 087250e3..16d9fb4c 100644 --- a/src/vscode/TaskGroup.hx +++ b/src/vscode/TaskGroup.hx @@ -37,5 +37,11 @@ extern class TaskGroup { */ var id(default, null):String; + /** + * Private constructor + * + * @param id Identifier of a task group. + * @param label The human-readable name of a task group. + */ private function new(id:String, label:String); } diff --git a/src/vscode/TaskPresentationOptions.hx b/src/vscode/TaskPresentationOptions.hx index 6aa93537..21e38628 100644 --- a/src/vscode/TaskPresentationOptions.hx +++ b/src/vscode/TaskPresentationOptions.hx @@ -37,4 +37,9 @@ typedef TaskPresentationOptions = { * Controls whether the terminal is cleared before executing the task. */ var ?clear:Bool; + + /** + * Controls whether the terminal is closed after executing the task. + */ + var ?close:Bool; } diff --git a/src/vscode/TaskProvider.hx b/src/vscode/TaskProvider.hx index 9ddfa51a..932dcdbf 100644 --- a/src/vscode/TaskProvider.hx +++ b/src/vscode/TaskProvider.hx @@ -8,7 +8,7 @@ typedef TaskProvider = { /** * Provides tasks. * @param token A cancellation token. - * @return an array of tasks + * @returns an array of tasks */ function provideTasks(token:CancellationToken):ProviderResult>; @@ -27,7 +27,7 @@ typedef TaskProvider = { * * @param task The task to resolve. * @param token A cancellation token. - * @return The resolved task + * @returns The resolved task */ function resolveTask(task:T, token:CancellationToken):ProviderResult; } diff --git a/src/vscode/TelemetryLogger.hx b/src/vscode/TelemetryLogger.hx new file mode 100644 index 00000000..21145511 --- /dev/null +++ b/src/vscode/TelemetryLogger.hx @@ -0,0 +1,70 @@ +package vscode; + +import Vscode.Record; + +/** + * A telemetry logger which can be used by extensions to log usage and error telementry. + * + * A logger wraps around an {@link TelemetrySender sender} but it guarantees that + * - user settings to disable or tweak telemetry are respected, and that + * - potential sensitive data is removed + * + * It also enables an "echo UI" that prints whatever data is send and it allows the editor + * to forward unhandled errors to the respective extensions. + * + * To get an instance of a `TelemetryLogger`, use + * {@link env.createTelemetryLogger `createTelemetryLogger`}. + */ +@:jsRequire("vscode", "TelemetryLogger") +extern class TelemetryLogger { + /** + * An {@link Event} which fires when the enablement state of usage or error telemetry changes. + */ + var onDidChangeEnableStates(default, null):Event; + + /** + * Whether or not usage telemetry is enabled for this logger. + */ + var isUsageEnabled(default, null):Bool; + + /** + * Whether or not error telemetry is enabled for this logger. + */ + var isErrorsEnabled(default, null):Bool; + + /** + * Log a usage event. + * + * After completing cleaning, telemetry setting checks, and data mix-in calls `TelemetrySender.sendEventData` to log the event. + * Automatically supports echoing to extension telemetry output channel. + * @param eventName The event name to log + * @param data The data to log + */ + function logUsage(eventName:String, ?data:Record>>):Void; + + /** + * Log an error event. + * + * After completing cleaning, telemetry setting checks, and data mix-in calls `TelemetrySender.sendEventData` to log the event. Differs from `logUsage` in that it will log the event if the telemetry setting is Error+. + * Automatically supports echoing to extension telemetry output channel. + * @param eventName The event name to log + * @param data The data to log + */ + overload function logError(eventName:String, ?data:Record>>):Void; + + /** + * Log an error event. + * + * Calls `TelemetrySender.sendErrorData`. Does cleaning, telemetry checks, and data mix-in. + * Automatically supports echoing to extension telemetry output channel. + * Will also automatically log any exceptions thrown within the extension host process. + * @param error The error object which contains the stack trace cleaned of PII + * @param data Additional data to log alongside the stack trace + */ + overload function logError(error:Error, ?data:Record>>):Void; + + /** + * Dispose this object and free resources. + */ + function dispose():Void; +} diff --git a/src/vscode/TelemetryLoggerOptions.hx b/src/vscode/TelemetryLoggerOptions.hx new file mode 100644 index 00000000..8c7a07fe --- /dev/null +++ b/src/vscode/TelemetryLoggerOptions.hx @@ -0,0 +1,25 @@ +package vscode; + +import Vscode.Record; + +/** + * Options for creating a {@link TelemetryLogger} + */ +typedef TelemetryLoggerOptions = { + /** + * Whether or not you want to avoid having the built-in common properties such as os, extension name, etc injected into the data object. + * Defaults to `false` if not defined. + */ + var ?ignoreBuiltInCommonProperties(default, null):Bool; + + /** + * Whether or not unhandled errors on the extension host caused by your extension should be logged to your sender. + * Defaults to `false` if not defined. + */ + var ?ignoreUnhandledErrors(default, null):Bool; + + /** + * Any additional common properties which should be injected into the data object. + */ + var ?additionalCommonProperties(default, null):Record; +} diff --git a/src/vscode/TelemetrySender.hx b/src/vscode/TelemetrySender.hx new file mode 100644 index 00000000..32737f2f --- /dev/null +++ b/src/vscode/TelemetrySender.hx @@ -0,0 +1,42 @@ +package vscode; + +import Vscode.Record; + +/** + * The telemetry sender is the contract between a telemetry logger and some telemetry service. **Note** that extensions must NOT + * call the methods of their sender directly as the logger provides extra guards and cleaning. + * + * ```js + * const sender: vscode.TelemetrySender = {...}; + * const logger = vscode.env.createTelemetryLogger(sender); + * + * // GOOD - uses the logger + * logger.logUsage('myEvent', { myData: 'myValue' }); + * + * // BAD - uses the sender directly: no data cleansing, ignores user settings, no echoing to the telemetry output channel etc + * sender.logEvent('myEvent', { myData: 'myValue' }); + * ``` + */ +typedef TelemetrySender = { + /** + * Function to send event data without a stacktrace. Used within a {@link TelemetryLogger} + * + * @param eventName The name of the event which you are logging + * @param data A serializable key value pair that is being logged + */ + function sendEventData(eventName:String, ?data:Record):Void; + + /** + * Function to send an error. Used within a {@link TelemetryLogger} + * + * @param error The error being logged + * @param data Any additional data to be collected with the exception + */ + function sendErrorData(error:Error, ?data:Record):Void; + + /** + * Optional flush function which will give this sender a chance to send any remaining events + * as its {@link TelemetryLogger} is being disposed + */ + function flush():Thenable; +} diff --git a/src/vscode/TelemetryTrustedValue.hx b/src/vscode/TelemetryTrustedValue.hx new file mode 100644 index 00000000..824054cb --- /dev/null +++ b/src/vscode/TelemetryTrustedValue.hx @@ -0,0 +1,20 @@ +package vscode; + +/** + * A special value wrapper denoting a value that is safe to not clean. + * This is to be used when you can guarantee no identifiable information is contained in the value and the cleaning is improperly redacting it. + */ +@:jsRequire("vscode", "TelemetryTrustedValue") +extern class TelemetryTrustedValue { + /** + * The value that is trusted to not contain PII. + */ + var value(default, null):T; + + /** + * Creates a new telementry trusted value. + * + * @param value A value to trust + */ + function new(value:T); +} diff --git a/src/vscode/Terminal.hx b/src/vscode/Terminal.hx index c370b4cf..7bdb1778 100644 --- a/src/vscode/Terminal.hx +++ b/src/vscode/Terminal.hx @@ -36,16 +36,32 @@ typedef Terminal = { */ var ?exitStatus(default, null):TerminalExitStatus; + /** + * The current state of the {@link Terminal}. + */ + var state(default, null):TerminalState; + + /** + * An object that contains [shell integration](https://code.visualstudio.com/docs/terminal/shell-integration)-powered + * features for the terminal. This will always be `undefined` immediately after the terminal + * is created. Listen to {@link window.onDidChangeTerminalShellIntegration} to be notified + * when shell integration is activated for a terminal. + * + * Note that this object may remain undefined if shell integration never activates. For + * example Command Prompt does not support shell integration and a user's shell setup could + * conflict with the automatic shell integration activation. + */ + var shellIntegration(default, null):Null; + /** * Send text to the terminal. The text is written to the stdin of the underlying pty process * (shell) of the terminal. * * @param text The text to send. - * @param addNewLine Whether to add a new line to the text being sent, this is normally - * required to run a command in the terminal. The character(s) added are \n or \r\n - * depending on the platform. This defaults to `true`. + * @param shouldExecute Indicates that the text being sent should be executed rather than just inserted in the terminal. + * The character(s) added are `\n` or `\r\n`, depending on the platform. This defaults to `true`. */ - function sendText(text:String, ?addNewLine:Bool):Void; + function sendText(text:String, ?shouldExecute:Bool):Void; /** * Show the terminal panel and reveal this terminal in the UI. diff --git a/src/vscode/TerminalEditorLocationOptions.hx b/src/vscode/TerminalEditorLocationOptions.hx new file mode 100644 index 00000000..dc932c70 --- /dev/null +++ b/src/vscode/TerminalEditorLocationOptions.hx @@ -0,0 +1,21 @@ +package vscode; + +/** + * Assumes a {@link TerminalLocation} of editor and allows specifying a {@link ViewColumn} and + * {@link TerminalEditorLocationOptions.preserveFocus preserveFocus } property + */ +typedef TerminalEditorLocationOptions = { + /** + * A view column in which the {@link Terminal terminal} should be shown in the editor area. + * The default is the {@link ViewColumn.Active active}. Columns that do not exist + * will be created as needed up to the maximum of {@linkcode ViewColumn.Nine}. + * Use {@linkcode ViewColumn.Beside} to open the editor to the side of the currently + * active one. + */ + var viewColumn:ViewColumn; + + /** + * An optional flag that when `true` will stop the {@link Terminal} from taking focus. + */ + var ?preserveFocus:Bool; +} diff --git a/src/vscode/TerminalExitReason.hx b/src/vscode/TerminalExitReason.hx new file mode 100644 index 00000000..f839db39 --- /dev/null +++ b/src/vscode/TerminalExitReason.hx @@ -0,0 +1,32 @@ +package vscode; + +/** + * Terminal exit reason kind. + */ +@:jsRequire("vscode", "TerminalExitReason") +extern enum abstract TerminalExitReason(Int) { + /** + * Unknown reason. + */ + var Unknown; + + /** + * The window closed/reloaded. + */ + var Shutdown; + + /** + * The shell process exited. + */ + var Process; + + /** + * The user closed the terminal. + */ + var User; + + /** + * An extension disposed the terminal. + */ + var Extension; +} diff --git a/src/vscode/TerminalExitStatus.hx b/src/vscode/TerminalExitStatus.hx index 0351d1d4..59d6977a 100644 --- a/src/vscode/TerminalExitStatus.hx +++ b/src/vscode/TerminalExitStatus.hx @@ -11,5 +11,10 @@ typedef TerminalExitStatus = { * - `undefined`: the user forcibly closed the terminal or a custom execution exited * without providing an exit code. */ - var ?code(default, null):Int; + var code(default, null):Null; + + /** + * The reason that triggered the exit of a terminal. + */ + var reason(default, null):TerminalExitReason; } diff --git a/src/vscode/TerminalLinkProvider.hx b/src/vscode/TerminalLinkProvider.hx index e70491be..d3b884db 100644 --- a/src/vscode/TerminalLinkProvider.hx +++ b/src/vscode/TerminalLinkProvider.hx @@ -10,7 +10,7 @@ typedef TerminalLinkProvider = { * that could have problems when asynchronous usage may overlap. * @param context Information about what links are being provided for. * @param token A cancellation token. - * @return A list of terminal links for the given line. + * @returns A list of terminal links for the given line. */ function provideTerminalLinks(context:TerminalLinkContext, token:CancellationToken):ProviderResult>; diff --git a/src/vscode/TerminalLocation.hx b/src/vscode/TerminalLocation.hx new file mode 100644 index 00000000..a37d703a --- /dev/null +++ b/src/vscode/TerminalLocation.hx @@ -0,0 +1,17 @@ +package vscode; + +/** + * The location of the terminal. + */ +@:jsRequire("vscode", "TerminalLocation") +extern enum abstract TerminalLocation(Int) { + /** + * In the terminal view + */ + var Panel; + + /** + * In the editor area + */ + var Editor; +} diff --git a/src/vscode/TerminalOptions.hx b/src/vscode/TerminalOptions.hx index 6f48aa0f..030201d1 100644 --- a/src/vscode/TerminalOptions.hx +++ b/src/vscode/TerminalOptions.hx @@ -34,7 +34,7 @@ typedef TerminalOptions = { * Whether the terminal process environment should be exactly as provided in * `TerminalOptions.env`. When this is false (default), the environment will be based on the * window's environment and also apply configured platform settings like - * `terminal.integrated.windows.env` on top. When this is true, the complete environment + * `terminal.integrated.env.windows` on top. When this is true, the complete environment * must be provided as nothing will be inherited from the process or any configuration. */ var ?strictEnv:Bool; @@ -44,7 +44,7 @@ typedef TerminalOptions = { * until `Terminal.show` is called. The typical usage for this is when you need to run * something that may need interactivity but only want to tell the user about it when * interaction is needed. Note that the terminals will still be exposed to all extensions - * as normal. + * as normal. The hidden terminals will not be restored when the workspace is next opened. */ var ?hideFromUser:Bool; @@ -58,7 +58,7 @@ typedef TerminalOptions = { /** * The icon path or {@link ThemeIcon} for the terminal. */ - var ?iconPath:EitherType>; + var ?iconPath:IconPath; /** * The icon {@link ThemeColor} for the terminal. @@ -66,4 +66,15 @@ typedef TerminalOptions = { * recommended for the best contrast and consistency across themes. */ var ?color:ThemeColor; + + /** + * The {@link TerminalLocation} or {@link TerminalEditorLocationOptions} or {@link TerminalSplitLocationOptions} for the terminal. + */ + var ?location:EitherType>; + + /** + * Opt-out of the default terminal persistence on restart and reload. + * This will only take effect when `terminal.integrated.enablePersistentSessions` is enabled. + */ + var ?isTransient:Bool; } diff --git a/src/vscode/TerminalShellExecution.hx b/src/vscode/TerminalShellExecution.hx new file mode 100644 index 00000000..e964e07f --- /dev/null +++ b/src/vscode/TerminalShellExecution.hx @@ -0,0 +1,58 @@ +package vscode; + +/** + * A command that was executed in a terminal. + */ +typedef TerminalShellExecution = { + /** + * The command line that was executed. The {@link TerminalShellExecutionCommandLineConfidence confidence} + * of this value depends on the specific shell's shell integration implementation. This + * value may become more accurate after {@link window.onDidEndTerminalShellExecution} is + * fired. + * + * @example + * // Log the details of the command line on start and end + * window.onDidStartTerminalShellExecution(event => { + * const commandLine = event.execution.commandLine; + * console.log(`Command started\n${summarizeCommandLine(commandLine)}`); + * }); + * window.onDidEndTerminalShellExecution(event => { + * const commandLine = event.execution.commandLine; + * console.log(`Command ended\n${summarizeCommandLine(commandLine)}`); + * }); + * function summarizeCommandLine(commandLine: TerminalShellExecutionCommandLine) { + * return [ + * ` Command line: ${command.commandLine.value}`, + * ` Confidence: ${command.commandLine.confidence}`, + * ` Trusted: ${command.commandLine.isTrusted} + * ].join('\n'); + * } + */ + var commandLine(default, null):TerminalShellExecutionCommandLine; + + /** + * The working directory that was reported by the shell when this command executed. This + * {@link Uri} may represent a file on another machine (eg. ssh into another machine). This + * requires the shell integration to support working directory reporting. + */ + var cwd(default, null):Null; + + /** + * Creates a stream of raw data (including escape sequences) that is written to the + * terminal. This will only include data that was written after `read` was called for + * the first time, ie. you must call `read` immediately after the command is executed via + * {@link TerminalShellIntegration.executeCommand} or + * {@link window.onDidStartTerminalShellExecution} to not miss any data. + * + * @example + * // Log all data written to the terminal for a command + * const command = term.shellIntegration.executeCommand({ commandLine: 'echo "Hello world"' }); + * const stream = command.read(); + * for await (const data of stream) { + * console.log(data); + * } + */ + function read():AsyncIterable; +} + +typedef AsyncIterable = () -> AsyncIterator; diff --git a/src/vscode/TerminalShellExecutionCommandLine.hx b/src/vscode/TerminalShellExecutionCommandLine.hx new file mode 100644 index 00000000..8b0bf6a9 --- /dev/null +++ b/src/vscode/TerminalShellExecutionCommandLine.hx @@ -0,0 +1,29 @@ +package vscode; + +/** + * A command line that was executed in a terminal. + */ +typedef TerminalShellExecutionCommandLine = { + /** + * The full command line that was executed, including both the command and its arguments. + */ + var value(default, null):String; + + /** + * Whether the command line value came from a trusted source and is therefore safe to + * execute without user additional confirmation, such as a notification that asks "Do you + * want to execute (command)?". This verification is likely only needed if you are going to + * execute the command again. + * + * This is `true` only when the command line was reported explicitly by the shell + * integration script (ie. {@link TerminalShellExecutionCommandLineConfidence.High high confidence}) + * and it used a nonce for verification. + */ + var isTrusted(default, null):Bool; + + /** + * The confidence of the command line value which is determined by how the value was + * obtained. This depends upon the implementation of the shell integration script. + */ + var confidence(default, null):TerminalShellExecutionCommandLineConfidence; +} diff --git a/src/vscode/TerminalShellExecutionCommandLineConfidence.hx b/src/vscode/TerminalShellExecutionCommandLineConfidence.hx new file mode 100644 index 00000000..21820526 --- /dev/null +++ b/src/vscode/TerminalShellExecutionCommandLineConfidence.hx @@ -0,0 +1,33 @@ +package vscode; + +/** + * The confidence of a {@link TerminalShellExecutionCommandLine} value. + */ +@:jsRequire("vscode", "TerminalShellExecutionCommandLineConfidence") +extern enum abstract TerminalShellExecutionCommandLineConfidence(Int) { + /** + * The command line value confidence is low. This means that the value was read from the + * terminal buffer using markers reported by the shell integration script. Additionally one + * of the following conditions will be met: + * + * - The command started on the very left-most column which is unusual, or + * - The command is multi-line which is more difficult to accurately detect due to line + * continuation characters and right prompts. + * - Command line markers were not reported by the shell integration script. + */ + var Low; + + /** + * The command line value confidence is medium. This means that the value was read from the + * terminal buffer using markers reported by the shell integration script. The command is + * single-line and does not start on the very left-most column (which is unusual). + */ + var Medium; + + /** + * The command line value confidence is high. This means that the value was explicitly sent + * from the shell integration script or the command was executed via the + * {@link TerminalShellIntegration.executeCommand} API. + */ + var High; +} diff --git a/src/vscode/TerminalShellExecutionEndEvent.hx b/src/vscode/TerminalShellExecutionEndEvent.hx new file mode 100644 index 00000000..d5f85e4a --- /dev/null +++ b/src/vscode/TerminalShellExecutionEndEvent.hx @@ -0,0 +1,55 @@ +package vscode; + +/** + * An event signalling that an execution has ended in a terminal. + */ +typedef TerminalShellExecutionEndEvent = { + /** + * The terminal that shell integration has been activated in. + */ + var terminal(default, null):Terminal; + + /** + * The shell integration object. + */ + var shellIntegration(default, null):TerminalShellIntegration; + + /** + * The terminal shell execution that has ended. + */ + var execution(default, null):TerminalShellExecution; + + /** + * The exit code reported by the shell. + * + * When this is `undefined` it can mean several things: + * + * - The shell either did not report an exit code (ie. the shell integration script is + * misbehaving) + * - The shell reported a command started before the command finished (eg. a sub-shell was + * opened). + * - The user canceled the command via ctrl+c. + * - The user pressed enter when there was no input. + * + * Generally this should not happen. Depending on the use case, it may be best to treat this + * as a failure. + * + * @example + * const execution = shellIntegration.executeCommand({ + * command: 'echo', + * args: ['Hello world'] + * }); + * window.onDidEndTerminalShellExecution(event => { + * if (event.execution === execution) { + * if (event.exitCode === undefined) { + * console.log('Command finished but exit code is unknown'); + * } else if (event.exitCode === 0) { + * console.log('Command succeeded'); + * } else { + * console.log('Command failed'); + * } + * } + * }); + */ + var exitCode(default, null):Null; +} diff --git a/src/vscode/TerminalShellExecutionStartEvent.hx b/src/vscode/TerminalShellExecutionStartEvent.hx new file mode 100644 index 00000000..fdaf6735 --- /dev/null +++ b/src/vscode/TerminalShellExecutionStartEvent.hx @@ -0,0 +1,21 @@ +package vscode; + +/** + * An event signalling that an execution has started in a terminal. + */ +typedef TerminalShellExecutionStartEvent = { + /** + * The terminal that shell integration has been activated in. + */ + var terminal(default, null):Terminal; + + /** + * The shell integration object. + */ + var shellIntegration(default, null):TerminalShellIntegration; + + /** + * The terminal shell execution that has ended. + */ + var execution(default, null):TerminalShellExecution; +} diff --git a/src/vscode/TerminalShellIntegration.hx b/src/vscode/TerminalShellIntegration.hx new file mode 100644 index 00000000..389e8abb --- /dev/null +++ b/src/vscode/TerminalShellIntegration.hx @@ -0,0 +1,116 @@ +package vscode; + +/** + * [Shell integration](https://code.visualstudio.com/docs/terminal/shell-integration)-powered capabilities owned by a terminal. + */ +@:jsRequire("vscode", "TerminalShellIntegration") +extern class TerminalShellIntegration { + /** + * The current working directory of the terminal. This {@link Uri} may represent a file on + * another machine (eg. ssh into another machine). This requires the shell integration to + * support working directory reporting. + */ + var cwd(default, null):Null; + + /** + * Execute a command, sending ^C as necessary to interrupt any running command if needed. + * + * @param commandLine The command line to execute, this is the exact text that will be sent + * to the terminal. + * + * @example + * // Execute a command in a terminal immediately after being created + * const myTerm = window.createTerminal(); + * window.onDidChangeTerminalShellIntegration(async ({ terminal, shellIntegration }) => { + * if (terminal === myTerm) { + * const execution = shellIntegration.executeCommand('echo "Hello world"'); + * window.onDidEndTerminalShellExecution(event => { + * if (event.execution === execution) { + * console.log(`Command exited with code ${event.exitCode}`); + * } + * }); + * } + * })); + * // Fallback to sendText if there is no shell integration within 3 seconds of launching + * setTimeout(() => { + * if (!myTerm.shellIntegration) { + * myTerm.sendText('echo "Hello world"'); + * // Without shell integration, we can't know when the command has finished or what the + * // exit code was. + * } + * }, 3000); + * + * @example + * // Send command to terminal that has been alive for a while + * const commandLine = 'echo "Hello world"'; + * if (term.shellIntegration) { + * const execution = shellIntegration.executeCommand({ commandLine }); + * window.onDidEndTerminalShellExecution(event => { + * if (event.execution === execution) { + * console.log(`Command exited with code ${event.exitCode}`); + * } + * }); + * } else { + * term.sendText(commandLine); + * // Without shell integration, we can't know when the command has finished or what the + * // exit code was. + * } + */ + overload function executeCommand(commandLine:String):TerminalShellExecution; + + /** + * Execute a command, sending ^C as necessary to interrupt any running command if needed. + * + * *Note* This is not guaranteed to work as [shell integration](https://code.visualstudio.com/docs/terminal/shell-integration) + * must be activated. Check whether {@link TerminalShellExecution.exitCode} is rejected to + * verify whether it was successful. + * + * @param executable A command to run. + * @param args Arguments to launch the executable with. The arguments will be escaped such + * that they are interpreted as single arguments when the argument both contains whitespace + * and does not include any single quote, double quote or backtick characters. + * + * Note that this escaping is not intended to be a security measure, be careful when passing + * untrusted data to this API as strings like `$(...)` can often be used in shells to + * execute code within a string. + * + * @example + * // Execute a command in a terminal immediately after being created + * const myTerm = window.createTerminal(); + * window.onDidChangeTerminalShellIntegration(async ({ terminal, shellIntegration }) => { + * if (terminal === myTerm) { + * const command = shellIntegration.executeCommand({ + * command: 'echo', + * args: ['Hello world'] + * }); + * const code = await command.exitCode; + * console.log(`Command exited with code ${code}`); + * } + * })); + * // Fallback to sendText if there is no shell integration within 3 seconds of launching + * setTimeout(() => { + * if (!myTerm.shellIntegration) { + * myTerm.sendText('echo "Hello world"'); + * // Without shell integration, we can't know when the command has finished or what the + * // exit code was. + * } + * }, 3000); + * + * @example + * // Send command to terminal that has been alive for a while + * const commandLine = 'echo "Hello world"'; + * if (term.shellIntegration) { + * const command = term.shellIntegration.executeCommand({ + * command: 'echo', + * args: ['Hello world'] + * }); + * const code = await command.exitCode; + * console.log(`Command exited with code ${code}`); + * } else { + * term.sendText(commandLine); + * // Without shell integration, we can't know when the command has finished or what the + * // exit code was. + * } + */ + overload function executeCommand(executable:String, args:Array):TerminalShellExecution; +} diff --git a/src/vscode/TerminalShellIntegrationChangeEvent.hx b/src/vscode/TerminalShellIntegrationChangeEvent.hx new file mode 100644 index 00000000..054c9900 --- /dev/null +++ b/src/vscode/TerminalShellIntegrationChangeEvent.hx @@ -0,0 +1,16 @@ +package vscode; + +/** + * An event signalling that a terminal's shell integration has changed. + */ +typedef TerminalShellIntegrationChangeEvent = { + /** + * The terminal that shell integration has been activated in. + */ + var terminal(default, null):Terminal; + + /** + * The shell integration object. + */ + var shellIntegration(default, null):TerminalShellIntegration; +} diff --git a/src/vscode/TerminalSplitLocationOptions.hx b/src/vscode/TerminalSplitLocationOptions.hx new file mode 100644 index 00000000..d75692e0 --- /dev/null +++ b/src/vscode/TerminalSplitLocationOptions.hx @@ -0,0 +1,12 @@ +package vscode; + +/** + * Uses the parent {@link Terminal}'s location for the terminal + */ +typedef TerminalSplitLocationOptions = { + /** + * The parent terminal to split this terminal beside. This works whether the parent terminal + * is in the panel or the editor area. + */ + var parentTerminal:Terminal; +} diff --git a/src/vscode/TerminalState.hx b/src/vscode/TerminalState.hx new file mode 100644 index 00000000..4082af3b --- /dev/null +++ b/src/vscode/TerminalState.hx @@ -0,0 +1,22 @@ +package vscode; + +/** + * Represents the state of a {@link Terminal}. + */ +typedef TerminalState = { + /** + * Whether the {@link Terminal} has been interacted with. Interaction means that the + * terminal has sent data to the process which depending on the terminal's _mode_. By + * default input is sent when a key is pressed or when a command or extension sends text, + * but based on the terminal's mode it can also happen on: + * + * - a pointer click event + * - a pointer scroll event + * - a pointer move event + * - terminal focus in/out + * + * For more information on events that can send data see "DEC Private Mode Set (DECSET)" on + * https://invisible-island.net/xterm/ctlseqs/ctlseqs.html + */ + var isInteractedWith(default, null):Bool; +} diff --git a/src/vscode/TestController.hx b/src/vscode/TestController.hx index 02d0df89..06182dc9 100644 --- a/src/vscode/TestController.hx +++ b/src/vscode/TestController.hx @@ -8,7 +8,7 @@ package vscode; */ typedef TestController = { /** - * The id of the controller passed in {@link vscode.tests.createTestController}. + * The id of the controller passed in {@link tests.createTestController}. * This must be globally unique. */ var id(default, null):String; @@ -24,7 +24,7 @@ typedef TestController = { * "test tree." * * The extension controls when to add tests. For example, extensions should - * add tests for a file when {@link vscode.workspace.onDidOpenTextDocument} + * add tests for a file when {@link workspace.onDidOpenTextDocument} * fires in order for decorations for tests within a file to be visible. * * However, the editor may sometimes explicitly request children using the @@ -39,17 +39,19 @@ typedef TestController = { * @param kind Configures what kind of execution this profile manages. * @param runHandler Function called to start a test run. * @param isDefault Whether this is the default action for its kind. + * @param tag Profile test tag. + * @param supportsContinuousRun Whether the profile supports continuous running. * @returns An instance of a {@link TestRunProfile}, which is automatically * associated with this controller. */ function createRunProfile(label:String, kind:TestRunProfileKind, runHandler:(request:TestRunRequest, token:CancellationToken) -> Thenable, - ?isDefault:Bool):TestRunProfile; + ?isDefault:Bool, ?tag:TestTag, ?supportsContinuousRun:Bool):TestRunProfile; /** * A function provided by the extension that the editor may call to request * children of a test item, if the {@link TestItem.canResolveChildren} is * `true`. When called, the item should discover children and call - * {@link vscode.tests.createTestItem} as children are discovered. + * {@link TestController.createTestItem} as children are discovered. * * Generally the extension manages the lifecycle of test items, but under * certain conditions the editor may request the children of a specific @@ -61,10 +63,23 @@ typedef TestController = { * the function returns or the returned thenable resolves. * * @param item An unresolved test item for which children are being - * requested, or `undefined` to resolve the controller's initial {@link items}. + * requested, or `undefined` to resolve the controller's initial {@link TestController.items items}. */ var resolveHandler:(item:Null) -> Thenable; + /** + * If this method is present, a refresh button will be present in the + * UI, and this method will be invoked when it's clicked. When called, + * the extension should scan the workspace for any new, changed, or + * removed tests. + * + * It's recommended that extensions try to update tests in realtime, using + * a {@link FileSystemWatcher} for example, and use this method as a fallback. + * + * @returns A thenable that resolves when tests have been refreshed. + */ + var refreshHandler:Null<(token:CancellationToken) -> Thenable>; + /** * Creates a {@link TestRun}. This should be called by the * {@link TestRunProfile} when a request is made to execute tests, and may @@ -100,6 +115,24 @@ typedef TestController = { */ function createTestItem(id:String, label:String, ?uri:Uri):TestItem; + /** + * Marks an item's results as being outdated. This is commonly called when + * code or configuration changes and previous results should no longer + * be considered relevant. The same logic used to mark results as outdated + * may be used to drive {@link TestRunRequest.continuous continuous test runs}. + * + * If an item is passed to this method, test results for the item and all of + * its children will be marked as outdated. If no item is passed, then all + * test owned by the TestController will be marked as outdated. + * + * Any test runs started before the moment this method is called, including + * runs which may still be ongoing, will be marked as outdated and deprioritized + * in the editor's UI. + * + * @param items Item to mark as outdated. If undefined, all the controller's items are marked outdated. + */ + function invalidateTestResults(?items:EitherType>):Void; + /** * Unregisters the test controller, disposing of its associated tests * and unpersisted results. diff --git a/src/vscode/TestCoverageCount.hx b/src/vscode/TestCoverageCount.hx new file mode 100644 index 00000000..3e608d0e --- /dev/null +++ b/src/vscode/TestCoverageCount.hx @@ -0,0 +1,24 @@ +package vscode; + +/** + * A class that contains information about a covered resource. A count can + * be give for lines, branches, and declarations in a file. + */ +@:jsRequire("vscode", "TestCoverageCount") +extern class TestCoverageCount { + /** + * Number of items covered in the file. + */ + var covered:Int; + + /** + * Total number of covered items in the file. + */ + var total:Int; + + /** + * @param covered Value for {@link TestCoverageCount.covered} + * @param total Value for {@link TestCoverageCount.total} + */ + function new(covered:Int, total:Int); +} diff --git a/src/vscode/TestItem.hx b/src/vscode/TestItem.hx index a15c5f6d..9b2ae1eb 100644 --- a/src/vscode/TestItem.hx +++ b/src/vscode/TestItem.hx @@ -18,7 +18,7 @@ typedef TestItem = { /** * URI this `TestItem` is associated with. May be a file or directory. */ - var ?uri(default, null):Uri; + var uri(default, null):Null; /** * The children of this test item. For a test suite, this may contain the @@ -29,9 +29,15 @@ typedef TestItem = { /** * The parent of this item. It's set automatically, and is undefined * top-level items in the {@link TestController.items} and for items that - * aren't yet included in another item's {@link children}. + * aren't yet included in another item's {@link TestItem.children children}. */ - var ?parent(default, null):TestItem; + var parent(default, null):Null; + + /** + * Tags associated with this test item. May be used in combination with + * {@link TestRunProfile.tag tags}, or simply as an organizational feature. + */ + var tags:ReadOnlyArray; /** * Indicates whether this test item may have children discovered by resolving. @@ -63,11 +69,18 @@ typedef TestItem = { var ?description:String; /** - * Location of the test item in its {@link uri}. + * A string that should be used when comparing this item + * with other items. When `falsy` the {@link TestItem.label label} + * is used. + */ + var ?sortText:Null; + + /** + * Location of the test item in its {@link TestItem.uri uri}. * * This is only meaningful if the `uri` points to a file. */ - var ?range:Range; + var range:Null; /** * Optional error encountered while loading the test. @@ -75,5 +88,5 @@ typedef TestItem = { * Note that this is not a test result and should only be used to represent errors in * test discovery, such as syntax errors. */ - var ?error:EitherType; + var error:Null>; } diff --git a/src/vscode/TestItemCollection.hx b/src/vscode/TestItemCollection.hx index 48ed641f..d371edbc 100644 --- a/src/vscode/TestItemCollection.hx +++ b/src/vscode/TestItemCollection.hx @@ -4,7 +4,8 @@ package vscode; * Collection of test items, found in {@link TestItem.children} and * {@link TestController.items}. */ -typedef TestItemCollection = { +typedef TestItemCollection = { // extends Iterable<[id: string, testItem: TestItem]> { + /** * Gets the number of items in the collection. */ @@ -27,7 +28,7 @@ typedef TestItemCollection = { /** * Adds the test item to the children. If an item with the same ID already * exists, it'll be replaced. - * @param items Item to add. + * @param item Item to add. */ function add(item:TestItem):Void; diff --git a/src/vscode/TestMessage.hx b/src/vscode/TestMessage.hx index 54c45e29..d70f7a5b 100644 --- a/src/vscode/TestMessage.hx +++ b/src/vscode/TestMessage.hx @@ -12,12 +12,12 @@ extern class TestMessage { var message:EitherType; /** - * Expected test output. If given with {@link actualOutput}, a diff view will be shown. + * Expected test output. If given with {@link TestMessage.actualOutput actualOutput }, a diff view will be shown. */ var expectedOutput:Null; /** - * Actual test output. If given with {@link expectedOutput}, a diff view will be shown. + * Actual test output. If given with {@link TestMessage.expectedOutput expectedOutput }, a diff view will be shown. */ var actualOutput:Null; @@ -26,6 +26,42 @@ extern class TestMessage { */ var location:Null; + /** + * Context value of the test item. This can be used to contribute message- + * specific actions to the test peek view. The value set here can be found + * in the `testMessage` property of the following `menus` contribution points: + * + * - `testing/message/context` - context menu for the message in the results tree + * - `testing/message/content` - a prominent button overlaying editor content where + * the message is displayed. + * + * For example: + * + * ```json + * "contributes": { + * "menus": { + * "testing/message/content": [ + * { + * "command": "extension.deleteCommentThread", + * "when": "testMessage == canApplyRichDiff" + * } + * ] + * } + * } + * ``` + * + * The command will be called with an object containing: + * - `test`: the {@link TestItem} the message is associated with, *if* it + * is still present in the {@link TestController.items} collection. + * - `message`: the {@link TestMessage} instance. + */ + var contextValue:Null; + + /** + * The stack trace associated with the message or failure. + */ + var stackTrace:Null>; + /** * Creates a new TestMessage that will present as a diff in the editor. * @param message Message to display to the user. diff --git a/src/vscode/TestMessageStackFrame.hx b/src/vscode/TestMessageStackFrame.hx new file mode 100644 index 00000000..121c6694 --- /dev/null +++ b/src/vscode/TestMessageStackFrame.hx @@ -0,0 +1,30 @@ +package vscode; + +/** + * A stack frame found in the {@link TestMessage.stackTrace}. + */ +@:jsRequire("vscode", "TestMessageStackFrame") +extern class TestMessageStackFrame { + /** + * The location of this stack frame. This should be provided as a URI if the + * location of the call frame can be accessed by the editor. + */ + var uri:Null; + + /** + * Position of the stack frame within the file. + */ + var position:Null; + + /** + * The name of the stack frame, typically a method or function name. + */ + var label:String; + + /** + * @param label The name of the stack frame + * @param file The file URI of the stack frame + * @param position The position of the stack frame within the file + */ + function new(label:String, ?uri:Uri, ?position:Position); +} diff --git a/src/vscode/TestRun.hx b/src/vscode/TestRun.hx index 47da2158..f2843fad 100644 --- a/src/vscode/TestRun.hx +++ b/src/vscode/TestRun.hx @@ -1,7 +1,8 @@ package vscode; /** - * Options given to {@link TestController.runTests} + * A TestRun represents an in-progress or completed test run and + * provides methods to report the state of individual tests in the run. */ typedef TestRun = { /** @@ -9,7 +10,7 @@ typedef TestRun = { * disambiguate multiple sets of results in a test run. It is useful if * tests are run across multiple platforms, for example. */ - var ?name(default, null):String; + var name(default, null):Null; /** * A cancellation token which will be triggered when the test run is @@ -44,7 +45,7 @@ typedef TestRun = { * Indicates a test has failed. You should pass one or more * {@link TestMessage TestMessages} to describe the failure. * @param test Test item to update. - * @param messages Messages associated with the test failure. + * @param message Messages associated with the test failure. * @param duration How long the test took to execute, in milliseconds. */ function failed(test:TestItem, message:EitherType>, ?duration:Float):Void; @@ -55,7 +56,7 @@ typedef TestRun = { * from the "failed" state in that it indicates a test that couldn't be * executed at all, from a compilation error for example. * @param test Test item to update. - * @param messages Messages associated with the test failure. + * @param message Messages associated with the test failure. * @param duration How long the test took to execute, in milliseconds. */ function errored(test:TestItem, message:EitherType>, ?duration:Float):Void; @@ -70,15 +71,30 @@ typedef TestRun = { /** * Appends raw output from the test runner. On the user's request, the * output will be displayed in a terminal. ANSI escape sequences, - * such as colors and text styles, are supported. + * such as colors and text styles, are supported. New lines must be given + * as CRLF (`\r\n`) rather than LF (`\n`). * * @param output Output text to append. + * @param location Indicate that the output was logged at the given + * location. + * @param test Test item to associate the output with. */ - function appendOutput(output:String):Void; + function appendOutput(output:String, ?location:Location, ?test:TestItem):Void; /** - * Signals that the end of the test run. Any tests included in the run whose + * Adds coverage for a file in the run. + */ + function addCoverage(fileCoverage:FileCoverage):Void; + + /** + * Signals the end of the test run. Any tests included in the run whose * states have not been updated will have their state reset. */ function end():Void; + + /** + * An event fired when the editor is no longer interested in data + * associated with the test run. + */ + function onDidDispose():Event; } diff --git a/src/vscode/TestRunProfile.hx b/src/vscode/TestRunProfile.hx index d6c9975b..3a983fa4 100644 --- a/src/vscode/TestRunProfile.hx +++ b/src/vscode/TestRunProfile.hx @@ -27,16 +27,38 @@ typedef TestRunProfile = { * the generic "run all" button, then the default profile for * {@link TestRunProfileKind.Run} will be executed, although the * user can configure this. + * + * Changes the user makes in their default profiles will be reflected + * in this property after a {@link onDidChangeDefault} event. */ var isDefault:Bool; + /** + * Fired when a user has changed whether this is a default profile. The + * event contains the new value of {@link isDefault} + */ + var onDidChangeDefault:Event; + + /** + * Whether this profile supports continuous running of requests. If so, + * then {@link TestRunRequest.continuous} may be set to `true`. Defaults + * to false. + */ + var supportsContinuousRun:Bool; + + /** + * Associated tag for the profile. If this is set, only {@link TestItem} + * instances with the same tag will be eligible to execute in this profile. + */ + var tag:Null; + /** * If this method is present, a configuration gear will be present in the * UI, and this method will be invoked when it's clicked. When called, * you can take other editor actions, such as showing a quick pick or * opening a configuration file. */ - var ?configureHandler:() -> Void; + var configureHandler:Null<() -> Void>; /** * Handler called to start a test run. When invoked, the function should call @@ -44,6 +66,11 @@ typedef TestRunProfile = { * associated with the request should be created before the function returns * or the returned promise is resolved. * + * If {@link supportsContinuousRun} is set, then {@link TestRunRequest.continuous} + * may be `true`. In this case, the profile should observe changes to + * source code and create new test runs by calling {@link TestController.createTestRun}, + * until the cancellation is requested on the `token`. + * * @param request Request information for the test run. * @param cancellationToken Token that signals the used asked to abort the * test run. If cancellation is requested on this token, all {@link TestRun} @@ -52,6 +79,41 @@ typedef TestRunProfile = { */ var runHandler:(request:TestRunRequest, token:CancellationToken) -> Thenable; + /** + * An extension-provided function that provides detailed statement and + * function-level coverage for a file. The editor will call this when more + * detail is needed for a file, such as when it's opened in an editor or + * expanded in the **Test Coverage** view. + * + * The {@link FileCoverage} object passed to this function is the same instance + * emitted on {@link TestRun.addCoverage} calls associated with this profile. + */ + var ?loadDetailedCoverage:(testRun:TestRun, fileCoverage:FileCoverage, token:CancellationToken) -> Thenable>; + + /** + * An extension-provided function that provides detailed statement and + * function-level coverage for a single test in a file. This is the per-test + * sibling of {@link TestRunProfile.loadDetailedCoverage}, called only if + * a test item is provided in {@link FileCoverage.includesTests} and only + * for files where such data is reported. + * + * Often {@link TestRunProfile.loadDetailedCoverage} will be called first + * when a user opens a file, and then this method will be called if they + * drill down into specific per-test coverage information. This method + * should then return coverage data only for statements and declarations + * executed by the specific test during the run. + * + * The {@link FileCoverage} object passed to this function is the same + * instance emitted on {@link TestRun.addCoverage} calls associated with this profile. + * + * @param testRun The test run that generated the coverage data. + * @param fileCoverage The file coverage object to load detailed coverage for. + * @param fromTestItem The test item to request coverage information for. + * @param token A cancellation token that indicates the operation should be cancelled. + */ + var ?loadDetailedCoverageForTest:(testRun:TestRun, fileCoverage:FileCoverage, fromTestItem:TestItem, + token:CancellationToken) -> Thenable>; + /** * Deletes the run profile. */ diff --git a/src/vscode/TestRunProfileKind.hx b/src/vscode/TestRunProfileKind.hx index 93ccd90b..fb8f85e9 100644 --- a/src/vscode/TestRunProfileKind.hx +++ b/src/vscode/TestRunProfileKind.hx @@ -5,7 +5,18 @@ package vscode; */ @:jsRequire("vscode", "TestRunProfileKind") extern enum abstract TestRunProfileKind(Int) { + /** + * The `Run` test profile kind. + */ final Run; + + /** + * The `Debug` test profile kind. + */ final Debug; + + /** + * The `Coverage` test profile kind. + */ final Coverage; } diff --git a/src/vscode/TestRunRequest.hx b/src/vscode/TestRunRequest.hx index bd10b756..a99c3137 100644 --- a/src/vscode/TestRunRequest.hx +++ b/src/vscode/TestRunRequest.hx @@ -2,9 +2,9 @@ package vscode; /** * A TestRunRequest is a precursor to a {@link TestRun}, which in turn is - * created by passing a request to {@link tests.runTests}. The TestRunRequest - * contains information about which tests should be run, which should not be - * run, and how they are run (via the {@link profile}). + * created by passing a request to {@link TestController.createTestRun}. The + * TestRunRequest contains information about which tests should be run, which + * should not be run, and how they are run (via the {@link TestRunRequest.profile profile}). * * In general, TestRunRequests are created by the editor and pass to * {@link TestRunProfile.runHandler}, however you can also create test @@ -21,7 +21,7 @@ extern class TestRunRequest { * The process of running tests should resolve the children of any test * items who have not yet been resolved. */ - var include(default, null):Null>; + var include(default, null):Null>; /** * An array of tests the user has marked as excluded from the test included @@ -30,7 +30,7 @@ extern class TestRunRequest { * May be omitted if no exclusions were requested. Test controllers should * not run excluded tests or any children of excluded tests. */ - var exclude(default, null):Null>; + var exclude(default, null):Null>; /** * The profile used for this request. This will always be defined @@ -40,9 +40,25 @@ extern class TestRunRequest { var profile(default, null):Null; /** - * @param tests Array of specific tests to run, or undefined to run all tests + * Whether the profile should run continuously as source code changes. Only + * relevant for profiles that set {@link TestRunProfile.supportsContinuousRun}. + */ + var continuous(default, null):Null; + + /** + * Controls how test Test Results view is focused. If true, the editor + * will keep the maintain the user's focus. If false, the editor will + * prefer to move focus into the Test Results view, although + * this may be configured by users. + */ + var preserveFocus(default, null):Bool; + + /** + * @param include Array of specific tests to run, or undefined to run all tests * @param exclude An array of tests to exclude from the run. * @param profile The run profile used for this request. + * @param continuous Whether to run tests continuously as source changes. + * @param preserveFocus Whether to preserve the user's focus when the run is started */ function new(?include:ReadOnlyArray, ?exclude:ReadOnlyArray, ?profile:TestRunProfile); } diff --git a/src/vscode/TestTag.hx b/src/vscode/TestTag.hx new file mode 100644 index 00000000..4b6bd7e2 --- /dev/null +++ b/src/vscode/TestTag.hx @@ -0,0 +1,21 @@ +package vscode; + +/** + * Tags can be associated with {@link TestItem TestItems} and + * {@link TestRunProfile TestRunProfiles}. A profile with a tag can only + * execute tests that include that tag in their {@link TestItem.tags} array. + */ +@:jsRequire("vscode", "TestTag") +extern class TestTag { + /** + * ID of the test tag. `TestTag` instances with the same ID are considered + * to be identical. + */ + var id(default, null):String; + + /** + * Creates a new TestTag instance. + * @param id ID of the test tag. + */ + function new(id:String); +} diff --git a/src/vscode/TextDocument.hx b/src/vscode/TextDocument.hx index 4c18793b..0ce27ef7 100644 --- a/src/vscode/TextDocument.hx +++ b/src/vscode/TextDocument.hx @@ -6,7 +6,8 @@ import js.lib.RegExp; * Represents a text document, such as a source file. Text documents have * {@link TextLine lines} and knowledge about an underlying resource like a file. */ -typedef TextDocument = { +@:jsRequire("vscode", "TextDocument") +extern class TextDocument { /** * The associated uri for this document. * @@ -56,9 +57,8 @@ typedef TextDocument = { /** * Save the underlying file. * - * @return A promise that will resolve to true when the file - * has been saved. If the file was not dirty or the save failed, - * will return false. + * @returns A promise that will resolve to `true` when the file + * has been saved. If the save failed, will return `false`. */ function save():Thenable; @@ -78,24 +78,24 @@ typedef TextDocument = { * that the returned object is *not* live and changes to the * document are not reflected. * - * @param line A line number in [0, lineCount). - * @return A {@link TextLine line}. - */ - // TODO: overload PLOX - // /** - // * Returns a text line denoted by the position. Note - // * that the returned object is *not* live and changes to the - // * document are not reflected. - // * - // * The position will be {@link TextDocument.validatePosition adjusted}. - // * - // * @see {@link TextDocument.lineAt} - // * - // * @param position A position. - // * @return A {@link TextLine line}. - // */ - @:overload(function(position:Position):TextLine {}) - function lineAt(line:Int):TextLine; + * @param line A line number in `[0, lineCount)`. + * @returns A {@link TextLine line}. + */ + overload function lineAt(line:Int):TextLine; + + /** + * Returns a text line denoted by the position. Note + * that the returned object is *not* live and changes to the + * document are not reflected. + * + * The position will be {@link TextDocument.validatePosition adjusted}. + * + * @see {@link TextDocument.lineAt} + * + * @param position A position. + * @returns A {@link TextLine line}. + */ + overload function lineAt(position:Position):TextLine; /** * Converts the position to a zero-based offset. @@ -103,7 +103,7 @@ typedef TextDocument = { * The position will be {@link TextDocument.validatePosition adjusted}. * * @param position A position. - * @return A valid zero-based offset. + * @returns A valid zero-based offset. */ function offsetAt(position:Position):Int; @@ -111,7 +111,7 @@ typedef TextDocument = { * Converts a zero-based offset to a position. * * @param offset A zero-based offset. - * @return A valid {@link Position}. + * @returns A valid {@link Position}. */ function positionAt(offset:Int):Position; @@ -120,14 +120,14 @@ typedef TextDocument = { * a range. The range will be {@link TextDocument.validateRange adjusted}. * * @param range Include only the text included by the range. - * @return The text inside the provided range or the entire text. + * @returns The text inside the provided range or the entire text. */ function getText(?range:Range):String; /** * Get a word-range at the given position. By default words are defined by * common separators, like space, -, _, etc. In addition, per language custom - * [word definitions} can be defined. It + * [word definitions] can be defined. It * is also possible to provide a custom regular expression. * * * *Note 1:* A custom regular expression must not match the empty string and @@ -140,7 +140,7 @@ typedef TextDocument = { * * @param position A position. * @param regex Optional regular expression that describes what a word is. - * @return A range spanning a word, or `undefined`. + * @returns A range spanning a word, or `undefined`. */ function getWordRangeAtPosition(position:Position, ?regex:RegExp):Null; @@ -148,7 +148,7 @@ typedef TextDocument = { * Ensure a range is completely contained in this document. * * @param range A range. - * @return The given range or a new, adjusted range. + * @returns The given range or a new, adjusted range. */ function validateRange(range:Range):Range; @@ -156,7 +156,7 @@ typedef TextDocument = { * Ensure a position is contained in the range of this document. * * @param position A position. - * @return The given position or a new, adjusted position. + * @returns The given position or a new, adjusted position. */ function validatePosition(position:Position):Position; } diff --git a/src/vscode/TextDocumentChangeEvent.hx b/src/vscode/TextDocumentChangeEvent.hx index 8991767e..c599dacb 100644 --- a/src/vscode/TextDocumentChangeEvent.hx +++ b/src/vscode/TextDocumentChangeEvent.hx @@ -16,7 +16,7 @@ typedef TextDocumentChangeEvent = { /** * The reason why the document was changed. - * Is undefined if the reason is not known. + * Is `undefined` if the reason is not known. */ - var ?reason(default, null):TextDocumentChangeReason; + var reason(default, null):Null; } diff --git a/src/vscode/TextDocumentChangeReason.hx b/src/vscode/TextDocumentChangeReason.hx index eb35094d..90bb550c 100644 --- a/src/vscode/TextDocumentChangeReason.hx +++ b/src/vscode/TextDocumentChangeReason.hx @@ -1,5 +1,8 @@ package vscode; +/** + * Reasons for why a text document has changed. + */ @:jsRequire("vscode", "TextDocumentChangeReason") extern enum abstract TextDocumentChangeReason(Int) { /** The text change is caused by an undo operation. */ diff --git a/src/vscode/TextDocumentContentProvider.hx b/src/vscode/TextDocumentContentProvider.hx index abbc5cb4..cdf7c5b4 100644 --- a/src/vscode/TextDocumentContentProvider.hx +++ b/src/vscode/TextDocumentContentProvider.hx @@ -27,7 +27,7 @@ typedef TextDocumentContentProvider = { * * @param uri An uri which scheme matches the scheme this provider was {@link workspace.registerTextDocumentContentProvider registered} for. * @param token A cancellation token. - * @return A string or a thenable that resolves to such. + * @returns A string or a thenable that resolves to such. */ function provideTextDocumentContent(uri:Uri, token:CancellationToken):ProviderResult; } diff --git a/src/vscode/TextDocumentShowOptions.hx b/src/vscode/TextDocumentShowOptions.hx index 93850c83..6c4e0897 100644 --- a/src/vscode/TextDocumentShowOptions.hx +++ b/src/vscode/TextDocumentShowOptions.hx @@ -6,10 +6,10 @@ package vscode; typedef TextDocumentShowOptions = { /** * An optional view column in which the {@link TextEditor editor} should be shown. - * The default is the {@link ViewColumn.Active active}, other values are adjusted to - * be `Min(column, columnCount + 1)`, the {@link ViewColumn.Active active}-column is - * not adjusted. Use {@linkcode ViewColumn.Beside} to open the - * editor to the side of the currently active one. + * The default is the {@link ViewColumn.Active active}. Columns that do not exist + * will be created as needed up to the maximum of {@linkcode ViewColumn.Nine}. + * Use {@linkcode ViewColumn.Beside} to open the editor to the side of the currently + * active one. */ var ?viewColumn:ViewColumn; @@ -19,8 +19,10 @@ typedef TextDocumentShowOptions = { var ?preserveFocus:Bool; /** - * An optional flag that controls if an {@link TextEditor editor}-tab will be replaced - * with the next editor or if it will be kept. + * An optional flag that controls if an {@link TextEditor editor}-tab shows as preview. Preview tabs will + * be replaced and reused until set to stay - either explicitly or through editing. + * + * *Note* that the flag is ignored if a user has disabled preview editors in settings. */ var ?preview:Bool; diff --git a/src/vscode/TextDocumentWillSaveEvent.hx b/src/vscode/TextDocumentWillSaveEvent.hx index 2d5b0ac0..455bd8d1 100644 --- a/src/vscode/TextDocumentWillSaveEvent.hx +++ b/src/vscode/TextDocumentWillSaveEvent.hx @@ -7,7 +7,8 @@ package vscode; * {@linkcode TextDocumentWillSaveEvent.waitUntil waitUntil}-function with a thenable * that resolves to an array of {@link TextEdit text edits}. */ -typedef TextDocumentWillSaveEvent = { +@:jsRequire("vscode", "TextDocumentWillSaveEvent") +extern class TextDocumentWillSaveEvent { /** * The document that will be saved. */ @@ -38,6 +39,14 @@ typedef TextDocumentWillSaveEvent = { * * @param thenable A thenable that resolves to {@link TextEdit pre-save-edits}. */ - @:overload(function(thenable:Thenable):Void {}) - function waitUntil(thenable:Thenable>):Void; + overload function waitUntil(thenable:Thenable>):Void; + + /** + * Allows to pause the event loop until the provided thenable resolved. + * + * *Note:* This function can only be called during event dispatch. + * + * @param thenable A thenable that delays saving. + */ + overload function waitUntil(thenable:Thenable):Void; } diff --git a/src/vscode/TextEdit.hx b/src/vscode/TextEdit.hx index 62fda008..d9ea0d91 100644 --- a/src/vscode/TextEdit.hx +++ b/src/vscode/TextEdit.hx @@ -11,7 +11,7 @@ extern class TextEdit { * * @param range A range. * @param newText A string. - * @return A new text edit object. + * @returns A new text edit object. */ static function replace(range:Range, newText:String):TextEdit; @@ -20,7 +20,7 @@ extern class TextEdit { * * @param position A position, will become an empty range. * @param newText A string. - * @return A new text edit object. + * @returns A new text edit object. */ static function insert(position:Position, newText:String):TextEdit; @@ -28,7 +28,7 @@ extern class TextEdit { * Utility to create a delete edit. * * @param range A range. - * @return A new text edit object. + * @returns A new text edit object. */ static function delete(range:Range):TextEdit; @@ -36,7 +36,7 @@ extern class TextEdit { * Utility to create an eol-edit. * * @param eol An eol-sequence - * @return A new text edit object. + * @returns A new text edit object. */ static function setEndOfLine(eol:EndOfLine):TextEdit; diff --git a/src/vscode/TextEditor.hx b/src/vscode/TextEditor.hx index aacccc5e..cc3d81c7 100644 --- a/src/vscode/TextEditor.hx +++ b/src/vscode/TextEditor.hx @@ -17,13 +17,13 @@ typedef TextEditor = { /** * The selections in this text editor. The primary selection is always at index 0. */ - var selections:Array; + var selections:ReadOnlyArray; /** * The current visible ranges in the editor (vertically). * This accounts only for vertical scrolling, and not for horizontal scrolling. */ - var visibleRanges(default, never):Array; + var visibleRanges(default, never):ReadOnlyArray; /** * Text editor options. @@ -35,7 +35,7 @@ typedef TextEditor = { * isn't one of the main editors, e.g. an embedded editor, or when the editor * column is larger than three. */ - var ?viewColumn(default, never):ViewColumn; + var viewColumn(default, never):Null; /** * Perform an edit on the document associated with this text editor. @@ -46,9 +46,18 @@ typedef TextEditor = { * * @param callback A function which can create edits using an {@link TextEditorEdit edit-builder}. * @param options The undo/redo behavior around this edit. By default, undo stops will be created before and after this edit. - * @return A promise that resolves with a value indicating if the edits could be applied. + * @returns A promise that resolves with a value indicating if the edits could be applied. */ - function edit(callback:TextEditorEdit->Void, ?options:{undoStopBefore:Bool, undoStopAfter:Bool}):Thenable; + function edit(callback:TextEditorEdit->Void, ?options:{ + /** + * Add undo stop before making the edits. + */ + undoStopBefore:Bool, + /** + * Add undo stop after making the edits. + */ + undoStopAfter:Bool + }):Thenable; /** * Insert a {@link SnippetString snippet} and put the editor into snippet mode. "Snippet mode" @@ -58,12 +67,18 @@ typedef TextEditor = { * @param snippet The snippet to insert in this edit. * @param location Position or range at which to insert the snippet, defaults to the current editor selection or selections. * @param options The undo/redo behavior around this edit. By default, undo stops will be created before and after this edit. - * @return A promise that resolves with a value indicating if the snippet could be inserted. Note that the promise does not signal + * @returns A promise that resolves with a value indicating if the snippet could be inserted. Note that the promise does not signal * that the snippet is completely filled-in or accepted. */ function insertSnippet(snippet:SnippetString, ?location:EitherType, ReadOnlyArray>>>, ?options:{ + /** + * Add undo stop before making the edits. + */ undoStopBefore:Bool, + /** + * Add undo stop after making the edits. + */ undoStopAfter:Bool }):Thenable; diff --git a/src/vscode/TextEditorEdit.hx b/src/vscode/TextEditorEdit.hx index 4de77633..459a949e 100644 --- a/src/vscode/TextEditorEdit.hx +++ b/src/vscode/TextEditorEdit.hx @@ -8,7 +8,7 @@ package vscode; typedef TextEditorEdit = { /** * Replace a certain text region with a new value. - * You can use \r\n or \n in `value` and they will be normalized to the current {@link TextDocument document}. + * You can use `\r\n` or `\n` in `value` and they will be normalized to the current {@link TextDocument document}. * * @param location The range this operation should remove. * @param value The new text this operation should insert after removing `location`. @@ -17,7 +17,7 @@ typedef TextEditorEdit = { /** * Insert text at a location. - * You can use \r\n or \n in `value` and they will be normalized to the current {@link TextDocument document}. + * You can use `\r\n` or `\n` in `value` and they will be normalized to the current {@link TextDocument document}. * Although the equivalent text edit can be made with {@link TextEditorEdit.replace replace}, `insert` will produce a different resulting selection (it will get moved). * * @param location The position where the new text should be inserted. diff --git a/src/vscode/TextEditorLineNumbersStyle.hx b/src/vscode/TextEditorLineNumbersStyle.hx index eac7ae2a..52352868 100644 --- a/src/vscode/TextEditorLineNumbersStyle.hx +++ b/src/vscode/TextEditorLineNumbersStyle.hx @@ -19,4 +19,9 @@ extern enum abstract TextEditorLineNumbersStyle(Int) { * Render the line numbers with values relative to the primary cursor location. */ var Relative; + + /** + * Render the line numbers on every 10th line number. + */ + var Interval; } diff --git a/src/vscode/TextEditorOptions.hx b/src/vscode/TextEditorOptions.hx index d65aff89..c605b194 100644 --- a/src/vscode/TextEditorOptions.hx +++ b/src/vscode/TextEditorOptions.hx @@ -7,13 +7,22 @@ typedef TextEditorOptions = { /** * The size in spaces a tab takes. This is used for two purposes: * - the rendering width of a tab character; - * - the number of spaces to insert when {@link TextEditorOptions.insertSpaces insertSpaces} is true. + * - the number of spaces to insert when {@link TextEditorOptions.insertSpaces insertSpaces} is true + * and `indentSize` is set to `"tabSize"`. * * When getting a text editor's options, this property will always be a number (resolved). * When setting a text editor's options, this property is optional and it can be a number or `"auto"`. */ var ?tabSize:EitherType; + /** + * The number of spaces to insert when {@link TextEditorOptions.insertSpaces insertSpaces} is true. + * + * When getting a text editor's options, this property will always be a number (resolved). + * When setting a text editor's options, this property is optional and it can be a number or `"tabSize"`. + */ + var ?indentSize:EitherType; + /** * When pressing Tab insert {@link TextEditorOptions.tabSize n} spaces. * When getting a text editor's options, this property will always be a boolean (resolved). diff --git a/src/vscode/TextEditorSelectionChangeEvent.hx b/src/vscode/TextEditorSelectionChangeEvent.hx index 6b859c97..298ac34e 100644 --- a/src/vscode/TextEditorSelectionChangeEvent.hx +++ b/src/vscode/TextEditorSelectionChangeEvent.hx @@ -18,5 +18,5 @@ typedef TextEditorSelectionChangeEvent = { * The {@link TextEditorSelectionChangeKind change kind} which has triggered this * event. Can be `undefined`. */ - var ?kind(default, null):TextEditorSelectionChangeKind; + var kind(default, null):Null; } diff --git a/src/vscode/ThemableDecorationAttachmentRenderOptions.hx b/src/vscode/ThemableDecorationAttachmentRenderOptions.hx index ec78e4a4..3e905b11 100644 --- a/src/vscode/ThemableDecorationAttachmentRenderOptions.hx +++ b/src/vscode/ThemableDecorationAttachmentRenderOptions.hx @@ -1,5 +1,9 @@ package vscode; +/** + * Represents theme specific rendering styles for {@link ThemableDecorationRenderOptions.before before} and + * {@link ThemableDecorationRenderOptions.after after} the content of text decorations. + */ typedef ThemableDecorationAttachmentRenderOptions = { /** * Defines a text content that is shown in the attachment. Either an icon or a text can be shown, but not both. diff --git a/src/vscode/ThemableDecorationInstanceRenderOptions.hx b/src/vscode/ThemableDecorationInstanceRenderOptions.hx index 71cd7d00..2a1e9a81 100644 --- a/src/vscode/ThemableDecorationInstanceRenderOptions.hx +++ b/src/vscode/ThemableDecorationInstanceRenderOptions.hx @@ -1,5 +1,8 @@ package vscode; +/** + * Represents themable render options for decoration instances. + */ typedef ThemableDecorationInstanceRenderOptions = { /** * Defines the rendering options of the attachment that is inserted before the decorated text. diff --git a/src/vscode/ThemeColor.hx b/src/vscode/ThemeColor.hx index fb482a8d..2b17f9dc 100644 --- a/src/vscode/ThemeColor.hx +++ b/src/vscode/ThemeColor.hx @@ -6,9 +6,14 @@ package vscode; */ @:jsRequire("vscode", "ThemeColor") extern class ThemeColor { + /** + * The id of this color. + */ + var id(default, null):String; + /** * Creates a reference to a theme color. - * @param id of the color. The available colors are listed in https://code.visualstudio.com/docs/getstarted/theme-color-reference. + * @param id of the color. The available colors are listed in https://code.visualstudio.com/api/references/theme-color. */ function new(id:String); } diff --git a/src/vscode/TreeCheckboxChangeEvent.hx b/src/vscode/TreeCheckboxChangeEvent.hx new file mode 100644 index 00000000..69469061 --- /dev/null +++ b/src/vscode/TreeCheckboxChangeEvent.hx @@ -0,0 +1,27 @@ +package vscode; + +/** + * An event describing the change in a tree item's checkbox state. + */ +typedef TreeCheckboxChangeEvent = { + /** + * The items that were checked or unchecked. + */ + var items(default, null):ReadOnlyArray>; +} + +@:dce +abstract TreeCheckboxChangeEventItemsTuple(Array) { + public var t(get, never):T; + public var state(get, never):TreeItemCheckboxState; + + public extern inline function new(t:String, state:FileType) { + this = [t, state]; + } + + extern inline function get_t():T + return this[0]; + + extern inline function get_state():TreeItemCheckboxState + return this[1]; +} diff --git a/src/vscode/TreeDataProvider.hx b/src/vscode/TreeDataProvider.hx index 8ece5225..c450d291 100644 --- a/src/vscode/TreeDataProvider.hx +++ b/src/vscode/TreeDataProvider.hx @@ -15,7 +15,7 @@ typedef TreeDataProvider = { * Get {@link TreeItem} representation of the `element` * * @param element The element for which {@link TreeItem} representation is asked for. - * @return {@link TreeItem} representation of the element + * @returns TreeItem representation of the element. */ function getTreeItem(element:T):EitherType>; @@ -23,7 +23,7 @@ typedef TreeDataProvider = { * Get the children of `element` or root if no element is passed. * * @param element The element from which the provider gets children. Can be `undefined`. - * @return Children of `element` or root if no element is passed. + * @returns Children of `element` or root if no element is passed. */ function getChildren(?element:T):ProviderResult>; @@ -34,9 +34,9 @@ typedef TreeDataProvider = { * **NOTE:** This method should be implemented in order to access {@link TreeView.reveal reveal} API. * * @param element The element for which the parent has to be returned. - * @return Parent of `element`. + * @returns Parent of `element`. */ - var ?getParent(default, never):(element:T) -> ProviderResult; + function getParent(element:T):ProviderResult; /** * Called on hover to resolve the {@link TreeItem.tooltip TreeItem} property if it is undefined. @@ -56,8 +56,8 @@ typedef TreeDataProvider = { * @param item Undefined properties of `item` should be set then `item` should be returned. * @param element The object associated with the TreeItem. * @param token A cancellation token. - * @return The resolved tree item or a thenable that resolves to such. It is OK to return the given + * @returns The resolved tree item or a thenable that resolves to such. It is OK to return the given * `item`. When no result is returned, the given `item` will be used. */ - var ?resolveTreeItem(default, never):(item:TreeItem, element:T, token:CancellationToken) -> ProviderResult; + function resolveTreeItem(item:TreeItem, element:T, token:CancellationToken):ProviderResult; } diff --git a/src/vscode/TreeDragAndDropController.hx b/src/vscode/TreeDragAndDropController.hx new file mode 100644 index 00000000..1372ce95 --- /dev/null +++ b/src/vscode/TreeDragAndDropController.hx @@ -0,0 +1,63 @@ +package vscode; + +/** + * Provides support for drag and drop in `TreeView`. + */ +@:jsRequire("vscode", "TreeDragAndDropController") +extern class TreeDragAndDropController { + /** + * The mime types that the {@link TreeDragAndDropController.handleDrop `handleDrop`} method of this `DragAndDropController` supports. + * This could be well-defined, existing, mime types, and also mime types defined by the extension. + * + * To support drops from trees, you will need to add the mime type of that tree. + * This includes drops from within the same tree. + * The mime type of a tree is recommended to be of the format `application/vnd.code.tree.`. + * + * Use the special `files` mime type to support all types of dropped files {@link DataTransferFile files}, regardless of the file's actual mime type. + * + * To learn the mime type of a dragged item: + * 1. Set up your `DragAndDropController` + * 2. Use the Developer: Set Log Level... command to set the level to "Debug" + * 3. Open the developer tools and drag the item with unknown mime type over your tree. The mime types will be logged to the developer console + * + * Note that mime types that cannot be sent to the extension will be omitted. + */ + var dropMimeTypes(default, null):ReadOnlyArray; + + /** + * The mime types that the {@link TreeDragAndDropController.handleDrag `handleDrag`} method of this `TreeDragAndDropController` may add to the tree data transfer. + * This could be well-defined, existing, mime types, and also mime types defined by the extension. + * + * The recommended mime type of the tree (`application/vnd.code.tree.`) will be automatically added. + */ + var dragMimeTypes(default, null):ReadOnlyArray; + + /** + * When the user starts dragging items from this `DragAndDropController`, `handleDrag` will be called. + * Extensions can use `handleDrag` to add their {@link DataTransferItem `DataTransferItem`} items to the drag and drop. + * + * When the items are dropped on **another tree item** in **the same tree**, your `DataTransferItem` objects + * will be preserved. Use the recommended mime type for the tree (`application/vnd.code.tree.`) to add + * tree objects in a data transfer. See the documentation for `DataTransferItem` for how best to take advantage of this. + * + * To add a data transfer item that can be dragged into the editor, use the application specific mime type "text/uri-list". + * The data for "text/uri-list" should be a string with `toString()`ed Uris separated by `\r\n`. To specify a cursor position in the file, + * set the Uri's fragment to `L3,5`, where 3 is the line number and 5 is the column number. + * + * @param source The source items for the drag and drop operation. + * @param dataTransfer The data transfer associated with this drag. + * @param token A cancellation token indicating that drag has been cancelled. + */ + overload function handleDrag(source:ReadOnlyArray, dataTransfer:DataTransfer, token:CancellationToken):Null>; + + /** + * Called when a drag and drop action results in a drop on the tree that this `DragAndDropController` belongs to. + * + * Extensions should fire {@link TreeDataProvider.onDidChangeTreeData onDidChangeTreeData} for any elements that need to be refreshed. + * + * @param target The target tree element that the drop is occurring on. When undefined, the target is the root. + * @param dataTransfer The data transfer items of the source of the drag. + * @param token A cancellation token indicating that the drop has been cancelled. + */ + overload function handleDrag(target:Null, dataTransfer:DataTransfer, token:CancellationToken):Null>; +} diff --git a/src/vscode/TreeItem.hx b/src/vscode/TreeItem.hx index f1042f2f..93cbcdfc 100644 --- a/src/vscode/TreeItem.hx +++ b/src/vscode/TreeItem.hx @@ -19,7 +19,7 @@ extern class TreeItem { * When `falsy`, {@link ThemeIcon.Folder Folder Theme Icon} is assigned, if item is collapsible otherwise {@link ThemeIcon.File File Theme Icon}. * When a file or folder {@link ThemeIcon} is specified, icon is derived from the current file icon theme for the specified theme icon using {@link TreeItem.resourceUri resourceUri} (if provided). */ - var iconPath:Null, dark:EitherType}, ThemeIcon>>>>; + var iconPath:Null>; /** * A human-readable string which is rendered less prominent. @@ -58,17 +58,17 @@ extern class TreeItem { * Context value of the tree item. This can be used to contribute item specific actions in the tree. * For example, a tree item is given a context value as `folder`. When contributing actions to `view/item/context` * using `menus` extension point, you can specify context value for key `viewItem` in `when` expression like `viewItem == folder`. - * ``` - * "contributes": { - * "menus": { - * "view/item/context": [ - * { - * "command": "extension.deleteFolder", - * "when": "viewItem == folder" - * } - * ] - * } - * } + * ```json + * "contributes": { + * "menus": { + * "view/item/context": [ + * { + * "command": "extension.deleteFolder", + * "when": "viewItem == folder" + * } + * ] + * } + * } * ``` * This will show action `extension.deleteFolder` only for items with `contextValue` is `folder`. */ @@ -81,6 +81,25 @@ extern class TreeItem { */ var accessibilityInformation:Null; + /** + * {@link TreeItemCheckboxState TreeItemCheckboxState} of the tree item. + * {@link TreeDataProvider.onDidChangeTreeData onDidChangeTreeData} should be fired when {@link TreeItem.checkboxState checkboxState} changes. + */ + var checkboxState:Null>; + /** * @param label A human-readable string describing this item * @param resourceUri The {@link Uri} of the resource representing this item. diff --git a/src/vscode/TreeItemCheckboxState.hx b/src/vscode/TreeItemCheckboxState.hx new file mode 100644 index 00000000..b688fb16 --- /dev/null +++ b/src/vscode/TreeItemCheckboxState.hx @@ -0,0 +1,17 @@ +package vscode; + +/** + * Checkbox state of the tree item + */ +@:jsRequire("vscode", "TreeItemCheckboxState") +extern enum abstract TreeItemCheckboxState(Int) { + /** + * Determines an item is unchecked + */ + var Unchecked; + + /** + * Determines an item is checked + */ + var Checked; +} diff --git a/src/vscode/TreeView.hx b/src/vscode/TreeView.hx index 5e710a8b..05d7b1fd 100644 --- a/src/vscode/TreeView.hx +++ b/src/vscode/TreeView.hx @@ -22,7 +22,7 @@ typedef TreeView = { /** * Currently selected elements. */ - var selection(default, null):Array; + var selection(default, null):ReadOnlyArray; /** * Event that is fired when the {@link TreeView.selection selection} has changed @@ -39,6 +39,11 @@ typedef TreeView = { */ var onDidChangeVisibility(default, null):Event; + /** + * An event to signal that an element or root has either been checked or unchecked. + */ + var onDidChangeCheckboxState(default, null):Event>; + /** * An optional human-readable message that will be rendered in the view. * Setting the message to null, undefined, or empty string will remove the message from the view. @@ -57,6 +62,12 @@ typedef TreeView = { */ var ?description:String; + /** + * The badge to display for this TreeView. + * To remove the badge, set to undefined. + */ + var ?badge:Null; + /** * Reveals the given element in the tree view. * If the tree view is not visible then the tree view is shown and element is revealed. @@ -65,9 +76,22 @@ typedef TreeView = { * In order to not to select, set the option `select` to `false`. * In order to focus, set the option `focus` to `true`. * In order to expand the revealed element, set the option `expand` to `true`. To expand recursively set `expand` to the number of levels to expand. - * **NOTE:** You can expand only to 3 levels maximum. * - * **NOTE:** The {@link TreeDataProvider} that the `TreeView` {@link window.createTreeView is registered with} with must implement {@link TreeDataProvider.getParent getParent} method to access this API. + * * *NOTE:* You can expand only to 3 levels maximum. + * * *NOTE:* The {@link TreeDataProvider} that the `TreeView` {@link window.createTreeView is registered with} with must implement {@link TreeDataProvider.getParent getParent} method to access this API. */ - function reveal(element:T, ?options:{?select:Bool, ?focus:Bool, ?exapnd:EitherType}):Thenable; + function reveal(element:T, ?options:{ + /** + * If true, then the element will be selected. + */ + ?select:Bool, + /** + * If true, then the element will be focused. + */ + ?focus:Bool, + /** + * If true, then the element will be expanded. If a number is passed, then up to that number of levels of children will be expanded + */ + ?exapnd:EitherType + }):Thenable; } diff --git a/src/vscode/TreeViewOptions.hx b/src/vscode/TreeViewOptions.hx index f64eaaf7..4b463aa3 100644 --- a/src/vscode/TreeViewOptions.hx +++ b/src/vscode/TreeViewOptions.hx @@ -20,4 +20,47 @@ typedef TreeViewOptions = { * array containing all selected tree items. */ var ?canSelectMany:Bool; + + /** + * An optional interface to implement drag and drop in the tree view. + */ + var ?dragAndDropController:TreeDragAndDropController; + + /** + * By default, when the children of a tree item have already been fetched, child checkboxes are automatically managed based on the checked state of the parent tree item. + * If the tree item is collapsed by default (meaning that the children haven't yet been fetched) then child checkboxes will not be updated. + * To override this behavior and manage child and parent checkbox state in the extension, set this to `true`. + * + * Examples where {@link TreeViewOptions.manageCheckboxStateManually} is false, the default behavior: + * + * 1. A tree item is checked, then its children are fetched. The children will be checked. + * + * 2. A tree item's parent is checked. The tree item and all of it's siblings will be checked. + * - [ ] Parent + * - [ ] Child 1 + * - [ ] Child 2 + * When the user checks Parent, the tree will look like this: + * - [x] Parent + * - [x] Child 1 + * - [x] Child 2 + * + * 3. A tree item and all of it's siblings are checked. The parent will be checked. + * - [ ] Parent + * - [ ] Child 1 + * - [ ] Child 2 + * When the user checks Child 1 and Child 2, the tree will look like this: + * - [x] Parent + * - [x] Child 1 + * - [x] Child 2 + * + * 4. A tree item is unchecked. The parent will be unchecked. + * - [x] Parent + * - [x] Child 1 + * - [x] Child 2 + * When the user unchecks Child 1, the tree will look like this: + * - [ ] Parent + * - [ ] Child 1 + * - [x] Child 2 + */ + var ?manageCheckboxStateManually:Bool; } diff --git a/src/vscode/TreeViewSelectionChangeEvent.hx b/src/vscode/TreeViewSelectionChangeEvent.hx index 9432af24..10e5e267 100644 --- a/src/vscode/TreeViewSelectionChangeEvent.hx +++ b/src/vscode/TreeViewSelectionChangeEvent.hx @@ -7,5 +7,5 @@ typedef TreeViewSelectionChangeEvent = { /** * Selected elements. */ - var selection(default, null):Array; + var selection(default, null):ReadOnlyArray; } diff --git a/src/vscode/TypeDefinitionProvider.hx b/src/vscode/TypeDefinitionProvider.hx index db8ff09e..5a2f0a7b 100644 --- a/src/vscode/TypeDefinitionProvider.hx +++ b/src/vscode/TypeDefinitionProvider.hx @@ -11,7 +11,7 @@ typedef TypeDefinitionProvider = { * @param document The document in which the command was invoked. * @param position The position at which the command was invoked. * @param token A cancellation token. - * @return A definition or a thenable that resolves to such. The lack of a result can be + * @returns A definition or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined` or `null`. */ function provideTypeDefinition(document:TextDocument, position:Position, diff --git a/src/vscode/TypeHierarchyItem.hx b/src/vscode/TypeHierarchyItem.hx new file mode 100644 index 00000000..c749d7bc --- /dev/null +++ b/src/vscode/TypeHierarchyItem.hx @@ -0,0 +1,56 @@ +package vscode; + +/** + * Represents an item of a type hierarchy, like a class or an interface. + */ +@:jsRequire("vscode", "TypeHierarchyItem") +extern class TypeHierarchyItem { + /** + * The name of this item. + */ + var name:String; + + /** + * The kind of this item. + */ + var kind:SymbolKind; + + /** + * Tags for this item. + */ + var tags:Null>; + + /** + * More detail for this item, e.g. the signature of a function. + */ + var detail:Null; + + /** + * The resource identifier of this item. + */ + var uri:Uri; + + /** + * The range enclosing this symbol not including leading/trailing whitespace + * but everything else, e.g. comments and code. + */ + var range:Range; + + /** + * The range that should be selected and revealed when this symbol is being + * picked, e.g. the name of a class. Must be contained by the {@link TypeHierarchyItem.range range}-property. + */ + var selectionRange:Range; + + /** + * Creates a new type hierarchy item. + * + * @param kind The kind of the item. + * @param name The name of the item. + * @param detail The details of the item. + * @param uri The Uri of the item. + * @param range The whole range of the item. + * @param selectionRange The selection range of the item. + */ + function new(kind:SymbolKind, name:String, detail:String, uri:Uri, range:Range, selectionRange:Range); +} diff --git a/src/vscode/TypeHierarchyProvider.hx b/src/vscode/TypeHierarchyProvider.hx new file mode 100644 index 00000000..6fcd5452 --- /dev/null +++ b/src/vscode/TypeHierarchyProvider.hx @@ -0,0 +1,45 @@ +package vscode; + +/** + * The type hierarchy provider interface describes the contract between extensions + * and the type hierarchy feature. + */ +typedef TypeHierarchyProvider = { + /** + * Bootstraps type hierarchy by returning the item that is denoted by the given document + * and position. This item will be used as entry into the type graph. Providers should + * return `undefined` or `null` when there is no item at the given location. + * + * @param document The document in which the command was invoked. + * @param position The position at which the command was invoked. + * @param token A cancellation token. + * @returns One or multiple type hierarchy items or a thenable that resolves to such. The lack of a result can be + * signaled by returning `undefined`, `null`, or an empty array. + */ + function prepareTypeHierarchy(document:TextDocument, position:Position, + token:CancellationToken):ProviderResult>>; + + /** + * Provide all supertypes for an item, e.g all types from which a type is derived/inherited. In graph terms this describes directed + * and annotated edges inside the type graph, e.g the given item is the starting node and the result is the nodes + * that can be reached. + * + * @param item The hierarchy item for which super types should be computed. + * @param token A cancellation token. + * @returns A set of direct supertypes or a thenable that resolves to such. The lack of a result can be + * signaled by returning `undefined` or `null`. + */ + function provideTypeHierarchySupertypes(item:TypeHierarchyItem, token:CancellationToken):ProviderResult>; + + /** + * Provide all subtypes for an item, e.g all types which are derived/inherited from the given item. In + * graph terms this describes directed and annotated edges inside the type graph, e.g the given item is the starting + * node and the result is the nodes that can be reached. + * + * @param item The hierarchy item for which subtypes should be computed. + * @param token A cancellation token. + * @returns A set of direct subtypes or a thenable that resolves to such. The lack of a result can be + * signaled by returning `undefined` or `null`. + */ + function provideTypeHierarchySubtypes(item:TypeHierarchyItem, token:CancellationToken):ProviderResult>; +} diff --git a/src/vscode/Uri.hx b/src/vscode/Uri.hx index eb63f8b2..36e4274c 100644 --- a/src/vscode/Uri.hx +++ b/src/vscode/Uri.hx @@ -7,7 +7,7 @@ package vscode; @:jsRequire("vscode", "Uri") extern class Uri { /** - * Create an URI from a string, e.g. `http://www.msft.com/some/path`, + * Create an URI from a string, e.g. `http://www.example.com/some/path`, * `file:///usr/home`, or `scheme:with/path`. * * *Note* that for a while uris without a `scheme` were accepted. That is not correct @@ -17,7 +17,7 @@ extern class Uri { * @see {@link Uri.toString} * @param value The string value of an Uri. * @param strict Throw an error when `value` is empty or when no `scheme` can be parsed. - * @return A new Uri instance. + * @returns A new Uri instance. */ static function parse(value:String, ?strict:Bool):Uri; @@ -34,6 +34,7 @@ extern class Uri { * good.scheme === 'file'; * good.path === '/coding/c#/project1'; * good.fragment === ''; + * * const bad = URI.parse('file://' + '/coding/c#/project1'); * bad.scheme === 'file'; * bad.path === '/coding/c'; // path is now broken @@ -41,7 +42,7 @@ extern class Uri { * ``` * * @param path A file system or UNC path. - * @return A new Uri instance. + * @returns A new Uri instance. */ static function file(path:String):Uri; @@ -72,13 +73,28 @@ extern class Uri { * * @see {@link Uri.toString} * @param components The component parts of an Uri. - * @return A new Uri instance. + * @returns A new Uri instance. */ static function from(components:{ + /** + * The scheme of the uri + */ scheme:String, + /** + * The authority of the uri + */ ?authority:String, + /** + * The path of the uri + */ ?path:String, + /** + * The query string of the uri + */ ?query:String, + /** + * The fragment identifier of the uri + */ ?fragment:String }):Uri; @@ -88,29 +104,29 @@ extern class Uri { private function new(scheme:String, authority:String, path:String, query:String, fragment:String); /** - * Scheme is the `http` part of `http://www.msft.com/some/path?query#fragment`. + * Scheme is the `http` part of `http://www.example.com/some/path?query#fragment`. * The part before the first colon. */ var scheme(default, null):String; /** - * Authority is the `www.msft.com` part of `http://www.msft.com/some/path?query#fragment`. + * Authority is the `www.example.com` part of `http://www.example.com/some/path?query#fragment`. * The part between the first double slashes and the next slash. */ var authority(default, null):String; /** - * Path is the `/some/path` part of `http://www.msft.com/some/path?query#fragment`. + * Path is the `/some/path` part of `http://www.example.com/some/path?query#fragment`. */ var path(default, null):String; /** - * Query is the `query` part of `http://www.msft.com/some/path?query#fragment`. + * Query is the `query` part of `http://www.example.com/some/path?query#fragment`. */ var query(default, null):String; /** - * Fragment is the `fragment` part of `http://www.msft.com/some/path?query#fragment`. + * Fragment is the `fragment` part of `http://www.example.com/some/path?query#fragment`. */ var fragment(default, null):String; @@ -130,7 +146,7 @@ extern class Uri { * ```ts * const u = URI.parse('file://server/c$/folder/file.txt') * u.authority === 'server' - * u.path === '/shares/c$/file.txt' + * u.path === '/c$/folder/file.txt' * u.fsPath === '\\server\c$\folder\file.txt' * ``` */ @@ -147,14 +163,29 @@ extern class Uri { * * @param change An object that describes a change to this Uri. To unset components use `null` or * the empty string. - * @return A new Uri that reflects the given change. Will return `this` Uri if the change + * @returns A new Uri that reflects the given change. Will return `this` Uri if the change * is not changing anything. */ function with(change:{ + /** + * The new scheme, defaults to this Uri's scheme. + */ ?scheme:String, + /** + * The new authority, defaults to this Uri's authority. + */ ?authority:String, + /** + * The new path, defaults to this Uri's path. + */ ?path:String, + /** + * The new query, defaults to this Uri's query. + */ ?query:String, + /** + * The new fragment, defaults to this Uri's fragment. + */ ?fragment:String }):Uri; @@ -180,7 +211,7 @@ extern class Uri { /** * Returns a JSON representation of this Uri. * - * @return An object. + * @returns An object. */ function toJSON():Any; } diff --git a/src/vscode/ViewBadge.hx b/src/vscode/ViewBadge.hx new file mode 100644 index 00000000..55bfbe41 --- /dev/null +++ b/src/vscode/ViewBadge.hx @@ -0,0 +1,16 @@ +package vscode; + +/** + * A badge presenting a value for a view + */ +typedef ViewBadge = { + /** + * A label to present in tooltip for the badge. + */ + var tooltip(default, null):String; + + /** + * The value to present in the badge. + */ + var value(default, null):Int; +} diff --git a/src/vscode/Webview.hx b/src/vscode/Webview.hx index e43fe449..e40cb3ac 100644 --- a/src/vscode/Webview.hx +++ b/src/vscode/Webview.hx @@ -62,6 +62,19 @@ typedef Webview = { * `package.json`, any `ArrayBuffer` values that appear in `message` will be more * efficiently transferred to the webview and will also be correctly recreated inside * of the webview. + * + * @returns A promise that resolves when the message is posted to a webview or when it is + * dropped because the message was not deliverable. + * + * Returns `true` if the message was posted to the webview. Messages can only be posted to + * live webviews (i.e. either visible webviews or hidden webviews that set `retainContextWhenHidden`). + * + * A response of `true` does not mean that the message was actually received by the webview. + * For example, no message listeners may be have been hooked up inside the webview or the webview may + * have been destroyed after the message was posted but before it was received. + * + * If you want confirm that a message as actually received, you can try having your webview posting a + * confirmation message back to your extension. */ function postMessage(message:Any):Thenable; @@ -83,8 +96,8 @@ typedef Webview = { * * This is the origin that should be used in a content security policy rule: * - * ``` - * img-src https: ${webview.cspSource} ...; + * ```ts + * `img-src https: ${webview.cspSource} ...;` * ``` */ var cspSource(default, null):String; diff --git a/src/vscode/WebviewOptions.hx b/src/vscode/WebviewOptions.hx index b3f41020..2f968f56 100644 --- a/src/vscode/WebviewOptions.hx +++ b/src/vscode/WebviewOptions.hx @@ -11,12 +11,22 @@ typedef WebviewOptions = { */ var ?enableScripts(default, null):Bool; + /** + * Controls whether forms are enabled in the webview content or not. + * + * Defaults to true if {@link WebviewOptions.enableScripts scripts are enabled}. Otherwise defaults to false. + * Explicitly setting this property to either true or false overrides the default. + */ + var ?enableForms(default, null):Bool; + /** * Controls whether command uris are enabled in webview content or not. * - * Defaults to false. + * Defaults to `false` (command uris are disabled). + * + * If you pass in an array, only the commands in the array are allowed. */ - var ?enableCommandUris(default, null):Bool; + var ?enableCommandUris(default, null):EitherType>; /** * Root paths from which the webview can load local (filesystem) resources using the `vscode-resource:` scheme. diff --git a/src/vscode/WebviewPanel.hx b/src/vscode/WebviewPanel.hx index 77c89e25..28061938 100644 --- a/src/vscode/WebviewPanel.hx +++ b/src/vscode/WebviewPanel.hx @@ -17,7 +17,16 @@ typedef WebviewPanel = { /** * Icon for the panel shown in UI. */ - var ?iconPath:EitherType; + var ?iconPath:EitherType; /** * {@linkcode Webview} belonging to the panel. @@ -33,7 +42,7 @@ typedef WebviewPanel = { * Editor position of the panel. This property is only set if the webview is in * one of the editor view columns. */ - var ?viewColumn(default, null):ViewColumn; + var viewColumn(default, null):Null; /** * Whether the panel is active (focused by the user). diff --git a/src/vscode/WebviewPanelOptions.hx b/src/vscode/WebviewPanelOptions.hx index 957c16cd..070d0f86 100644 --- a/src/vscode/WebviewPanelOptions.hx +++ b/src/vscode/WebviewPanelOptions.hx @@ -7,7 +7,7 @@ typedef WebviewPanelOptions = { /** * Controls if the find widget is enabled in the panel. * - * Defaults to false. + * Defaults to `false`. */ var ?enableFindWidget(default, null):Bool; diff --git a/src/vscode/WebviewPanelSerializer.hx b/src/vscode/WebviewPanelSerializer.hx index 594b2981..ab3f8645 100644 --- a/src/vscode/WebviewPanelSerializer.hx +++ b/src/vscode/WebviewPanelSerializer.hx @@ -43,7 +43,7 @@ typedef WebviewPanelSerializer = { * serializer must restore the webview's `.html` and hook up all webview events. * @param state Persisted state from the webview content. * - * @return Thenable indicating that the webview has been fully restored. + * @returns Thenable indicating that the webview has been fully restored. */ function deserializeWebviewPanel(webviewPanel:WebviewPanel, state:T):Thenable; } diff --git a/src/vscode/WebviewView.hx b/src/vscode/WebviewView.hx index 5fba3ff5..6701d637 100644 --- a/src/vscode/WebviewView.hx +++ b/src/vscode/WebviewView.hx @@ -26,6 +26,12 @@ typedef WebviewView = { */ var ?description:String; + /** + * The badge to display for this webview view. + * To remove the badge, set to undefined. + */ + var ?badge:Null; + /** * Event fired when the view is disposed. * diff --git a/src/vscode/WebviewViewProvider.hx b/src/vscode/WebviewViewProvider.hx index e1dfe9d3..8f762f4c 100644 --- a/src/vscode/WebviewViewProvider.hx +++ b/src/vscode/WebviewViewProvider.hx @@ -5,7 +5,7 @@ package vscode; */ typedef WebviewViewProvider = { /** - * Revolves a webview view. + * Resolves a webview view. * * `resolveWebviewView` is called when a view first becomes visible. This may happen when the view is * first loaded or when the user hides and then shows a view again. @@ -15,7 +15,7 @@ typedef WebviewViewProvider = { * @param context Additional metadata about the view being resolved. * @param token Cancellation token indicating that the view being provided is no longer needed. * - * @return Optional thenable indicating that the view has been fully resolved. + * @returns Optional thenable indicating that the view has been fully resolved. */ function resolveWebviewView(webviewView:WebviewView, context:WebviewViewResolveContext, token:CancellationToken):Null>; // can't have EitherType<...,Void> diff --git a/src/vscode/WindowState.hx b/src/vscode/WindowState.hx index d583665c..61883f8f 100644 --- a/src/vscode/WindowState.hx +++ b/src/vscode/WindowState.hx @@ -8,4 +8,10 @@ typedef WindowState = { * Whether the current window is focused. */ var focused(default, null):Bool; + + /** + * Whether the window has been interacted with recently. This will change + * immediately on activity, or after a short time of user inactivity. + */ + var active(default, null):Bool; } diff --git a/src/vscode/WorkspaceConfiguration.hx b/src/vscode/WorkspaceConfiguration.hx index befc6aec..a9d4322d 100644 --- a/src/vscode/WorkspaceConfiguration.hx +++ b/src/vscode/WorkspaceConfiguration.hx @@ -9,18 +9,17 @@ package vscode; * - *Workspace Folder settings* - From one of the {@link workspace.workspaceFolders Workspace Folders} under which requested resource belongs to. * - *Language settings* - Settings defined under requested language. * - * The *effective* value (returned by {@linkcode WorkspaceConfiguration.get get}) is computed by overriding or merging the values in the following order. + * The *effective* value (returned by {@linkcode WorkspaceConfiguration.get get}) is computed by overriding or merging the values in the following order: + * + * 1. `defaultValue` (if defined in `package.json` otherwise derived from the value's type) + * 1. `globalValue` (if defined) + * 1. `workspaceValue` (if defined) + * 1. `workspaceFolderValue` (if defined) + * 1. `defaultLanguageValue` (if defined) + * 1. `globalLanguageValue` (if defined) + * 1. `workspaceLanguageValue` (if defined) + * 1. `workspaceFolderLanguageValue` (if defined) * - * ``` - * `defaultValue` (if defined in `package.json` otherwise derived from the value's type) - * `globalValue` (if defined) - * `workspaceValue` (if defined) - * `workspaceFolderValue` (if defined) - * `defaultLanguageValue` (if defined) - * `globalLanguageValue` (if defined) - * `workspaceLanguageValue` (if defined) - * `workspaceFolderLanguageValue` (if defined) - * ``` * **Note:** Only `object` value types are merged and all other value types are overridden. * * Example 1: Overriding @@ -64,21 +63,30 @@ package vscode; * * Refer to [Settings](https://code.visualstudio.com/docs/getstarted/settings) for more information. */ -typedef WorkspaceConfiguration = { +@:jsRequire("vscode", "WorkspaceConfiguration") +extern class WorkspaceConfiguration { + /** + * Return a value from this configuration. + * + * @param section Configuration name, supports _dotted_ names. + * @returns The value `section` denotes or `undefined`. + */ + overload function get(section:String):Null; + /** * Return a value from this configuration. * * @param section Configuration name, supports _dotted_ names. - * @return The value `section` denotes or `undefined`. + * @param defaultValue A value should be returned when no value could be found, is `undefined`. + * @returns The value `section` denotes or the default. */ - @:overload(function(section:String, defaultValue:T):T {}) - function get(section:String):Null; + overload function get(section:String, defaultValue:T):T; /** * Check if this configuration has a certain value. * * @param section Configuration name, supports _dotted_ names. - * @return `true` if the section doesn't resolve to `undefined`. + * @returns `true` if the section doesn't resolve to `undefined`. */ function has(section:String):Bool; @@ -94,18 +102,48 @@ typedef WorkspaceConfiguration = { * (`editor.fontSize` vs `editor`) otherwise no result is returned. * * @param section Configuration name, supports _dotted_ names. - * @return Information about a configuration setting or `undefined`. + * @returns Information about a configuration setting or `undefined`. */ function inspect(section:String):Null<{ + /** + * The fully qualified key of the configuration value + */ key:String, + /** + * The default value which is used when no other value is defined + */ ?defaultValue:T, + /** + * The global or installation-wide value. + */ ?globalValue:T, + /** + * The workspace-specific value. + */ ?workspaceValue:T, + /** + * The workspace-folder-specific value. + */ ?workspaceFolderValue:T, + /** + * Language specific default value when this configuration value is created for a {@link ConfigurationScope language scope}. + */ ?defaultLanguageValue:T, + /** + * Language specific global value when this configuration value is created for a {@link ConfigurationScope language scope}. + */ ?globalLanguageValue:T, + /** + * Language specific workspace value when this configuration value is created for a {@link ConfigurationScope language scope}. + */ ?workspaceLanguageValue:T, + /** + * Language specific workspace-folder value when this configuration value is created for a {@link ConfigurationScope language scope}. + */ ?workspaceFolderLanguageValue:T, + /** + * All language identifiers for which this configuration is defined. + */ ?languageIds:Array, }>; diff --git a/src/vscode/WorkspaceEdit.hx b/src/vscode/WorkspaceEdit.hx index 97839f75..97844ea4 100644 --- a/src/vscode/WorkspaceEdit.hx +++ b/src/vscode/WorkspaceEdit.hx @@ -1,5 +1,7 @@ package vscode; +import js.lib.Uint8Array; + /** * A workspace edit is a collection of textual and files changes for * multiple resources and documents. @@ -48,37 +50,78 @@ extern class WorkspaceEdit { * Check if a text edit for a resource exists. * * @param uri A resource identifier. - * @return `true` if the given resource will be touched by this edit. + * @returns `true` if the given resource will be touched by this edit. */ function has(uri:Uri):Bool; /** - * Set (and replace) text edits for a resource. + * Set (and replace) text edits or snippet edits for a resource. + * + * @param uri A resource identifier. + * @param edits An array of edits. + */ + overload function set(uri:Uri, edits:ReadOnlyArray>):Void; + + /** + * Set (and replace) text edits or snippet edits with metadata for a resource. + * + * @param uri A resource identifier. + * @param edits An array of edits. + */ + overload function set(uri:Uri, edits:ReadOnlyArray):Void; + + /** + * Set (and replace) notebook edits for a resource. + * + * @param uri A resource identifier. + * @param edits An array of edits. + */ + overload function set(uri:Uri, edits:ReadOnlyArray):Void; + + /** + * Set (and replace) notebook edits with metadata for a resource. * * @param uri A resource identifier. - * @param edits An array of text edits. + * @param edits An array of edits. */ - function set(uri:Uri, edits:Array):Void; + overload function set(uri:Uri, edits:ReadOnlyArray):Void; /** * Get the text edits for a resource. * * @param uri A resource identifier. - * @return An array of text edits. + * @returns An array of text edits. */ function get(uri:Uri):Array; /** * Create a regular file. * - * @param uri Uri of the new file.. + * @param uri Uri of the new file. * @param options Defines if an existing file should be overwritten or be - * ignored. When overwrite and ignoreIfExists are both set overwrite wins. + * ignored. When `overwrite` and `ignoreIfExists` are both set `overwrite` wins. * When both are unset and when the file already exists then the edit cannot - * be applied successfully. + * be applied successfully. The `content`-property allows to set the initial contents + * the file is being created with. * @param metadata Optional metadata for the entry. */ - function createFile(uri:Uri, ?options:{?overwrite:Bool, ?ignoreIfExists:Bool}, ?metadata:WorkspaceEditEntryMetadata):Void; + function createFile(uri:Uri, ?options:{ + /** + * Overwrite existing file. Overwrite wins over `ignoreIfExists` + */ + ?overwrite:Bool, + /** + * Do nothing if a file with `uri` exists already. + */ + ?ignoreIfExists:Bool, + /** + * The initial contents of the new file. + * + * If creating a file from a {@link DocumentDropEditProvider drop operation}, you can + * pass in a {@link DataTransferFile} to improve performance by avoiding extra data copying. + */ + ?contents:EitherType + }, ?metadata:WorkspaceEditEntryMetadata):Void; /** * Delete a file or folder. @@ -86,7 +129,16 @@ extern class WorkspaceEdit { * @param uri The uri of the file that is to be deleted. * @param metadata Optional metadata for the entry. */ - function deleteFile(uri:Uri, ?options:{?recursive:Bool, ?ignoreIfNotExists:Bool}, ?metadata:WorkspaceEditEntryMetadata):Void; + function deleteFile(uri:Uri, ?options:{ + /** + * Delete the content recursively if a folder is denoted. + */ + ?recursive:Bool, + /** + * Do nothing if a file with `uri` exists already. + */ + ?ignoreIfNotExists:Bool + }, ?metadata:WorkspaceEditEntryMetadata):Void; /** * Rename a file or folder. @@ -97,12 +149,21 @@ extern class WorkspaceEdit { * ignored. When overwrite and ignoreIfExists are both set overwrite wins. * @param metadata Optional metadata for the entry. */ - function renameFile(oldUri:Uri, newUri:Uri, ?options:{?overwrite:Bool, ?ignoreIfExists:Bool}, ?metadata:WorkspaceEditEntryMetadata):Void; + function renameFile(oldUri:Uri, newUri:Uri, ?options:{ + /** + * Overwrite existing file. Overwrite wins over `ignoreIfExists` + */ + ?overwrite:Bool, + /** + * Do nothing if a file with `uri` exists already. + */ + ?ignoreIfExists:Bool + }, ?metadata:WorkspaceEditEntryMetadata):Void; /** * Get all text edits grouped by resource. * - * @return A shallow copy of `[Uri, TextEdit[]]`-tuples. + * @returns A shallow copy of `[Uri, TextEdit[]]`-tuples. */ function entries():Array; } @@ -118,3 +179,27 @@ abstract WorkspaceEditEntriesTuple(Array) to Array { extern inline function get_edits():Array return this[1]; } + +@:dce +abstract WorkspaceEditMetadataTuple(Array) to Array { + public var edit(get, never):EitherType; + public var meta(get, never):Null; + + extern inline function get_edit():EitherType + return this[0]; + + extern inline function get_meta():Null + return this[1]; +} + +@:dce +abstract WorkspaceEditNotebookMetadataTuple(Array) to Array { + public var edit(get, never):NotebookEdit; + public var meta(get, never):Null; + + extern inline function get_edit():NotebookEdit + return this[0]; + + extern inline function get_meta():Null + return this[1]; +} diff --git a/src/vscode/WorkspaceEditEntryMetadata.hx b/src/vscode/WorkspaceEditEntryMetadata.hx index f28d6101..2d4748bd 100644 --- a/src/vscode/WorkspaceEditEntryMetadata.hx +++ b/src/vscode/WorkspaceEditEntryMetadata.hx @@ -24,5 +24,5 @@ typedef WorkspaceEditEntryMetadata = { /** * The icon path or {@link ThemeIcon} for the edit. */ - var ?iconPath:EitherType>; + var ?iconPath:IconPath; } diff --git a/src/vscode/WorkspaceEditMetadata.hx b/src/vscode/WorkspaceEditMetadata.hx new file mode 100644 index 00000000..f5c8cba9 --- /dev/null +++ b/src/vscode/WorkspaceEditMetadata.hx @@ -0,0 +1,11 @@ +package vscode; + +/** + * Additional data about a workspace edit. + */ +typedef WorkspaceEditMetadata = { + /** + * Signal to the editor that this edit is a refactoring. + */ + var ?isRefactoring:Bool; +} diff --git a/src/vscode/WorkspaceSymbolProvider.hx b/src/vscode/WorkspaceSymbolProvider.hx index 7b34f380..953017a6 100644 --- a/src/vscode/WorkspaceSymbolProvider.hx +++ b/src/vscode/WorkspaceSymbolProvider.hx @@ -19,7 +19,7 @@ typedef WorkspaceSymbolProvider = { * * @param query A query string, can be the empty string in which case all symbols should be returned. * @param token A cancellation token. - * @return An array of document highlights or a thenable that resolves to such. The lack of a result can be + * @returns An array of document highlights or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined`, `null`, or an empty array. */ function provideWorkspaceSymbols(query:String, token:CancellationToken):ProviderResult>; @@ -33,7 +33,7 @@ typedef WorkspaceSymbolProvider = { * @param symbol The symbol that is to be resolved. Guaranteed to be an instance of an object returned from an * earlier call to `provideWorkspaceSymbols`. * @param token A cancellation token. - * @return The resolved symbol or a thenable that resolves to that. When no result is returned, + * @returns The resolved symbol or a thenable that resolves to that. When no result is returned, * the given `symbol` is used. */ var ?resolveWorkspaceSymbol:(symbol:T, token:CancellationToken) -> ProviderResult;