api.md

June 24, 2016 · View on GitHub

node-ansiterminal

Example

var ansiterminal = require('node-ansiterminal')

node-ansiterminal
- static
  - .TChar
    - new TChar(c, attr, gb, width)
    - instance
      - .clone() ⇒ TChar
      - .equals(other) ⇒ boolean
      - .serialize() ⇒ Array
      - .getAttributes() ⇒ TAttributes
      - .getJSONAttributes() ⇒ TJSONAttributes
      - .setAttributes(attributes)
    - static
      - .deserialize(o) ⇒ TChar
  - .TRow
    - new TRow(length, tchar)
    - instance
      - .serialize() ⇒ Array
      - .toString(opts) ⇒ string
      - .toMergedArray(opts) ⇒ Array
      - .toJSON(opts) ⇒ JSONTRow
      - .toEscapeString(opts) ⇒ string
      - .toHTML(opts) ⇒ string
    - static
      - .deserialize(o) ⇒ TRow
  - .AnsiTerminal
  - .wcswidth(s) ⇒ number
  - .get_color(value) ⇒ string
  - .DCS_Dummy()
  - .DCS_DECRQSS()
- inner
  - ~TColors : Object
  - ~TAttributes : Object
  - ~TJSONColors : Object
  - ~TJSONAttributes : Object
  - ~JSONTRow : Object

ansiterminal.TChar

A TChar is a terminal character with text attributes and width. In the terminal emulator it represents a terminal cell in a TRow. The actual character is saved in c.

width is the printed space of the character according to unicode. It can be 1 (halfwidth codepoints), 2 (fullwidth codepoints) or 0 (as intermediate state after a fullwidth codepoint). width always defaults to 1 and is not calculated upon initialization. The correct width value is set by the emulator while processing a printable character.

For small memory footprint and quick state changes a TChar object stores the text attributes in the 2 4-byte numbers attr and gb.

Bits of attr:

  1-8     background color in 256 mode / background RED in RGB mode
  9-16    foreground color in 256 mode / foreground RED in RGB mode
  17      bold
  18      italic
  19      underline
  20      blink
  21      inverse
  22      conceal
  23      cursor (not set by default)
  24      <unused>
  25      background set (for 256 and RGB mode)
  26      background in RGB mode (true for RGB, false for 256)
  27      foreground set (for 256 and RGB mode)
  28      foreground in RGB mode (true for RGB, false for 256)
  29-32   <unused>

Bits of gb:

  1-8         background BLUE in RGB mode
  9-16        foreground BLUE in RGB mode
  17-24       background GREEN in RGB mode
  25-32       foreground GREEN in RGB mode

Kind: static class of node-ansiterminal
Properties

Name	Type	Description
c	`string`	unicode character (multiple if surrogate or combining)
attr	`number`	text attributes as integer
gb	`number`	green and blue part of RGB as integer
width	`number`	printed space of character

.TChar
- new TChar(c, attr, gb, width)
- instance
  - .clone() ⇒ TChar
  - .equals(other) ⇒ boolean
  - .serialize() ⇒ Array
  - .getAttributes() ⇒ TAttributes
  - .getJSONAttributes() ⇒ TJSONAttributes
  - .setAttributes(attributes)
- static
  - .deserialize(o) ⇒ TChar

new TChar(c, attr, gb, width)

Param	Type	Description
c	`string`	unicode character (multiple if surrogate or combining)
attr	`number`	text attributes as integer
gb	`number`	green and blue part of RGB as integer
width	`number`	printed space of character

tchar.clone() ⇒ `TChar`

Clone a TChar object.

Kind: instance method of TChar

tchar.equals(other) ⇒ `boolean`

Test equality of TChar.

Kind: instance method of TChar

Param	Type
other	`TChar`

tchar.serialize() ⇒ `Array`

Serialize a TChar.

Kind: instance method of TChar

tchar.getAttributes() ⇒ `TAttributes`

Get all text attributes in a readable manner. The attributes object may contain left over color values of a former RGB setting. This is due to the way xterm handles those values internally. For cleaned attributes see getJSONAttributes

Kind: instance method of TChar

tchar.getJSONAttributes() ⇒ `TJSONAttributes`

Get all text attributes in a readable manner without state internals. Use this in favour of getAttributes if you need the attributes in a clean way without remnant color values.

Except the colors all attributes are simple boolean values. The color attributes default to false and will turn into an object with a mode and a color attribute if a color is set. For mode '256' the color will be a single integer indicating the color in the 256 color scheme. For mode 'RGB' color is an array with the RGB color values.

NOTE: The simple 8bit colors are not directly supported by the terminal emulator. They will be translated to the lower colors of the 256 color scheme.

Example output with a foreground color set:

