From 7e55ab7e6c8843d74d2a4b08498ff25fd0749eba Mon Sep 17 00:00:00 2001 From: Jeremy Albright Date: Fri, 22 Nov 2019 20:56:42 -1000 Subject: [PATCH 1/6] 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 --- doc/api/readline.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/doc/api/readline.md b/doc/api/readline.md index ceda170bc2bf5d..e90ffc80cb4a34 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -349,6 +349,48 @@ async function processLineByLine() { } ``` +### rl.line + +* {string} + +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); +process.stdin.on('keypress', (c, k) => { + debounce(() => { + console.log( + '\n', + values.filter((val) => val.startsWith(rl.line)).join(' ') + ); + }, 300); +}); +``` + +### rl.cursor + +* {number} + +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\]) * {string} @@ -381,6 +384,9 @@ process.stdin.on('keypress', (c, k) => { ``` ### rl.cursor + * {number} From 5710c4691a0baf815146fc6a47f1b0ffe6f4b4d7 Mon Sep 17 00:00:00 2001 From: Jeremy Albright Date: Mon, 2 Dec 2019 11:47:08 -0900 Subject: [PATCH 3/6] update results fn to align with standard debounce usage --- doc/api/readline.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/api/readline.md b/doc/api/readline.md index bc36b28909ccb2..66ed3af878bc6f 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -373,13 +373,14 @@ 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) => { - debounce(() => { - console.log( - '\n', - values.filter((val) => val.startsWith(rl.line)).join(' ') - ); - }, 300); + showResults(); }); ``` From 2fa2d8d7ee89fe9a86e41046f5a298106a2e755c Mon Sep 17 00:00:00 2001 From: Jeremy Albright <1935258+Js-Brecht@users.noreply.github.com> Date: Fri, 6 Dec 2019 13:53:56 -0900 Subject: [PATCH 4/6] change `rl.line` type to {string|undefined} Co-Authored-By: Anna Henningsen --- doc/api/readline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/readline.md b/doc/api/readline.md index 66ed3af878bc6f..fddfc9ee590133 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -354,7 +354,7 @@ async function processLineByLine() { added: REPLACEME --> -* {string} +* {string|undefined} The current input data being processed by node. From f193236fac630012672b04e51fc505b9ea8dddd5 Mon Sep 17 00:00:00 2001 From: Jeremy Albright Date: Fri, 6 Dec 2019 12:55:21 -1000 Subject: [PATCH 5/6] change `rl.cursor` type to {number|undefined} --- doc/api/readline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/readline.md b/doc/api/readline.md index fddfc9ee590133..5630c05410a4ae 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -389,7 +389,7 @@ process.stdin.on('keypress', (c, k) => { added: REPLACEME --> -* {number} +* {number|undefined} The cursor position relative to `rl.line`. From ac4e8ba71df27b230e64fa8990adb6521a129404 Mon Sep 17 00:00:00 2001 From: Jeremy Albright Date: Fri, 6 Dec 2019 12:59:25 -1000 Subject: [PATCH 6/6] YAML doc > added: 0.1.98 Verified property exists at the creation of the readline module: version 0.1.98 --- doc/api/readline.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/readline.md b/doc/api/readline.md index 5630c05410a4ae..ce63dbaa3905f6 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -351,7 +351,7 @@ async function processLineByLine() { ### rl.line * {string|undefined} @@ -386,7 +386,7 @@ process.stdin.on('keypress', (c, k) => { ### rl.cursor * {number|undefined}