|
|
|
# Readline
|
|
|
|
|
|
|
|
Stability: 2 - Unstable
|
|
|
|
|
|
|
|
To use this module, do `require('readline')`. Readline allows reading of a
|
|
|
|
stream (such as `process.stdin`) on a line-by-line basis.
|
|
|
|
|
|
|
|
Note that once you've invoked this module, your node program will not
|
|
|
|
terminate until you've closed the interface. Here's how to allow your
|
|
|
|
program to gracefully exit:
|
|
|
|
|
|
|
|
var readline = require('readline');
|
|
|
|
|
|
|
|
var rl = readline.createInterface({
|
|
|
|
input: process.stdin,
|
|
|
|
output: process.stdout
|
|
|
|
});
|
|
|
|
|
|
|
|
rl.question("What do you think of node.js? ", function(answer) {
|
|
|
|
// TODO: Log the answer in a database
|
|
|
|
console.log("Thank you for your valuable feedback:", answer);
|
|
|
|
|
|
|
|
rl.close();
|
|
|
|
});
|
|
|
|
|
|
|
|
## readline.createInterface(options)
|
|
|
|
|
|
|
|
Creates a readline `Interface` instance. Accepts an "options" Object that takes
|
|
|
|
the following values:
|
|
|
|
|
|
|
|
- `input` - the readable stream to listen to (Required).
|
|
|
|
|
|
|
|
- `output` - the writable stream to write readline data to (Required).
|
|
|
|
|
|
|
|
- `completer` - an optional function that is used for Tab autocompletion. See
|
|
|
|
below for an example of using this.
|
|
|
|
|
|
|
|
- `terminal` - pass `true` if the `input` and `output` streams should be
|
|
|
|
treated like a TTY, and have ANSI/VT100 escape codes written to it.
|
|
|
|
Defaults to checking `isTTY` on the `output` stream upon instantiation.
|
|
|
|
|
|
|
|
The `completer` function is given the current line entered by the user, and
|
|
|
|
is supposed to return an Array with 2 entries:
|
|
|
|
|
|
|
|
1. An Array with matching entries for the completion.
|
|
|
|
|
|
|
|
2. The substring that was used for the matching.
|
|
|
|
|
|
|
|
Which ends up looking something like:
|
|
|
|
`[[substr1, substr2, ...], originalsubstring]`.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
function completer(line) {
|
|
|
|
var completions = '.help .error .exit .quit .q'.split(' ')
|
|
|
|
var hits = completions.filter(function(c) { return c.indexOf(line) == 0 })
|
|
|
|
// show all completions if none found
|
|
|
|
return [hits.length ? hits : completions, line]
|
|
|
|
}
|
|
|
|
|
|
|
|
Also `completer` can be run in async mode if it accepts two arguments:
|
|
|
|
|
|
|
|
function completer(linePartial, callback) {
|
|
|
|
callback(null, [['123'], linePartial]);
|
|
|
|
}
|
|
|
|
|
|
|
|
`createInterface` is commonly used with `process.stdin` and
|
|
|
|
`process.stdout` in order to accept user input:
|
|
|
|
|
|
|
|
var readline = require('readline');
|
|
|
|
var rl = readline.createInterface({
|
|
|
|
input: process.stdin,
|
|
|
|
output: process.stdout
|
|
|
|
});
|
|
|
|
|
|
|
|
Once you have a readline instance, you most commonly listen for the
|
|
|
|
`"line"` event.
|
|
|
|
|
|
|
|
If `terminal` is `true` for this instance then the `output` stream will get
|
|
|
|
the best compatibility if it defines an `output.columns` property, and fires
|
|
|
|
a `"resize"` event on the `output` if/when the columns ever change
|
|
|
|
(`process.stdout` does this automatically when it is a TTY).
|
|
|
|
|
|
|
|
## Class: Interface
|
|
|
|
|
|
|
|
The class that represents a readline interface with an input and output
|
|
|
|
stream.
|
|
|
|
|
|
|
|
### rl.setPrompt(prompt, length)
|
|
|
|
|
|
|
|
Sets the prompt, for example when you run `node` on the command line, you see
|
|
|
|
`> `, which is node's prompt.
|
|
|
|
|
|
|
|
### rl.prompt([preserveCursor])
|
|
|
|
|
|
|
|
Readies readline for input from the user, putting the current `setPrompt`
|
|
|
|
options on a new line, giving the user a new spot to write. Set `preserveCursor`
|
|
|
|
to `true` to prevent the cursor placement being reset to `0`.
|
|
|
|
|
|
|
|
This will also resume the `input` stream used with `createInterface` if it has
|
|
|
|
been paused.
|
|
|
|
|
|
|
|
### rl.question(query, callback)
|
|
|
|
|
|
|
|
Prepends the prompt with `query` and invokes `callback` with the user's
|
|
|
|
response. Displays the query to the user, and then invokes `callback`
|
|
|
|
with the user's response after it has been typed.
|
|
|
|
|
|
|
|
This will also resume the `input` stream used with `createInterface` if
|
|
|
|
it has been paused.
|
|
|
|
|
|
|
|
Example usage:
|
|
|
|
|
|
|
|
interface.question('What is your favorite food?', function(answer) {
|
|
|
|
console.log('Oh, so your favorite food is ' + answer);
|
|
|
|
});
|
|
|
|
|
|
|
|
### rl.pause()
|
|
|
|
|
|
|
|
Pauses the readline `input` stream, allowing it to be resumed later if needed.
|
|
|
|
|
|
|
|
### rl.resume()
|
|
|
|
|
|
|
|
Resumes the readline `input` stream.
|
|
|
|
|
|
|
|
### rl.close()
|
|
|
|
|
|
|
|
Closes the `Interface` instance, relinquishing control on the `input` and
|
|
|
|
`output` streams. The "close" event will also be emitted.
|
|
|
|
|
|
|
|
### rl.write(data, [key])
|
|
|
|
|
|
|
|
Writes `data` to `output` stream. `key` is an object literal to represent a key
|
|
|
|
sequence; available if the terminal is a TTY.
|
|
|
|
|
|
|
|
This will also resume the `input` stream if it has been paused.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
rl.write('Delete me!');
|
|
|
|
// Simulate ctrl+u to delete the line written previously
|
|
|
|
rl.write(null, {ctrl: true, name: 'u'});
|
|
|
|
|
|
|
|
## Events
|
|
|
|
|
|
|
|
### Event: 'line'
|
|
|
|
|
|
|
|
`function (line) {}`
|
|
|
|
|
|
|
|
Emitted whenever the `input` stream receives a `\n`, usually received when the
|
|
|
|
user hits enter, or return. This is a good hook to listen for user input.
|
|
|
|
|
|
|
|
Example of listening for `line`:
|
|
|
|
|
|
|
|
rl.on('line', function (cmd) {
|
|
|
|
console.log('You just typed: '+cmd);
|
|
|
|
});
|
|
|
|
|
|
|
|
### Event: 'pause'
|
|
|
|
|
|
|
|
`function () {}`
|
|
|
|
|
|
|
|
Emitted whenever the `input` stream is paused.
|
|
|
|
|
|
|
|
Also emitted whenever the `input` stream is not paused and receives the
|
|
|
|
`SIGCONT` event. (See events `SIGTSTP` and `SIGCONT`)
|
|
|
|
|
|
|
|
Example of listening for `pause`:
|
|
|
|
|
|
|
|
rl.on('pause', function() {
|
|
|
|
console.log('Readline paused.');
|
|
|
|
});
|
|
|
|
|
|
|
|
### Event: 'resume'
|
|
|
|
|
|
|
|
`function () {}`
|
|
|
|
|
|
|
|
Emitted whenever the `input` stream is resumed.
|
|
|
|
|
|
|
|
Example of listening for `resume`:
|
|
|
|
|
|
|
|
rl.on('resume', function() {
|
|
|
|
console.log('Readline resumed.');
|
|
|
|
});
|
|
|
|
|
|
|
|
### Event: 'close'
|
|
|
|
|
|
|
|
`function () {}`
|
|
|
|
|
|
|
|
Emitted when `close()` is called.
|
|
|
|
|
|
|
|
Also emitted when the `input` stream receives its "end" event. The `Interface`
|
|
|
|
instance should be considered "finished" once this is emitted. For example, when
|
|
|
|
the `input` stream receives `^D`, respectively known as `EOT`.
|
|
|
|
|
|
|
|
This event is also called if there is no `SIGINT` event listener present when
|
|
|
|
the `input` stream receives a `^C`, respectively known as `SIGINT`.
|
|
|
|
|
|
|
|
### Event: 'SIGINT'
|
|
|
|
|
|
|
|
`function () {}`
|
|
|
|
|
|
|
|
Emitted whenever the `input` stream receives a `^C`, respectively known as
|
|
|
|
`SIGINT`. If there is no `SIGINT` event listener present when the `input`
|
|
|
|
stream receives a `SIGINT`, `pause` will be triggered.
|
|
|
|
|
|
|
|
Example of listening for `SIGINT`:
|
|
|
|
|
|
|
|
rl.on('SIGINT', function() {
|
|
|
|
rl.question('Are you sure you want to exit?', function(answer) {
|
|
|
|
if (answer.match(/^y(es)?$/i)) rl.pause();
|
|
|
|
});
|
|
|
|
});
|
|
|
|
|
|
|
|
### Event: 'SIGTSTP'
|
|
|
|
|
|
|
|
`function () {}`
|
|
|
|
|
|
|
|
**This does not work on Windows.**
|
|
|
|
|
|
|
|
Emitted whenever the `input` stream receives a `^Z`, respectively known as
|
|
|
|
`SIGTSTP`. If there is no `SIGTSTP` event listener present when the `input`
|
|
|
|
stream receives a `SIGTSTP`, the program will be sent to the background.
|
|
|
|
|
|
|
|
When the program is resumed with `fg`, the `pause` and `SIGCONT` events will be
|
|
|
|
emitted. You can use either to resume the stream.
|
|
|
|
|
|
|
|
The `pause` and `SIGCONT` events will not be triggered if the stream was paused
|
|
|
|
before the program was sent to the background.
|
|
|
|
|
|
|
|
Example of listening for `SIGTSTP`:
|
|
|
|
|
|
|
|
rl.on('SIGTSTP', function() {
|
|
|
|
// This will override SIGTSTP and prevent the program from going to the
|
|
|
|
// background.
|
|
|
|
console.log('Caught SIGTSTP.');
|
|
|
|
});
|
|
|
|
|
|
|
|
### Event: 'SIGCONT'
|
|
|
|
|
|
|
|
`function () {}`
|
|
|
|
|
|
|
|
**This does not work on Windows.**
|
|
|
|
|
|
|
|
Emitted whenever the `input` stream is sent to the background with `^Z`,
|
|
|
|
respectively known as `SIGTSTP`, and then continued with `fg(1)`. This event
|
|
|
|
only emits if the stream was not paused before sending the program to the
|
|
|
|
background.
|
|
|
|
|
|
|
|
Example of listening for `SIGCONT`:
|
|
|
|
|
|
|
|
rl.on('SIGCONT', function() {
|
|
|
|
// `prompt` will automatically resume the stream
|
|
|
|
rl.prompt();
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
|
|
## Example: Tiny CLI
|
|
|
|
|
|
|
|
Here's an example of how to use all these together to craft a tiny command
|
|
|
|
line interface:
|
|
|
|
|
|
|
|
var readline = require('readline'),
|
|
|
|
rl = readline.createInterface(process.stdin, process.stdout);
|
|
|
|
|
|
|
|
rl.setPrompt('OHAI> ');
|
|
|
|
rl.prompt();
|
|
|
|
|
|
|
|
rl.on('line', function(line) {
|
|
|
|
switch(line.trim()) {
|
|
|
|
case 'hello':
|
|
|
|
console.log('world!');
|
|
|
|
break;
|
|
|
|
default:
|
|
|
|
console.log('Say what? I might have heard `' + line.trim() + '`');
|
|
|
|
break;
|
|
|
|
}
|
|
|
|
rl.prompt();
|
|
|
|
}).on('close', function() {
|
|
|
|
console.log('Have a great day!');
|
|
|
|
process.exit(0);
|
|
|
|
});
|
|
|
|
|