diff options
author | Jeremy Albright <myrlin1@gmail.com> | 2019-11-23 09:56:42 +0300 |
---|---|---|
committer | Anna Henningsen <anna@addaleax.net> | 2019-12-08 01:06:25 +0300 |
commit | bd9be0418a4ce528c3497ff80d5d70404be10f6f (patch) | |
tree | a458c4452bba417d4bdd0120cea60c90e60fd29f /doc/api/readline.md | |
parent | a9abc17153921294150cda8df84c5d81faae02c4 (diff) |
doc: include line/cursor in readline documentation
Documents the existence and purpose of the `line` and `cursor`
properties. `line` can be used for reading the current input value
during runtime, if reading from a TTY stream. Both properties are
necessary when developing a custom CLI input process using `readline`
as a backend.
Refs: https://github.com/nodejs/node/issues/30347
Refs: https://github.com/DefinitelyTyped/DefinitelyTyped/pull/40513
PR-URL: https://github.com/nodejs/node/pull/30667
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Diffstat (limited to 'doc/api/readline.md')
-rw-r--r-- | doc/api/readline.md | 49 |
1 files changed, 49 insertions, 0 deletions
diff --git a/doc/api/readline.md b/doc/api/readline.md index ceda170bc2b..ce63dbaa390 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -349,6 +349,55 @@ async function processLineByLine() { } ``` +### rl.line +<!-- YAML +added: 0.1.98 +--> + +* {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 +<!-- YAML +added: 0.1.98 +--> + +* {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\]) <!-- YAML added: v0.7.7 |