clidejs/ttyutil

About

A terminal utility module for node.js serving a cross-platform console api. Works with Node.js v0.8 and above.

Changelog

Note

This project is still under development and thus the API may change, please report any bugs here, and feel free to make feature requests.

Installation

Since this is a native c++ node.js addon, you will need these tools to build the packages (see node-gyp):

• python (v2.7+, but not 3.x)
• on unix:
  • make
  • c++ compiler (e.g. gcc)
• on mac:
  • xcode command line tools
• on windows:
  • Visual Studio 2010 or 2013

Simply add ttyutil to the dependencies of your project:

npm install --save ttyutil

And require it anywhere in your codebase:

var TTYUtil = require("ttyutil");

Usage

TTYUtil

The TTYUtil exposes the TTYUtil constructor (var ttyu = new TTYUtil()). This creates the ttyu object which is used to interact with the terminal.

ttyu.on(event, listener)

Adds an event listener callback for the event(see TTYUtil.EVENT). For the event callback parameter see here.

ttyu.removeListener(event, listener)

Remove the event listener callback from the event (see TTYUtil.EVENT).

ttyu.off(event, listener)

Shortcut for ttyu.removeListener(event, listener).

ttyu.emit(event)

Emit an event programmatically, see /tests/key.js. more documentation will be added soon.

ttyu.start()

Start emitting input events (mouse, key and resize events) to the listeners attached by tty.on(event, listener).

ttyu.pause()

Pause emitting input events.

ttyu.destroy()

Destroy the object and release all resources. You wont be able to use any more functions or restart.

ttyu.running

Boolean flag indicating if input events are emitted (true when ttyu.start() was executed). read-only

ttyu.width

Integer amount of horizontal character space in the terminal. read-only

ttyu.height

Integer amount of vertical character space in the terminal. read-only

ttyu.mode

Integer identifier for current terminal mode (can be one of TTYUtil.MODE). read-only

ttyu.colors

Integer amount of colors available in the terminal (16-256). read-only

ttyu.x

Current x-position of the terminal cursor.

ttyu.y

Current y-position of the terminal cursor.

ttyu.goto(x, y)

Function to set the current cursor position to (x, y).

ttyu.write(chunk, fg, bg)

Function to write a string chunk at the current cursor position (ttyu.x, ttyu.y) with the foreground color fg and the background color bg to the terminal buffer. fg and bg can be terminal color codes, hexadecimal strings (e.g. "#FF0000") or rgb strings (e.g. "rgb(255,0,0)").

ttyu.prepare(chunk, fg, bg)

Function to prepare a string chunk with the foreground color fg and background color bg. Works like ttyu.write(chunk, fg, bg), but returns the formatted string without printing it to the terminal.

ttyu.beep()

Function to create a warning sound or visual warning effect.

ttyu.clear(x, y, width, height)

Function to clear a part of the terminal buffer. x and y describe the top-left corner of the rectangle and width and height define the size of the rectangle to clear. When called without arguments, this function will clear the complete (visible) terminal buffer.

ttyu.color(str)

Function to get the terminal color code from str, a hexadecimal string (e.g. "#FF0000") or rgb string (e.g. "rgb(255,0,0)").

TTYUtil.EVENT

This object wraps all input events as constants:

• TTYUtil.EVENT.ERROR {String}: ERROR identifier for error events
• TTYUtil.EVENT.SIGNAL {String}: SIGNAL identifier for process signal events
• TTYUtil.EVENT.KEY {String}: KEY identifier for key events
• TTYUtil.EVENT.RESIZE {String}: RESIZE identifier for resize events
• TTYUtil.EVENT.MOUSEDOWN {String}: MOUSEDOWN identifier for mousedown events (mouse button pressed)
• TTYUtil.EVENT.MOUSEUP {String}: MOUSEUP identifier for mouse up events (mouse button released)
• TTYUtil.EVENT.MOUSEMOVE {String}: MOUSEMOVE identifier for mouse move events
• TTYUtil.EVENT.MOUSEWHEEL {String}: MOUSEWHEEL identifier for mouse wheel events (vertical scroll events)
• TTYUtil.EVENT.MOUSEHWHEEL {String}: MOUSEHWHEEL identifier for the mouse hwheel events (horizontal scroll events)

