Document preferred language ids and register() methods

Author: krassowski

packages/jupyterlab-lsp/src/adapters/adapter.ts

@@ -17,6 +17,7 @@ import { ILSPExtension } from '../index';
 import { IFeatureEditorIntegration, IFeature } from '../feature';
 import { EditorAdapter } from '../editor_integration/editor_adapter';
 import IEditor = CodeEditor.IEditor;
+import { LanguageIdentifier } from '../lsp';
 
 export class StatusMessage {
   /**
@@ -195,8 +196,9 @@ export abstract class WidgetAdapter<T extends IDocumentWidget> {
     return this.widget.id;
   }
 
-  get language(): string {
-    // the values should follow https://microsoft.github.io/language-server-protocol/specification guidelines
+  get language(): LanguageIdentifier {
+    // the values should follow https://microsoft.github.io/language-server-protocol/specification guidelines,
+    // see the table in https://microsoft.github.io/language-server-protocol/specification#textDocumentItem
     if (mime_type_language_map.hasOwnProperty(this.mime_type)) {
       return mime_type_language_map[this.mime_type] as string;
     } else {

packages/jupyterlab-lsp/src/extractors/manager.ts

@@ -9,6 +9,9 @@ export class CodeExtractorsManager implements ILSPCodeExtractorsManager {
     this.registry = {};
   }
 
+  /**
+   * Register an extractor to extract foreign code from host documents of specified language.
+   */
   register(extractor: IForeignCodeExtractor, host_language: string): void {
     if (!this.registry.hasOwnProperty(host_language)) {
       this.registry[host_language] = [];

packages/jupyterlab-lsp/src/extractors/types.ts

@@ -1,4 +1,5 @@
 import { CodeEditor } from '@jupyterlab/codeeditor';
+import { LanguageIdentifier } from '../lsp';
 
 export interface IExtractedCode {
   /**
@@ -40,9 +41,9 @@ export interface IExtractedCode {
  */
 export interface IForeignCodeExtractor {
   /**
-   * The foreign language. TODO what is language, what is host language, ILanguageInfo
+   * The foreign language.
    */
-  language: string;
+  language: LanguageIdentifier;
 
   /**
    * Split the code into the host and foreign code (if any foreign code was detected)

packages/jupyterlab-lsp/src/lsp.ts

@@ -46,3 +46,75 @@ export enum CompletionTriggerKind {
 }
 
 export type CompletionItemKindStrings = keyof typeof CompletionItemKind;
+
+/**
+ * The language identifier for LSP, with the preferred identifier as defined in the documentation
+ * see the table in https://microsoft.github.io/language-server-protocol/specification#textDocumentItem
+ */
+export enum Languages {
+  'abap' = 'ABAP',
+  'bat' = 'Windows Bat',
+  'bibtex' = 'BibTeX',
+  'clojure' = 'Clojure',
+  'coffeescript' = 'Coffeescript',
+  'c' = 'C',
+  'cpp' = 'C++',
+  'csharp' = 'C#',
+  'css' = 'CSS',
+  'diff' = 'Diff',
+  'dart' = 'Dart',
+  'dockerfile' = 'Dockerfile',
+  'elixir' = 'Elixir',
+  'erlang' = 'Erlang',
+  'fsharp' = 'F#',
+  'git-commit' = 'Git (commit)',
+  'git-rebase' = 'Git (rebase)',
+  'go' = 'Go',
+  'groovy' = 'Groovy',
+  'handlebars' = 'Handlebars',
+  'html' = 'HTML',
+  'ini' = 'Ini',
+  'java' = 'Java',
+  'javascript' = 'JavaScript',
+  'javascriptreact' = 'JavaScript React',
+  'json' = 'JSON',
+  'latex' = 'LaTeX',
+  'less' = 'Less',
+  'lua' = 'Lua',
+  'makefile' = 'Makefile',
+  'markdown' = 'Markdown',
+  'objective-c' = 'Objective-C',
+  'objective-cpp' = 'Objective-C++',
+  'perl' = 'Perl',
+  'perl6' = 'Perl 6',
+  'php' = 'PHP',
+  'powershell' = 'Powershell',
+  'jade' = 'Pug',
+  'python' = 'Python',
+  'r' = 'R',
+  'razor' = 'Razor (cshtml)',
+  'ruby' = 'Ruby',
+  'rust' = 'Rust',
+  'scss' = 'SCSS (syntax using curly brackets)',
+  'sass' = 'SCSS (indented syntax)',
+  'scala' = 'Scala',
+  'shaderlab' = 'ShaderLab',
+  'shellscript' = 'Shell Script (Bash)',
+  'sql' = 'SQL',
+  'swift' = 'Swift',
+  'typescript' = 'TypeScript',
+  'typescriptreact' = 'TypeScript React',
+  'tex' = 'TeX',
+  'vb' = 'Visual Basic',
+  'xml' = 'XML',
+  'xsl' = 'XSL',
+  'yaml' = 'YAML'
+}
+
+export type RecommendedLanguageIdentifier = keyof typeof Languages;
+
+/**
+ * Language identifier for the LSP server, allowing any string but preferring
+ * the identifiers as recommended by the LSP documentation.
+ */
+export type LanguageIdentifier = RecommendedLanguageIdentifier | string;

packages/jupyterlab-lsp/src/overrides/tokens.ts

@@ -1,5 +1,6 @@
 import { PLUGIN_ID } from '../tokens';
 import { Token } from '@lumino/coreutils';
+import { LanguageIdentifier } from '../lsp';
 
 export type replacer = (...args: string[]) => string;
 
@@ -44,7 +45,10 @@ export interface IScopedCodeOverride extends ICodeOverride {
  */
 export interface ILSPCodeOverridesManager {
   readonly registry: ICodeOverridesRegistry;
-  register(override: IScopedCodeOverride, language: string): void;
+  /**
+   * Register a code override to replace code fragments in documents of specified language.
+   */
+  register(override: IScopedCodeOverride, language: LanguageIdentifier): void;
 }
 
 export const ILSPCodeOverridesManager = new Token<ILSPCodeOverridesManager>(

packages/jupyterlab-lsp/src/tokens.ts

@@ -21,6 +21,7 @@ import {
   IForeignCodeExtractor,
   IForeignCodeExtractorsRegistry
 } from './extractors/types';
+import { LanguageIdentifier } from './lsp';
 
 export type TLanguageServerId = string;
 export type TLanguageId = string;
@@ -173,7 +174,10 @@ export interface ILSPCodeExtractorsManager {
   /**
    * Register the extraction rules to be applied in documents with language `host_language`.
    */
-  register(extractor: IForeignCodeExtractor, host_language: string): void;
+  register(
+    extractor: IForeignCodeExtractor,
+    host_language: LanguageIdentifier
+  ): void;
 }
 
 export const PLUGIN_ID = '@krassowski/jupyterlab-lsp';

packages/jupyterlab-lsp/src/virtual/document.ts

@@ -17,6 +17,7 @@ import { DocumentConnectionManager } from '../connection_manager';
 import { create_console, EditorLogConsole } from './console';
 import IRange = CodeEditor.IRange;
 import { ReversibleOverridesMap } from '../overrides/maps';
+import { LanguageIdentifier } from '../lsp';
 
 type language = string;
 
@@ -124,11 +125,17 @@ export class VirtualDocumentInfo implements IDocumentInfo {
 
 export namespace VirtualDocument {
   export interface IOptions {
-    language: string;
+    language: LanguageIdentifier;
     foreign_code_extractors: IForeignCodeExtractorsRegistry;
     overrides_registry: ICodeOverridesRegistry;
     path: string;
     file_extension: string;
+    /**
+     * Notebooks or any other aggregates of documents are not supported
+     * by the LSP specification, and we need to make appropriate
+     * adjustments for them, pretending they are simple files
+     * so that the LSP servers do not refuse to cooperate.
+     */
     has_lsp_supported_file: boolean;
     /**
      * Being standalone is relevant to foreign documents