Skip to content

Commit

Permalink
doc: sort readline alphabetically
Browse files Browse the repository at this point in the history
Reorders, with no contextual changes, the readline documentation
alphabetically.

PR-URL: #3662
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
  • Loading branch information
tflanagan authored and rvagg committed Nov 13, 2015
1 parent 389ead3 commit 29054ff
Showing 1 changed file with 105 additions and 106 deletions.
211 changes: 105 additions & 106 deletions doc/api/readline.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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])

Expand Down Expand Up @@ -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])

Expand All @@ -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) {}`
Expand Down Expand Up @@ -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'

Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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.

0 comments on commit 29054ff

Please sign in to comment.