Description

If you have some location in the document of which you want to know what would be its new location according to document changes, this library aims to provide you with that updated location.

Important:

It is an experimental library. It requires further testing regarding its ability to effectively update the wanted location.

Here if you wish, is where you could help and provide situations in which the updated location is not correct. There are debug loggings which can aid you with this. You will see more details about this below.

Library's API

The API of this library consists in a single function that you will use.

This function is called getUpdatedRanges().

How to use

Install the library in your project

• npm install vscode-position-tracking

Example

// Import it.
const { getUpdatedRanges } = require('vscode-position-tracking')

// To update your document locations according to each
// document change that occurs,
// the getUpdatedRanges() function has to be used 
// within an onDidChangeTextDocument event listener.
vscode.workspace.onDidChangeTextDocument((event) => {

   const updatedRanges = getUpdatedRanges(
      // The locations you want to update,
      // under the form of an array of ranges.
      // It is a required argument.
      someRanges,
      // Array of document changes.
      // It is a required argument.
      event.contentChanges,
      // An object with various options.
      // It is not a required argument,
      // nor any of its options.
      { 
         onDeletion: 'remove',
         onAddition: 'split',
         outputChannel: extensionOutputChannel
      }
   ) 
   // The function returns the updated locations
   // according to document changes,
   // under the form of a new array of ranges.
})

Options object

The options object is not a required argument, nor any of its options.

Available options:

• onDeletion

  • It tells what happens if a document change that consists in deletion intersects with the range you want to update.

  • Values:

    • 'remove'

      Removes the range. In other words, the returned array will not contain that range or its update.

      

    • 'shrink'

      Shrinks the range.

      

  • Default value: 'shrink'

• onAddition

  • It tells what happens if a document change that consists in addition intersects with the range you want to update.

  • Values:

    • 'remove'

      Removes the range. In other words, the returned array will not contain that range or its update.

      

    • 'extend'

      Extends the range.

      

    • 'split'

      Splits the range.

      

  • Default value: 'extend'

• outputChannel

  • It shows logs for debug purposes. For each onDidChangeTextDocument event it will log document change ranges, to update ranges, and updated ranges. The logs are shown on the terminal's output tab in the extension host window / end user window.

    Debug logs example

  • Note 1: The updated ranges are the ones that the library calculated.

  • Note 2: Try and not do logs on the debug console of the development window. From my testing, logging to the debug console creates a lag, the ranges wont be updated in real time.

  • Values:

    • vscode.outputChannel

    
    

  • Default value: undefined

Return value

• The updated ranges from the returned array are in the same order as the ones from the array of ranges that you want to update.

• In the case of having the onAddition option set to 'split', the new split ranges will be positioned in the returned array in the order they appear in document and from the position of the original range that was split.

  Example: toUpdateRanges = [A, B, C], if B was split into two ranges, the returned array will be [updatedA, D, E, updatedC].

Signature of getUpdatedRanges()

getUpdatedRanges(
   ranges: vscode.Range[],
   changes: vscode.TextDocumentContentChangeEvent[],
   options?: {
      onDeletion?: 'remove'|'shrink',
      onAddition?: 'remove'|'extend'|'split',
      outputChannel?: vscode.OutputChannel
   }
): vscode.Range[]

Feedback

You can use the Issues tab of the library's repository for any questions, suggestions and problems you have.

If the library calculates the wrong updated location:

Passing a vscode.OutputChannel object to the outputChannel option will help in gathering some of the data: document change ranges, to update ranges, and updated ranges.

In this case, the updated ranges from the logs will be the wrong ones. So what else should be provided in the opened issue will be the correct updated ranges.