@xterm/xterm 5.4.0-beta.1

package/src/common/parser/Types.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Copyright (c) 2017 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { IDisposable } from 'common/Types';
+import { ParserState } from 'common/parser/Constants';
+
+
+/** sequence params serialized to js arrays */
+export type ParamsArray = (number | number[])[];
+
+/** Params constructor type. */
+export interface IParamsConstructor {
+  new(maxLength: number, maxSubParamsLength: number): IParams;
+
+  /** create params from ParamsArray */
+  fromArray(values: ParamsArray): IParams;
+}
+
+/** Interface of Params storage class. */
+export interface IParams {
+  /** from ctor */
+  maxLength: number;
+  maxSubParamsLength: number;
+
+  /** param values and its length */
+  params: Int32Array;
+  length: number;
+
+  /** methods */
+  clone(): IParams;
+  toArray(): ParamsArray;
+  reset(): void;
+  addParam(value: number): void;
+  addSubParam(value: number): void;
+  hasSubParams(idx: number): boolean;
+  getSubParams(idx: number): Int32Array | null;
+  getSubParamsAll(): {[idx: number]: Int32Array};
+}
+
+/**
+ * Internal state of EscapeSequenceParser.
+ * Used as argument of the error handler to allow
+ * introspection at runtime on parse errors.
+ * Return it with altered values to recover from
+ * faulty states (not yet supported).
+ * Set `abort` to `true` to abort the current parsing.
+ */
+export interface IParsingState {
+  // position in parse string
+  position: number;
+  // actual character code
+  code: number;
+  // current parser state
+  currentState: ParserState;
+  // collect buffer with intermediate characters
+  collect: number;
+  // params buffer
+  params: IParams;
+  // should abort (default: false)
+  abort: boolean;
+}
+
+/**
+ * Command handler interfaces.
+ */
+
+/**
+ * CSI handler types.
+ * Note: `params` is borrowed.
+ */
+export type CsiHandlerType = (params: IParams) => boolean | Promise<boolean>;
+export type CsiFallbackHandlerType = (ident: number, params: IParams) => void;
+
+/**
+ * DCS handler types.
+ */
+export interface IDcsHandler {
+  /**
+   * Called when a DCS command starts.
+   * Prepare needed data structures here.
+   * Note: `params` is borrowed.
+   */
+  hook(params: IParams): void;
+  /**
+   * Incoming payload chunk.
+   * Note: `params` is borrowed.
+   */
+  put(data: Uint32Array, start: number, end: number): void;
+  /**
+   * End of DCS command. `success` indicates whether the
+   * command finished normally or got aborted, thus final
+   * execution of the command should depend on `success`.
+   * To save memory also cleanup data structures here.
+   */
+  unhook(success: boolean): boolean | Promise<boolean>;
+}
+export type DcsFallbackHandlerType = (ident: number, action: 'HOOK' | 'PUT' | 'UNHOOK', payload?: any) => void;
+
+/**
+ * ESC handler types.
+ */
+export type EscHandlerType = () => boolean | Promise<boolean>;
+export type EscFallbackHandlerType = (identifier: number) => void;
+
+/**
+ * EXECUTE handler types.
+ */
+export type ExecuteHandlerType = () => boolean;
+export type ExecuteFallbackHandlerType = (ident: number) => void;
+
+/**
+ * OSC handler types.
+ */
+export interface IOscHandler {
+  /**
+   * Announces start of this OSC command.
+   * Prepare needed data structures here.
+   */
+  start(): void;
+  /**
+   * Incoming data chunk.
+   * Note: Data is borrowed.
+   */
+  put(data: Uint32Array, start: number, end: number): void;
+  /**
+   * End of OSC command. `success` indicates whether the
+   * command finished normally or got aborted, thus final
+   * execution of the command should depend on `success`.
+   * To save memory also cleanup data structures here.
+   */
+  end(success: boolean): boolean | Promise<boolean>;
+}
+export type OscFallbackHandlerType = (ident: number, action: 'START' | 'PUT' | 'END', payload?: any) => void;
+
+/**
+ * PRINT handler types.
+ */
+export type PrintHandlerType = (data: Uint32Array, start: number, end: number) => void;
+export type PrintFallbackHandlerType = PrintHandlerType;
+
+
+/**
+ * EscapeSequenceParser interface.
+ */
+export interface IEscapeSequenceParser extends IDisposable {
+  /**
+   * Preceding grapheme-join-state.
+   * Used for joining grapheme clusters across calls to `print`.
+   * Also used by REP to check if repeating a character is allowed.
+   * It gets reset by the parser for any valid sequence besides text.
+   */
+  precedingJoinState: number; // More specifically: UnicodeJoinProperties
+
+  /**
+   * Reset the parser to its initial state (handlers are kept).
+   */
+  reset(): void;
+
+  /**
+   * Parse UTF32 codepoints in `data` up to `length`.
+   * @param data The data to parse.
+   */
+  parse(data: Uint32Array, length: number, promiseResult?: boolean): void | Promise<boolean>;
+
+  /**
+   * Get string from numercial function identifier `ident`.
+   * Useful in fallback handlers which expose the low level
+   * numcerical function identifier for debugging purposes.
+   * Note: A full back translation to `IFunctionIdentifier`
+   * is not implemented.
+   */
+  identToString(ident: number): string;
+
+  setPrintHandler(handler: PrintHandlerType): void;
+  clearPrintHandler(): void;
+
+  registerEscHandler(id: IFunctionIdentifier, handler: EscHandlerType): IDisposable;
+  clearEscHandler(id: IFunctionIdentifier): void;
+  setEscHandlerFallback(handler: EscFallbackHandlerType): void;
+
+  setExecuteHandler(flag: string, handler: ExecuteHandlerType): void;
+  clearExecuteHandler(flag: string): void;
+  setExecuteHandlerFallback(handler: ExecuteFallbackHandlerType): void;
+
+  registerCsiHandler(id: IFunctionIdentifier, handler: CsiHandlerType): IDisposable;
+  clearCsiHandler(id: IFunctionIdentifier): void;
+  setCsiHandlerFallback(callback: CsiFallbackHandlerType): void;
+
+  registerDcsHandler(id: IFunctionIdentifier, handler: IDcsHandler): IDisposable;
+  clearDcsHandler(id: IFunctionIdentifier): void;
+  setDcsHandlerFallback(handler: DcsFallbackHandlerType): void;
+
+  registerOscHandler(ident: number, handler: IOscHandler): IDisposable;
+  clearOscHandler(ident: number): void;
+  setOscHandlerFallback(handler: OscFallbackHandlerType): void;
+
+  setErrorHandler(handler: (state: IParsingState) => IParsingState): void;
+  clearErrorHandler(): void;
+}
+
+/**
+ * Subparser interfaces.
+ * The subparsers are instantiated in `EscapeSequenceParser` and
+ * called during `EscapeSequenceParser.parse`.
+ */
+export interface ISubParser<T, U> extends IDisposable {
+  reset(): void;
+  registerHandler(ident: number, handler: T): IDisposable;
+  clearHandler(ident: number): void;
+  setHandlerFallback(handler: U): void;
+  put(data: Uint32Array, start: number, end: number): void;
+}
+
+export interface IOscParser extends ISubParser<IOscHandler, OscFallbackHandlerType> {
+  start(): void;
+  end(success: boolean, promiseResult?: boolean): void | Promise<boolean>;
+}
+
+export interface IDcsParser extends ISubParser<IDcsHandler, DcsFallbackHandlerType> {
+  hook(ident: number, params: IParams): void;
+  unhook(success: boolean, promiseResult?: boolean): void | Promise<boolean>;
+}
+
+/**
+ * Interface to denote a specific ESC, CSI or DCS handler slot.
+ * The values are used to create an integer respresentation during handler
+ * regristation before passed to the subparsers as `ident`.
+ * The integer translation is made to allow a faster handler access
+ * in `EscapeSequenceParser.parse`.
+ */
+export interface IFunctionIdentifier {
+  prefix?: string;
+  intermediates?: string;
+  final: string;
+}
+
+export interface IHandlerCollection<T> {
+  [key: string]: T[];
+}
+
+/**
+ * Types for async parser support.
+ */
+
+// type of saved stack state in parser
+export const enum ParserStackType {
+  NONE = 0,
+  FAIL,
+  RESET,
+  CSI,
+  ESC,
+  OSC,
+  DCS
+}
+
+// aggregate of resumable handler lists
+export type ResumableHandlersType = CsiHandlerType[] | EscHandlerType[];
+
+// saved stack state of the parser
+export interface IParserStackState {
+  state: ParserStackType;
+  handlers: ResumableHandlersType;
+  handlerPos: number;
+  transition: number;
+  chunkPos: number;
+}
+
+// saved stack state of subparser (OSC and DCS)
+export interface ISubParserStackState {
+  paused: boolean;
+  loopPosition: number;
+  fallThrough: boolean;
+}

