Class: InterfaceConstructor#
Added in: v0.1.104
Instances of the InterfaceConstructor class are constructed using the
readlinePromises.createInterface() or readline.createInterface() method.
Every instance is associated with a single input Readable stream and a
single output Writable stream.
The output stream is used to print prompts for user input that arrives on,
and is read from, the input stream.
Event: 'close'#
Added in: v0.1.98
The 'close' event is emitted when one of the following occur:
- The
rl.close() method is called and the InterfaceConstructor instance has
relinquished control over the input and output streams;
- The
input stream receives its 'end' event;
- The
input stream receives Ctrl+D to signal
end-of-transmission (EOT);
- The
input stream receives Ctrl+C to signal SIGINT
and there is no 'SIGINT' event listener registered on the
InterfaceConstructor instance.
The listener function is called without passing any arguments.
The InterfaceConstructor instance is finished once the 'close' event is
emitted.
Event: 'line'#
Added in: v0.1.98
The 'line' event is emitted whenever the input stream receives an
end-of-line input (\n, \r, or \r\n). This usually occurs when the user
presses Enter or Return.
The 'line' event is also emitted if new data has been read from a stream and
that stream ends without a final end-of-line marker.
The listener function is called with a string containing the single line of
received input.
rl.on('line', (input) => {
console.log(`Received: ${input}`);
});
Event: 'history'#
Added in: v15.8.0, v14.18.0
The 'history' event is emitted whenever the history array has changed.
The listener function is called with an array containing the history array.
It will reflect all changes, added lines and removed lines due to
historySize and removeHistoryDuplicates.
The primary purpose is to allow a listener to persist the history.
It is also possible for the listener to change the history object. This
could be useful to prevent certain lines to be added to the history, like
a password.
rl.on('history', (history) => {
console.log(`Received: ${history}`);
});
Event: 'pause'#
Added in: v0.7.5
The 'pause' event is emitted when one of the following occur:
- The
input stream is paused.
- The
input stream is not paused and receives the 'SIGCONT' event. (See
events 'SIGTSTP' and 'SIGCONT'.)
The listener function is called without passing any arguments.
rl.on('pause', () => {
console.log('Readline paused.');
});
Event: 'resume'#
Added in: v0.7.5
The 'resume' event is emitted whenever the input stream is resumed.
The listener function is called without passing any arguments.
rl.on('resume', () => {
console.log('Readline resumed.');
});
Event: 'SIGCONT'#
Added in: v0.7.5
The 'SIGCONT' event is emitted when a Node.js process previously moved into
the background using Ctrl+Z (i.e. SIGTSTP) is then
brought back to the foreground using fg(1p).
If the input stream was paused before the SIGTSTP request, this event will
not be emitted.
The listener function is invoked without passing any arguments.
rl.on('SIGCONT', () => {
rl.prompt();
});
The 'SIGCONT' event is not supported on Windows.
Event: 'SIGINT'#
Added in: v0.3.0
The 'SIGINT' event is emitted whenever the input stream receives
a Ctrl+C input, known typically as SIGINT. If there are no
'SIGINT' event listeners registered when the input stream receives a
SIGINT, the 'pause' event will be emitted.
The listener function is invoked without passing any arguments.
rl.on('SIGINT', () => {
rl.question('Are you sure you want to exit? ', (answer) => {
if (answer.match(/^y(es)?$/i)) rl.pause();
});
});
Event: 'SIGTSTP'#
Added in: v0.7.5
The 'SIGTSTP' event is emitted when the input stream receives
a Ctrl+Z input, typically known as SIGTSTP. If there are
no 'SIGTSTP' event listeners registered when the input stream receives a
SIGTSTP, the Node.js process will be sent to the background.
When the program is resumed using fg(1p), the 'pause' and 'SIGCONT' events
will be emitted. These can be used to resume the input stream.
The 'pause' and 'SIGCONT' events will not be emitted if the input was
paused before the process was sent to the background.
The listener function is invoked without passing any arguments.
rl.on('SIGTSTP', () => {
console.log('Caught SIGTSTP.');
});
The 'SIGTSTP' event is not supported on Windows.
rl.close()#
Added in: v0.1.98
The rl.close() method closes the InterfaceConstructor instance and
relinquishes control over the input and output streams. When called,
the 'close' event will be emitted.
Calling rl.close() does not immediately stop other events (including 'line')
from being emitted by the InterfaceConstructor instance.
rl[Symbol.dispose]()#
Added in: v22.15.0
Alias for rl.close().
rl.pause()#
Added in: v0.3.4
The rl.pause() method pauses the input stream, allowing it to be resumed
later if necessary.
Calling rl.pause() does not immediately pause other events (including
'line') from being emitted by the InterfaceConstructor instance.
rl.prompt([preserveCursor])#
Added in: v0.1.98
preserveCursor <boolean> If true, prevents the cursor placement from
being reset to 0.
The rl.prompt() method writes the InterfaceConstructor instances configured
prompt to a new line in output in order to provide a user with a new
location at which to provide input.
When called, rl.prompt() will resume the input stream if it has been
paused.
If the InterfaceConstructor was created with output set to null or
undefined the prompt is not written.
rl.resume()#
Added in: v0.3.4
The rl.resume() method resumes the input stream if it has been paused.
rl.setPrompt(prompt)#
Added in: v0.1.98
The rl.setPrompt() method sets the prompt that will be written to output
whenever rl.prompt() is called.
rl.getPrompt()#
Added in: v15.3.0, v14.17.0
- Returns: <string> the current prompt string
The rl.getPrompt() method returns the current prompt used by rl.prompt().
rl.write(data[, key])#
Added in: v0.1.98
The rl.write() method will write either data or a key sequence identified
by key to the output. The key argument is supported only if output is
a TTY text terminal. See TTY keybindings for a list of key
combinations.
If key is specified, data is ignored.
When called, rl.write() will resume the input stream if it has been
paused.
If the InterfaceConstructor was created with output set to null or
undefined the data and key are not written.
rl.write('Delete this!');
rl.write(null, { ctrl: true, name: 'u' });
The rl.write() method will write the data to the readline Interface's
input as if it were provided by the user.
rl[Symbol.asyncIterator]()#
Create an AsyncIterator object that iterates through each line in the input
stream as a string. This method allows asynchronous iteration of
InterfaceConstructor objects through for await...of loops.
Errors in the input stream are not forwarded.
If the loop is terminated with break, throw, or return,
rl.close() will be called. In other words, iterating over a
InterfaceConstructor will always consume the input stream fully.
Performance is not on par with the traditional 'line' event API. Use 'line'
instead for performance-sensitive applications.
async function processLineByLine() {
const rl = readline.createInterface({
});
for await (const line of rl) {
}
}
readline.createInterface() will start to consume the input stream once
invoked. Having asynchronous operations between interface creation and
asynchronous iteration may result in missed lines.
rl.line#
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:
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#
Added in: v0.1.98
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.
rl.getCursorPos()#
Added in: v13.5.0, v12.16.0
- Returns: <Object>
rows <number> the row of the prompt the cursor currently lands on
cols <number> the screen column the cursor currently lands on
Returns the real position of the cursor in relation to the input
prompt + string. Long input (wrapping) strings, as well as multiple
line prompts are included in the calculations.
Example: Read file stream line-by-Line#
A common use case for readline is to consume an input file one line at a
time. The easiest way to do so is leveraging the fs.ReadStream API as
well as a for await...of loop:
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';
async function processLineByLine() {
const fileStream = createReadStream('input.txt');
const rl = createInterface({
input: fileStream,
crlfDelay: Infinity,
});
for await (const line of rl) {
console.log(`Line from file: ${line}`);
}
}
processLineByLine();const { createReadStream } = require('node:fs');
const { createInterface } = require('node:readline');
async function processLineByLine() {
const fileStream = createReadStream('input.txt');
const rl = createInterface({
input: fileStream,
crlfDelay: Infinity,
});
for await (const line of rl) {
console.log(`Line from file: ${line}`);
}
}
processLineByLine();
Alternatively, one could use the 'line' event:
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';
const rl = createInterface({
input: createReadStream('sample.txt'),
crlfDelay: Infinity,
});
rl.on('line', (line) => {
console.log(`Line from file: ${line}`);
});const { createReadStream } = require('node:fs');
const { createInterface } = require('node:readline');
const rl = createInterface({
input: createReadStream('sample.txt'),
crlfDelay: Infinity,
});
rl.on('line', (line) => {
console.log(`Line from file: ${line}`);
});
Currently, for await...of loop can be a bit slower. If async / await
flow and speed are both essential, a mixed approach can be applied:
import { once } from 'node:events';
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';
(async function processLineByLine() {
try {
const rl = createInterface({
input: createReadStream('big-file.txt'),
crlfDelay: Infinity,
});
rl.on('line', (line) => {
});
await once(rl, 'close');
console.log('File processed.');
} catch (err) {
console.error(err);
}
})();const { once } = require('node:events');
const { createReadStream } = require('node:fs');
const { createInterface } = require('node:readline');
(async function processLineByLine() {
try {
const rl = createInterface({
input: createReadStream('big-file.txt'),
crlfDelay: Infinity,
});
rl.on('line', (line) => {
});
await once(rl, 'close');
console.log('File processed.');
} catch (err) {
console.error(err);
}
})();