node_modules/xterm/src/browser/Linkifier.ts

   1 /**
   2  * Copyright (c) 2017 The xterm.js authors. All rights reserved.
   3  * @license MIT
   4  */
   5
   6 import { ILinkifierEvent, ILinkMatcher, LinkMatcherHandler, ILinkMatcherOptions, ILinkifier, IMouseZoneManager, IMouseZone, IRegisteredLinkMatcher } from 'browser/Types';
   7 import { IBufferStringIteratorResult } from 'common/buffer/Types';
   8 import { getStringCellWidth } from 'common/CharWidth';
   9 import { EventEmitter, IEvent } from 'common/EventEmitter';
  10 import { ILogService, IBufferService } from 'common/services/Services';
  11
  12 /**
  13  * Limit of the unwrapping line expansion (overscan) at the top and bottom
  14  * of the actual viewport in ASCII characters.
  15  * A limit of 2000 should match most sane urls.
  16  */
  17 const OVERSCAN_CHAR_LIMIT = 2000;
  18
  19 /**
  20  * The Linkifier applies links to rows shortly after they have been refreshed.
  21  */
  22 export class Linkifier implements ILinkifier {
  23   /**
  24    * The time to wait after a row is changed before it is linkified. This prevents
  25    * the costly operation of searching every row multiple times, potentially a
  26    * huge amount of times.
  27    */
  28   protected static _timeBeforeLatency = 200;
  29
  30   protected _linkMatchers: IRegisteredLinkMatcher[] = [];
  31
  32   private _mouseZoneManager: IMouseZoneManager | undefined;
  33   private _element: HTMLElement | undefined;
  34
  35   private _rowsTimeoutId: number | undefined;
  36   private _nextLinkMatcherId = 0;
  37   private _rowsToLinkify: { start: number | undefined, end: number | undefined };
  38
  39   private _onLinkHover = new EventEmitter<ILinkifierEvent>();
  40   public get onLinkHover(): IEvent<ILinkifierEvent> { return this._onLinkHover.event; }
  41   private _onLinkLeave = new EventEmitter<ILinkifierEvent>();
  42   public get onLinkLeave(): IEvent<ILinkifierEvent> { return this._onLinkLeave.event; }
  43   private _onLinkTooltip = new EventEmitter<ILinkifierEvent>();
  44   public get onLinkTooltip(): IEvent<ILinkifierEvent> { return this._onLinkTooltip.event; }
  45
  46   constructor(
  47     protected readonly _bufferService: IBufferService,
  48     private readonly _logService: ILogService
  49   ) {
  50     this._rowsToLinkify = {
  51       start: undefined,
  52       end: undefined
  53     };
  54   }
  55
  56   /**
  57    * Attaches the linkifier to the DOM, enabling linkification.
  58    * @param mouseZoneManager The mouse zone manager to register link zones with.
  59    */
  60   public attachToDom(element: HTMLElement, mouseZoneManager: IMouseZoneManager): void {
  61     this._element = element;
  62     this._mouseZoneManager = mouseZoneManager;
  63   }
  64
  65   /**
  66    * Queue linkification on a set of rows.
  67    * @param start The row to linkify from (inclusive).
  68    * @param end The row to linkify to (inclusive).
  69    */
  70   public linkifyRows(start: number, end: number): void {
  71     // Don't attempt linkify if not yet attached to DOM
  72     if (!this._mouseZoneManager) {
  73       return;
  74     }
  75
  76     // Increase range to linkify
  77     if (this._rowsToLinkify.start === undefined || this._rowsToLinkify.end === undefined) {
  78       this._rowsToLinkify.start = start;
  79       this._rowsToLinkify.end = end;
  80     } else {
  81       this._rowsToLinkify.start = Math.min(this._rowsToLinkify.start, start);
  82       this._rowsToLinkify.end = Math.max(this._rowsToLinkify.end, end);
  83     }
  84
  85     // Clear out any existing links on this row range
  86     this._mouseZoneManager.clearAll(start, end);
  87
  88     // Restart timer
  89     if (this._rowsTimeoutId) {
  90       clearTimeout(this._rowsTimeoutId);
  91     }
  92     this._rowsTimeoutId = <number><any>setTimeout(() => this._linkifyRows(), Linkifier._timeBeforeLatency);
  93   }
  94
  95   /**
  96    * Linkifies the rows requested.
  97    */
  98   private _linkifyRows(): void {
  99     this._rowsTimeoutId = undefined;
 100     const buffer = this._bufferService.buffer;
 101
 102     if (this._rowsToLinkify.start === undefined || this._rowsToLinkify.end === undefined) {
 103       this._logService.debug('_rowToLinkify was unset before _linkifyRows was called');
 104       return;
 105     }
 106
 107     // Ensure the start row exists
 108     const absoluteRowIndexStart = buffer.ydisp + this._rowsToLinkify.start;
 109     if (absoluteRowIndexStart >= buffer.lines.length) {
 110       return;
 111     }
 112
 113     // Invalidate bad end row values (if a resize happened)
 114     const absoluteRowIndexEnd = buffer.ydisp + Math.min(this._rowsToLinkify.end, this._bufferService.rows) + 1;
 115
 116     // Iterate over the range of unwrapped content strings within start..end
 117     // (excluding).
 118     // _doLinkifyRow gets full unwrapped lines with the start row as buffer offset
 119     // for every matcher.
 120     // The unwrapping is needed to also match content that got wrapped across
 121     // several buffer lines. To avoid a worst case scenario where the whole buffer
 122     // contains just a single unwrapped string we limit this line expansion beyond
 123     // the viewport to +OVERSCAN_CHAR_LIMIT chars (overscan) at top and bottom.
 124     // This comes with the tradeoff that matches longer than OVERSCAN_CHAR_LIMIT
 125     // chars will not match anymore at the viewport borders.
 126     const overscanLineLimit = Math.ceil(OVERSCAN_CHAR_LIMIT / this._bufferService.cols);
 127     const iterator = this._bufferService.buffer.iterator(
 128       false, absoluteRowIndexStart, absoluteRowIndexEnd, overscanLineLimit, overscanLineLimit);
 129     while (iterator.hasNext()) {
 130       const lineData: IBufferStringIteratorResult = iterator.next();
 131       for (let i = 0; i < this._linkMatchers.length; i++) {
 132         this._doLinkifyRow(lineData.range.first, lineData.content, this._linkMatchers[i]);
 133       }
 134     }
 135
 136     this._rowsToLinkify.start = undefined;
 137     this._rowsToLinkify.end = undefined;
 138   }
 139
 140   /**
 141    * Registers a link matcher, allowing custom link patterns to be matched and
 142    * handled.
 143    * @param regex The regular expression to search for. Specifically, this
 144    * searches the textContent of the rows. You will want to use \s to match a
 145    * space ' ' character for example.
 146    * @param handler The callback when the link is called.
 147    * @param options Options for the link matcher.
 148    * @return The ID of the new matcher, this can be used to deregister.
 149    */
 150   public registerLinkMatcher(regex: RegExp, handler: LinkMatcherHandler, options: ILinkMatcherOptions = {}): number {
 151     if (!handler) {
 152       throw new Error('handler must be defined');
 153     }
 154     const matcher: IRegisteredLinkMatcher = {
 155       id: this._nextLinkMatcherId++,
 156       regex,
 157       handler,
 158       matchIndex: options.matchIndex,
 159       validationCallback: options.validationCallback,
 160       hoverTooltipCallback: options.tooltipCallback,
 161       hoverLeaveCallback: options.leaveCallback,
 162       willLinkActivate: options.willLinkActivate,
 163       priority: options.priority || 0
 164     };
 165     this._addLinkMatcherToList(matcher);
 166     return matcher.id;
 167   }
 168
 169   /**
 170    * Inserts a link matcher to the list in the correct position based on the
 171    * priority of each link matcher. New link matchers of equal priority are
 172    * considered after older link matchers.
 173    * @param matcher The link matcher to be added.
 174    */
 175   private _addLinkMatcherToList(matcher: IRegisteredLinkMatcher): void {
 176     if (this._linkMatchers.length === 0) {
 177       this._linkMatchers.push(matcher);
 178       return;
 179     }
 180
 181     for (let i = this._linkMatchers.length - 1; i >= 0; i--) {
 182       if (matcher.priority <= this._linkMatchers[i].priority) {
 183         this._linkMatchers.splice(i + 1, 0, matcher);
 184         return;
 185       }
 186     }
 187
 188     this._linkMatchers.splice(0, 0, matcher);
 189   }
 190
 191   /**
 192    * Deregisters a link matcher if it has been registered.
 193    * @param matcherId The link matcher's ID (returned after register)
 194    * @return Whether a link matcher was found and deregistered.
 195    */
 196   public deregisterLinkMatcher(matcherId: number): boolean {
 197     for (let i = 0; i < this._linkMatchers.length; i++) {
 198       if (this._linkMatchers[i].id === matcherId) {
 199         this._linkMatchers.splice(i, 1);
 200         return true;
 201       }
 202     }
 203     return false;
 204   }
 205
 206   /**
 207    * Linkifies a row given a specific handler.
 208    * @param rowIndex The row index to linkify (absolute index).
 209    * @param text string content of the unwrapped row.
 210    * @param matcher The link matcher for this line.
 211    */
 212   private _doLinkifyRow(rowIndex: number, text: string, matcher: ILinkMatcher): void {
 213     // clone regex to do a global search on text
 214     const rex = new RegExp(matcher.regex.source, (matcher.regex.flags || '') + 'g');
 215     let match;
 216     let stringIndex = -1;
 217     while ((match = rex.exec(text)) !== null) {
 218       const uri = match[typeof matcher.matchIndex !== 'number' ? 0 : matcher.matchIndex];
 219       if (!uri) {
 220         // something matched but does not comply with the given matchIndex
 221         // since this is most likely a bug the regex itself we simply do nothing here
 222         this._logService.debug('match found without corresponding matchIndex', match, matcher);
 223         break;
 224       }
 225
 226       // Get index, match.index is for the outer match which includes negated chars
 227       // therefore we cannot use match.index directly, instead we search the position
 228       // of the match group in text again
 229       // also correct regex and string search offsets for the next loop run
 230       stringIndex = text.indexOf(uri, stringIndex + 1);
 231       rex.lastIndex = stringIndex + uri.length;
 232       if (stringIndex < 0) {
 233         // invalid stringIndex (should not have happened)
 234         break;
 235       }
 236
 237       // get the buffer index as [absolute row, col] for the match
 238       const bufferIndex = this._bufferService.buffer.stringIndexToBufferIndex(rowIndex, stringIndex);
 239       if (bufferIndex[0] < 0) {
 240         // invalid bufferIndex (should not have happened)
 241         break;
 242       }
 243
 244       const line = this._bufferService.buffer.lines.get(bufferIndex[0]);
 245       if (!line) {
 246         break;
 247       }
 248
 249       const attr = line.getFg(bufferIndex[1]);
 250       const fg = attr ? (attr >> 9) & 0x1ff : undefined;
 251
 252       if (matcher.validationCallback) {
 253         matcher.validationCallback(uri, isValid => {
 254           // Discard link if the line has already changed
 255           if (this._rowsTimeoutId) {
 256             return;
 257           }
 258           if (isValid) {
 259             this._addLink(bufferIndex[1], bufferIndex[0] - this._bufferService.buffer.ydisp, uri, matcher, fg);
 260           }
 261         });
 262       } else {
 263         this._addLink(bufferIndex[1], bufferIndex[0] - this._bufferService.buffer.ydisp, uri, matcher, fg);
 264       }
 265     }
 266   }
 267
 268   /**
 269    * Registers a link to the mouse zone manager.
 270    * @param x The column the link starts.
 271    * @param y The row the link is on.
 272    * @param uri The URI of the link.
 273    * @param matcher The link matcher for the link.
 274    * @param fg The link color for hover event.
 275    */
 276   private _addLink(x: number, y: number, uri: string, matcher: ILinkMatcher, fg: number | undefined): void {
 277     if (!this._mouseZoneManager || !this._element) {
 278       return;
 279     }
 280
 281     const width = getStringCellWidth(uri);
 282     const x1 = x % this._bufferService.cols;
 283     const y1 = y + Math.floor(x / this._bufferService.cols);
 284     let x2 = (x1 + width) % this._bufferService.cols;
 285     let y2 = y1 + Math.floor((x1 + width) / this._bufferService.cols);
 286     if (x2 === 0) {
 287       x2 = this._bufferService.cols;
 288       y2--;
 289     }
 290
 291     this._mouseZoneManager.add(new MouseZone(
 292       x1 + 1,
 293       y1 + 1,
 294       x2 + 1,
 295       y2 + 1,
 296       e => {
 297         if (matcher.handler) {
 298           return matcher.handler(e, uri);
 299         }
 300         window.open(uri, '_blank');
 301       },
 302       () => {
 303         this._onLinkHover.fire(this._createLinkHoverEvent(x1, y1, x2, y2, fg));
 304         this._element!.classList.add('xterm-cursor-pointer');
 305       },
 306       e => {
 307         this._onLinkTooltip.fire(this._createLinkHoverEvent(x1, y1, x2, y2, fg));
 308         if (matcher.hoverTooltipCallback) {
 309           // Note that IViewportRange use 1-based coordinates to align with escape sequences such
 310           // as CUP which use 1,1 as the default for row/col
 311           matcher.hoverTooltipCallback(e, uri, { start: { x: x1, y: y1 }, end: { x: x2, y: y2 } });
 312         }
 313       },
 314       () => {
 315         this._onLinkLeave.fire(this._createLinkHoverEvent(x1, y1, x2, y2, fg));
 316         this._element!.classList.remove('xterm-cursor-pointer');
 317         if (matcher.hoverLeaveCallback) {
 318           matcher.hoverLeaveCallback();
 319         }
 320       },
 321       e => {
 322         if (matcher.willLinkActivate) {
 323           return matcher.willLinkActivate(e, uri);
 324         }
 325         return true;
 326       }
 327     ));
 328   }
 329
 330   private _createLinkHoverEvent(x1: number, y1: number, x2: number, y2: number, fg: number | undefined): ILinkifierEvent {
 331     return { x1, y1, x2, y2, cols: this._bufferService.cols, fg };
 332   }
 333 }
 334
 335 export class MouseZone implements IMouseZone {
 336   constructor(
 337     public x1: number,
 338     public y1: number,
 339     public x2: number,
 340     public y2: number,
 341     public clickCallback: (e: MouseEvent) => any,
 342     public hoverCallback: (e: MouseEvent) => any,
 343     public tooltipCallback: (e: MouseEvent) => any,
 344     public leaveCallback: () => void,
 345     public willLinkActivate: (e: MouseEvent) => boolean
 346   ) {
 347   }
 348 }