package/src/common/public/AddonManager.ts

@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) 2019 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { ITerminalAddon, IDisposable, Terminal } from '@xterm/xterm';
+
+export interface ILoadedAddon {
+  instance: ITerminalAddon;
+  dispose: () => void;
+  isDisposed: boolean;
+}
+
+export class AddonManager implements IDisposable {
+  protected _addons: ILoadedAddon[] = [];
+
+  public dispose(): void {
+    for (let i = this._addons.length - 1; i >= 0; i--) {
+      this._addons[i].instance.dispose();
+    }
+  }
+
+  public loadAddon(terminal: Terminal, instance: ITerminalAddon): void {
+    const loadedAddon: ILoadedAddon = {
+      instance,
+      dispose: instance.dispose,
+      isDisposed: false
+    };
+    this._addons.push(loadedAddon);
+    instance.dispose = () => this._wrappedAddonDispose(loadedAddon);
+    instance.activate(terminal as any);
+  }
+
+  private _wrappedAddonDispose(loadedAddon: ILoadedAddon): void {
+    if (loadedAddon.isDisposed) {
+      // Do nothing if already disposed
+      return;
+    }
+    let index = -1;
+    for (let i = 0; i < this._addons.length; i++) {
+      if (this._addons[i] === loadedAddon) {
+        index = i;
+        break;
+      }
+    }
+    if (index === -1) {
+      throw new Error('Could not dispose an addon that has not been loaded');
+    }
+    loadedAddon.isDisposed = true;
+    loadedAddon.dispose.apply(loadedAddon.instance);
+    this._addons.splice(index, 1);
+  }
+}

