diff options
author | Jeremy Albright <myrlin1@gmail.com> | 2019-11-22 20:56:42 -1000 |
---|---|---|
committer | Anna Henningsen <anna@addaleax.net> | 2019-12-07 23:06:25 +0100 |
commit | bd9be0418a4ce528c3497ff80d5d70404be10f6f (patch) | |
tree | a458c4452bba417d4bdd0120cea60c90e60fd29f | |
parent | a9abc17153921294150cda8df84c5d81faae02c4 (diff) | |
download | android-node-v8-bd9be0418a4ce528c3497ff80d5d70404be10f6f.tar.gz android-node-v8-bd9be0418a4ce528c3497ff80d5d70404be10f6f.tar.bz2 android-node-v8-bd9be0418a4ce528c3497ff80d5d70404be10f6f.zip |
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>
-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 ceda170bc2..ce63dbaa39 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 |