terminal-api v0.1.7
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.