package/src/common/public/BufferApiView.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) 2021 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { IBuffer as IBufferApi, IBufferLine as IBufferLineApi, IBufferCell as IBufferCellApi } from '@xterm/xterm';
+import { IBuffer } from 'common/buffer/Types';
+import { BufferLineApiView } from 'common/public/BufferLineApiView';
+import { CellData } from 'common/buffer/CellData';
+
+export class BufferApiView implements IBufferApi {
+  constructor(
+    private _buffer: IBuffer,
+    public readonly type: 'normal' | 'alternate'
+  ) { }
+
+  public init(buffer: IBuffer): BufferApiView {
+    this._buffer = buffer;
+    return this;
+  }
+
+  public get cursorY(): number { return this._buffer.y; }
+  public get cursorX(): number { return this._buffer.x; }
+  public get viewportY(): number { return this._buffer.ydisp; }
+  public get baseY(): number { return this._buffer.ybase; }
+  public get length(): number { return this._buffer.lines.length; }
+  public getLine(y: number): IBufferLineApi | undefined {
+    const line = this._buffer.lines.get(y);
+    if (!line) {
+      return undefined;
+    }
+    return new BufferLineApiView(line);
+  }
+  public getNullCell(): IBufferCellApi { return new CellData(); }
+}

package/src/common/public/BufferLineApiView.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) 2021 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { CellData } from 'common/buffer/CellData';
+import { IBufferLine, ICellData } from 'common/Types';
+import { IBufferCell as IBufferCellApi, IBufferLine as IBufferLineApi } from '@xterm/xterm';
+
+export class BufferLineApiView implements IBufferLineApi {
+  constructor(private _line: IBufferLine) { }
+
+  public get isWrapped(): boolean { return this._line.isWrapped; }
+  public get length(): number { return this._line.length; }
+  public getCell(x: number, cell?: IBufferCellApi): IBufferCellApi | undefined {
+    if (x < 0 || x >= this._line.length) {
+      return undefined;
+    }
+
+    if (cell) {
+      this._line.loadCell(x, cell as ICellData);
+      return cell;
+    }
+    return this._line.loadCell(x, new CellData());
+  }
+  public translateToString(trimRight?: boolean, startColumn?: number, endColumn?: number): string {
+    return this._line.translateToString(trimRight, startColumn, endColumn);
+  }
+}

