diff options
authorJeremy Albright <>2019-11-22 20:56:42 -1000
committerAnna Henningsen <>2019-12-07 23:06:25 +0100
commitbd9be0418a4ce528c3497ff80d5d70404be10f6f (patch)
parenta9abc17153921294150cda8df84c5d81faae02c4 (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: Refs: PR-URL: Reviewed-By: Anna Henningsen <>
1 files changed, 49 insertions, 0 deletions
diff --git a/doc/api/ b/doc/api/
index ceda170bc2..ce63dbaa39 100644
--- a/doc/api/
+++ b/doc/api/
@@ -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:
+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