@jupyterlab/lsp 4.0.0-alpha.19 → 4.0.0-alpha.21

package/src/extractors/manager.ts

@@ -0,0 +1,84 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { ILSPCodeExtractorsManager } from '../tokens';
+import { IForeignCodeExtractor } from './types';
+
+/**
+ * Manager for the code extractors
+ */
+export class CodeExtractorsManager implements ILSPCodeExtractorsManager {
+  constructor() {
+    this._extractorMap = new Map<
+      string,
+      Map<string, IForeignCodeExtractor[]>
+    >();
+
+    this._extractorMapAnyLanguage = new Map<string, IForeignCodeExtractor[]>();
+  }
+
+  /**
+   * Get the extractors for the input cell type and the main language of
+   * the document
+   *
+   * @param  cellType - type of cell
+   * @param  hostLanguage - main language of the document
+   */
+  getExtractors(
+    cellType: string,
+    hostLanguage: string | null
+  ): IForeignCodeExtractor[] {
+    if (hostLanguage) {
+      const currentMap = this._extractorMap.get(cellType);
+      if (!currentMap) {
+        return [];
+      }
+      return currentMap!.get(hostLanguage) ?? [];
+    } else {
+      return this._extractorMapAnyLanguage.get(cellType) ?? [];
+    }
+  }
+
+  /**
+   * Register an extractor to extract foreign code from host documents of specified language.
+   */
+  register(
+    extractor: IForeignCodeExtractor,
+    hostLanguage: string | null
+  ): void {
+    const cellType = extractor.cellType;
+    if (hostLanguage) {
+      cellType.forEach(type => {
+        if (!this._extractorMap.has(type)) {
+          this._extractorMap.set(type, new Map());
+        }
+        const currentMap = this._extractorMap.get(type)!;
+        const extractorList = currentMap.get(hostLanguage);
+        if (!extractorList) {
+          currentMap.set(hostLanguage, [extractor]);
+        } else {
+          extractorList.push(extractor);
+        }
+      });
+    } else {
+      cellType.forEach(type => {
+        if (!this._extractorMapAnyLanguage.has(type)) {
+          this._extractorMapAnyLanguage.set(type, []);
+        }
+        this._extractorMapAnyLanguage.get(type)!.push(extractor);
+      });
+    }
+  }
+
+  /**
+   * The map with key is the type of cell, value is another map between
+   * the language of cell and its code extractor.
+   */
+  private _extractorMap: Map<string, Map<string, IForeignCodeExtractor[]>>;
+
+  /**
+   * The map with key is the cell type, value is the code extractor associated
+   * with this cell type, this is used for the non-code cell types.
+   */
+  private _extractorMapAnyLanguage: Map<string, IForeignCodeExtractor[]>;
+}

package/src/extractors/text_extractor.ts