package/src/common/public/BufferNamespaceApi.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) 2021 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { IBuffer as IBufferApi, IBufferNamespace as IBufferNamespaceApi } from '@xterm/xterm';
+import { BufferApiView } from 'common/public/BufferApiView';
+import { EventEmitter } from 'common/EventEmitter';
+import { ICoreTerminal } from 'common/Types';
+import { Disposable } from 'common/Lifecycle';
+
+export class BufferNamespaceApi extends Disposable implements IBufferNamespaceApi {
+  private _normal: BufferApiView;
+  private _alternate: BufferApiView;
+
+  private readonly _onBufferChange = this.register(new EventEmitter<IBufferApi>());
+  public readonly onBufferChange = this._onBufferChange.event;
+
+  constructor(private _core: ICoreTerminal) {
+    super();
+    this._normal = new BufferApiView(this._core.buffers.normal, 'normal');
+    this._alternate = new BufferApiView(this._core.buffers.alt, 'alternate');
+    this._core.buffers.onBufferActivate(() => this._onBufferChange.fire(this.active));
+  }
+  public get active(): IBufferApi {
+    if (this._core.buffers.active === this._core.buffers.normal) { return this.normal; }
+    if (this._core.buffers.active === this._core.buffers.alt) { return this.alternate; }
+    throw new Error('Active buffer is neither normal nor alternate');
+  }
+  public get normal(): IBufferApi {
+    return this._normal.init(this._core.buffers.normal);
+  }
+  public get alternate(): IBufferApi {
+    return this._alternate.init(this._core.buffers.alt);
+  }
+}

package/src/common/public/ParserApi.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) 2021 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { IParams } from 'common/parser/Types';
+import { IDisposable, IFunctionIdentifier, IParser } from '@xterm/xterm';
+import { ICoreTerminal } from 'common/Types';
+
+export class ParserApi implements IParser {
+  constructor(private _core: ICoreTerminal) { }
+
+  public registerCsiHandler(id: IFunctionIdentifier, callback: (params: (number | number[])[]) => boolean | Promise<boolean>): IDisposable {
+    return this._core.registerCsiHandler(id, (params: IParams) => callback(params.toArray()));
+  }
+  public addCsiHandler(id: IFunctionIdentifier, callback: (params: (number | number[])[]) => boolean | Promise<boolean>): IDisposable {
+    return this.registerCsiHandler(id, callback);
+  }
+  public registerDcsHandler(id: IFunctionIdentifier, callback: (data: string, param: (number | number[])[]) => boolean | Promise<boolean>): IDisposable {
+    return this._core.registerDcsHandler(id, (data: string, params: IParams) => callback(data, params.toArray()));
+  }
+  public addDcsHandler(id: IFunctionIdentifier, callback: (data: string, param: (number | number[])[]) => boolean | Promise<boolean>): IDisposable {
+    return this.registerDcsHandler(id, callback);
+  }
+  public registerEscHandler(id: IFunctionIdentifier, handler: () => boolean | Promise<boolean>): IDisposable {
+    return this._core.registerEscHandler(id, handler);
+  }
+  public addEscHandler(id: IFunctionIdentifier, handler: () => boolean | Promise<boolean>): IDisposable {
+    return this.registerEscHandler(id, handler);
+  }
+  public registerOscHandler(ident: number, callback: (data: string) => boolean | Promise<boolean>): IDisposable {
+    return this._core.registerOscHandler(ident, callback);
+  }
+  public addOscHandler(ident: number, callback: (data: string) => boolean | Promise<boolean>): IDisposable {
+    return this.registerOscHandler(ident, callback);
+  }
+}

