From bd9be0418a4ce528c3497ff80d5d70404be10f6f Mon Sep 17 00:00:00 2001
From: Jeremy Albright <myrlin1@gmail.com>
Date: Fri, 22 Nov 2019 20:56:42 -1000
Subject: 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>
---
 doc/api/readline.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

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
-- 
cgit v1.2.3