@theia/plugin 1.28.0-next.9 → 1.29.0-next.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.28.0-next.9+c0ee4dcf6bb",
+  "version": "1.29.0-next.10+c617a60355d",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -27,10 +27,10 @@
     "watch": "theiaext watch"
   },
   "devDependencies": {
-    "@theia/ext-scripts": "1.27.0"
+    "@theia/ext-scripts": "1.28.0"
   },
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "c0ee4dcf6bb10be905cc5a58d04b10faa3800d67"
+  "gitHead": "c617a60355d5cbfaf1fecb3554cda9329eeeb1f9"
 }

package/src/theia.d.ts

@@ -617,7 +617,7 @@ export module '@theia/plugin' {
      * Provides additional metadata over normal [location](#Location) definitions, including the range of
      * the defining symbol
      */
-    export interface DefinitionLink {
+    export interface LocationLink {
         /**
          * Span of the symbol being defined in the source file.
          *
@@ -2300,6 +2300,11 @@ export module '@theia/plugin' {
      * Options for configuration behavior of the quick pick
      */
     export interface QuickPickOptions {
+        /**
+         * An optional string that represents the title of the quick pick.
+         */
+        title?: string;
+
         /**
          * A flag to include the description when filtering
          */
@@ -3464,6 +3469,13 @@ export module '@theia/plugin' {
      */
     export interface Memento {
 
+        /**
+         * Returns the stored keys.
+         *
+         * @return The stored keys.
+         */
+        keys(): readonly string[];
+
         /**
          * Return a value.
          *
@@ -5635,12 +5647,14 @@ export module '@theia/plugin' {
          * Returns `true` if the given section for the given resource (if provided) is affected.
          *
          * @param section Configuration name, supports _dotted_ names.
-         * @param resource A resource Uri.
+         * @param scope a {@link ConfigurationScope}
          * @return `true` if the given section for the given resource (if provided) is affected.
          */
-        affectsConfiguration(section: string, resource?: Uri): boolean;
+        affectsConfiguration(section: string, scope?: ConfigurationScope): boolean;
     }
 
+    export type ConfigurationScope = Uri | WorkspaceFolder | TextDocument | { uri?: Uri, languageId: string };
+
     /**
      * An event describing a change to the set of [workspace folders](#workspace.workspaceFolders).
      */
@@ -6295,13 +6309,13 @@ export module '@theia/plugin' {
          * is returned. Dots in the section-identifier are interpreted as child-access,
          * like `{ myExt: { setting: { doIt: true }}}` and `getConfiguration('myExt.setting').get('doIt') === true`.
          *
-         * When a resource is provided, configuration scoped to that resource is returned.
+         * When a scope is provided configuration confined to that scope is returned. Scope can be a resource or a language identifier or both.
          *
          * @param section A dot-separated identifier.
-         * @param resource A resource for which the configuration is asked for
+         * @param scope A scope for which the configuration is asked for.
          * @return The full configuration or a subset.
          */
-        export function getConfiguration(section?: string, resource?: Uri | null): WorkspaceConfiguration;
+        export function getConfiguration(section?: string, scope?: ConfigurationScope | null): WorkspaceConfiguration;
 
         /**
          * An event that is emitted when the [configuration](#WorkspaceConfiguration) changed.
@@ -6528,6 +6542,14 @@ export module '@theia/plugin' {
          */
         export const appRoot: string;
 
+        /**
+         * 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
+         */
+        export const appHost: string;
+
         /**
          * The custom uri scheme the editor registers to in the operating system.
          */
@@ -6538,6 +6560,35 @@ export module '@theia/plugin' {
          */
         export const language: string;
 
+        /**
+         * Indicates that this is a fresh install of the application.
+         * `true` if within the first day of installation otherwise `false`.
+         */
+        export const isNewAppInstall: boolean;
+
+        /**
+         * Indicates whether the users has telemetry enabled.
+         * Can be observed to determine if the extension should send telemetry.
+         */
+        export const isTelemetryEnabled: boolean;
+
+        /**
+         * An {@link Event} which fires when the user enabled or disables telemetry.
+         * `true` if the user has enabled telemetry or `false` if the user has disabled telemetry.
+         */
+        export const onDidChangeTelemetryEnabled: Event<boolean>;
+
+        /**
+         * 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.
+         *
+         * *Note* that the value is `undefined` when there is no remote extension host but that the
+         * value is defined in all extension hosts (local and remote) in case a remote extension host
+         * exists. Use {@link Extension.extensionKind} to know if
+         * a specific extension runs remote or not.
+         */
+        export const remoteName: string | undefined;
+
         /**
          * The detected default shell for the extension host.
          */
@@ -6889,6 +6940,13 @@ export module '@theia/plugin' {
          */
         parameters: ParameterInformation[];
 
+        /**
+         * The index of the active parameter.
+         *
+         * If provided, this is used in place of SignatureHelp.activeParameter.
+         */
+        activeParameter?: number;
+
         /**
          * Creates a new signature information object.
          *
@@ -7840,10 +7898,12 @@ export module '@theia/plugin' {
     }
 
     /**
-     * Represents the connection of two locations. Provides additional metadata over normal {@link Location locations},
-     * including an origin range.
+     * Information about where a symbol is defined.
+     *
+     * Provides additional metadata over normal {@link Location} definitions, including the range of
+     * the defining symbol
      */
-    export type LocationLink = DefinitionLink;
+    export type DefinitionLink = LocationLink;
 
     /**
      * The declaration of a symbol representation as one or many {@link Location locations}
@@ -9216,6 +9276,18 @@ export module '@theia/plugin' {
          */
         export function registerHoverProvider(selector: DocumentSelector, provider: HoverProvider): Disposable;
 
+        /**
+         * Register a provider that locates evaluatable expressions in text documents.
+         * The editor will evaluate the expression in the active debug session and will show the result in the debug hover.
+         *
+         * If multiple providers are registered for a language an arbitrary provider will be used.
+         *
+         * @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.
+         */
+        export function registerEvaluatableExpressionProvider(selector: DocumentSelector, provider: EvaluatableExpressionProvider): Disposable;
+
         /**
          * Register a workspace symbol provider.
          *
@@ -9529,6 +9601,54 @@ export module '@theia/plugin' {
         provideHover(document: TextDocument, position: Position, token: CancellationToken | undefined): ProviderResult<Hover>;
     }
 
+    /**
+     * An EvaluatableExpression represents an expression in a document that can be evaluated by an active debugger or runtime.
+     * The result of this evaluation is shown in a tooltip-like widget.
+     * If only a range is specified, the expression will be extracted from the underlying document.
+     * An optional expression can be used to override the extracted expression.
+     * In this case the range is still used to highlight the range in the document.
+     */
+    export class EvaluatableExpression {
+
+        /*
+         * The range is used to extract the evaluatable expression from the underlying document and to highlight it.
+         */
+        readonly range: Range;
+
+        /*
+         * If specified the expression overrides the extracted expression.
+         */
+        readonly expression?: string | undefined;
+
+        /**
+         * Creates a new evaluatable expression object.
+         *
+         * @param range The range in the underlying document from which the evaluatable expression is extracted.
+         * @param expression If specified overrides the extracted expression.
+         */
+        constructor(range: Range, expression?: string);
+    }
+
+    /**
+     * The evaluatable expression provider interface defines the contract between extensions and
+     * the debug hover. In this contract the provider returns an evaluatable expression for a given position
+     * in a document and the editor evaluates this expression in the active debug session and shows the result in a debug hover.
+     */
+    export interface EvaluatableExpressionProvider {
+        /**
+         * Provide an evaluatable expression for the given document and position.
+         * The editor will evaluate this expression in the active debug session and will show the result in the debug hover.
+         * The expression can be implicitly specified by the range in the underlying document or by explicitly returning an expression.
+         *
+         * @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
+         * signaled by returning `undefined` or `null`.
+         */
+        provideEvaluatableExpression(document: TextDocument, position: Position, token: CancellationToken | undefined): ProviderResult<EvaluatableExpression>;
+    }
+
     /**
      * A document highlight kind.
      */
@@ -9609,6 +9729,11 @@ export module '@theia/plugin' {
          * A string to show as place holder in the input box to guide the user.
          */
         placeholder: string;
+
+        /**
+         * Controls whether the input box is visible (default is true).
+         */
+        visible: boolean;
     }
 
     interface QuickDiffProvider {
@@ -9851,6 +9976,20 @@ export module '@theia/plugin' {
         // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_ProtocolMessage).
     }
 
+    /**
+     * 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.
+     */
+    export interface DebugProtocolBreakpoint {
+        // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Breakpoint)
+    }
+
+    /**
+     * 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.
+     */
+    export interface DebugProtocolSource {
+        // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source)
+    }
+
     /**
      * Configuration for a debug session.
      */
@@ -9910,6 +10049,15 @@ export module '@theia/plugin' {
          * Send a custom request to the debug adapter.
          */
         customRequest(command: string, args?: any): Thenable<any>;
+
+        /**
+         * Maps a breakpoint in the editor to the corresponding Debug Adapter Protocol (DAP) breakpoint that
+         * is managed by the debug adapter of the debug session. 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 Breakpoint in the editor.
+         */
+        getDebugProtocolBreakpoint(breakpoint: Breakpoint): PromiseLike<DebugProtocolBreakpoint | undefined>
     }
 
     /**
@@ -10385,6 +10533,16 @@ export module '@theia/plugin' {
          */
         export function registerDebugAdapterDescriptorFactory(debugType: string, factory: DebugAdapterDescriptorFactory): Disposable;
 
+        /**
+         * Converts a "Source" descriptor object received via the Debug Adapter Protocol into a Uri that can be used to load its contents.
+         * If the source descriptor is based on a path, a file Uri is returned. If the source descriptor uses a reference number, a
+         * specific debug Uri (scheme 'debug') is constructed that requires a corresponding ContentProvider and a running debug session
+         * If the "Source" descriptor has insufficient information for creating the Uri, an error is thrown.
+         * @param source An object conforming to the 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.
+         */
+        export function asDebugSourceUri(source: DebugProtocolSource, session?: DebugSession): Uri;
+
         /**
          * 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.