Initial API of the semantic highlighting protocol extension.

Signed-off-by: Akos Kitta <kittaakos@typefox.io>

Author: Akos Kitta

client/src/main.ts

@@ -25,6 +25,7 @@ import { ConfigurationFeature as PullConfigurationFeature} from './configuration
 import { ImplementationFeature }  from './implementation'
 import { TypeDefinitionFeature } from './typeDefinition';
 import { WorkspaceFoldersFeature } from './workspaceFolders';
+// import { SemanticHighlightingFeature } from './semanticHighlighting.proposed';
 
 import * as Is from './utils/is';
 import * as electron from './utils/electron';
@@ -493,6 +494,7 @@ export class SettingMonitor {
 export namespace ProposedFeatures {
 	export function createAll(_client: BaseLanguageClient): (StaticFeature | DynamicFeature<any>)[] {
 		let result: (StaticFeature | DynamicFeature<any>)[] = [];
+		// result.push(new SemanticHighlightingFeature(_client));
 		return result;
 	}
 }

client/src/semanticHighlighting.proposed.ts

@@ -0,0 +1,99 @@
+/* --------------------------------------------------------------------------------------------
+ * Copyright (c) TypeFox. All rights reserved.
+ * Licensed under the MIT License. See License.txt in the project root for license information.
+ * ------------------------------------------------------------------------------------------ */
+'use strict';
+
+import { Disposable, Uri, Range, window, DecorationRenderOptions, TextEditorDecorationType, workspace, TextEditor } from 'vscode';
+import {
+	TextDocumentRegistrationOptions, ClientCapabilities, ServerCapabilities, DocumentSelector, NotificationHandler,
+	SemanticHighlightingNotification, SemanticHighlightingParams, SemanticHighlightingInformation
+} from 'vscode-languageserver-protocol';
+
+import * as UUID from './utils/uuid';
+import { TextDocumentFeature, BaseLanguageClient } from './client';
+
+export class SemanticHighlightingFeature extends TextDocumentFeature<TextDocumentRegistrationOptions> {
+
+	protected readonly toDispose: Disposable[];
+	protected readonly decorations: Map<string, any>;
+	protected readonly handlers: NotificationHandler<SemanticHighlightingParams>[];
+
+	constructor(client: BaseLanguageClient) {
+		super(client, SemanticHighlightingNotification.type);
+		this.toDispose = [];
+		this.decorations = new Map();
+		this.handlers = [];
+		this.toDispose.push({ dispose: () => this.decorations.clear() });
+		this.toDispose.push(workspace.onDidCloseTextDocument(e => {
+			const uri = e.uri.toString();
+			if (this.decorations.has(uri)) {
+				// TODO: do the proper disposal of the decorations.
+				this.decorations.delete(uri);
+			}
+		}));
+	}
+
+	dispose(): void {
+		this.toDispose.forEach(disposable => disposable.dispose());
+		super.dispose();
+	}
+
+	fillClientCapabilities(capabilities: ClientCapabilities): void {
+		if (!!capabilities.textDocument) {
+			capabilities.textDocument = {};
+		}
+		capabilities.textDocument!.semanticHighlighting = true;
+	}
+
+	initialize(capabilities: ServerCapabilities, documentSelector: DocumentSelector): void {
+		console.log('TODO: Currently, the server capabilities are ignored.', capabilities);
+		if (documentSelector) {
+			const id = UUID.generateUuid();
+			this.register(this.messages, {
+				id,
+				registerOptions: Object.assign({}, { documentSelector })
+			});
+		}
+	}
+
+	protected registerLanguageProvider(options: TextDocumentRegistrationOptions): Disposable {
+		if (options.documentSelector === null) {
+			return new Disposable(() => { });
+		}
+		const handler = this.newNotificationHandler.bind(this)();
+		this._client.onNotification(SemanticHighlightingNotification.type, handler);
+		return new Disposable(() => {
+			const indexOf = this.handlers.indexOf(handler);
+			if (indexOf !== -1) {
+				this.handlers.splice(indexOf, 1);
+			}
+		})
+	}
+
+	protected newNotificationHandler(): NotificationHandler<SemanticHighlightingParams> {
+		return (params: SemanticHighlightingParams) => {
+			const editorPredicate = this.editorPredicate(params.uri);
+			window.visibleTextEditors.filter(editorPredicate).forEach(editor => this.applyDecorations(editor, params));
+		};
+	}
+
+	protected editorPredicate(uri: string): (editor: TextEditor) => boolean {
+		const predicateUri = Uri.parse(uri);
+		return (editor: TextEditor) => editor.document.uri.toString() === predicateUri.toString();
+	}
+
+	protected applyDecorations(editor: TextEditor, params: SemanticHighlightingParams): void {
+		console.log('TODO: Apply the decorations on the editor.', editor, params);
+	}
+
+	protected decorationType(options: DecorationRenderOptions = {}) {
+		return window.createTextEditorDecorationType(options);
+	}
+
+	protected map2Decoration(lines: SemanticHighlightingInformation[]): [TextEditorDecorationType, Range[]] {
+		console.log('TODO: Map the lines (and the tokens) to the desired decoration type.', lines);
+		return [this.decorationType(), []];
+	}
+
+}

protocol/src/protocol.semanticHighlighting.proposed.md

@@ -0,0 +1,89 @@
+#### Semantic Highlighting
+
+While the syntax highlighting are done on the client-side and can handle keywords, strings, and other low-level tokens from the grammar, it cannot adequately support complex coloring. Semantic highlighting information is calculated on the language server and pushed to the client as a notification. This notification carries information about the ranges that have to be colored. The desired coloring details are given as [TextMate scopes](https://manual.macromates.com/en/language_grammars) for each affected range. For the semantic highlighting information the following additions are proposed:
+
+_Client Capabilities_:
+
+Capability that has to be set by the language client if it can accept and process the semantic highlighting information received from the server.
+
+```ts
+/**
+ * The text document client capabilities.
+ */
+textDocument: {
+
+	/**
+	 * `true` if the client supports semantic highlighting support text documents. Otherwise, `false`. It is `false` by default.
+	 */
+	semanticHighlighting?: boolean;
+}
+```
+
+##### SemanticHighlighting Notification
+
+The `textDocument/semanticHighlighting` notification is pushed from the server to the client to inform the client about additional semantic highlighting information that has to be applied on the text document. It is the server's responsibility to decide which lines are included in the highlighting information. In other words, the server is capable of sending only a delta information. For instance, after opening the text document (`DidOpenTextDocumentNotification`) the server sends the semantic highlighting information for the entire document, but if the server receives a `DidChangeTextDocumentNotification`, it pushes the information only about the affected lines in the document.
+
+_Notification_:
+
+* method: 'workspace/semanticHighlighting'
+* params: `SemanticHighlightingParams` defined as follows:
+
+```ts
+/**
+ * Parameters for the semantic highlighting (server-side) push notification.
+ */
+export interface SemanticHighlightingParams {
+
+	/**
+	 * The URI for which semantic highlighting information is reported to.
+	 */
+	uri: string;
+
+	/**
+	 * An array of semantic highlighting information.
+	 */
+	lines: SemanticHighlightingInformation[];
+
+}
+
+/**
+ * Represents a semantic highlighting information that has to be applied on a specific line of the text document.
+ */
+export interface SemanticHighlightingInformation {
+
+	/**
+	 * The zero-based line position in the text document.
+	 */
+	line: number;
+
+	/**
+	 * An array of highlighting tokens for the current line in the text document.
+	 */
+	tokens: SemanticHighlightingToken[];
+
+}
+
+/**
+ * Representation of a single semantic highlighting token that has to be applied on a line of the text document.
+ */
+export interface SemanticHighlightingToken {
+
+	/**
+	 * The zero-based character offset on the line in a text document where this token applies. If negative, defaults to `0`.
+	 * If greater than the length of the current line, defaults to the end of the line.
+	 */
+	character: number;
+
+	/**
+	 * The length of the token. If negative, defaults to `0`. If the sum of the `character` and the `length` exceeds the length of the line,
+	 * it defaults back to the end of the line.
+	 */
+	length: number;
+
+	/**
+	 * An array of semantic highlighting [TextMate scopes](https://manual.macromates.com/en/language_grammars) for the current token.
+	 */
+	scopes: string[];
+
+}
+```

protocol/src/protocol.semanticHighlighting.proposed.ts

@@ -0,0 +1,90 @@
+/* --------------------------------------------------------------------------------------------
+ * Copyright (c) TypeFox. All rights reserved.
+ * Licensed under the MIT License. See License.txt in the project root for license information.
+ * ------------------------------------------------------------------------------------------ */
+'use strict';
+
+import { NotificationType } from 'vscode-jsonrpc';
+
+/**
+ * Parameters for the semantic highlighting (server-side) push notification.
+ */
+export interface SemanticHighlightingParams {
+
+	/**
+	 * The URI for which semantic highlighting information is reported to.
+	 */
+	uri: string;
+
+	/**
+	 * An array of semantic highlighting information.
+	 */
+	lines: SemanticHighlightingInformation[];
+
+}
+
+/**
+ * Represents a semantic highlighting information that has to be applied on a specific line of the text document.
+ */
+export interface SemanticHighlightingInformation {
+
+	/**
+	 * The zero-based line position in the text document.
+	 */
+	line: number;
+
+	/**
+	 * An array of highlighting tokens for the current line in the text document.
+	 */
+	tokens: SemanticHighlightingToken[];
+
+}
+
+/**
+ * Representation of a single semantic highlighting token that has to be applied on a line of the text document.
+ */
+export interface SemanticHighlightingToken {
+
+	/**
+	 * The zero-based character offset on the line in a text document where this token applies. If negative, defaults to `0`.
+	 * If greater than the length of the current line, defaults to the end of the line.
+	 */
+	character: number;
+
+	/**
+	 * The length of the token. If negative, defaults to `0`. If the sum of the `character` and the `length` exceeds the length of the line,
+	 * it defaults back to the end of the line.
+	 */
+	length: number;
+
+	/**
+	 * An array of semantic highlighting [TextMate scopes](https://manual.macromates.com/en/language_grammars) for the current token.
+	 */
+	scopes: string[];
+
+}
+
+/**
+ * Language server push notification providing the semantic highlighting information for a text document.
+ */
+export namespace SemanticHighlightingNotification {
+	export const type = new NotificationType<SemanticHighlightingParams, void>('textDocument/semanticHighlighting');
+}
+
+/**
+ * Capability that has to be set by the language client if that supports the semantic highlighting feature for the text documents.
+ */
+export interface SemanticHighlightingClientCapabilities {
+
+	/**
+	 * The text document client capabilities.
+	 */
+	textDocument?: {
+
+		/**
+		 * `true` if the client supports semantic highlighting support text documents. Otherwise, `false`. It is `false` by default.
+		 */
+		semanticHighlighting?: boolean;
+
+	}
+}

protocol/src/protocol.ts

@@ -30,6 +30,10 @@ import {
 	Color, ColorInformation, ColorPresentation, ColorServerCapabilities, ColorClientCapabilities,
 } from './protocol.colorProvider';
 
+import {
+	SemanticHighlightingNotification, SemanticHighlightingParams, SemanticHighlightingInformation, SemanticHighlightingToken, SemanticHighlightingClientCapabilities
+} from './protocol.semanticHighlighting.proposed';
+
 /**
  * A document filter denotes a document by different properties like
  * the [language](#TextDocument.languageId), the [scheme](#Uri.scheme) of
@@ -545,7 +549,7 @@ export interface _ClientCapabilities {
 }
 
 export type ClientCapabilities = _ClientCapabilities & ImplementationClientCapabilities & TypeDefinitionClientCapabilities &
-	WorkspaceFoldersClientCapabilities & ConfigurationClientCapabilities & ColorClientCapabilities;
+	WorkspaceFoldersClientCapabilities & ConfigurationClientCapabilities & ColorClientCapabilities & SemanticHighlightingClientCapabilities;
 
 /**
  * Defines how the host (editor) should sync
@@ -1786,5 +1790,6 @@ export {
 	TypeDefinitionRequest,
 	WorkspaceFoldersRequest, DidChangeWorkspaceFoldersNotification, DidChangeWorkspaceFoldersParams, WorkspaceFolder, WorkspaceFoldersChangeEvent,
 	ConfigurationRequest, ConfigurationParams, ConfigurationItem,
-	DocumentColorRequest, ColorPresentationRequest, ColorProviderOptions, DocumentColorParams, ColorPresentationParams, Color, ColorInformation, ColorPresentation
+	DocumentColorRequest, ColorPresentationRequest, ColorProviderOptions, DocumentColorParams, ColorPresentationParams, Color, ColorInformation, ColorPresentation,
+	SemanticHighlightingNotification, SemanticHighlightingParams, SemanticHighlightingInformation, SemanticHighlightingToken
 };