TTYUtil.MODE

This object wraps all terminal modes as constants:

• TTYUtil.MODE.CMD {Integer}: 0 identifier for the windows cmd.exe
• TTYUtil.MODE.VT102 {Integer}: 1 identifier for VT102 compilant terminals (e.g. iTerm2 for OSX or xTerm for X11)
• TTYUtil.MODE.VT100 {Integer}: 2 identifier for VT100 compilant terminals (e.g. Terminal.app for OSX)

TTYUtil.MOUSE

This object wraps all mouse buttons identifier as constants:

• TTYUtil.MOUSE.LEFT {Integer}: 1 left-most mouse button
• TTYUtil.MOUSE.LEFT2 {Integer}: 4 second left-most mouse button
• TTYUtil.MOUSE.LEFT3 {Integer}: 8 thrid left-most mouse button
• TTYUtil.MOUSE.LEFT4 {Integer}: 16 fourth left-most mouse button
• TTYUtil.MOUSE.RIGHT {Integer}: 2 right-most mouse button

TTYUtil.CTRL

This object wraps all control key identifier as constants:

• TTYUtil.CTRL.NULL {Integer}: 0 no control key is active
• TTYUtil.CTRL.ALT {Integer}: 1 the alt key is pressed
• TTYUtil.CTRL.CTRL {Integer}: 2 the ctrl key is pressed
• TTYUtil.CTRL.SHIFT {Integer}: 4 the shift key is pressed
• TTYUtil.CTRL.ENHANCED {Integer}: 8 the enhanced key is pressed
• TTYUtil.CTRL.CMD {Integer}: 16 the cmd key is pressed (OSX)
• TTYUtil.CTRL.NUMLOCK {Integer}: 32 numlock is activated
• TTYUtil.CTRL.SCROLLLOCK {Integer}: 64 scrolllock is activated
• TTYUtil.CTRL.CAPSLOCK {Integer}: 128 capslock is activated

TTYUtil.SIGNAL

This object contains a list of all signals that can be catched by ttyutil:

• TTYUtil.SIGNAL.SIGINT {String}: SIGINT interrupt event (e.g. CTRL+C)
• TTYUtil.SIGNAL.SIGTERM {String}: SIGTERM termination event
• TTYUtil.SIGNAL.SIGPIPE {String}: SIGPIPE pipe error event
• TTYUtil.SIGNAL.SIGHUP {String}: SIGHUP terminal close event

TTYUtil.WHICH

This object wraps all key codes as constants. (see /const.js for the complete list)

TTYUtil event callback parameter

Every event emits one object to the callbacks. Every object contains a type property which is one of TTYUtil.EVENT, to identify the event.

• ERROR-Event emits an object containing information about the error in the error property
• SIGNAL-Event emits an object containing the raised signal (see TTYUtil.SIGNAL) in the signal property (e.g. { signal: "SIGINT" })
• KEY-Event emits an object containing following properties:
  • ctrl {Integer} the control characters currently pressed (see TTYUtil.CTRL)
  • char {String} the string representation of the pressed key
  • code {Integer} the ascii key-code of the pressed key
  • which {Integer} unique identifier for the pressed key (seeTTYUtil.WHICH)
• RESIZE-Event emits an object with only the event type parameter, use ttyu.width/ttyu.height to get the new window size
• MOUSE...-Events emit an object containing following properties:
  • button {Integer} the button pressed (see TTYUtil.MOUSE)
  • x {Integer} x-coordinate in the terminal, the event occured in
  • y {Integer} x-coordinate in the terminal, the event occured in
  • ctrl {Integer} the control characters currently pressed (see TTYUtil.CTRL)

Test

run the tests using npm test. check out /tests for test cases.

Example

see the /examples folder

License: MIT

Copyright (c) 2015 Bernhard Bücherl

---

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.