@xterm/xterm 5.4.0-beta.1

package/src/common/parser/OscParser.ts

@@ -0,0 +1,238 @@
+/**
+ * Copyright (c) 2019 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { IOscHandler, IHandlerCollection, OscFallbackHandlerType, IOscParser, ISubParserStackState } from 'common/parser/Types';
+import { OscState, PAYLOAD_LIMIT } from 'common/parser/Constants';
+import { utf32ToString } from 'common/input/TextDecoder';
+import { IDisposable } from 'common/Types';
+
+const EMPTY_HANDLERS: IOscHandler[] = [];
+
+export class OscParser implements IOscParser {
+  private _state = OscState.START;
+  private _active = EMPTY_HANDLERS;
+  private _id = -1;
+  private _handlers: IHandlerCollection<IOscHandler> = Object.create(null);
+  private _handlerFb: OscFallbackHandlerType = () => { };
+  private _stack: ISubParserStackState = {
+    paused: false,
+    loopPosition: 0,
+    fallThrough: false
+  };
+
+  public registerHandler(ident: number, handler: IOscHandler): IDisposable {
+    if (this._handlers[ident] === undefined) {
+      this._handlers[ident] = [];
+    }
+    const handlerList = this._handlers[ident];
+    handlerList.push(handler);
+    return {
+      dispose: () => {
+        const handlerIndex = handlerList.indexOf(handler);
+        if (handlerIndex !== -1) {
+          handlerList.splice(handlerIndex, 1);
+        }
+      }
+    };
+  }
+  public clearHandler(ident: number): void {
+    if (this._handlers[ident]) delete this._handlers[ident];
+  }
+  public setHandlerFallback(handler: OscFallbackHandlerType): void {
+    this._handlerFb = handler;
+  }
+
+  public dispose(): void {
+    this._handlers = Object.create(null);
+    this._handlerFb = () => { };
+    this._active = EMPTY_HANDLERS;
+  }
+
+  public reset(): void {
+    // force cleanup handlers if payload was already sent
+    if (this._state === OscState.PAYLOAD) {
+      for (let j = this._stack.paused ? this._stack.loopPosition - 1 : this._active.length - 1; j >= 0; --j) {
+        this._active[j].end(false);
+      }
+    }
+    this._stack.paused = false;
+    this._active = EMPTY_HANDLERS;
+    this._id = -1;
+    this._state = OscState.START;
+  }
+
+  private _start(): void {
+    this._active = this._handlers[this._id] || EMPTY_HANDLERS;
+    if (!this._active.length) {
+      this._handlerFb(this._id, 'START');
+    } else {
+      for (let j = this._active.length - 1; j >= 0; j--) {
+        this._active[j].start();
+      }
+    }
+  }
+
+  private _put(data: Uint32Array, start: number, end: number): void {
+    if (!this._active.length) {
+      this._handlerFb(this._id, 'PUT', utf32ToString(data, start, end));
+    } else {
+      for (let j = this._active.length - 1; j >= 0; j--) {
+        this._active[j].put(data, start, end);
+      }
+    }
+  }
+
+  public start(): void {
+    // always reset leftover handlers
+    this.reset();
+    this._state = OscState.ID;
+  }
+
+  /**
+   * Put data to current OSC command.
+   * Expects the identifier of the OSC command in the form
+   * OSC id ; payload ST/BEL
+   * Payload chunks are not further processed and get
+   * directly passed to the handlers.
+   */
+  public put(data: Uint32Array, start: number, end: number): void {
+    if (this._state === OscState.ABORT) {
+      return;
+    }
+    if (this._state === OscState.ID) {
+      while (start < end) {
+        const code = data[start++];
+        if (code === 0x3b) {
+          this._state = OscState.PAYLOAD;
+          this._start();
+          break;
+        }
+        if (code < 0x30 || 0x39 < code) {
+          this._state = OscState.ABORT;
+          return;
+        }
+        if (this._id === -1) {
+          this._id = 0;
+        }
+        this._id = this._id * 10 + code - 48;
+      }
+    }
+    if (this._state === OscState.PAYLOAD && end - start > 0) {
+      this._put(data, start, end);
+    }
+  }
+
+  /**
+   * Indicates end of an OSC command.
+   * Whether the OSC got aborted or finished normally
+   * is indicated by `success`.
+   */
+  public end(success: boolean, promiseResult: boolean = true): void | Promise<boolean> {
+    if (this._state === OscState.START) {
+      return;
+    }
+    // do nothing if command was faulty
+    if (this._state !== OscState.ABORT) {
+      // if we are still in ID state and get an early end
+      // means that the command has no payload thus we still have
+      // to announce START and send END right after
+      if (this._state === OscState.ID) {
+        this._start();
+      }
+
+      if (!this._active.length) {
+        this._handlerFb(this._id, 'END', success);
+      } else {
+        let handlerResult: boolean | Promise<boolean> = false;
+        let j = this._active.length - 1;
+        let fallThrough = false;
+        if (this._stack.paused) {
+          j = this._stack.loopPosition - 1;
+          handlerResult = promiseResult;
+          fallThrough = this._stack.fallThrough;
+          this._stack.paused = false;
+        }
+        if (!fallThrough && handlerResult === false) {
+          for (; j >= 0; j--) {
+            handlerResult = this._active[j].end(success);
+            if (handlerResult === true) {
+              break;
+            } else if (handlerResult instanceof Promise) {
+              this._stack.paused = true;
+              this._stack.loopPosition = j;
+              this._stack.fallThrough = false;
+              return handlerResult;
+            }
+          }
+          j--;
+        }
+        // cleanup left over handlers
+        // we always have to call .end for proper cleanup,
+        // here we use `success` to indicate whether a handler should execute
+        for (; j >= 0; j--) {
+          handlerResult = this._active[j].end(false);
+          if (handlerResult instanceof Promise) {
+            this._stack.paused = true;
+            this._stack.loopPosition = j;
+            this._stack.fallThrough = true;
+            return handlerResult;
+          }
+        }
+      }
+
+    }
+    this._active = EMPTY_HANDLERS;
+    this._id = -1;
+    this._state = OscState.START;
+  }
+}
+
+/**
+ * Convenient class to allow attaching string based handler functions
+ * as OSC handlers.
+ */
+export class OscHandler implements IOscHandler {
+  private _data = '';
+  private _hitLimit: boolean = false;
+
+  constructor(private _handler: (data: string) => boolean | Promise<boolean>) { }
+
+  public start(): void {
+    this._data = '';
+    this._hitLimit = false;
+  }
+
+  public put(data: Uint32Array, start: number, end: number): void {
+    if (this._hitLimit) {
+      return;
+    }
+    this._data += utf32ToString(data, start, end);
+    if (this._data.length > PAYLOAD_LIMIT) {
+      this._data = '';
+      this._hitLimit = true;
+    }
+  }
+
+  public end(success: boolean): boolean | Promise<boolean> {
+    let ret: boolean | Promise<boolean> = false;
+    if (this._hitLimit) {
+      ret = false;
+    } else if (success) {
+      ret = this._handler(this._data);
+      if (ret instanceof Promise) {
+        // need to hold data until `ret` got resolved
+        // dont care for errors, data will be freed anyway on next start
+        return ret.then(res => {
+          this._data = '';
+          this._hitLimit = false;
+          return res;
+        });
+      }
+    }
+    this._data = '';
+    this._hitLimit = false;
+    return ret;
+  }
+}

