Home

Awesome

Build Status Coverage Status

A parser for ANSI escape code sequences. It implements the parser described here http://vt100.net/emu/dec_ansi_parser (thanks to Paul Williams).

NOTE ON UNICODE: The parser works with unicode strings. High characters (any above 0x9f) are only allowed within the string consuming states GROUND (for print), OSC_STRING and DCS_PASSTHROUGH. At any other state they will either be ignored (CSI_IGNORE and DCS_IGNORE) or cancel the active escape sequence. Although this doesn't follow any official specification (since I haven't found any) it seems to work with unicode terminal streams.

The parser uses callbacks to methods of a given terminal object. Methods a terminal should implement:

NOTE ON CALLBACK INVOCATIONS All callbacks will be triggered as soon as the escape sequence is finished.

The callbacks inst_o, inst_x, inst_c, inst_e, inst_H and int_U are guaranteed to be finished. If a corresponding escape sequence is not finished at the end of the parse input the parser will not trigger the callback until the sequence gets finished by later .parse calls.

inst_p and inst_P are not guaranteed to be finished. They can occur multiple times in a row and they will always be triggered at the end of the parse input:

Although the OSC subsystem is intended to work similar to the DCS subsystem the parser does not expose the osc_start, osc_end and osc_put calls. The OSC use cases are well defined and the data part is likely to be very short. Therefore the parser summarizes the OSC actions to only one final OSC callback. OSC parsing itself is not covered by this parser.

There is an optional inst_E(e) callback to track parsing errors with e containing all internal parser states at error time. By returning a similar object from this callback you can inject new values to the parsing process or abort it with {abort:true}. The parser will fall to state 'GROUND' and continue with the next character if you don't return anything (default behavior).

NOTE: If the terminal object doesn't provide the needed methods the parser will inject dummy methods to keep working.

Methods

Usage example

This example uses a simple terminal object, which just logs the actions:

var AnsiParser = require('node-ansiparser');

var terminal = {
    inst_p: function(s) {console.log('print', s);},
    inst_o: function(s) {console.log('osc', s);},
    inst_x: function(flag) {console.log('execute', flag.charCodeAt(0));},
    inst_c: function(collected, params, flag) {console.log('csi', collected, params, flag);},
    inst_e: function(collected, flag) {console.log('esc', collected, flag);},
    inst_H: function(collected, params, flag) {console.log('dcs-Hook', collected, params, flag);},
    inst_P: function(dcs) {console.log('dcs-Put', dcs);},
    inst_U: function() {console.log('dcs-Unhook');}
};


var parser = new AnsiParser(terminal);
parser.parse('\x1b[31mHello World!\n');
parser.parse('\x1bP0!u%5\x1b\'');

For a more complex terminal see node-ansiterminal.

Parser Throughput

The parser has a throughput of 50 - 100 MB/s with my desktop computer.