{
    bold: false,
    italic: false,
    underline: false,
    blink: false,
    inverse: false,
    conceal: false,
    foreground: {mode: '256', color: 12},
    background: false
}

Kind: instance method of TChar

tchar.setAttributes(attributes)

Set the text attributes. The parameter must be in the form of the output of getAttributes.

Kind: instance method of TChar

Param	Type
attributes	`TAttributes`

tchar.deserialize(o) ⇒ `TChar`

Deserialize a serialization object to TChar.

Kind: static method of TChar

Param	Type
o	`object`

ansiterminal.TRow

A TRow contains single terminal cells (TChar) in cells. The global unique ID uniqueId will never change for an existing TRow. The version attributes will be incremented by the terminal emulator upon changes. This can be used to implement a partial refresh of a view output.

Kind: static class of node-ansiterminal
Properties

Name	Type	Description
cells	`array`	array containing the single TChar objects
uniqueId	`number`	global unique id of the row object
version	`number`	incremented by emulator upon changes

.TRow
- new TRow(length, tchar)
- instance
  - .serialize() ⇒ Array
  - .toString(opts) ⇒ string
  - .toMergedArray(opts) ⇒ Array
  - .toJSON(opts) ⇒ JSONTRow
  - .toEscapeString(opts) ⇒ string
  - .toHTML(opts) ⇒ string
- static
  - .deserialize(o) ⇒ TRow

new TRow(length, tchar)

The constructor will create length cells of cloned tchar objects.

Param	Type	Description
length	`number`	amount of cells to create
tchar	`TChar`	base object to be cloned as initial

tRow.serialize() ⇒ `Array`

Serialize a TRow.

Kind: instance method of TRow

tRow.toString(opts) ⇒ `string`

String representation of TRow.

Kind: instance method of TRow

Param	Type
opts	`object`

tRow.toMergedArray(opts) ⇒ `Array`

Array representation of merged TChars objects with same text attributes.

Kind: instance method of TRow
Returns: Array - array of merged TChar objects

Param
opts

tRow.toJSON(opts) ⇒ `JSONTRow`

Drilled down JSON representation of a TRow. Returns objects of sub strings with distinct text attributes.

Kind: instance method of TRow
Note: The print space width is summed up.

Param
opts

tRow.toEscapeString(opts) ⇒ `string`

String representation of TRow with escape codes.

Kind: instance method of TRow

Param
opts

tRow.toHTML(opts) ⇒ `string`

HTML string representation of TRow.

The terminal string gets decorated by span elements with textattributes either set via class names or inline styles.

Options are:

rtrim            Trim empty cells from right.
                 Defaults to true.
empty_cell       Fill empty_cells with given string.
                 Defaults to none break space character '\xa0'.
blinkanimation   CSS animation class name. Since an animation in CSS
                 can't be declared inline, this is mandatory for
                 classes false.
classes          Use CSS classes (true) or inline styles (false).
                 The class names are: 'blink', 'italic',
                 'underline', 'blink', 'conceal', 'fgX', 'bgX'
                 For foreground and background colors the 'X'
                 is the number of a 256 color table, e.g. 'fg134'.
                 Default foreground and background colors have
                 no class name. Therefore inverted default colors
                 are named as 'fg-1' and 'bg-1'.
                 Defaults to true.
colors           Customizable callback for inline colors.
                 The callback has to support one parameter as
                 color number from 0..255 or the keywords
                 'foreground' or 'background' for default colors).
                 The default callback uses the xterm colorset.
escape_html      Escape html characters in terminal string.
                 Default is true.

Kind: instance method of TRow
Returns: string - HTML string

Param
opts

TRow.deserialize(o) ⇒ `TRow`

Deserialize a TRow.

Kind: static method of TRow

Param
o

ansiterminal.AnsiTerminal

AnsiTerminal - an offscreen xterm like terminal.

The terminal implements the interface of node-ansiparser. Since the parser calls the methods directly this terminal has no direct input method. Use the parser's parse(s) method instead (see documentation of the parser and the example below).

The terminal has no direct screen representation beside a toString() method for debug purposes. Use the output methods of the TRow primitive to build a view of the terminal content.

Like xterm the terminal maintains 2 different screen buffers. The normal screen has a scrolling history while the alternate has none. Most simple programs operate on the normal screen while more advanced command line programs (e.g. curses based) use the alternate screen as a canvas. The current active screen is always accessible via the screen attribute.

Kind: static class of node-ansiterminal

.AnsiTerminal

new AnsiTerminal(cols, rows, scrollLength)

The constructor creates a new terminal object with cols width and rows height. The scrollLength parameter is the max history length (number of lines) of the normal screen buffer.

Param	Type	Description
cols	`number`	columns of the terminal.
rows	`number`	rows of the terminal.
scrollLength	`number`	lines of scrollbuffer.

Example

