diff options
Diffstat (limited to 'doc/api/readline.md')
| -rw-r--r-- | doc/api/readline.md | 71 |
1 files changed, 57 insertions, 14 deletions
diff --git a/doc/api/readline.md b/doc/api/readline.md index b9e4c28699..31d910e1b6 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -63,7 +63,9 @@ Once this code is invoked, the Node.js application will not terminate until the received on the `input` stream. <a id='readline_class_interface'></a> + ## Class: `InterfaceConstructor` + <!-- YAML added: v0.1.104 --> @@ -78,6 +80,7 @@ The `output` stream is used to print prompts for user input that arrives on, and is read from, the `input` stream. ### Event: `'close'` + <!-- YAML added: v0.1.98 --> @@ -99,6 +102,7 @@ The `InterfaceConstructor` instance is finished once the `'close'` event is emitted. ### Event: `'line'` + <!-- YAML added: v0.1.98 --> @@ -117,6 +121,7 @@ rl.on('line', (input) => { ``` ### Event: `'history'` + <!-- YAML added: - v15.8.0 @@ -141,6 +146,7 @@ rl.on('history', (history) => { ``` ### Event: `'pause'` + <!-- YAML added: v0.7.5 --> @@ -160,6 +166,7 @@ rl.on('pause', () => { ``` ### Event: `'resume'` + <!-- YAML added: v0.7.5 --> @@ -175,6 +182,7 @@ rl.on('resume', () => { ``` ### Event: `'SIGCONT'` + <!-- YAML added: v0.7.5 --> @@ -183,7 +191,7 @@ The `'SIGCONT'` event is emitted when a Node.js process previously moved into the background using <kbd>Ctrl</kbd>+<kbd>Z</kbd> (i.e. `SIGTSTP`) is then brought back to the foreground using fg(1p). -If the `input` stream was paused *before* the `SIGTSTP` request, this event will +If the `input` stream was paused _before_ the `SIGTSTP` request, this event will not be emitted. The listener function is invoked without passing any arguments. @@ -198,14 +206,15 @@ rl.on('SIGCONT', () => { The `'SIGCONT'` event is _not_ supported on Windows. ### Event: `'SIGINT'` + <!-- YAML added: v0.3.0 --> -The `'SIGINT'` event is emitted whenever the `input` stream receives a -<kbd>Ctrl+C</kbd> input, known typically as `SIGINT`. If there are no `'SIGINT'` -event listeners registered when the `input` stream receives a `SIGINT`, the -`'pause'` event will be emitted. +The `'SIGINT'` event is emitted whenever the `input` stream receives +a <kbd>Ctrl+C</kbd> input, known typically as `SIGINT`. If there are no +`'SIGINT'` event listeners registered when the `input` stream receives a +`SIGINT`, the `'pause'` event will be emitted. The listener function is invoked without passing any arguments. @@ -218,12 +227,13 @@ rl.on('SIGINT', () => { ``` ### Event: `'SIGTSTP'` + <!-- YAML added: v0.7.5 --> -The `'SIGTSTP'` event is emitted when the `input` stream receives a -<kbd>Ctrl</kbd>+<kbd>Z</kbd> input, typically known as `SIGTSTP`. If there are +The `'SIGTSTP'` event is emitted when the `input` stream receives +a <kbd>Ctrl</kbd>+<kbd>Z</kbd> input, typically known as `SIGTSTP`. If there are no `'SIGTSTP'` event listeners registered when the `input` stream receives a `SIGTSTP`, the Node.js process will be sent to the background. @@ -246,6 +256,7 @@ rl.on('SIGTSTP', () => { The `'SIGTSTP'` event is _not_ supported on Windows. ### `rl.close()` + <!-- YAML added: v0.1.98 --> @@ -258,6 +269,7 @@ Calling `rl.close()` does not immediately stop other events (including `'line'`) from being emitted by the `InterfaceConstructor` instance. ### `rl.pause()` + <!-- YAML added: v0.3.4 --> @@ -269,6 +281,7 @@ Calling `rl.pause()` does not immediately pause other events (including `'line'`) from being emitted by the `InterfaceConstructor` instance. ### `rl.prompt([preserveCursor])` + <!-- YAML added: v0.1.98 --> @@ -287,6 +300,7 @@ If the `InterfaceConstructor` was created with `output` set to `null` or `undefined` the prompt is not written. ### `rl.question(query[, options], callback)` + <!-- YAML added: v0.3.3 --> @@ -358,6 +372,7 @@ questionExample(); ``` ### `rl.resume()` + <!-- YAML added: v0.3.4 --> @@ -365,6 +380,7 @@ added: v0.3.4 The `rl.resume()` method resumes the `input` stream if it has been paused. ### `rl.setPrompt(prompt)` + <!-- YAML added: v0.1.98 --> @@ -375,6 +391,7 @@ The `rl.setPrompt()` method sets the prompt that will be written to `output` whenever `rl.prompt()` is called. ### `rl.getPrompt()` + <!-- YAML added: - v15.3.0 @@ -386,6 +403,7 @@ added: The `rl.getPrompt()` method returns the current prompt used by `rl.prompt()`. ### `rl.write(data[, key])` + <!-- YAML added: v0.1.98 --> @@ -417,9 +435,10 @@ rl.write(null, { ctrl: true, name: 'u' }); ``` The `rl.write()` method will write the data to the `readline` `Interface`'s -`input` *as if it were provided by the user*. +`input` _as if it were provided by the user_. ### `rl[Symbol.asyncIterator]()` + <!-- YAML added: - v11.4.0 @@ -465,6 +484,7 @@ invoked. Having asynchronous operations between interface creation and asynchronous iteration may result in missed lines. ### `rl.line` + <!-- YAML added: v0.1.98 changes: @@ -506,6 +526,7 @@ process.stdin.on('keypress', (c, k) => { ``` ### `rl.cursor` + <!-- YAML added: v0.1.98 --> @@ -520,6 +541,7 @@ portion of the input string that will be modified as input is processed, as well as the column where the terminal caret will be rendered. ### `rl.getCursorPos()` + <!-- YAML added: - v13.5.0 @@ -535,6 +557,7 @@ prompt + string. Long input (wrapping) strings, as well as multiple line prompts are included in the calculations. ## Promises API + <!-- YAML added: v17.0.0 --> @@ -542,6 +565,7 @@ added: v17.0.0 > Stability: 1 - Experimental ### Class: `readlinePromises.Interface` + <!-- YAML added: v17.0.0 --> @@ -555,6 +579,7 @@ The `output` stream is used to print prompts for user input that arrives on, and is read from, the `input` stream. #### `rl.question(query[, options])` + <!-- YAML added: v17.0.0 --> @@ -601,11 +626,13 @@ setTimeout(() => ac.abort(), 10000); ``` ### Class: `readlinePromises.Readline` + <!-- YAML added: v17.0.0 --> #### `new readlinePromises.Readline(stream[, options])` + <!-- YAML added: v17.0.0 --> @@ -615,6 +642,7 @@ added: v17.0.0 * `autoCommit` {boolean} If `true`, no need to call `rl.commit()`. #### `rl.clearLine(dir)` + <!-- YAML added: v17.0.0 --> @@ -632,6 +660,7 @@ Call `rl.commit()` to see the effect of this method, unless `autoCommit: true` was passed to the constructor. #### `rl.clearScreenDown()` + <!-- YAML added: v17.0.0 --> @@ -645,6 +674,7 @@ Call `rl.commit()` to see the effect of this method, unless `autoCommit: true` was passed to the constructor. #### `rl.commit()` + <!-- YAML added: v17.0.0 --> @@ -655,6 +685,7 @@ The `rl.commit()` method sends all the pending actions to the associated `stream` and clears the internal list of pending actions. #### `rl.cursorTo(x[, y])` + <!-- YAML added: v17.0.0 --> @@ -669,6 +700,7 @@ Call `rl.commit()` to see the effect of this method, unless `autoCommit: true` was passed to the constructor. #### `rl.moveCursor(dx, dy)` + <!-- YAML added: v17.0.0 --> @@ -678,12 +710,13 @@ added: v17.0.0 * Returns: this The `rl.moveCursor()` method adds to the internal list of pending action an -action that moves the cursor *relative* to its current position in the +action that moves the cursor _relative_ to its current position in the associated `stream`. Call `rl.commit()` to see the effect of this method, unless `autoCommit: true` was passed to the constructor. #### `rl.rollback()` + <!-- YAML added: v17.0.0 --> @@ -694,20 +727,21 @@ The `rl.rollback` methods clears the internal list of pending actions without sending it to the associated `stream`. ### `readlinePromises.createInterface(options)` + <!-- YAML added: v17.0.0 --> * `options` {Object} * `input` {stream.Readable} The [Readable][] stream to listen to. This option - is *required*. + is _required_. * `output` {stream.Writable} The [Writable][] stream to write readline data to. * `completer` {Function} An optional function used for Tab autocompletion. * `terminal` {boolean} `true` if the `input` and `output` streams should be treated like a TTY, and have ANSI/VT100 escape codes written to it. **Default:** checking `isTTY` on the `output` stream upon instantiation. - * `history` {string[]} Initial list of history lines. This option makes sense + * `history` {string\[]} Initial list of history lines. This option makes sense only if `terminal` is set to `true` by the user or by an internal `output` check, otherwise the history caching mechanism is not initialized at all. **Default:** `[]`. @@ -789,11 +823,13 @@ async function completer(linePartial) { ``` ## Callback API + <!-- YAML added: v0.1.104 --> ### Class: `readline.Interface` + <!-- YAML added: v0.1.104 changes: @@ -811,6 +847,7 @@ The `output` stream is used to print prompts for user input that arrives on, and is read from, the `input` stream. #### `rl.question(query[, options], callback)` + <!-- YAML added: v0.3.3 --> @@ -882,6 +919,7 @@ questionExample(); ``` ### `readline.clearLine(stream, dir[, callback])` + <!-- YAML added: v0.7.7 changes: @@ -904,6 +942,7 @@ The `readline.clearLine()` method clears current line of given [TTY][] stream in a specified direction identified by `dir`. ### `readline.clearScreenDown(stream[, callback])` + <!-- YAML added: v0.7.7 changes: @@ -922,6 +961,7 @@ The `readline.clearScreenDown()` method clears the given [TTY][] stream from the current position of the cursor down. ### `readline.createInterface(options)` + <!-- YAML added: v0.1.98 changes: @@ -956,14 +996,14 @@ changes: * `options` {Object} * `input` {stream.Readable} The [Readable][] stream to listen to. This option - is *required*. + is _required_. * `output` {stream.Writable} The [Writable][] stream to write readline data to. * `completer` {Function} An optional function used for Tab autocompletion. * `terminal` {boolean} `true` if the `input` and `output` streams should be treated like a TTY, and have ANSI/VT100 escape codes written to it. **Default:** checking `isTTY` on the `output` stream upon instantiation. - * `history` {string[]} Initial list of history lines. This option makes sense + * `history` {string\[]} Initial list of history lines. This option makes sense only if `terminal` is set to `true` by the user or by an internal `output` check, otherwise the history caching mechanism is not initialized at all. **Default:** `[]`. @@ -1058,6 +1098,7 @@ function completer(linePartial, callback) { ``` ### `readline.cursorTo(stream, x[, y][, callback])` + <!-- YAML added: v0.7.7 changes: @@ -1078,6 +1119,7 @@ The `readline.cursorTo()` method moves cursor to the specified position in a given [TTY][] `stream`. ### `readline.moveCursor(stream, dx, dy[, callback])` + <!-- YAML added: v0.7.7 changes: @@ -1094,10 +1136,11 @@ changes: the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. -The `readline.moveCursor()` method moves the cursor *relative* to its current +The `readline.moveCursor()` method moves the cursor _relative_ to its current position in a given [TTY][] `stream`. ## `readline.emitKeypressEvents(stream[, interface])` + <!-- YAML added: v0.7.7 --> |