package/src/common/public/UnicodeApi.ts

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2021 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { ICoreTerminal } from 'common/Types';
+import { IUnicodeHandling, IUnicodeVersionProvider } from '@xterm/xterm';
+
+export class UnicodeApi implements IUnicodeHandling {
+  constructor(private _core: ICoreTerminal) { }
+
+  public register(provider: IUnicodeVersionProvider): void {
+    this._core.unicodeService.register(provider);
+  }
+
+  public get versions(): string[] {
+    return this._core.unicodeService.versions;
+  }
+
+  public get activeVersion(): string {
+    return this._core.unicodeService.activeVersion;
+  }
+
+  public set activeVersion(version: string) {
+    this._core.unicodeService.activeVersion = version;
+  }
+}

package/src/common/services/BufferService.ts

@@ -0,0 +1,151 @@
+/**
+ * Copyright (c) 2019 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { EventEmitter } from 'common/EventEmitter';
+import { Disposable } from 'common/Lifecycle';
+import { IAttributeData, IBufferLine, ScrollSource } from 'common/Types';
+import { BufferSet } from 'common/buffer/BufferSet';
+import { IBuffer, IBufferSet } from 'common/buffer/Types';
+import { IBufferService, IOptionsService } from 'common/services/Services';
+
+export const MINIMUM_COLS = 2; // Less than 2 can mess with wide chars
+export const MINIMUM_ROWS = 1;
+
+export class BufferService extends Disposable implements IBufferService {
+  public serviceBrand: any;
+
+  public cols: number;
+  public rows: number;
+  public buffers: IBufferSet;
+  /** Whether the user is scrolling (locks the scroll position) */
+  public isUserScrolling: boolean = false;
+
+  private readonly _onResize = this.register(new EventEmitter<{ cols: number, rows: number }>());
+  public readonly onResize = this._onResize.event;
+  private readonly _onScroll = this.register(new EventEmitter<number>());
+  public readonly onScroll = this._onScroll.event;
+
+  public get buffer(): IBuffer { return this.buffers.active; }
+
+  /** An IBufferline to clone/copy from for new blank lines */
+  private _cachedBlankLine: IBufferLine | undefined;
+
+  constructor(@IOptionsService optionsService: IOptionsService) {
+    super();
+    this.cols = Math.max(optionsService.rawOptions.cols || 0, MINIMUM_COLS);
+    this.rows = Math.max(optionsService.rawOptions.rows || 0, MINIMUM_ROWS);
+    this.buffers = this.register(new BufferSet(optionsService, this));
+  }
+
+  public resize(cols: number, rows: number): void {
+    this.cols = cols;
+    this.rows = rows;
+    this.buffers.resize(cols, rows);
+    // TODO: This doesn't fire when scrollback changes - add a resize event to BufferSet and forward
+    //       event
+    this._onResize.fire({ cols, rows });
+  }
+
+  public reset(): void {
+    this.buffers.reset();
+    this.isUserScrolling = false;
+  }
+
+  /**
+   * Scroll the terminal down 1 row, creating a blank line.
+   * @param eraseAttr The attribute data to use the for blank line.
+   * @param isWrapped Whether the new line is wrapped from the previous line.
+   */
+  public scroll(eraseAttr: IAttributeData, isWrapped: boolean = false): void {
+    const buffer = this.buffer;
+
+    let newLine: IBufferLine | undefined;
+    newLine = this._cachedBlankLine;
+    if (!newLine || newLine.length !== this.cols || newLine.getFg(0) !== eraseAttr.fg || newLine.getBg(0) !== eraseAttr.bg) {
+      newLine = buffer.getBlankLine(eraseAttr, isWrapped);
+      this._cachedBlankLine = newLine;
+    }
+    newLine.isWrapped = isWrapped;
+
+    const topRow = buffer.ybase + buffer.scrollTop;
+    const bottomRow = buffer.ybase + buffer.scrollBottom;
+
+    if (buffer.scrollTop === 0) {
+      // Determine whether the buffer is going to be trimmed after insertion.
+      const willBufferBeTrimmed = buffer.lines.isFull;
+
+      // Insert the line using the fastest method
+      if (bottomRow === buffer.lines.length - 1) {
+        if (willBufferBeTrimmed) {
+          buffer.lines.recycle().copyFrom(newLine);
+        } else {
+          buffer.lines.push(newLine.clone());
+        }
+      } else {
+        buffer.lines.splice(bottomRow + 1, 0, newLine.clone());
+      }
+
+      // Only adjust ybase and ydisp when the buffer is not trimmed
+      if (!willBufferBeTrimmed) {
+        buffer.ybase++;
+        // Only scroll the ydisp with ybase if the user has not scrolled up
+        if (!this.isUserScrolling) {
+          buffer.ydisp++;
+        }
+      } else {
+        // When the buffer is full and the user has scrolled up, keep the text
+        // stable unless ydisp is right at the top
+        if (this.isUserScrolling) {
+          buffer.ydisp = Math.max(buffer.ydisp - 1, 0);
+        }
+      }
+    } else {
+      // scrollTop is non-zero which means no line will be going to the
+      // scrollback, instead we can just shift them in-place.
+      const scrollRegionHeight = bottomRow - topRow + 1 /* as it's zero-based */;
+      buffer.lines.shiftElements(topRow + 1, scrollRegionHeight - 1, -1);
+      buffer.lines.set(bottomRow, newLine.clone());
+    }
+
+    // Move the viewport to the bottom of the buffer unless the user is
+    // scrolling.
+    if (!this.isUserScrolling) {
+      buffer.ydisp = buffer.ybase;
+    }
+
+    this._onScroll.fire(buffer.ydisp);
+  }
+
+  /**
+   * Scroll the display of the terminal
+   * @param disp The number of lines to scroll down (negative scroll up).
+   * @param suppressScrollEvent Don't emit the scroll event as scrollLines. This is used
+   * to avoid unwanted events being handled by the viewport when the event was triggered from the
+   * viewport originally.
+   */
+  public scrollLines(disp: number, suppressScrollEvent?: boolean, source?: ScrollSource): void {
+    const buffer = this.buffer;
+    if (disp < 0) {
+      if (buffer.ydisp === 0) {
+        return;
+      }
+      this.isUserScrolling = true;
+    } else if (disp + buffer.ydisp >= buffer.ybase) {
+      this.isUserScrolling = false;
+    }
+
+    const oldYdisp = buffer.ydisp;
+    buffer.ydisp = Math.max(Math.min(buffer.ydisp + disp, buffer.ybase), 0);
+
+    // No change occurred, don't trigger scroll/refresh
+    if (oldYdisp === buffer.ydisp) {
+      return;
+    }
+
+    if (!suppressScrollEvent) {
+      this._onScroll.fire(buffer.ydisp);
+    }
+  }
+}

package/src/common/services/CharsetService.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright (c) 2019 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { ICharsetService } from 'common/services/Services';
+import { ICharset } from 'common/Types';
+
+export class CharsetService implements ICharsetService {
+  public serviceBrand: any;
+
+  public charset: ICharset | undefined;
+  public glevel: number = 0;
+
+  private _charsets: (ICharset | undefined)[] = [];
+
+  public reset(): void {
+    this.charset = undefined;
+    this._charsets = [];
+    this.glevel = 0;
+  }
+
+  public setgLevel(g: number): void {
+    this.glevel = g;
+    this.charset = this._charsets[g];
+  }
+
+  public setgCharset(g: number, charset: ICharset | undefined): void {
+    this._charsets[g] = charset;
+    if (this.glevel === g) {
+      this.charset = charset;
+    }
+  }
+}