var AnsiTerminal = require('node-ansiterminal').AnsiTerminal;
var AnsiParser = require('node-ansiparser');
var terminal = new AnsiTerminal(80, 25, 500);
var parser = new AnsiParser(terminal);
parser.parse('\x1b[31mHello World!\x1b[0m');
console.log(terminal.toString());

ansiTerminal.reset()

Hard reset of the terminal.

Kind: instance method of AnsiTerminal

ansiTerminal.toString(opts) ⇒ `string`

String representation of active terminal buffer.

Kind: instance method of AnsiTerminal

Param
opts

ansiTerminal.resize(cols, rows)

Resize terminal to cols x rows.

Kind: instance method of AnsiTerminal

Param	Type	Description
cols	`number`	new columns value
rows	`number`	new rows value

ansiTerminal.registerDCSHandler(handler, collected, flag)

Register a DCS handler for flag and collected. The handler must follow the DCS "interface" with a hook, feed and unhook method (see DCS_Dummy).

Kind: instance method of AnsiTerminal

Param	Type
handler	`function`
collected	`string`
flag	`string`

ansiTerminal.unregisterDCSHandler(handler)

Unregister a DCS handler.

Kind: instance method of AnsiTerminal

Param	Type	Description
handler	`function`	previously registered handler

ansiTerminal.inst_p(s)

inst_p - handle printable characters

The print implementation is aware of combining and surrogate characters and respects half and full width print space according to unicode.

Kind: instance method of AnsiTerminal

Param	Type
s	`string`

ansiTerminal.inst_o(s)

inst_o - handle OSC instruction

Kind: instance method of AnsiTerminal

Param
s

ansiTerminal.inst_x(flag)

inst_x - handle single character instruction

Kind: instance method of AnsiTerminal

Param
flag

ansiTerminal.inst_c(collected, params, flag)

inst_c - handle CSI instruction

Kind: instance method of AnsiTerminal

Param
collected
params
flag

ansiTerminal.inst_e(collected, flag)

inst_e - handle ESC instruction

Kind: instance method of AnsiTerminal

Param
collected
flag

ansiTerminal.inst_H(collected, params, flag)

inst_H - enter DCS handler state

Kind: instance method of AnsiTerminal

Param
collected
params
flag

ansiTerminal.inst_P(data)

inst_P - handle DCS data

Kind: instance method of AnsiTerminal

Param
data

ansiTerminal.inst_U()

inst_U - leave DCS handler state

Kind: instance method of AnsiTerminal

ansiTerminal.DECALN()

DECALN - Screen Alignment Pattern

Kind: instance method of AnsiTerminal
See: http://www.vt100.net/docs/vt510-rm/DECALN

ansiTerminal.SD(params)

SD - Scroll Down (Pan Up) - CSI Pn T Also SU moves scrolled out lines to scroll buffer, SD only adds new lines at the top.

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/SD

Param	Type	Description
params	`Array`	one numerical parameter (defaults to 1 even if 0 is given)

ansiTerminal.SU(params)

SU - Scroll Up (Pan Down) - CSI Pn S Scrolled out lines go into the scroll buffer.

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/SU

Param	Type	Description
params	`Array`	one numerical parameter (defaults to 1 even if 0 is given)

ansiTerminal.REP(params)

REP - Repeat the preceding graphic character P s times (REP) - CSI Ps b

Kind: instance method of AnsiTerminal

Param
params

ansiTerminal.NEL()

NEL - Next Line - ESC E

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/NEL

ansiTerminal.IND()

IND - Index - ESC D

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/IND

ansiTerminal.VPR(params)

VPR - Vertical Position Relative - CSI Pn e

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/VPR

Param
params

ansiTerminal.HPR(params)

HPR - Horizontal Position Relative - CSI Pn a

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/HPR

Param
params

ansiTerminal.HPA(params)

HPA - Horizontal Position Absolute - CSI Pn '

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/HPA

Param
params

ansiTerminal.CBT(params)

CBT - Cursor Backward Tabulation - CSI Pn Z

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/CBT

Param
params

ansiTerminal.CHT(params)

CHT - Cursor Horizontal Forward Tabulation - CSI Pn I

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/CHT

Param
params

ansiTerminal.CPL(params)

CPL - Cursor Previous Line - CSI Pn F

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/CPL

Param
params

ansiTerminal.CNL(params)

CNL - Cursor Next Line - CSI Pn E

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/CNL

Param
params

ansiTerminal.DL(params)

DL - Delete Line - CSI Pn M

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/DL

Param
params

ansiTerminal.ICH(params)

ICH - Insert Character - CSI Pn @

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/ICH

Param
params

ansiTerminal.VPA(params)

VPA - Vertical Line Position Absolute - CSI Pn d

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/VPA

Param
params

ansiTerminal.ECH(params)

