Skip to content

Commit

Permalink
Initial API of the semantic highlighting protocol extension.
Browse files Browse the repository at this point in the history
Signed-off-by: Akos Kitta <[email protected]>
  • Loading branch information
Akos Kitta committed Jul 2, 2018
1 parent 6d8ddcc commit e773d7c
Show file tree
Hide file tree
Showing 5 changed files with 287 additions and 2 deletions.
2 changes: 2 additions & 0 deletions client/src/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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;
}
}
99 changes: 99 additions & 0 deletions client/src/semanticHighlighting.proposed.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
/* --------------------------------------------------------------------------------------------
* Copyright (c) Microsoft Corporation. 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(), []];
}

}
89 changes: 89 additions & 0 deletions protocol/src/protocol.semanticHighlighting.proposed.md
Original file line number Diff line number Diff line change
@@ -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[];

}
```
90 changes: 90 additions & 0 deletions protocol/src/protocol.semanticHighlighting.proposed.ts
Original file line number Diff line number Diff line change
@@ -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;

}
}
9 changes: 7 additions & 2 deletions protocol/src/protocol.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
};

0 comments on commit e773d7c

Please sign in to comment.