diff --git a/doc/api/readline.markdown b/doc/api/readline.markdown index 50ddaf660a87ac..ac5c61fa1cc9cf 100644 --- a/doc/api/readline.markdown +++ b/doc/api/readline.markdown @@ -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.close() +### 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.