Skip to content

Commit

Permalink
doc: include line/cursor in readline documentation
Browse files Browse the repository at this point in the history
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 targos committed Dec 9, 2019
1 parent 14269d1 commit 2123d53
Showing 1 changed file with 49 additions and 0 deletions.
49 changes: 49 additions & 0 deletions doc/api/readline.md
Original file line number Diff line number Diff line change
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 2123d53

Please sign in to comment.