@ -23,75 +23,21 @@ program to gracefully exit:
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 (Optional).
- `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.
- `historySize` - maximum number of history lines retained. Defaults to `30` .
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 )
### rl.close()
Sets the prompt, for example when you run `node` on the command line, you see
`> ` , which is node.js's prompt.
Closes the `Interface` instance, relinquishing control on the `input` and
`output` streams. The "close" event will also be emitted.
### rl.pause()
Pauses the readline `input` stream, allowing it to be resumed later if needed.
Note that this doesn't immediately pause the stream of events. Several events may be emitted after calling `pause` , including `line` .
### rl.prompt([preserveCursor])
@ -123,20 +69,14 @@ Example usage:
console.log('Oh, so your favorite food is ' + answer);
});
### rl.pause()
Pauses the readline `input` stream, allowing it to be resumed later if needed.
Note that this doesn't immediately pause the stream of events. Several events may be emitted after calling `pause` , including `line` .
### rl.resume()
Resumes the readline `input` stream.
### rl.clo se()
### rl.setPrompt(prompt)
Closes the `Interface` instance, relinquishing control on the `input` and
`output` streams. The "close" event will also be emitted .
Sets the prompt, for example when you run `node` on the command line, you see
`> ` , which is node.js's prompt .
### rl.write(data[, key])
@ -154,6 +94,19 @@ Example:
## Events
### 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: 'line'
`function (line) {}`
@ -194,18 +147,23 @@ Example of listening for `resume`:
console.log('Readline resumed.');
});
### Event: 'close '
### Event: 'SIGCONT '
`function () {}`
Emitted when `close()` is called.
**This does not work on Windows.**
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` .
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.
This event is also called if there is no `SIGINT` event listener present when
the `input` stream receives a `^C` , respectively known as `SIGINT` .
Example of listening for `SIGCONT` :
rl.on('SIGCONT', function() {
// `prompt` will automatically resume the stream
rl.prompt();
});
### Event: 'SIGINT'
@ -247,25 +205,6 @@ Example of listening for `SIGTSTP`:
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
@ -292,14 +231,6 @@ line interface:
process.exit(0);
});
## readline.cursorTo(stream, x, y)
Move cursor to the specified position in a given TTY stream.
## readline.moveCursor(stream, dx, dy)
Move cursor relative to it's current position in a given TTY stream.
## readline.clearLine(stream, dir)
Clears current line of given TTY stream in a specified direction.
@ -312,3 +243,71 @@ Clears current line of given TTY stream in a specified direction.
## readline.clearScreenDown(stream)
Clears the screen from the current position of the cursor down.
## 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 (Optional).
- `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.
- `historySize` - maximum number of history lines retained. Defaults to `30` .
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).
## readline.cursorTo(stream, x, y)
Move cursor to the specified position in a given TTY stream.
## readline.moveCursor(stream, dx, dy)
Move cursor relative to it's current position in a given TTY stream.
Tristian Flanagan
9 years ago
James M Snell