@jupyterlab/lsp 4.0.0-alpha.11 → 4.0.0-alpha.12

package/lib/virtual/document.d.ts

@@ -1,12 +1,12 @@
-import { IDocumentInfo } from 'lsp-ws-connection';
+import { IDisposable } from '@lumino/disposable';
+import { IDocumentInfo } from '../ws-connection/types';
+import { IPosition } from '../positioning';
 import { CodeEditor } from '@jupyterlab/codeeditor';
-import { CellType } from '@jupyterlab/nbformat';
-import { Signal } from '@lumino/signaling';
+import { ISignal } from '@lumino/signaling';
 import { ILSPCodeExtractorsManager } from '../';
 import { LanguageIdentifier } from '../lsp';
 import { IEditorPosition, IRootPosition, ISourcePosition, IVirtualPosition } from '../positioning';
 import { DefaultMap } from '../utils';
-import type * as CodeMirror from 'codemirror';
 declare type IRange = CodeEditor.IRange;
 declare type language = string;
 interface IVirtualLine {
@@ -18,26 +18,56 @@ interface IVirtualLine {
      * Where does the virtual line belongs to in the source document?
      */
     sourceLine: number | null;
+    /**
+     * The editor holding this virtual line
+     */
     editor: CodeEditor.IEditor;
 }
 export interface ICodeBlockOptions {
+    /**
+     * The editor holding this code block
+     */
     ceEditor: CodeEditor.IEditor;
+    /**
+     * The value of code block
+     */
     value: string;
-    type: CellType;
+    /**
+     * Type of the cell holding this block
+     */
+    type: string;
 }
 export interface IVirtualDocumentBlock {
     /**
      * Line corresponding to the block in the entire foreign document
      */
     virtualLine: number;
+    /**
+     * The virtual document holding this virtual line.
+     */
     virtualDocument: VirtualDocument;
+    /**
+     * The CM editor associated with this virtual line.
+     */
     editor: CodeEditor.IEditor;
 }
 export declare type ForeignDocumentsMap = Map<IRange, IVirtualDocumentBlock>;
 interface ISourceLine {
+    /**
+     * Line corresponding to the block in the entire foreign document
+     */
     virtualLine: number;
+    /**
+     * The CM editor associated with this virtual line.
+     */
     editor: CodeEditor.IEditor;
+    /**
+     * Line in the CM editor corresponding to the virtual line.
+     */
     editorLine: number;
+    /**
+     * Shift of the virtual line
+     */
     editorShift: CodeEditor.IPosition;
     /**
      * Everything which is not in the range of foreign documents belongs to the host.
@@ -45,7 +75,13 @@ interface ISourceLine {
     foreignDocumentsMap: ForeignDocumentsMap;
 }
 export interface IForeignContext {
+    /**
+     * The virtual document
+     */
     foreignDocument: VirtualDocument;
+    /**
+     * The document holding the virtual document.
+     */
     parentHost: VirtualDocument;
 }
 /**
@@ -56,21 +92,55 @@ export interface IForeignContext {
  */
 export declare function isWithinRange(position: CodeEditor.IPosition, range: CodeEditor.IRange): boolean;
 /**
- * a virtual implementation of IDocumentInfo
+ * A virtual implementation of IDocumentInfo
  */
 export declare class VirtualDocumentInfo implements IDocumentInfo {
-    private _document;
-    version: number;
+    /**
+     * Creates an instance of VirtualDocumentInfo.
+     * @param document - the virtual document need to
+     * be wrapped.
+     */
     constructor(document: VirtualDocument);
+    /**
+     * Current version of the virtual document.
+     */
+    version: number;
+    /**
+     * Get the text content of the virtual document.
+     */
     get text(): string;
+    /**
+     * Get the uri of the virtual document, if the document is not available,
+     * it returns an empty string, users need to check for the length of returned
+     * value before using it.
+     */
     get uri(): string;
+    /**
+     * Get the language identifier of the document.
+     */
     get languageId(): string;
+    /**
+     * The wrapped virtual document.
+     */
+    private _document;
 }
 export declare namespace VirtualDocument {
     interface IOptions {
+        /**
+         * The language identifier of the document.
+         */
         language: LanguageIdentifier;
+        /**
+         * The foreign code extractor manager token.
+         */
         foreignCodeExtractors: ILSPCodeExtractorsManager;
+        /**
+         * Path to the document.
+         */
         path: string;
+        /**
+         * File extension of the document.
+         */
         fileExtension: string | undefined;
         /**
          * Notebooks or any other aggregates of documents are not supported
@@ -87,10 +157,14 @@ export declare namespace VirtualDocument {
          *
          */
         standalone?: boolean;
+        /**
+         * Parent of the current virtual document.
+         */
         parent?: VirtualDocument;
     }
 }
 /**
+ *
  * A notebook can hold one or more virtual documents; there is always one,
  * "root" document, corresponding to the language of the kernel. All other
  * virtual documents are extracted out of the notebook, based on magics,
@@ -110,101 +184,278 @@ export declare namespace VirtualDocument {
  * No dependency on editor implementation (such as CodeMirrorEditor)
  * is allowed for VirtualEditor.
  */
-export declare class VirtualDocument {
-    language: string;
-    standalone: boolean;
-    isDisposed: boolean;
+export declare class VirtualDocument implements IDisposable {
+    constructor(options: VirtualDocument.IOptions);
+    /**
+     * Convert from code editor position into code mirror position.
+     */
+    static ceToCm(position: CodeEditor.IPosition): IPosition;
+    /**
+     * Number of blank lines appended to the virtual document between
+     * each cell.
+     */
     blankLinesBetweenCells: number;
+    /**
+     * Line number of the last line in the real document.
+     */
     lastSourceLine: number;
-    foreignDocumentClosed: Signal<VirtualDocument, IForeignContext>;
-    foreignDocumentOpened: Signal<VirtualDocument, IForeignContext>;
+    /**
+     * Line number of the last line in the virtual document.
+     */
     lastVirtualLine: number;
     /**
      * the remote document uri, version and other server-related info
      */
     documentInfo: IDocumentInfo;
     /**
-     * Virtual lines keep all the lines present in the document AND extracted to the foreign document.
+     * Parent of the current virtual document.
      */
-    virtualLines: Map<number, IVirtualLine>;
-    changed: Signal<VirtualDocument, VirtualDocument>;
-    path: string;
-    fileExtension: string | undefined;
-    hasLspSupportedFile: boolean;
     parent?: VirtualDocument | null;
-    updateManager: UpdateManager;
-    foreignDocuments: Map<VirtualDocument.virtualId, VirtualDocument>;
+    /**
+     * The language identifier of the document.
+     */
+    readonly language: string;
+    /**
+     * Being standalone is relevant to foreign documents
+     * and defines whether following chunks of code in the same
+     * language should be appended to this document (false, not standalone)
+     * or should be considered separate documents (true, standalone)
+     */
+    readonly standalone: boolean;
+    /**
+     * Path to the document.
+     */
+    readonly path: string;
+    /**
+     * File extension of the document.
+     */
+    readonly fileExtension: string | undefined;
+    /**
+     * 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.
+     */
+    readonly hasLspSupportedFile: boolean;
+    /**
+     * Map holding the children `VirtualDocument` .
+     */
+    readonly foreignDocuments: Map<VirtualDocument.virtualId, VirtualDocument>;
+    /**
+     * The update manager object.
+     */
+    readonly updateManager: UpdateManager;
+    /**
+     * Unique id of the virtual document.
+     */
     readonly instanceId: number;
-    protected sourceLines: Map<number, ISourceLine>;
-    protected lineBlocks: Array<string>;
-    protected unusedDocuments: Set<VirtualDocument>;
-    protected unusedStandaloneDocuments: DefaultMap<language, Array<VirtualDocument>>;
-    private _remainingLifetime;
-    private _editorToSourceLine;
-    private _editorToSourceLineNew;
-    private _foreignCodeExtractors;
-    private previousValue;
-    private static instancesCount;
-    private readonly options;
-    constructor(options: VirtualDocument.IOptions);
+    /**
+     * Test whether the document is disposed.
+     */
+    get isDisposed(): boolean;
+    /**
+     * Signal emitted when the foreign document is closed
+     */
+    get foreignDocumentClosed(): ISignal<VirtualDocument, IForeignContext>;
+    /**
+     * Signal emitted when the foreign document is opened
+     */
+    get foreignDocumentOpened(): ISignal<VirtualDocument, IForeignContext>;
+    /**
+     * Signal emitted when the foreign document is changed
+     */
+    get changed(): ISignal<VirtualDocument, VirtualDocument>;
+    /**
+     * Id of the virtual document.
+     */
+    get virtualId(): VirtualDocument.virtualId;
+    /**
+     * Return the ancestry to this document.
+     */
+    get ancestry(): Array<VirtualDocument>;
+    /**
+     * Return the id path to the virtual document.
+     */
+    get idPath(): VirtualDocument.idPath;
+    /**
+     * Get the uri of the virtual document.
+     */
+    get uri(): VirtualDocument.uri;
+    /**
+     * Get the text value of the document
+     */
+    get value(): string;
+    /**
+     * Get the last line in the virtual document
+     */
+    get lastLine(): string;
+    /**
+     * Get the root document of current virtual document.
+     */
+    get root(): VirtualDocument;
+    /**
+     * Dispose the virtual document.
+     */
     dispose(): void;
     /**
-     * When this counter goes down to 0, the document will be destroyed and the associated connection will be closed;
-     * This is meant to reduce the number of open connections when a a foreign code snippet was removed from the document.
-     *
-     * Note: top level virtual documents are currently immortal (unless killed by other means); it might be worth
-     * implementing culling of unused documents, but if and only if JupyterLab will also implement culling of
-     * idle kernels - otherwise the user experience could be a bit inconsistent, and we would need to invent our own rules.
+     * Clear the virtual document and all related stuffs
      */
-    protected get remainingLifetime(): number;
-    protected set remainingLifetime(value: number);
     clear(): void;
+    /**
+     * Get the virtual document from the cursor position of the source
+     * document
+     * @param position - position in source document
+     */
     documentAtSourcePosition(position: ISourcePosition): VirtualDocument;
+    /**
+     * Detect if the input source position is belong to the current
+     * virtual document.
+     *
+     * @param sourcePosition - position in the source document
+     */
     isWithinForeign(sourcePosition: ISourcePosition): boolean;
+    /**
+     * Compute the position in root document from the position of
+     * a child editor.
+     *
+     * @param editor - the active editor.
+     * @param position - position in the active editor.
+     */
     transformFromEditorToRoot(editor: CodeEditor.IEditor, position: IEditorPosition): IRootPosition | null;
+    /**
+     * Compute the position in the virtual document from the position
+     * if the source document.
+     *
+     * @param sourcePosition - position in source document
+     */
     virtualPositionAtDocument(sourcePosition: ISourcePosition): IVirtualPosition;
+    /**
+     * Append a code block to the end of the virtual document.
+     *
+     * @param  block - block to be appended
+     * @param  editorShift - position shift in source
+     * document
+     * @param  [virtualShift] - position shift in
+     * virtual document.
+     */
     appendCodeBlock(block: ICodeBlockOptions, editorShift?: CodeEditor.IPosition, virtualShift?: CodeEditor.IPosition): void;
+    /**
+     * Extract a code block into list of string in supported language and
+     * a map of foreign document if any.
+     * @param  block - block to be appended
+     * @param  editorShift - position shift in source document
+     */
     prepareCodeBlock(block: ICodeBlockOptions, editorShift?: CodeEditor.IPosition): {
         lines: string[];
         foreignDocumentsMap: Map<CodeEditor.IRange, IVirtualDocumentBlock>;
     };
+    /**
+     * Extract the foreign code from input block by using the registered
+     * extractors.
+     * @param  block - block to be appended
+     * @param  editorShift - position shift in source document
+     */
     extractForeignCode(block: ICodeBlockOptions, editorShift: CodeEditor.IPosition): {
         cellCodeKept: string;
         foreignDocumentsMap: Map<CodeEditor.IRange, IVirtualDocumentBlock>;
     };
-    private chooseForeignDocument;
-    private openForeign;
-    private forwardClosedSignal;
-    private forwardOpenedSignal;
+    /**
+     * Close a foreign document and disconnect all associated signals
+     */
     closeForeign(document: VirtualDocument): void;
+    /**
+     * Close all foreign documents.
+     */
     closeAllForeignDocuments(): void;
-    get value(): string;
-    get lastLine(): string;
+    /**
+     * Close all expired documents.
+     */
     closeExpiredDocuments(): void;
-    get virtualId(): VirtualDocument.virtualId;
-    get ancestry(): Array<VirtualDocument>;
-    get idPath(): VirtualDocument.idPath;
-    get uri(): VirtualDocument.uri;
+    /**
+     * Transform the position of the source to the editor
+     * position.
+     *
+     * @param  pos - position in the source document
+     * @return position in the editor.
+     */
     transformSourceToEditor(pos: ISourcePosition): IEditorPosition;
     /**
-    Can be null because some lines are added as padding/anchors
-    to the virtual document and those do not exist in the source document
-    and thus they are absent in the editor.
-    */
+     * Transform the position in the virtual document to the
+     * editor position.
+     * Can be null because some lines are added as padding/anchors
+     * to the virtual document and those do not exist in the source document
+     * and thus they are absent in the editor.
+     */
     transformVirtualToEditor(virtualPosition: IVirtualPosition): IEditorPosition | null;
     /**
-    Can be null because some lines are added as padding/anchors
-    to the virtual document and those do not exist in the source document.
-    */
+     * Transform the position in the virtual document to the source.
+     * Can be null because some lines are added as padding/anchors
+     * to the virtual document and those do not exist in the source document.
+     */
     transformVirtualToSource(position: IVirtualPosition): ISourcePosition | null;
-    get root(): VirtualDocument;
+    /**
+     * Get the corresponding editor of the virtual line.
+     */
     getEditorAtVirtualLine(pos: IVirtualPosition): CodeEditor.IEditor;
+    /**
+     * Get the corresponding editor of the source line
+     */
     getEditorAtSourceLine(pos: ISourcePosition): CodeEditor.IEditor;
     /**
      * Recursively emits changed signal from the document or any descendant foreign document.
      */
     maybeEmitChanged(): void;
-    static ceToCm(position: CodeEditor.IPosition): CodeMirror.Position;
+    /**
+     * When this counter goes down to 0, the document will be destroyed and the associated connection will be closed;
+     * This is meant to reduce the number of open connections when a a foreign code snippet was removed from the document.
+     *
+     * Note: top level virtual documents are currently immortal (unless killed by other means); it might be worth
+     * implementing culling of unused documents, but if and only if JupyterLab will also implement culling of
+     * idle kernels - otherwise the user experience could be a bit inconsistent, and we would need to invent our own rules.
+     */
+    protected get remainingLifetime(): number;
+    protected set remainingLifetime(value: number);
+    /**
+     * Virtual lines keep all the lines present in the document AND extracted to the foreign document.
+     */
+    protected virtualLines: Map<number, IVirtualLine>;
+    protected sourceLines: Map<number, ISourceLine>;
+    protected lineBlocks: Array<string>;
+    protected unusedDocuments: Set<VirtualDocument>;
+    protected unusedStandaloneDocuments: DefaultMap<language, Array<VirtualDocument>>;
+    private _isDisposed;
+    private _remainingLifetime;
+    private _editorToSourceLine;
+    private _editorToSourceLineNew;
+    private _foreignCodeExtractors;
+    private previousValue;
+    private static instancesCount;
+    private readonly options;
+    /**
+     * Get the foreign document that can be opened with the input extractor.
+     */
+    private chooseForeignDocument;
+    /**
+     * Create a foreign document from input language and file extension.
+     *
+     * @param  language - the required language
+     * @param  standalone - the document type is supported natively by LSP?
+     * @param  fileExtension - File extension.
+     */
+    private openForeign;
+    /**
+     * Forward the closed signal from the foreign document to the host document's
+     * signal
+     */
+    private forwardClosedSignal;
+    /**
+     * Forward the opened signal from the foreign document to the host document's
+     * signal
+     */
+    private forwardOpenedSignal;
+    private _foreignDocumentClosed;
+    private _foreignDocumentOpened;
+    private _changed;
 }
 export declare namespace VirtualDocument {
     /**
@@ -224,35 +475,54 @@ export declare namespace VirtualDocument {
      */
     type uri = string;
 }
+/**
+ * Create foreign documents if available from input virtual documents.
+ * @param virtualDocument - the virtual document to be collected
+ * @return - Set of generated foreign documents
+ */
 export declare function collectDocuments(virtualDocument: VirtualDocument): Set<VirtualDocument>;
 export interface IBlockAddedInfo {
+    /**
+     * The virtual document.
+     */
     virtualDocument: VirtualDocument;
+    /**
+     * Option of the code block.
+     */
     block: ICodeBlockOptions;
 }
-export declare class UpdateManager {
+export declare class UpdateManager implements IDisposable {
     private virtualDocument;
+    constructor(virtualDocument: VirtualDocument);
     /**
-     * Virtual documents update guard.
+     * Promise resolved when the updating process finishes.
      */
-    private isUpdateInProgress;
-    private updateLock;
-    protected isDisposed: boolean;
+    get updateDone(): Promise<void>;
     /**
-     * Signal emitted by the editor that triggered the update, providing the root document of the updated documents.
+     * Test whether the document is disposed.
      */
-    private documentUpdated;
-    blockAdded: Signal<UpdateManager, IBlockAddedInfo>;
-    updateDone: Promise<void>;
-    updateBegan: Signal<UpdateManager, ICodeBlockOptions[]>;
-    updateFinished: Signal<UpdateManager, ICodeBlockOptions[]>;
-    constructor(virtualDocument: VirtualDocument);
-    dispose(): void;
+    get isDisposed(): boolean;
     /**
-     * Once all the foreign documents were refreshed, the unused documents (and their connections)
-     * should be terminated if their lifetime has expired.
+     * Signal emitted when a code block is added to the document.
+     */
+    get blockAdded(): ISignal<UpdateManager, IBlockAddedInfo>;
+    /**
+     * Signal emitted by the editor that triggered the update,
+     * providing the root document of the updated documents.
+     */
+    get documentUpdated(): ISignal<UpdateManager, VirtualDocument>;
+    /**
+     * Signal emitted when the update is started
+     */
+    get updateBegan(): ISignal<UpdateManager, ICodeBlockOptions[]>;
+    /**
+     * Signal emitted when the update is finished
+     */
+    get updateFinished(): ISignal<UpdateManager, ICodeBlockOptions[]>;
+    /**
+     * Dispose the class
      */
-    private onUpdated;
-    private canUpdate;
+    dispose(): void;
     /**
      * Execute provided callback within an update-locked context, which guarantees that:
      *  - the previous updates must have finished before the callback call, and
@@ -266,5 +536,31 @@ export declare class UpdateManager {
      * as to avoid an easy trap of ignoring the changes in the virtual documents.
      */
     updateDocuments(blocks: ICodeBlockOptions[]): Promise<void>;
+    private _isDisposed;
+    /**
+     * Promise resolved when the updating process finishes.
+     */
+    private _updateDone;
+    /**
+     * Virtual documents update guard.
+     */
+    private _isUpdateInProgress;
+    /**
+     * Update lock to prevent multiple updates are applied at the same time.
+     */
+    private _updateLock;
+    private _blockAdded;
+    private _documentUpdated;
+    private _updateBegan;
+    private _updateFinished;
+    /**
+     * Once all the foreign documents were refreshed, the unused documents (and their connections)
+     * should be terminated if their lifetime has expired.
+     */
+    private _onUpdated;
+    /**
+     * Check if the document can be updated.
+     */
+    private _canUpdate;
 }
 export {};