Skip to content
Permalink
Browse files

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: #30347
Refs: DefinitelyTyped/DefinitelyTyped#40513

PR-URL: #30667
Reviewed-By: Anna Henningsen <anna@addaleax.net>
  • Loading branch information
Js-Brecht authored and addaleax committed Nov 23, 2019
1 parent a9abc17 commit bd9be0418a4ce528c3497ff80d5d70404be10f6f
Showing with 49 additions and 0 deletions.
  1. +49 −0 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

0 comments on commit bd9be04

Please sign in to comment.
You can’t perform that action at this time.