@@ -0,0 +1,94 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { LanguageIdentifier } from '../lsp';
+import { positionAtOffset } from '../positioning';
+
+import { IExtractedCode, IForeignCodeExtractor } from './types';
+
+/**
+ * The code extractor for the raw and markdown text.
+ */
+export class TextForeignCodeExtractor implements IForeignCodeExtractor {
+  constructor(options: TextForeignCodeExtractor.IOptions) {
+    this.language = options.language;
+    this.standalone = options.isStandalone;
+    this.fileExtension = options.file_extension;
+    this.cellType = options.cellType;
+  }
+  /**
+   * The foreign language.
+   */
+  readonly language: LanguageIdentifier;
+
+  /**
+   * Should the foreign code be appended (False) to the previously established virtual document of the same language,
+   * or is it standalone snippet which requires separate connection?
+   */
+  readonly standalone: boolean;
+
+  /**
+   * Extension of the virtual document (some servers check extensions of files), e.g. 'py' or 'R'.
+   */
+  readonly fileExtension: string;
+
+  /**
+   * The supported cell types.
+   */
+  readonly cellType: string[];
+
+  /**
+   * Test if there is any foreign code in provided code snippet.
+   */
+  hasForeignCode(code: string, cellType: string): boolean {
+    return this.cellType.includes(cellType);
+  }
+
+  /**
+   * Split the code into the host and foreign code (if any foreign code was detected)
+   */
+  extractForeignCode(code: string): IExtractedCode[] {
+    let lines = code.split('\n');
+
+    let extracts = new Array<IExtractedCode>();
+
+    let foreignCodeFragment = code;
+
+    let start = positionAtOffset(0, lines);
+    let end = positionAtOffset(foreignCodeFragment.length, lines);
+
+    extracts.push({
+      hostCode: '',
+      foreignCode: foreignCodeFragment,
+      range: { start, end },
+      virtualShift: null
+    });
+
+    return extracts;
+  }
+}
+
+namespace TextForeignCodeExtractor {
+  export interface IOptions {
+    /**
+     * The foreign language.
+     */
+    language: string;
+
+    /**
+     * Should the foreign code be appended (False) to the previously established virtual document of the same language,
+     * or is it standalone snippet which requires separate connection?
+     */
+    isStandalone: boolean;
+
+    /**
+     * Extension of the virtual document (some servers check extensions of files), e.g. 'py' or 'R'.
+     */
+    file_extension: string;
+
+    /**
+     * The supported cell types.
+     */
+    cellType: string[];
+  }
+}

package/src/extractors/types.ts

@@ -0,0 +1,78 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { CodeEditor } from '@jupyterlab/codeeditor';
+
+import { LanguageIdentifier } from '../lsp';
+
+export interface IExtractedCode {
+  /**
+   * Foreign code (may be empty, for example line of '%R') or null if none.
+   */
+  foreignCode: string | null;
+  /**
+   * Range of the foreign code relative to the original source.
+   * `null` is used internally to represent a leftover host code after extraction.
+   */
+  range: CodeEditor.IRange | null;
+  /**
+   * Shift due to any additional code inserted at the beginning of the virtual document
+   * (usually in order to mock the arguments passed to a magic, or to provide other context clues for the linters)
+   */
+  virtualShift: CodeEditor.IPosition | null;
+  /**
+   * Code to be retained in the virtual document of the host.
+   */
+  hostCode: string | null;
+}
+
+/**
+ * Foreign code extractor makes it possible to analyze code of language X embedded in code (or notebook) of language Y.
+ *
+ * The typical examples are:
+ *  - (X=CSS< Y=HTML), or
+ *  - (X=JavaScript, Y=HTML),
+ *
+ * while in the data analysis realm, examples include:
+ *   - (X=R, Y=IPython),
+ *   - (X=LATEX Y=IPython),
+ *   - (X=SQL, Y=IPython)
+ *
+ * This extension does not aim to provide comprehensive abilities for foreign code extraction,
+ * but it does intend to provide stable interface for other extensions to build on it.
+ *
+ * A simple, regular expression based, configurable foreign extractor is implemented
+ * to provide a good reference and a good initial experience for the users.
+ */
+export interface IForeignCodeExtractor {
+  /**
+   * The foreign language.
+   */
+  readonly language: LanguageIdentifier;
+
+  /**
+   * The supported cell types.
+   */
+  readonly cellType: string[];
+
+  /**
+   * Split the code into the host and foreign code (if any foreign code was detected)
+   */
+  extractForeignCode(code: string): IExtractedCode[];
+
+  /**
+   * Does the extractor produce code which should be appended to the previously established virtual document (False)
+   * of the same language, or does it produce standalone snippets which require separate connections (True)?
+   */
+  readonly standalone: boolean;
+
+  /**
+   * Test if there is any foreign code in provided code snippet.
+   */
+  hasForeignCode(code: string, cellType: string): boolean;
+
+  /**
+   * Extension of the virtual document (some servers check extensions of files), e.g. 'py' or 'R'.
+   */
+  readonly fileExtension: string;
+}

