terminal-api

terminal-api

Installation | Usage | API | Colors | Styles | License

terminal-api is a thin layer around low-level terminal commands, providing easy access without escape codes or other dirty details.

• Manages terminal states
• Handles position, color and styling
• Supports 256 color
• No dependencies

Installation ^

npm install --save terminal-api

Usage ^

const TerminalApi = require('terminal-api');

// initialize
const t = new TerminalApi();

// clear screen
t.clear();

// show/hide cursor
t.setCursor(false);

// set background/foreground color
t.setBgColor(t.colors.basic.magenta);
t.setFgColor(t.colors.rgb6(4, 5, 1));

// set styles
t.setStyles({bold: true, underline: true});

// set position
t.setPosition(10, 5);

// write
t.write('Hello world!');

// shortcut methods
t.w('Goodbye world!', {
    x: 10, y: 7,
    bgColor: t.colors.basic.white,
    fgColor: t.colors.gray[3],
    styles: ['strikethrough', 'dim'],
    wrap: true
});

Also, run examples/demo.js to see a more colorful example:

node examples/demo.js

API ^

constructor(stream, encoding) ^

Creates terminal-api instance.

• stream: WritableStream. Default: process.stdout
• encoding: String. Default: 'utf8'

setStream(stream) ^

Sets stream.

• stream: WritableStream. Default: process.stdout

setEncoding(encoding) ^

Sets encoding.

• encoding: String. Default: 'utf8'

setOptions(options, force) ^

Sets multiple options at a time.

• options: Object. Possible keys: wrap, x, y, bgColor, fgColor, cursor, styles
• force: Boolean. Forces operation even if not needed. Default: false

setWrap(wrap) ^

Enables/disables wrapping at the end of the line.

• wrap: Boolean. Default: true

setPosition(x, y, force) ^

Sets cursor position.

• x: Number. Default: 0
• y: Number. Default: 0
• force: Boolean. Forces operation even if not needed. Default: false

setX(x, force) ^

Sets cursor x position.

• x: Number. Default: 0
• force: Boolean. Forces operation even if not needed. Default: false

setY(y, force) ^

Sets cursor y position.

• y: Number. Default: 0
• force: Boolean. Forces operation even if not needed. Default: false

setBgColor(color, force) ^

Sets background color. See Colors for more information.

• color: Number.
• force: Boolean. Forces operation even if not needed. Default: false

setFgColor(color, force) ^

Sets foreground color. See Colors for more information.

• color: Number.
• force: Boolean. Forces operation even if not needed. Default: false

resetBgColor(force) ^

Resets background color to terminal default.

• force: Boolean. Forces operation even if not needed. Default: false

resetFgColor(force) ^

Resets foreground color to terminal default.

• force: Boolean. Forces operation even if not needed. Default: false

setCursor(cursor, force) ^

Shows/hides cursor.

• cursor: Boolean. Default: true
• force: Boolean. Forces operation even if not needed. Default: false

setStyles(styles, force) ^

Enables/disables multiple styles at once. See Styles for more information.

• styles: Object. Should be structured as {styleName: styleState}
• force: Boolean. Forces operation even if not needed. Default: false

enableStyles(styleList, force) ^

Enables multiple styles at once. See Styles for more information.

• styleList: Array. List of style names.
• force: Boolean. Forces operation even if not needed. Default: false

disableStyles(styleList, force) ^

Disables multiple styles at once. See Styles for more information.

• styleList: Array. List of style names.
• force: Boolean. Forces operation even if not needed. Default: false

reset() ^

Resets terminal and instance state.

clear() ^

Clears terminal.

write(text) ^

Writes text on terminal.

• text: String.

w(text, options, revert, force) ^

Shortcut method for changing options, writing text, and optionally reverting options back.

• text: String.
• options: Object. See setOptions method.
• revert: Boolean. Whether to revert options back after writing. Default: false
• force: Boolean. Forces operation even if not needed. Default: false

Colors ^

Color availability and representations might differ between systems and configurations. For maximum compatibility, only basic and bright colors should be used.

Even though there are 256 colors, it's not the usual 256 color space. On most systems, these color groups partially overlap with each other.

While terminal-api accepts only color codes, colors object provides access to color codes in a user-friendly way. It can be accessed from class or instance:

const TerminalApi = require('terminal-api');
const colors = TerminalApi.colors;
// or
const t = new TerminalApi();
const colors = t.colors;

colors object is structured as:

const colors = {
  basic: { /* black, red, green, yellow, blue, magenta, cyan, white */ },
  bright: { /* black, red, green, yellow, blue, magenta, cyan, white */ },
  gray: [/* 0, ..., 23 */]
};

Also, it has a minimal API.

Colors API ^

rgb6(r, g, b)

Returns color code for given rgb values of 256 colors.

• r: Number. Must be in range 0 - 5. Default: 0
• g: Number. Must be in range 0 - 5. Default: 0
• b: Number. Must be in range 0 - 5. Default: 0

rgb256(r, g, b)

Returns closest color code for given rgb values of 16M colors.

• r: Number. Must be in range 0 - 255. Default: 0
• g: Number. Must be in range 0 - 255. Default: 0
• b: Number. Must be in range 0 - 255. Default: 0

rgb256Hex(hex)

Returns closest color code for given rgb values of 16M colors.

• hex: String. Must be hexadecimal RGB code. Default: 000000

Usage ^

const TerminalApi = require('terminal-api');
const t = new TerminalApi();
t.setBgColor(t.colors.basic.magenta);
t.setFgColor(t.colors.rgb256Hex('#ff9900'));

Styles ^

Available styles: 'bold', 'dim', 'italic', 'underline', 'blink', 'inverse', 'hidden', 'strikethrough'

Style availability depends on system. For maximum compatibility, only bold, underline and reverse should be used.

License ^

MIT