ECH - Erase Character - CSI Pn X

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/ECH

Param
params

ansiTerminal.IL(params)

IL - Insert Line - CSI Pn L

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/IL

Param
params

ansiTerminal.DECSTBM(params)

DECSTBM - Set Top and Bottom Margins - CSI Pt ; Pb r

Kind: instance method of AnsiTerminal
Note: currently broken
See: http://vt100.net/docs/vt510-rm/DECSTBM

Param
params

ansiTerminal.DECSTR()

DECSTR - Soft Terminal Reset - CSI ! p

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/DECSTR

ansiTerminal.RI()

RI - Reverse Index - ESC M

Kind: instance method of AnsiTerminal

ansiTerminal.DECSC()

DECSC - Save Cursor - ESC 7

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/DECSC

ansiTerminal.DECRC()

DECRC - Restore Cursor - ESC 8

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/DECRC

ansiTerminal.CHA(params)

CHA - Cursor Horizontal Absolute - CSI Pn G

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/CHA

Param
params

ansiTerminal.CUB(params)

CUB - Cursor Backward - CSI Pn D

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/CUB

Param
params

ansiTerminal.CUD(params)

CUD - Cursor Down - CSI Pn B

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/CUD

Param
params

ansiTerminal.CUF(params)

CUD - Cursor Forward - CSI Pn C

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/CUF

Param
params

ansiTerminal.CUU(params)

CUD - Cursor Up - CSI Pn A

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/CUU

Param
params

ansiTerminal.CUP(params)

CUP - Cursor Position - CSI Pl ; Pc H

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/CUP

Param
params

ansiTerminal.DCH(params)

DCH - Delete Character - CSI Pn P

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/DCH

Param
params

ansiTerminal.ED(params)

ED - Erase in Display - CSI Ps J

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/ED

Param
params

ansiTerminal.EL(params)

EL - Erase in Line - CSI Ps K

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/EL

Param
params

ansiTerminal.SGR(params)

SGR - Select Graphic Rendition - CSI Ps ; Ps ... m

Kind: instance method of AnsiTerminal
See: http://vt100.net/docs/vt510-rm/SGR

Param
params

ansiterminal.wcswidth(s) ⇒ `number`

Calculate print space of a string. The returned number denotes the taken halfwidth space.

Kind: static method of node-ansiterminal
Returns: number - halfwidth length of the string
Note: Terminals and fonts may behave differently for some codepoints since unicode knows more widths than half and full width.

Param	Type	Description
s	`string`	single character or string

Example

> var wcswidth = require('node-ansiterminal').wcswidth
undefined
> wcswidth('￥￥￥￥￥')
10

ansiterminal.get_color(value) ⇒ `string`

Default color mapper function with xterm colorset in white on black.

Kind: static method of node-ansiterminal
Returns: string - hex color string

Param
value

ansiterminal.DCS_Dummy()

DCS dummy handler

This is a dummy for a dcs handler. It handles all DCS sequences that have no real implementation.

Kind: static method of node-ansiterminal

ansiterminal.DCS_DECRQSS()

DECRQSS - Request Selection or Setting - DCS $ q D..D ST

DCS handler for DECRQSS. Currently only SGR and DECSTBM reports are fully implemented.

Difference to DEC specification - P1 for valid, P0 for invalid request (following the xterm scheme)

Kind: static method of node-ansiterminal
See: http://www.vt100.net/docs/vt510-rm/DECRQSS.html

ansiterminal~TColors : `Object`

Kind: inner typedef of node-ansiterminal
Properties

Name	Type	Description
set	`boolean`	true if color is set
RGB	`boolean`	true if color is in RGB mode
color	`array`	[R, G, B] or [color value, unused, unused]

ansiterminal~TAttributes : `Object`

Kind: inner typedef of node-ansiterminal
Properties

Name	Type
bold	`boolean`
italic	`boolean`
underline	`boolean`
blink	`boolean`
inverse	`boolean`
conceal	`boolean`
foreground	`TColors`
background	`TColors`

ansiterminal~TJSONColors : `Object`

Kind: inner typedef of node-ansiterminal
Properties

Name	Type	Description
mode	`string`	'256' or 'RGB'
color	`number` \| `array`	[R, G, B] for 'RGB' mode

ansiterminal~TJSONAttributes : `Object`

Kind: inner typedef of node-ansiterminal
Properties

Name	Type
bold	`boolean`
italic	`boolean`
underline	`boolean`
blink	`boolean`
inverse	`boolean`
conceal	`boolean`
foreground	`TJSONColors` \| `false`
background	`TJSONColors` \| `false`

ansiterminal~JSONTRow : `Object`

Kind: inner typedef of node-ansiterminal
Properties

Name	Type	Description
string	`string`	sub string
width	`width`	print space of string
attributes	`TJSONAttributes`	text attributes