readline-utils

Readline utils, for moving the cursor, clearing lines, creating a readline interface, and more.

Install

Install with npm:

$ npm install --save readline-utils

Usage

var utils = require('readline-utils');

API

.createInterface

Create a readline interface with the given options.

Params

• options {Object}

.up

Move cursor up by n lines.

Params

• rl {Readline}: Readline interface
• n {Number}: Lines up to move. Default is 1.

.down

Move cursor down by n lines.

Params

• rl {Readline}: Readline interface
• n {Number}: Lines down to move. Default is 1.

.left

Move cursor left by n colums.

Params

• rl {Readline}: Readline interface
• n {Number}: Characters to move left. Default is 1.

.right

Move cursor right by n colums.

Params

• rl {Readline}: Readline interface
• n {Number}: Characters to move right. Default is 1.

.move

Move cursor up, down, left or right by 1 line.

Params

• rl {Readline}: Readline interface

Example

var utils = require('readline-utils');
var rl = utils.createInterface();
rl.input.on('keypress', function(str, key) {
  utils.move(rl, key);
});

.auto

Callback function for the keypress event, to automatically move cursor up, down, left or right by 1 line.

Params

• rl {Readline}: Readline interface

Example

var utils = require('readline-utils');
var rl = utils.createInterface();
rl.input.on('keypress', utils.auto(rl));

.clearAfter

Clear n lines after the cursor.

Params

• rl {Readline}: Readline interface
• n {Number}: Number of lines to clear

.clearScreen

Clear the terminal.

Params

• rl {Readline}: Readline interface
• n {Number}: Number of lines to clear

.lastLine

Get the last line from the given str

Params

• str {String}
• returns {String}

.height

Get the height (rows) of the given str

Params

• str {String}
• returns {Number}

.hideCursor

Hide the cursor so it doesn't show during a prompt. This is useful for multiple-choice or list prompts, or any prompt where the user will not be entering input.

Params

• rl {Readline}: Readline interface
• returns {Object}: readline-utils object for chaining

.showCursor

Show the cursor.

Params

• rl {Readline}: Readline interface
• returns {Object}: readline-utils object for chaining

.close

Close the interface, remove event listeners, and restore/unmute prompt functionality

Params

• rl {Readline}: Readline interface
• returns {Object}: readline-utils object for chaining

.forceClose

Close the interface when the keypress is ^C

Params

• rl {Readline}: Readline interface
• returns {Object}: readline-utils object for chaining

.eraseLines

Erase n lines

Params

• n {Number}
• returns {String}: Returns the unicode to erase lines

Example

utils.eraseLines(3);

.clearTrailingLines

Remove lines from the bottom of the terminal.

Params

• rl {Number}: Readline interface
• lines {Number}: Number of lines to remove
• height {Number}: Content height
• returns {Object}: Returns the readline-utils object for chaining

.cursorPosition

Remember the cursor position

• returns {Object}: readline-utils object

.restoreCursorPos

Restore the cursor position to where it has been previously stored.

• returns {Object}: readline-utils object

.cliWidth

Get the width of the terminal

Params

• fallback {Number}: A fallback width to use if the actual width is not found.
• returns {Number}: Returns the number of columns.

.breakLines

Break lines longer than the cli width so we can normalize the natural line returns behavior accross terminals. (I don't see how this can work consistently. It seems brittle and will probably be replaced with https://github.com/jonschlinkert/word-wrap)

Params

• lines {Array}: Array of lines
• width {Number}: Terminal width

.forceLineReturn

Joins the lines returned from .breakLines.

Params

• lines {Array|String}: String or array of lines.
• width {Number}: Terminal width
• returns {String}

.normalizeLF

Ensure the given str ends in a newline.

Params

• str {String}: The input string
• returns {String}

Example

console.log(utils.normalizeLF('foo'));
//=> 'foo\n'

.keypress

This module offers the internal "keypress" functionality from node-core's readline module, for your own programs and modules to use.

The keypress function accepts a readable Stream instance and makes it emit "keypress" events. Usage:

Params

• {Stream}: stream

Example

require('keypress')(process.stdin);

process.stdin.on('keypress', function(ch, key) {
  console.log(ch, key);
  if (key.ctrl && key.name === 'c') {
    process.stdin.pause();
  }
});
proces.stdin.resume();

.enableMouse

Enables "mousepress" events on the input stream. Note that stream must be an output stream (i.e. a Writable Stream instance), usually process.stdout.

Params

• {Stream}: stream writable stream instance

.disableMouse

Disables "mousepress" events from being sent to the input

stream. Note that stream must be an output stream (i.e. a Writable Stream instance), usually process.stdout.

Params

• {Stream}: stream writable stream instance

Attribution

Some of this code was initially borrowed from [Inquirer][].

About

Related projects

• choices-separator: Separator for choices arrays in prompts. Based on the Separator from inquirer. | homepage
• enquirer: Intuitive, plugin-based prompt system for node.js. | homepage
• prompt-choices: Create an array of multiple choice objects for use in prompts. | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Please read the contributing guide for advice on opening issues, pull requests, and coding standards.

Contributors

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2017, Jon Schlinkert. Released under the MIT License.

This file was generated by verb-generate-readme, v0.6.0, on July 11, 2017.