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

package/lib/virtual/document.js

@@ -1,6 +1,7 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
 import { Signal } from '@lumino/signaling';
 import { DocumentConnectionManager } from '../connection_manager';
-import { PositionError } from '../positioning';
 import { DefaultMap, untilReady } from '../utils';
 /**
  * Check if given position is within range.
@@ -23,25 +24,48 @@ export function isWithinRange(position, range) {
         (position.line > range.start.line && position.line < range.end.line));
 }
 /**
- * a virtual implementation of IDocumentInfo
+ * A virtual implementation of IDocumentInfo
  */
 export class VirtualDocumentInfo {
+    /**
+     * Creates an instance of VirtualDocumentInfo.
+     * @param document - the virtual document need to
+     * be wrapped.
+     */
     constructor(document) {
+        /**
+         * Current version of the virtual document.
+         */
         this.version = 0;
         this._document = document;
     }
+    /**
+     * Get the text content of the virtual document.
+     */
     get text() {
         return this._document.value;
     }
+    /**
+     * 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() {
         const uris = DocumentConnectionManager.solveUris(this._document, this.languageId);
+        if (!uris) {
+            return '';
+        }
         return uris.document;
     }
+    /**
+     * Get the language identifier of the document.
+     */
     get languageId() {
         return this._document.language;
     }
 }
 /**
+ *
  * 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,
@@ -63,8 +87,15 @@ export class VirtualDocumentInfo {
  */
 export class VirtualDocument {
     constructor(options) {
-        this.isDisposed = false;
+        /**
+         * Number of blank lines appended to the virtual document between
+         * each cell.
+         */
         this.blankLinesBetweenCells = 2;
+        this._isDisposed = false;
+        this._foreignDocumentClosed = new Signal(this);
+        this._foreignDocumentOpened = new Signal(this);
+        this._changed = new Signal(this);
         this.options = options;
         this.path = this.options.path;
         this.fileExtension = options.fileExtension;
@@ -81,9 +112,6 @@ export class VirtualDocument {
         VirtualDocument.instancesCount += 1;
         this.unusedStandaloneDocuments = new DefaultMap(() => new Array());
         this._remainingLifetime = 6;
-        this.foreignDocumentClosed = new Signal(this);
-        this.foreignDocumentOpened = new Signal(this);
-        this.changed = new Signal(this);
         this.unusedDocuments = new Set();
         this.documentInfo = new VirtualDocumentInfo(this);
         this.updateManager = new UpdateManager(this);
@@ -98,11 +126,104 @@ export class VirtualDocument {
         }, this);
         this.clear();
     }
+    /**
+     * Convert from code editor position into code mirror position.
+     */
+    static ceToCm(position) {
+        return { line: position.line, ch: position.column };
+    }
+    /**
+     * Test whether the document is disposed.
+     */
+    get isDisposed() {
+        return this._isDisposed;
+    }
+    /**
+     * Signal emitted when the foreign document is closed
+     */
+    get foreignDocumentClosed() {
+        return this._foreignDocumentClosed;
+    }
+    /**
+     * Signal emitted when the foreign document is opened
+     */
+    get foreignDocumentOpened() {
+        return this._foreignDocumentOpened;
+    }
+    /**
+     * Signal emitted when the foreign document is changed
+     */
+    get changed() {
+        return this._changed;
+    }
+    /**
+     * Id of the virtual document.
+     */
+    get virtualId() {
+        // for easier debugging, the language information is included in the ID:
+        return this.standalone
+            ? this.instanceId + '(' + this.language + ')'
+            : this.language;
+    }
+    /**
+     * Return the ancestry to this document.
+     */
+    get ancestry() {
+        if (!this.parent) {
+            return [this];
+        }
+        return this.parent.ancestry.concat([this]);
+    }
+    /**
+     * Return the id path to the virtual document.
+     */
+    get idPath() {
+        if (!this.parent) {
+            return this.virtualId;
+        }
+        return this.parent.idPath + '-' + this.virtualId;
+    }
+    /**
+     * Get the uri of the virtual document.
+     */
+    get uri() {
+        const encodedPath = encodeURI(this.path);
+        if (!this.parent) {
+            return encodedPath;
+        }
+        return encodedPath + '.' + this.idPath + '.' + this.fileExtension;
+    }
+    /**
+     * Get the text value of the document
+     */
+    get value() {
+        let linesPadding = '\n'.repeat(this.blankLinesBetweenCells);
+        return this.lineBlocks.join(linesPadding);
+    }
+    /**
+     * Get the last line in the virtual document
+     */
+    get lastLine() {
+        const linesInLastBlock = this.lineBlocks[this.lineBlocks.length - 1].split('\n');
+        return linesInLastBlock[linesInLastBlock.length - 1];
+    }
+    /**
+     * Get the root document of current virtual document.
+     */
+    get root() {
+        if (this.parent == null) {
+            return this;
+        }
+        return this.parent.root;
+    }
+    /**
+     * Dispose the virtual document.
+     */
     dispose() {
-        if (this.isDisposed) {
+        if (this._isDisposed) {
             return;
         }
-        this.isDisposed = true;
+        this._isDisposed = true;
         this.parent = null;
         this.closeAllForeignDocuments();
         this.updateManager.dispose();
@@ -113,29 +234,14 @@ export class VirtualDocument {
         this.unusedStandaloneDocuments.clear();
         this.virtualLines.clear();
         // just to be sure - if anything is accessed after disposal (it should not) we
-        // will get alterted by errors in the console AND this will limit memory leaks
+        // will get altered by errors in the console AND this will limit memory leaks
         this.documentInfo = null;
         this.lineBlocks = null;
+        Signal.clearData(this);
     }
     /**
-     * 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
      */
-    get remainingLifetime() {
-        if (!this.parent) {
-            return Infinity;
-        }
-        return this._remainingLifetime;
-    }
-    set remainingLifetime(value) {
-        if (this.parent) {
-            this._remainingLifetime = value;
-        }
-    }
     clear() {
         for (let document of this.foreignDocuments.values()) {
             document.clear();
@@ -149,6 +255,11 @@ export class VirtualDocument {
         this.lastSourceLine = 0;
         this.lineBlocks = [];
     }
+    /**
+     * Get the virtual document from the cursor position of the source
+     * document
+     * @param position - position in source document
+     */
     documentAtSourcePosition(position) {
         let sourceLine = this.sourceLines.get(position.line);
         if (sourceLine == null) {
@@ -169,6 +280,12 @@ export class VirtualDocument {
         }
         return this;
     }
+    /**
+     * Detect if the input source position is belong to the current
+     * virtual document.
+     *
+     * @param sourcePosition - position in the source document
+     */
     isWithinForeign(sourcePosition) {
         let sourceLine = this.sourceLines.get(sourcePosition.line);
         let sourcePositionCe = {
@@ -182,6 +299,13 @@ export class VirtualDocument {
         }
         return false;
     }
+    /**
+     * 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, position) {
         if (!this._editorToSourceLine.has(editor)) {
             console.log('Editor not found in _editorToSourceLine map');
@@ -190,10 +314,16 @@ export class VirtualDocument {
         let shift = this._editorToSourceLine.get(editor);
         return Object.assign(Object.assign({}, position), { line: position.line + shift });
     }
+    /**
+     * Compute the position in the virtual document from the position
+     * if the source document.
+     *
+     * @param sourcePosition - position in source document
+     */
     virtualPositionAtDocument(sourcePosition) {
         let sourceLine = this.sourceLines.get(sourcePosition.line);
         if (sourceLine == null) {
-            throw new PositionError('Source line not mapped to virtual position');
+            throw new Error('Source line not mapped to virtual position');
         }
         let virtualLine = sourceLine.virtualLine;
         // position inside the cell (block)
@@ -224,6 +354,15 @@ export class VirtualDocument {
             line: virtualLine
         };
     }
+    /**
+     * 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, editorShift = { line: 0, column: 0 }, virtualShift) {
         let cellCode = block.value;
         let ceEditor = block.ceEditor;
@@ -270,11 +409,23 @@ export class VirtualDocument {
         this.lastVirtualLine += this.blankLinesBetweenCells;
         this.lastSourceLine += sourceCellLines.length;
     }
+    /**
+     * 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, editorShift = { line: 0, column: 0 }) {
         let { cellCodeKept, foreignDocumentsMap } = this.extractForeignCode(block, editorShift);
         let lines = cellCodeKept.split('\n');
         return { lines, foreignDocumentsMap };
     }
+    /**
+     * 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, editorShift) {
         let foreignDocumentsMap = new Map();
         let cellCode = block.value;
@@ -322,41 +473,11 @@ export class VirtualDocument {
         }
         return { cellCodeKept: cellCode, foreignDocumentsMap };
     }
-    chooseForeignDocument(extractor) {
-        let foreignDocument;
-        // if not standalone, try to append to existing document
-        let foreignExists = this.foreignDocuments.has(extractor.language);
-        if (!extractor.standalone && foreignExists) {
-            foreignDocument = this.foreignDocuments.get(extractor.language);
-        }
-        else {
-            // if (previous document does not exists) or (extractor produces standalone documents
-            // and no old standalone document could be reused): create a new document
-            foreignDocument = this.openForeign(extractor.language, extractor.standalone, extractor.fileExtension);
-        }
-        return foreignDocument;
-    }
-    openForeign(language, standalone, fileExtension) {
-        let document = new VirtualDocument(Object.assign(Object.assign({}, this.options), { parent: this, standalone: standalone, fileExtension: fileExtension, language: language }));
-        const context = {
-            foreignDocument: document,
-            parentHost: this
-        };
-        this.foreignDocumentOpened.emit(context);
-        // pass through any future signals
-        document.foreignDocumentClosed.connect(this.forwardClosedSignal, this);
-        document.foreignDocumentOpened.connect(this.forwardOpenedSignal, this);
-        this.foreignDocuments.set(document.virtualId, document);
-        return document;
-    }
-    forwardClosedSignal(host, context) {
-        this.foreignDocumentClosed.emit(context);
-    }
-    forwardOpenedSignal(host, context) {
-        this.foreignDocumentOpened.emit(context);
-    }
+    /**
+     * Close a foreign document and disconnect all associated signals
+     */
     closeForeign(document) {
-        this.foreignDocumentClosed.emit({
+        this._foreignDocumentClosed.emit({
             foreignDocument: document,
             parentHost: this
         });
@@ -368,52 +489,32 @@ export class VirtualDocument {
         document.foreignDocumentOpened.disconnect(this.forwardOpenedSignal, this);
         document.dispose();
     }
+    /**
+     * Close all foreign documents.
+     */
     closeAllForeignDocuments() {
         for (let document of this.foreignDocuments.values()) {
             this.closeForeign(document);
         }
     }
-    get value() {
-        let linesPadding = '\n'.repeat(this.blankLinesBetweenCells);
-        return this.lineBlocks.join(linesPadding);
-    }
-    get lastLine() {
-        const linesInLastBlock = this.lineBlocks[this.lineBlocks.length - 1].split('\n');
-        return linesInLastBlock[linesInLastBlock.length - 1];
-    }
+    /**
+     * Close all expired documents.
+     */
     closeExpiredDocuments() {
         for (let document of this.unusedDocuments.values()) {
             document.remainingLifetime -= 1;
             if (document.remainingLifetime <= 0) {
-                /** TODO */
+                document.dispose();
             }
         }
     }
-    get virtualId() {
-        // for easier debugging, the language information is included in the ID:
-        return this.standalone
-            ? this.instanceId + '(' + this.language + ')'
-            : this.language;
-    }
-    get ancestry() {
-        if (!this.parent) {
-            return [this];
-        }
-        return this.parent.ancestry.concat([this]);
-    }
-    get idPath() {
-        if (!this.parent) {
-            return this.virtualId;
-        }
-        return this.parent.idPath + '-' + this.virtualId;
-    }
-    get uri() {
-        const encodedPath = encodeURI(this.path);
-        if (!this.parent) {
-            return encodedPath;
-        }
-        return encodedPath + '.' + this.idPath + '.' + this.fileExtension;
-    }
+    /**
+     * Transform the position of the source to the editor
+     * position.
+     *
+     * @param  pos - position in the source document
+     * @return position in the editor.
+     */
     transformSourceToEditor(pos) {
         let sourceLine = this.sourceLines.get(pos.line);
         let editorLine = sourceLine.editorLine;
@@ -427,10 +528,12 @@ export class VirtualDocument {
         };
     }
     /**
-    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) {
         let sourcePosition = this.transformVirtualToSource(virtualPosition);
         if (sourcePosition == null) {
@@ -439,9 +542,10 @@ export class VirtualDocument {
         return this.transformSourceToEditor(sourcePosition);
     }
     /**
-    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) {
         const line = this.virtualLines.get(position.line).sourceLine;
         if (line == null) {
@@ -452,12 +556,9 @@ export class VirtualDocument {
             line: line
         };
     }
-    get root() {
-        if (this.parent == null) {
-            return this;
-        }
-        return this.parent.root;
-    }
+    /**
+     * Get the corresponding editor of the virtual line.
+     */
     getEditorAtVirtualLine(pos) {
         let line = pos.line;
         // tolerate overshot by one (the hanging blank line at the end)
@@ -466,6 +567,9 @@ export class VirtualDocument {
         }
         return this.virtualLines.get(line).editor;
     }
+    /**
+     * Get the corresponding editor of the source line
+     */
     getEditorAtSourceLine(pos) {
         return this.sourceLines.get(pos.line).editor;
     }
@@ -474,18 +578,90 @@ export class VirtualDocument {
      */
     maybeEmitChanged() {
         if (this.value !== this.previousValue) {
-            this.changed.emit(this);
+            this._changed.emit(this);
         }
         this.previousValue = this.value;
         for (let document of this.foreignDocuments.values()) {
             document.maybeEmitChanged();
         }
     }
-    static ceToCm(position) {
-        return { line: position.line, ch: position.column };
+    /**
+     * 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.
+     */
+    get remainingLifetime() {
+        if (!this.parent) {
+            return Infinity;
+        }
+        return this._remainingLifetime;
+    }
+    set remainingLifetime(value) {
+        if (this.parent) {
+            this._remainingLifetime = value;
+        }
+    }
+    /**
+     * Get the foreign document that can be opened with the input extractor.
+     */
+    chooseForeignDocument(extractor) {
+        let foreignDocument;
+        // if not standalone, try to append to existing document
+        let foreignExists = this.foreignDocuments.has(extractor.language);
+        if (!extractor.standalone && foreignExists) {
+            foreignDocument = this.foreignDocuments.get(extractor.language);
+        }
+        else {
+            // if (previous document does not exists) or (extractor produces standalone documents
+            // and no old standalone document could be reused): create a new document
+            foreignDocument = this.openForeign(extractor.language, extractor.standalone, extractor.fileExtension);
+        }
+        return foreignDocument;
+    }
+    /**
+     * 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.
+     */
+    openForeign(language, standalone, fileExtension) {
+        let document = new VirtualDocument(Object.assign(Object.assign({}, this.options), { parent: this, standalone: standalone, fileExtension: fileExtension, language: language }));
+        const context = {
+            foreignDocument: document,
+            parentHost: this
+        };
+        this._foreignDocumentOpened.emit(context);
+        // pass through any future signals
+        document.foreignDocumentClosed.connect(this.forwardClosedSignal, this);
+        document.foreignDocumentOpened.connect(this.forwardOpenedSignal, this);
+        this.foreignDocuments.set(document.virtualId, document);
+        return document;
+    }
+    /**
+     * Forward the closed signal from the foreign document to the host document's
+     * signal
+     */
+    forwardClosedSignal(host, context) {
+        this._foreignDocumentClosed.emit(context);
+    }
+    /**
+     * Forward the opened signal from the foreign document to the host document's
+     * signal
+     */
+    forwardOpenedSignal(host, context) {
+        this._foreignDocumentOpened.emit(context);
     }
 }
 VirtualDocument.instancesCount = 0;
+/**
+ * Create foreign documents if available from input virtual documents.
+ * @param virtualDocument - the virtual document to be collected
+ * @return - Set of generated foreign documents
+ */
 export function collectDocuments(virtualDocument) {
     let collected = new Set();
     collected.add(virtualDocument);
@@ -498,41 +674,74 @@ export function collectDocuments(virtualDocument) {
 export class UpdateManager {
     constructor(virtualDocument) {
         this.virtualDocument = virtualDocument;
+        this._isDisposed = false;
         /**
-         * Virtual documents update guard.
+         * Promise resolved when the updating process finishes.
          */
-        this.isUpdateInProgress = false;
-        this.updateLock = false;
-        this.isDisposed = false;
-        this.updateDone = new Promise(resolve => {
+        this._updateDone = new Promise(resolve => {
             resolve();
         });
-        this.documentUpdated = new Signal(this);
-        this.blockAdded = new Signal(this);
-        this.updateBegan = new Signal(this);
-        this.updateFinished = new Signal(this);
-        this.documentUpdated.connect(this.onUpdated, this);
+        /**
+         * Virtual documents update guard.
+         */
+        this._isUpdateInProgress = false;
+        /**
+         * Update lock to prevent multiple updates are applied at the same time.
+         */
+        this._updateLock = false;
+        this._blockAdded = new Signal(this);
+        this._documentUpdated = new Signal(this);
+        this._updateBegan = new Signal(this);
+        this._updateFinished = new Signal(this);
+        this.documentUpdated.connect(this._onUpdated, this);
     }
-    dispose() {
-        if (this.isDisposed) {
-            return;
-        }
-        this.documentUpdated.disconnect(this.onUpdated, this);
+    /**
+     * Promise resolved when the updating process finishes.
+     */
+    get updateDone() {
+        return this._updateDone;
     }
     /**
-     * Once all the foreign documents were refreshed, the unused documents (and their connections)
-     * should be terminated if their lifetime has expired.
+     * Test whether the document is disposed.
      */
-    onUpdated(manager, rootDocument) {
-        try {
-            rootDocument.closeExpiredDocuments();
-        }
-        catch (e) {
-            console.warn('Failed to close expired documents');
-        }
+    get isDisposed() {
+        return this._isDisposed;
+    }
+    /**
+     * Signal emitted when a code block is added to the document.
+     */
+    get blockAdded() {
+        return this._blockAdded;
+    }
+    /**
+     * Signal emitted by the editor that triggered the update,
+     * providing the root document of the updated documents.
+     */
+    get documentUpdated() {
+        return this._documentUpdated;
+    }
+    /**
+     * Signal emitted when the update is started
+     */
+    get updateBegan() {
+        return this._updateBegan;
     }
-    canUpdate() {
-        return !this.isDisposed && !this.isUpdateInProgress && !this.updateLock;
+    /**
+     * Signal emitted when the update is finished
+     */
+    get updateFinished() {
+        return this._updateFinished;
+    }
+    /**
+     * Dispose the class
+     */
+    dispose() {
+        if (this._isDisposed) {
+            return;
+        }
+        this._isDisposed = true;
+        Signal.clearData(this);
+        this.documentUpdated.disconnect(this._onUpdated, this);
     }
     /**
      * Execute provided callback within an update-locked context, which guarantees that:
@@ -541,13 +750,13 @@ export class UpdateManager {
      * @param fn - the callback to execute in update lock
      */
     async withUpdateLock(fn) {
-        await untilReady(() => this.canUpdate(), 12, 10).then(() => {
+        await untilReady(() => this._canUpdate(), 12, 10).then(() => {
             try {
-                this.updateLock = true;
+                this._updateLock = true;
                 fn();
             }
             finally {
-                this.updateLock = false;
+                this._updateLock = false;
             }
         });
     }
@@ -560,25 +769,25 @@ export class UpdateManager {
         let update = new Promise((resolve, reject) => {
             // defer the update by up to 50 ms (10 retrials * 5 ms break),
             // awaiting for the previous update to complete.
-            untilReady(() => this.canUpdate(), 10, 5)
+            untilReady(() => this._canUpdate(), 10, 5)
                 .then(() => {
                 if (this.isDisposed || !this.virtualDocument) {
                     resolve();
                 }
                 try {
-                    this.isUpdateInProgress = true;
-                    this.updateBegan.emit(blocks);
+                    this._isUpdateInProgress = true;
+                    this._updateBegan.emit(blocks);
                     this.virtualDocument.clear();
                     for (let codeBlock of blocks) {
-                        this.blockAdded.emit({
+                        this._blockAdded.emit({
                             block: codeBlock,
                             virtualDocument: this.virtualDocument
                         });
                         this.virtualDocument.appendCodeBlock(codeBlock);
                     }
-                    this.updateFinished.emit(blocks);
+                    this._updateFinished.emit(blocks);
                     if (this.virtualDocument) {
-                        this.documentUpdated.emit(this.virtualDocument);
+                        this._documentUpdated.emit(this.virtualDocument);
                         this.virtualDocument.maybeEmitChanged();
                     }
                     resolve();
@@ -588,13 +797,31 @@ export class UpdateManager {
                     reject(e);
                 }
                 finally {
-                    this.isUpdateInProgress = false;
+                    this._isUpdateInProgress = false;
                 }
             })
                 .catch(console.error);
         });
-        this.updateDone = update;
+        this._updateDone = update;
         return update;
     }
+    /**
+     * Once all the foreign documents were refreshed, the unused documents (and their connections)
+     * should be terminated if their lifetime has expired.
+     */
+    _onUpdated(manager, rootDocument) {
+        try {
+            rootDocument.closeExpiredDocuments();
+        }
+        catch (e) {
+            console.warn('Failed to close expired documents');
+        }
+    }
+    /**
+     * Check if the document can be updated.
+     */
+    _canUpdate() {
+        return !this.isDisposed && !this._isUpdateInProgress && !this._updateLock;
+    }
 }
 //# sourceMappingURL=document.js.map