package/src/feature.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { ISignal, Signal } from '@lumino/signaling';
+import mergeWith from 'lodash.mergewith';
+
+import { ClientCapabilities } from './lsp';
+import { IFeature, ILSPFeatureManager } from './tokens';
+
+/**
+ * Class to manager the registered features of the language servers.
+ */
+export class FeatureManager implements ILSPFeatureManager {
+  constructor() {
+    this._featuresRegistered = new Signal(this);
+  }
+  /**
+   * List of registered features
+   */
+  readonly features: Array<IFeature> = [];
+
+  /**
+   * Signal emitted when a new feature is registered.
+   */
+  get featuresRegistered(): ISignal<ILSPFeatureManager, IFeature> {
+    return this._featuresRegistered;
+  }
+
+  /**
+   * Register a new feature, skip if it is already registered.
+   */
+  register(feature: IFeature): void {
+    if (this.features.some(ft => ft.id === feature.id)) {
+      console.warn(
+        `Feature with id ${feature.id} is already registered, skipping.`
+      );
+    } else {
+      this.features.push(feature);
+      this._featuresRegistered.emit(feature);
+    }
+  }
+
+  /**
+   * Get the capabilities of all clients.
+   */
+  clientCapabilities(): ClientCapabilities {
+    let capabilities: ClientCapabilities = {};
+    for (const feature of this.features) {
+      if (!feature.capabilities) {
+        continue;
+      }
+      capabilities = mergeWith(capabilities, feature.capabilities);
+    }
+    return capabilities;
+  }
+
+  private _featuresRegistered: Signal<ILSPFeatureManager, IFeature>;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+/**
+ * @packageDocumentation
+ * @module lsp
+ */
+
+export * from './adapters/adapter';
+export * from './connection_manager';
+export * from './extractors';
+export * from './feature';
+export * from './manager';
+export * from './plugin';
+export * from './positioning';
+export * from './tokens';
+export * from './utils';
+export * from './virtual/document';

package/src/lsp.ts

@@ -0,0 +1,160 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import type * as lsp from 'vscode-languageserver-protocol';
+
+export type ClientCapabilities = lsp.ClientCapabilities;
+
+export enum DiagnosticSeverity {
+  Error = 1,
+  Warning = 2,
+  Information = 3,
+  Hint = 4
+}
+
+export enum DiagnosticTag {
+  Unnecessary = 1,
+  Deprecated = 2
+}
+
+export enum CompletionItemTag {
+  Deprecated = 1
+}
+
+export enum CompletionItemKind {
+  Text = 1,
+  Method = 2,
+  Function = 3,
+  Constructor = 4,
+  Field = 5,
+  Variable = 6,
+  Class = 7,
+  Interface = 8,
+  Module = 9,
+  Property = 10,
+  Unit = 11,
+  Value = 12,
+  Enum = 13,
+  Keyword = 14,
+  Snippet = 15,
+  Color = 16,
+  File = 17,
+  Reference = 18,
+  Folder = 19,
+  EnumMember = 20,
+  Constant = 21,
+  Struct = 22,
+  Event = 23,
+  Operator = 24,
+  TypeParameter = 25
+}
+
+export enum DocumentHighlightKind {
+  Text = 1,
+  Read = 2,
+  Write = 3
+}
+
+export enum CompletionTriggerKind {
+  Invoked = 1,
+  TriggerCharacter = 2,
+  TriggerForIncompleteCompletions = 3
+}
+
+export enum AdditionalCompletionTriggerKinds {
+  AutoInvoked = 9999
+}
+
+export type ExtendedCompletionTriggerKind =
+  | CompletionTriggerKind
+  | AdditionalCompletionTriggerKinds;
+
+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;
+
+/**
+ * Type represents a location inside a resource, such as a line
+ * inside a text file.
+ */
+export type AnyLocation =
+  | lsp.Location
+  | lsp.Location[]
+  | lsp.LocationLink[]
+  | undefined
+  | null;
+
+/**
+ * Type represents the completion result.
+ */
+export type AnyCompletion = lsp.CompletionList | lsp.CompletionItem[];