diff --git a/doc/api/readline.md b/doc/api/readline.md index b74cad03befa12..9fd8f1f1ecacc1 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -349,6 +349,55 @@ async function processLineByLine() { } ``` +### rl.line + + +* {string|undefined} + +The current input data being processed by node. + +This can be used when collecting input from a TTY stream to retrieve the +current value that has been processed thus far, prior to the `line` event +being emitted. Once the `line` event has been emitted, this property will +be an empty string. + +Be aware that modifying the value during the instance runtime may have +unintended consequences if `rl.cursor` is not also controlled. + +**If not using a TTY stream for input, use the [`'line'`][] event.** + +One possible use case would be as follows: + +```js +const values = ['lorem ipsum', 'dolor sit amet']; +const rl = readline.createInterface(process.stdin); +const showResults = debounce(() => { + console.log( + '\n', + values.filter((val) => val.startsWith(rl.line)).join(' ') + ); +}, 300); +process.stdin.on('keypress', (c, k) => { + showResults(); +}); +``` + +### rl.cursor + + +* {number|undefined} + +The cursor position relative to `rl.line`. + +This will track where the current cursor lands in the input string, when +reading input from a TTY stream. The position of cursor determines the +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. + ## `readline.clearLine(stream, dir[, callback])`