Skip to content

Latest commit

 

History

History
1128 lines (840 loc) · 43 KB

api.md

File metadata and controls

1128 lines (840 loc) · 43 KB
Raw

node-ansiterminal

Example

var ansiterminal = require('node-ansiterminal')

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

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

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

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