2 * Copyright (c) 2017 The xterm.js authors. All rights reserved.
6 import { IDisposable } from 'common/Types';
7 import { ParserState } from 'common/parser/Constants';
9 /** sequence params serialized to js arrays */
10 export type ParamsArray = (number | number[])[];
12 /** Params constructor type. */
13 export interface IParamsConstructor {
14 new(maxLength: number, maxSubParamsLength: number): IParams;
16 /** create params from ParamsArray */
17 fromArray(values: ParamsArray): IParams;
20 /** Interface of Params storage class. */
21 export interface IParams {
24 maxSubParamsLength: number;
26 /** param values and its length */
32 toArray(): ParamsArray;
34 addParam(value: number): void;
35 addSubParam(value: number): void;
36 hasSubParams(idx: number): boolean;
37 getSubParams(idx: number): Int32Array | null;
38 getSubParamsAll(): {[idx: number]: Int32Array};
42 * Internal state of EscapeSequenceParser.
43 * Used as argument of the error handler to allow
44 * introspection at runtime on parse errors.
45 * Return it with altered values to recover from
46 * faulty states (not yet supported).
47 * Set `abort` to `true` to abort the current parsing.
49 export interface IParsingState {
50 // position in parse string
52 // actual character code
54 // current parser state
55 currentState: ParserState;
56 // collect buffer with intermediate characters
60 // should abort (default: false)
65 * Command handler interfaces.
70 * Note: `params` is borrowed.
72 export type CsiHandlerType = (params: IParams) => boolean | void;
73 export type CsiFallbackHandlerType = (ident: number, params: IParams) => void;
78 export interface IDcsHandler {
80 * Called when a DCS command starts.
81 * Prepare needed data structures here.
82 * Note: `params` is borrowed.
84 hook(params: IParams): void;
86 * Incoming payload chunk.
87 * Note: `params` is borrowed.
89 put(data: Uint32Array, start: number, end: number): void;
91 * End of DCS command. `success` indicates whether the
92 * command finished normally or got aborted, thus final
93 * execution of the command should depend on `success`.
94 * To save memory also cleanup data structures here.
96 unhook(success: boolean): void | boolean;
98 export type DcsFallbackHandlerType = (ident: number, action: 'HOOK' | 'PUT' | 'UNHOOK', payload?: any) => void;
103 export type EscHandlerType = () => boolean | void;
104 export type EscFallbackHandlerType = (identifier: number) => void;
107 * EXECUTE handler types.
109 export type ExecuteHandlerType = () => boolean | void;
110 export type ExecuteFallbackHandlerType = (ident: number) => void;
115 export interface IOscHandler {
117 * Announces start of this OSC command.
118 * Prepare needed data structures here.
122 * Incoming data chunk.
123 * Note: Data is borrowed.
125 put(data: Uint32Array, start: number, end: number): void;
127 * End of OSC command. `success` indicates whether the
128 * command finished normally or got aborted, thus final
129 * execution of the command should depend on `success`.
130 * To save memory also cleanup data structures here.
132 end(success: boolean): void | boolean;
134 export type OscFallbackHandlerType = (ident: number, action: 'START' | 'PUT' | 'END', payload?: any) => void;
137 * PRINT handler types.
139 export type PrintHandlerType = (data: Uint32Array, start: number, end: number) => void;
140 export type PrintFallbackHandlerType = PrintHandlerType;
144 * EscapeSequenceParser interface.
146 export interface IEscapeSequenceParser extends IDisposable {
148 * Preceding codepoint to get REP working correctly.
149 * This must be set by the print handler as last action.
150 * It gets reset by the parser for any valid sequence beside REP itself.
152 precedingCodepoint: number;
155 * Reset the parser to its initial state (handlers are kept).
160 * Parse UTF32 codepoints in `data` up to `length`.
161 * @param data The data to parse.
163 parse(data: Uint32Array, length: number): void;
166 * Get string from numercial function identifier `ident`.
167 * Useful in fallback handlers which expose the low level
168 * numcerical function identifier for debugging purposes.
169 * Note: A full back translation to `IFunctionIdentifier`
170 * is not implemented.
172 identToString(ident: number): string;
174 setPrintHandler(handler: PrintHandlerType): void;
175 clearPrintHandler(): void;
177 setEscHandler(id: IFunctionIdentifier, handler: EscHandlerType): void;
178 clearEscHandler(id: IFunctionIdentifier): void;
179 setEscHandlerFallback(handler: EscFallbackHandlerType): void;
180 addEscHandler(id: IFunctionIdentifier, handler: EscHandlerType): IDisposable;
182 setExecuteHandler(flag: string, handler: ExecuteHandlerType): void;
183 clearExecuteHandler(flag: string): void;
184 setExecuteHandlerFallback(handler: ExecuteFallbackHandlerType): void;
186 setCsiHandler(id: IFunctionIdentifier, handler: CsiHandlerType): void;
187 clearCsiHandler(id: IFunctionIdentifier): void;
188 setCsiHandlerFallback(callback: CsiFallbackHandlerType): void;
189 addCsiHandler(id: IFunctionIdentifier, handler: CsiHandlerType): IDisposable;
191 setDcsHandler(id: IFunctionIdentifier, handler: IDcsHandler): void;
192 clearDcsHandler(id: IFunctionIdentifier): void;
193 setDcsHandlerFallback(handler: DcsFallbackHandlerType): void;
194 addDcsHandler(id: IFunctionIdentifier, handler: IDcsHandler): IDisposable;
196 setOscHandler(ident: number, handler: IOscHandler): void;
197 clearOscHandler(ident: number): void;
198 setOscHandlerFallback(handler: OscFallbackHandlerType): void;
199 addOscHandler(ident: number, handler: IOscHandler): IDisposable;
201 setErrorHandler(handler: (state: IParsingState) => IParsingState): void;
202 clearErrorHandler(): void;
206 * Subparser interfaces.
207 * The subparsers are instantiated in `EscapeSequenceParser` and
208 * called during `EscapeSequenceParser.parse`.
210 export interface ISubParser<T, U> extends IDisposable {
212 addHandler(ident: number, handler: T): IDisposable;
213 setHandler(ident: number, handler: T): void;
214 clearHandler(ident: number): void;
215 setHandlerFallback(handler: U): void;
216 put(data: Uint32Array, start: number, end: number): void;
219 export interface IOscParser extends ISubParser<IOscHandler, OscFallbackHandlerType> {
221 end(success: boolean): void;
224 export interface IDcsParser extends ISubParser<IDcsHandler, DcsFallbackHandlerType> {
225 hook(ident: number, params: IParams): void;
226 unhook(success: boolean): void;
230 * Interface to denote a specific ESC, CSI or DCS handler slot.
231 * The values are used to create an integer respresentation during handler
232 * regristation before passed to the subparsers as `ident`.
233 * The integer translation is made to allow a faster handler access
234 * in `EscapeSequenceParser.parse`.
236 export interface IFunctionIdentifier {
238 intermediates?: string;
242 export interface IHandlerCollection<T> {