hooks for custom control sequences

fixtures/typings-test/typings-test.ts

@@ -4,7 +4,7 @@
 
 /// <reference path="../../typings/xterm.d.ts" />
 
-import { Terminal } from 'xterm';
+import { Terminal, IDisposable } from 'xterm';
 
 namespace constructor {
   {
@@ -119,6 +119,12 @@ namespace methods_core {
     const t: Terminal = new Terminal();
     t.attachCustomKeyEventHandler((e: KeyboardEvent) => true);
     t.attachCustomKeyEventHandler((e: KeyboardEvent) => false);
+    const d1: IDisposable = t.addCsiHandler("x",
+       (params: number[], collect: string): boolean => params[0]===1);
+    d1.dispose();
+    const d2: IDisposable = t.addOscHandler(199,
+       (data: string): boolean => true);
+    d2.dispose();
   }
   namespace options {
     {

src/EscapeSequenceParser.ts

@@ -4,8 +4,13 @@
  */
 
 import { ParserState, ParserAction, IParsingState, IDcsHandler, IEscapeSequenceParser } from './Types';
+import { IDisposable } from 'xterm';
 import { Disposable } from './common/Lifecycle';
 
+interface IHandlerLink extends IDisposable {
+  nextHandler: IHandlerLink | null;
+}
+
 /**
  * Returns an array filled with numbers between the low and high parameters (right exclusive).
  * @param low The low number.
@@ -41,7 +46,7 @@ export class TransitionTable {
    * @param action parser action to be done
    * @param next next parser state
    */
-  add(code: number, state: number, action: number | null, next: number | null): void {
+  add(code: number, state: number, action: number | null, next: number | null):  void {
     this.table[state << 8 | code] = ((action | 0) << 4) | ((next === undefined) ? state : next);
   }
 
@@ -303,6 +308,38 @@ export class EscapeSequenceParser extends Disposable implements IEscapeSequenceP
     this._executeHandlerFb = callback;
   }
 
+  private _linkHandler(handlers: object[], index: number, newCallback: object): IDisposable {
+    const newHead: any = newCallback;
+    newHead.nextHandler = handlers[index] as IHandlerLink;
+    newHead.dispose = function (): void {
+          let previous = null;
+          let cur = handlers[index] as IHandlerLink;
+          for (; cur && cur.nextHandler;
+                 previous = cur, cur = cur.nextHandler) {
+            if (cur === newHead) {
+              if (previous) { previous.nextHandler = cur.nextHandler; }
+              else { handlers[index] = cur.nextHandler; }
+              break;
+            }
+          }
+      };
+    handlers[index] = newHead;
+    return newHead;
+  }
+
+  addCsiHandler(flag: string, callback: (params: number[], collect: string) => boolean): IDisposable {
+    const index = flag.charCodeAt(0);
+    const newHead =
+      (params: number[], collect: string): void => {
+        if (! callback(params, collect)) {
+          const next = (newHead as unknown as IHandlerLink).nextHandler;
+          if (next) { (next as any)(params, collect); }
+          else { this._csiHandlerFb(collect, params, index); }
+        }
+      };
+    return this._linkHandler(this._csiHandlers, index, newHead);
+  }
+
   setCsiHandler(flag: string, callback: (params: number[], collect: string) => void): void {
     this._csiHandlers[flag.charCodeAt(0)] = callback;
   }
@@ -323,6 +360,17 @@ export class EscapeSequenceParser extends Disposable implements IEscapeSequenceP
     this._escHandlerFb = callback;
   }
 
+  addOscHandler(ident: number, callback: (data: string) => boolean): IDisposable {
+    const newHead =
+      (data: string): void => {
+        if (! callback(data)) {
+          const next = (newHead as unknown as IHandlerLink).nextHandler;
+          if (next) { (next as any)(data); }
+          else { this._oscHandlerFb(ident, data); }
+        }
+      };
+    return this._linkHandler(this._oscHandlers, ident, newHead);
+  }
   setOscHandler(ident: number, callback: (data: string) => void): void {
     this._oscHandlers[ident] = callback;
   }

src/InputHandler.ts

@@ -12,6 +12,7 @@ import { FLAGS } from './renderer/Types';
 import { wcwidth } from './CharWidth';
 import { EscapeSequenceParser } from './EscapeSequenceParser';
 import { ICharset } from './core/Types';
+import { IDisposable } from 'xterm';
 import { Disposable } from './common/Lifecycle';
 
 /**
@@ -465,6 +466,13 @@ export class InputHandler extends Disposable implements IInputHandler {
     this._terminal.updateRange(buffer.y);
   }
 
+  addCsiHandler(flag: string, callback: (params: number[], collect: string) => boolean): IDisposable {
+    return this._parser.addCsiHandler(flag, callback);
+  }
+  addOscHandler(ident: number, callback: (data: string) => boolean): IDisposable {
+    return this._parser.addOscHandler(ident, callback);
+  }
+
   /**
    * BEL
    * Bell (Ctrl-G).

src/Terminal.ts

@@ -1413,6 +1413,15 @@ export class Terminal extends EventEmitter implements ITerminal, IDisposable, II
     this._customKeyEventHandler = customKeyEventHandler;
   }
 
+  /** Add handler for CSI escape sequence. See xterm.d.ts for details. */
+  public addCsiHandler(flag: string, callback: (params: number[], collect: string) => boolean): IDisposable {
+    return this._inputHandler.addCsiHandler(flag, callback);
+  }
+  /** Add handler for OSC escape sequence. See xterm.d.ts for details. */
+  public addOscHandler(ident: number, callback: (data: string) => boolean): IDisposable {
+    return this._inputHandler.addOscHandler(ident, callback);
+  }
+
   /**
    * Registers a link matcher, allowing custom link patterns to be matched and
    * handled.

src/Types.ts

@@ -492,6 +492,8 @@ export interface IEscapeSequenceParser extends IDisposable {
   setCsiHandler(flag: string, callback: (params: number[], collect: string) => void): void;
   clearCsiHandler(flag: string): void;
   setCsiHandlerFallback(callback: (collect: string, params: number[], flag: number) => void): void;
+  addCsiHandler(flag: string, callback: (params: number[], collect: string) => boolean): IDisposable;
+  addOscHandler(ident: number, callback: (data: string) => boolean): IDisposable;
 
   setEscHandler(collectAndFlag: string, callback: () => void): void;
   clearEscHandler(collectAndFlag: string): void;

src/public/Terminal.ts

@@ -59,6 +59,12 @@ export class Terminal implements ITerminalApi {
   public attachCustomKeyEventHandler(customKeyEventHandler: (event: KeyboardEvent) => boolean): void {
     this._core.attachCustomKeyEventHandler(customKeyEventHandler);
   }
+  public addCsiHandler(flag: string, callback: (params: number[], collect: string) => boolean): IDisposable {
+    return this._core.addCsiHandler(flag, callback);
+  }
+  public addOscHandler(ident: number, callback: (data: string) => boolean): IDisposable {
+    return this._core.addOscHandler(ident, callback);
+  }
   public registerLinkMatcher(regex: RegExp, handler: (event: MouseEvent, uri: string) => void, options?: ILinkMatcherOptions): number {
     return this._core.registerLinkMatcher(regex, handler, options);
   }

src/ui/TestUtils.test.ts

@@ -54,6 +54,12 @@ export class MockTerminal implements ITerminal {
   attachCustomKeyEventHandler(customKeyEventHandler: (event: KeyboardEvent) => boolean): void {
     throw new Error('Method not implemented.');
   }
+  addCsiHandler(flag: string, callback: (params: number[], collect: string) => boolean): IDisposable {
+      throw new Error('Method not implemented.');
+  }
+  addOscHandler(ident: number, callback: (data: string) => boolean): IDisposable {
+      throw new Error('Method not implemented.');
+  }
   registerLinkMatcher(regex: RegExp, handler: (event: MouseEvent, uri: string) => boolean | void, options?: ILinkMatcherOptions): number {
     throw new Error('Method not implemented.');
   }

typings/xterm.d.ts

@@ -481,6 +481,31 @@ declare module 'xterm' {
      */
     attachCustomKeyEventHandler(customKeyEventHandler: (event: KeyboardEvent) => boolean): void;
 
+    /**
+     * (EXPERIMENTAL) Adds a handler for CSI escape sequences.
+     * @param flag The flag should be one-character string, which specifies
+     *   the final character (e.g "m" for SGR) of the CSI sequence.
+     * @param callback The function to handle the escape sequence.
+     *   The callback is called with the numerical params,
+     *   as well as the special characters (e.g. "$" for DECSCPP).
+     *   Return true if the sequence was handled; false if we should
+     *   try a previous handler (set by addCsiHandler or setCsiHandler).
+     *   The most recently-added handler is tried first.
+     * @return An IDisposable you can call to remove this handler.
+     */
+    addCsiHandler(flag: string, callback: (params: number[], collect: string) => boolean): IDisposable;
+
+    /**
+     * (EXPERIMENTAL) Adds a handler for OSC escape sequences.
+     * @param ident The number (first parameter) of the sequence.
+     * @param callback The function to handle the escape sequence.
+     *   The callback is called with OSC data string.
+     *   Return true if the sequence was handled; false if we should
+     *   try a previous handler (set by addOscHandler or setOscHandler).
+     *   The most recently-added handler is tried first.
+     * @return An IDisposable you can call to remove this handler.
+     */
+    addOscHandler(ident: number, callback: (data: string) => boolean): IDisposable;
     /**
      * (EXPERIMENTAL) Registers a link matcher, allowing custom link patterns to
      * be matched and handled.