package/src/common/parser/Params.ts

@@ -0,0 +1,229 @@
+/**
+ * Copyright (c) 2019 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+import { IParams, ParamsArray } from 'common/parser/Types';
+
+// max value supported for a single param/subparam (clamped to positive int32 range)
+const MAX_VALUE = 0x7FFFFFFF;
+// max allowed subparams for a single sequence (hardcoded limitation)
+const MAX_SUBPARAMS = 256;
+
+/**
+ * Params storage class.
+ * This type is used by the parser to accumulate sequence parameters and sub parameters
+ * and transmit them to the input handler actions.
+ *
+ * NOTES:
+ *  - params object for action handlers is borrowed, use `.toArray` or `.clone` to get a copy
+ *  - never read beyond `params.length - 1` (likely to contain arbitrary data)
+ *  - `.getSubParams` returns a borrowed typed array, use `.getSubParamsAll` for cloned sub params
+ *  - hardcoded limitations:
+ *    - max. value for a single (sub) param is 2^31 - 1 (greater values are clamped to that)
+ *    - max. 256 sub params possible
+ *    - negative values are not allowed beside -1 (placeholder for default value)
+ *
+ * About ZDM (Zero Default Mode):
+ * ZDM is not orchestrated by this class. If the parser is in ZDM,
+ * it should add 0 for empty params, otherwise -1. This does not apply
+ * to subparams, empty subparams should always be added with -1.
+ */
+export class Params implements IParams {
+  // params store and length
+  public params: Int32Array;
+  public length: number;
+
+  // sub params store and length
+  protected _subParams: Int32Array;
+  protected _subParamsLength: number;
+
+  // sub params offsets from param: param idx --> [start, end] offset
+  private _subParamsIdx: Uint16Array;
+  private _rejectDigits: boolean;
+  private _rejectSubDigits: boolean;
+  private _digitIsSub: boolean;
+
+  /**
+   * Create a `Params` type from JS array representation.
+   */
+  public static fromArray(values: ParamsArray): Params {
+    const params = new Params();
+    if (!values.length) {
+      return params;
+    }
+    // skip leading sub params
+    for (let i = (Array.isArray(values[0])) ? 1 : 0; i < values.length; ++i) {
+      const value = values[i];
+      if (Array.isArray(value)) {
+        for (let k = 0; k < value.length; ++k) {
+          params.addSubParam(value[k]);
+        }
+      } else {
+        params.addParam(value);
+      }
+    }
+    return params;
+  }
+
+  /**
+   * @param maxLength max length of storable parameters
+   * @param maxSubParamsLength max length of storable sub parameters
+   */
+  constructor(public maxLength: number = 32, public maxSubParamsLength: number = 32) {
+    if (maxSubParamsLength > MAX_SUBPARAMS) {
+      throw new Error('maxSubParamsLength must not be greater than 256');
+    }
+    this.params = new Int32Array(maxLength);
+    this.length = 0;
+    this._subParams = new Int32Array(maxSubParamsLength);
+    this._subParamsLength = 0;
+    this._subParamsIdx = new Uint16Array(maxLength);
+    this._rejectDigits = false;
+    this._rejectSubDigits = false;
+    this._digitIsSub = false;
+  }
+
+  /**
+   * Clone object.
+   */
+  public clone(): Params {
+    const newParams = new Params(this.maxLength, this.maxSubParamsLength);
+    newParams.params.set(this.params);
+    newParams.length = this.length;
+    newParams._subParams.set(this._subParams);
+    newParams._subParamsLength = this._subParamsLength;
+    newParams._subParamsIdx.set(this._subParamsIdx);
+    newParams._rejectDigits = this._rejectDigits;
+    newParams._rejectSubDigits = this._rejectSubDigits;
+    newParams._digitIsSub = this._digitIsSub;
+    return newParams;
+  }
+
+  /**
+   * Get a JS array representation of the current parameters and sub parameters.
+   * The array is structured as follows:
+   *    sequence: "1;2:3:4;5::6"
+   *    array   : [1, 2, [3, 4], 5, [-1, 6]]
+   */
+  public toArray(): ParamsArray {
+    const res: ParamsArray = [];
+    for (let i = 0; i < this.length; ++i) {
+      res.push(this.params[i]);
+      const start = this._subParamsIdx[i] >> 8;
+      const end = this._subParamsIdx[i] & 0xFF;
+      if (end - start > 0) {
+        res.push(Array.prototype.slice.call(this._subParams, start, end));
+      }
+    }
+    return res;
+  }
+
+  /**
+   * Reset to initial empty state.
+   */
+  public reset(): void {
+    this.length = 0;
+    this._subParamsLength = 0;
+    this._rejectDigits = false;
+    this._rejectSubDigits = false;
+    this._digitIsSub = false;
+  }
+
+  /**
+   * Add a parameter value.
+   * `Params` only stores up to `maxLength` parameters, any later
+   * parameter will be ignored.
+   * Note: VT devices only stored up to 16 values, xterm seems to
+   * store up to 30.
+   */
+  public addParam(value: number): void {
+    this._digitIsSub = false;
+    if (this.length >= this.maxLength) {
+      this._rejectDigits = true;
+      return;
+    }
+    if (value < -1) {
+      throw new Error('values lesser than -1 are not allowed');
+    }
+    this._subParamsIdx[this.length] = this._subParamsLength << 8 | this._subParamsLength;
+    this.params[this.length++] = value > MAX_VALUE ? MAX_VALUE : value;
+  }
+
+  /**
+   * Add a sub parameter value.
+   * The sub parameter is automatically associated with the last parameter value.
+   * Thus it is not possible to add a subparameter without any parameter added yet.
+   * `Params` only stores up to `subParamsLength` sub parameters, any later
+   * sub parameter will be ignored.
+   */
+  public addSubParam(value: number): void {
+    this._digitIsSub = true;
+    if (!this.length) {
+      return;
+    }
+    if (this._rejectDigits || this._subParamsLength >= this.maxSubParamsLength) {
+      this._rejectSubDigits = true;
+      return;
+    }
+    if (value < -1) {
+      throw new Error('values lesser than -1 are not allowed');
+    }
+    this._subParams[this._subParamsLength++] = value > MAX_VALUE ? MAX_VALUE : value;
+    this._subParamsIdx[this.length - 1]++;
+  }
+
+  /**
+   * Whether parameter at index `idx` has sub parameters.
+   */
+  public hasSubParams(idx: number): boolean {
+    return ((this._subParamsIdx[idx] & 0xFF) - (this._subParamsIdx[idx] >> 8) > 0);
+  }
+
+  /**
+   * Return sub parameters for parameter at index `idx`.
+   * Note: The values are borrowed, thus you need to copy
+   * the values if you need to hold them in nonlocal scope.
+   */
+  public getSubParams(idx: number): Int32Array | null {
+    const start = this._subParamsIdx[idx] >> 8;
+    const end = this._subParamsIdx[idx] & 0xFF;
+    if (end - start > 0) {
+      return this._subParams.subarray(start, end);
+    }
+    return null;
+  }
+
+  /**
+   * Return all sub parameters as {idx: subparams} mapping.
+   * Note: The values are not borrowed.
+   */
+  public getSubParamsAll(): {[idx: number]: Int32Array} {
+    const result: {[idx: number]: Int32Array} = {};
+    for (let i = 0; i < this.length; ++i) {
+      const start = this._subParamsIdx[i] >> 8;
+      const end = this._subParamsIdx[i] & 0xFF;
+      if (end - start > 0) {
+        result[i] = this._subParams.slice(start, end);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Add a single digit value to current parameter.
+   * This is used by the parser to account digits on a char by char basis.
+   */
+  public addDigit(value: number): void {
+    let length;
+    if (this._rejectDigits
+      || !(length = this._digitIsSub ? this._subParamsLength : this.length)
+      || (this._digitIsSub && this._rejectSubDigits)
+    ) {
+      return;
+    }
+
+    const store = this._digitIsSub ? this._subParams : this.params;
+    const cur = store[length - 1];
+    store[length - 1] = ~cur ? Math.min(cur * 10 + value, MAX_VALUE) : value;
+  }
+}