Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
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 BethGriggs committed Feb 6, 2020
1 parent b2a2c6c commit 6db2562
Showing 1 changed file with 49 additions and 0 deletions.
49 changes: 49 additions & 0 deletions doc/api/readline.md
Expand Up @@ -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
Expand Down

0 comments on commit 6db2562

Please sign in to comment.