Событие: 'close'

Событие 'close' генерируется при наступлении одного из следующих условий:

• Вызывается метод rl.close(), и экземпляр InterfaceConstructor освобождает управление потоками input и output;
• Поток input получает событие 'end';
• Поток input получает Ctrl+D, сигнализируя о конце передачи (EOT);
• Поток input получает Ctrl+C, сигнализируя о SIGINT, и в экземпляре InterfaceConstructor не зарегистрирован обработчик события 'SIGINT'.

Функция-обработчик вызывается без аргументов.

Работа экземпляра InterfaceConstructor завершается после генерации события 'close'.

Событие: 'line'

Событие 'line' генерируется каждый раз, когда поток input получает символ конца строки (\n, \r или \r\n). Обычно это происходит, когда пользователь нажимает Enter или Return.

Событие 'line' также генерируется, если из потока были прочитаны новые данные, а затем поток завершается без завершающего символа конца строки.

Функция-обработчик вызывается со строкой, содержащей одну строку полученных данных.

rl.on('line', (input) => {
  console.log(`Received: ${input}`);
}); copy

Событие: 'history'

Событие 'history' генерируется каждый раз, когда изменяется массив истории.

Функция-обработчик вызывается с массивом, содержащим массив истории. Он отражает все изменения, добавленные и удалённые строки, вызванные методами historySize и removeHistoryDuplicates.

Основная цель — дать обработчику возможность сохранять историю. Обработчик также может изменить объект истории. Это может быть полезно, чтобы не добавлять в историю определённые строки, например пароль.

rl.on('history', (history) => {
  console.log(`Received: ${history}`);
}); copy

Событие: 'pause'

Событие 'pause' генерируется при наступлении одного из следующих условий:

• Поток input приостанавливается.
• Поток input не приостановлен и получает событие 'SIGCONT'. (См. события 'SIGTSTP' и 'SIGCONT'.)

Функция-обработчик вызывается без аргументов.

rl.on('pause', () => {
  console.log('Readline paused.');
}); copy

Событие: 'resume'

Событие 'resume' генерируется каждый раз, когда поток input возобновляет работу.

Функция-обработчик вызывается без аргументов.

rl.on('resume', () => {
  console.log('Readline resumed.');
}); copy

Событие: 'SIGCONT'

Событие 'SIGCONT' генерируется, когда процесс Node.js, ранее переведённый в фоновый режим с помощью Ctrl+Z (то есть SIGTSTP), возвращается на передний план с помощью fg(1p).

Если поток input был приостановлен до запроса SIGTSTP, это событие не будет сгенерировано.

Функция-обработчик вызывается без аргументов.

rl.on('SIGCONT', () => {
  // `prompt` will automatically resume the stream
  rl.prompt();
}); copy

Событие 'SIGCONT' не поддерживается в Windows.

Событие: 'SIGINT'

Событие 'SIGINT' генерируется каждый раз, когда поток input получает нажатие Ctrl+C, обычно называемое SIGINT. Если при получении потоком input сигнала SIGINT не зарегистрирован ни один обработчик события 'SIGINT', будет сгенерировано событие 'pause'.

Функция-обработчик вызывается без аргументов.

rl.on('SIGINT', () => {
  rl.question('Are you sure you want to exit? ', (answer) => {
    if (answer.match(/^y(es)?$/i)) rl.pause();
  });
}); copy

Событие: 'SIGTSTP'

Событие 'SIGTSTP' генерируется, когда поток input получает нажатие Ctrl+Z, обычно называемое SIGTSTP. Если при получении потоком input сигнала SIGTSTP не зарегистрирован ни один обработчик события 'SIGTSTP', процесс Node.js будет переведён в фоновый режим.

После возобновления работы программы с помощью fg(1p) будут сгенерированы события 'pause' и 'SIGCONT'. Их можно использовать, чтобы возобновить поток input.

События 'pause' и 'SIGCONT' не будут сгенерированы, если input был приостановлен до перевода процесса в фоновый режим.

Функция-обработчик вызывается без аргументов.

rl.on('SIGTSTP', () => {
  // This will override SIGTSTP and prevent the program from going to the
  // background.
  console.log('Caught SIGTSTP.');
}); copy

Событие 'SIGTSTP' не поддерживается в Windows.

rl.close()

Метод rl.close() закрывает экземпляр InterfaceConstructor и освобождает управление потоками input и output. При его вызове будет сгенерировано событие 'close'.

Вызов rl.close() не приводит к немедленному прекращению генерации других событий (включая 'line') экземпляром InterfaceConstructor.

rl[Symbol.dispose]()

Псевдоним для rl.close().

rl.pause()

Метод rl.pause() приостанавливает поток input, чтобы при необходимости его можно было возобновить позже.

Вызов rl.pause() не приводит к немедленному прекращению генерации других событий (включая 'line') экземпляром InterfaceConstructor.

rl.prompt([preserveCursor])

• preserveCursor <boolean> Если значение true, курсор не будет перемещён в начальное положение 0.

Метод rl.prompt() выводит настроенное значение prompt экземпляров InterfaceConstructor в новой строке в output, чтобы предоставить пользователю новое место для ввода данных.

При вызове rl.prompt() возобновит поток input, если он был приостановлен.

Если объект InterfaceConstructor создан с параметром output, установленным в значение null или undefined, приглашение не выводится.

rl.resume()

Метод rl.resume() возобновляет поток input, если он был приостановлен.

rl.setPrompt(prompt)

• prompt <string>

Метод rl.setPrompt() задаёт приглашение, которое будет выводиться в output при каждом вызове rl.prompt().

rl.getPrompt()

• Возвращает: <string> текущую строку приглашения

Метод rl.getPrompt() возвращает текущее приглашение, используемое rl.prompt().

rl.write(data[, key])

• data <string>
• key <Object>
  • ctrl <boolean> true для указания клавиши Ctrl.
  • meta <boolean> true для указания клавиши Meta.
  • shift <boolean> true для указания клавиши Shift.
  • name <string> Название клавиши.

Метод rl.write() выводит в output значение data или последовательность клавиш, заданную параметром key. Аргумент key поддерживается только в том случае, если output является текстовым терминалом TTY. Список сочетаний клавиш см. в разделе Сочетания клавиш TTY.

Если указан параметр key, параметр data игнорируется.

При вызове rl.write() возобновит поток input, если он был приостановлен.

Если объект InterfaceConstructor создан с параметром output, установленным в значение null или undefined, значения data и key не выводятся.

rl.write('Delete this!');
// Simulate Ctrl+U to delete the line written previously
rl.write(null, { ctrl: true, name: 'u' }); copy

Метод rl.write() выводит данные в readline Interface's input, как если бы их ввёл пользователь.

rl[Symbol.asyncIterator]()

• Возвращает: <AsyncIterator>

Создаёт объект AsyncIterator, который перебирает каждую строку входного потока как строку. Этот метод позволяет асинхронно перебирать объекты InterfaceConstructor с помощью циклов for await...of.

Ошибки входного потока не передаются.

Если цикл завершается с помощью break, throw или return, будет вызван rl.close(). Иными словами, перебор объекта InterfaceConstructor всегда приводит к полному чтению входного потока.

Производительность уступает традиционному API событий 'line'. Для приложений, чувствительных к производительности, используйте вместо него 'line'.

async function processLineByLine() {
  const rl = readline.createInterface({
    // ...
  });

  for await (const line of rl) {
    // Each line in the readline input will be successively available here as
    // `line`.
  }
} copy

readline.createInterface() начинает считывать входной поток сразу после вызова. Асинхронные операции между созданием интерфейса и началом асинхронного перебора могут привести к пропуску строк.

rl.line

• Тип: <string>

Текущие входные данные, обрабатываемые Node.js.

Это свойство можно использовать при сборе данных из потока TTY, чтобы получить текущее обработанное значение до генерации события line. После генерации события line это свойство будет содержать пустую строку.

Учтите, что изменение значения во время работы экземпляра может привести к непредвиденным последствиям, если также не контролировать rl.cursor.

Если для ввода используется не поток TTY, используйте событие 'line'.

Один из возможных вариантов использования:

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();
}); copy

rl.cursor

• Тип: <number> | <undefined>

Позиция курсора относительно rl.line.

При чтении данных из потока TTY отслеживается положение текущего курсора во входной строке. Положение курсора определяет, какая часть входной строки будет изменена при обработке данных, а также в каком столбце будет отображаться курсор терминала.

rl.getCursorPos()

• Возвращает: <Object>
  • rows <number> строка приглашения, на которой сейчас находится курсор
  • cols <number> столбец экрана, в котором сейчас находится курсор

Возвращает фактическое положение курсора относительно строки приглашения и введённой строки. При вычислении учитываются длинные строки ввода с переносами, а также многострочные приглашения.

Класс: readlinePromises.Interface

• Наследует: <readline.InterfaceConstructor>

Экземпляры класса readlinePromises.Interface создаются с помощью метода readlinePromises.createInterface(). Каждый экземпляр связан с одним потоком input Readable и одним потоком output Writable. Поток output используется для вывода приглашений к вводу, который поступает из потока input и считывается из него.

const answer = await rl.question('What is your favorite food? ');
console.log(`Oh, so your favorite food is ${answer}`); copy

const signal = AbortSignal.timeout(10_000);

signal.addEventListener('abort', () => {
  console.log('The food question timed out');
}, { once: true });

const answer = await rl.question('What is your favorite food? ', { signal });
console.log(`Oh, so your favorite food is ${answer}`); copy

Класс: readlinePromises.Readline

readlinePromises.createInterface(options)

• options <Object>
  • input <stream.Readable> Поток Readable, который нужно прослушивать. Этот параметр обязателен.
  • output <stream.Writable> Поток Writable, в который нужно записывать данные readline.
  • completer <Function> Необязательная функция для автодополнения по клавише Tab.
  • terminal <boolean> true, если потоки input и output следует считать потоками TTY и записывать в них управляющие последовательности ANSI/VT100. По умолчанию: проверка isTTY в потоке output при создании экземпляра.
  • history <string[]> Начальный список строк истории. Этот параметр имеет смысл, только если пользователь или внутренняя проверка output установили terminal в true; в противном случае механизм кэширования истории вообще не инициализируется. По умолчанию: [].
  • historySize <number> Максимальное число сохраняемых строк истории. Чтобы отключить историю, установите это значение в 0. Этот параметр имеет смысл, только если пользователь или внутренняя проверка output установили terminal в true; в противном случае механизм кэширования истории вообще не инициализируется. По умолчанию: 30.
  • removeHistoryDuplicates <boolean> Если true, при добавлении в список истории новой строки ввода, совпадающей с более старой, старая строка удаляется из списка. По умолчанию: false.
  • prompt <string> Используемая строка приглашения. По умолчанию: '> '.
  • crlfDelay <number> Если задержка между \r и \n превышает crlfDelay миллисекунд, \r и \n будут считаться отдельными символами конца строки. Значение crlfDelay будет преобразовано в число не меньше 100. Можно задать значение Infinity; в этом случае \r, за которым следует \n, всегда будет считаться одним символом новой строки (это может быть целесообразно при чтении файлов с разделителем строк \r\n). По умолчанию: 100.
  • escapeCodeTimeout <number> Время, в течение которого readlinePromises ожидает появления символа (при чтении неоднозначной последовательности клавиш, которая может как образовать полную последовательность клавиш с уже прочитанными данными, так и требовать дополнительных данных для завершения более длинной последовательности клавиш). По умолчанию: 500.
  • tabSize <integer> Количество пробелов, эквивалентное одной табуляции (минимум 1). По умолчанию: 8.
  • signal <AbortSignal> Позволяет закрыть интерфейс с помощью AbortSignal.
• Возвращает: <readlinePromises.Interface>

Метод readlinePromises.createInterface() создаёт новый экземпляр readlinePromises.Interface.

import { createInterface } from 'node:readline/promises';
import { stdin, stdout } from 'node:process';
const rl = createInterface({
  input: stdin,
  output: stdout,
});

const { createInterface } = require('node:readline/promises');
const rl = createInterface({
  input: process.stdin,
  output: process.stdout,
});

После создания экземпляра readlinePromises.Interface чаще всего прослушивают событие 'line':

rl.on('line', (line) => {
  console.log(`Received: ${line}`);
}); copy

Если для этого экземпляра terminal имеет значение true, поток output будет наиболее совместимым, если в нём определено свойство output.columns и генерируется событие 'resize' в потоке output при изменении числа столбцов (это происходит автоматически для process.stdout, если он является TTY).

function completer(line) {
  const completions = '.help .error .exit .quit .q'.split(' ');
  const hits = completions.filter((c) => c.startsWith(line));
  // Show all completions if none found
  return [hits.length ? hits : completions, line];
} copy

async function completer(linePartial) {
  await someAsyncWork();
  return [['123'], linePartial];
} copy

Класс: readline.Interface

• Расширяет: <readline.InterfaceConstructor>

Экземпляры класса readline.Interface создаются с помощью метода readline.createInterface(). Каждый экземпляр связан с одним потоком input Readable и одним потоком output Writable. Поток output используется для вывода подсказок к пользовательскому вводу, поступающему из потока input и считываемому из него.

rl.question('What is your favorite food? ', (answer) => {
  console.log(`Oh, so your favorite food is ${answer}`);
}); copy

const ac = new AbortController();
const signal = ac.signal;

rl.question('What is your favorite food? ', { signal }, (answer) => {
  console.log(`Oh, so your favorite food is ${answer}`);
});

signal.addEventListener('abort', () => {
  console.log('The food question timed out');
}, { once: true });

setTimeout(() => ac.abort(), 10000); copy

readline.clearLine(stream, dir[, callback])

• stream <stream.Writable>
• dir <number>
  • -1: слева от курсора
  • 1: справа от курсора
  • 0: вся строка
• callback <Function> Вызывается после завершения операции.
• Возвращает: <boolean> false, если stream хочет, чтобы вызывающий код дождался отправки события 'drain', прежде чем продолжить запись дополнительных данных; в противном случае — true.

Метод readline.clearLine() очищает текущую строку заданного потока TTY в направлении, указанном параметром dir.

readline.clearScreenDown(stream[, callback])

• stream <stream.Writable>
• callback <Function> Вызывается после завершения операции.
• Возвращает: <boolean> false, если stream хочет, чтобы вызывающий код дождался отправки события 'drain', прежде чем продолжить запись дополнительных данных; в противном случае — true.

Метод readline.clearScreenDown() очищает заданный поток TTY от текущего положения курсора вниз.

readline.createInterface(options)

• options <Object>
  • input <stream.Readable> Поток Readable, события которого нужно отслеживать. Этот параметр обязателен.
  • output <stream.Writable> Поток Writable, в который записываются данные readline.
  • completer <Function> Необязательная функция для автодополнения по клавише Tab.
  • terminal <boolean> true, если потоки input и output следует считать терминалом TTY и записывать в них управляющие последовательности ANSI/VT100. По умолчанию: проверка isTTY для потока output при создании экземпляра.
  • history <string[]> Начальный список строк истории. Этот параметр имеет смысл, только если пользователь установил terminal в true или если такая настройка задана внутренней проверкой output; в противном случае механизм кэширования истории вообще не инициализируется. По умолчанию: [].
  • historySize <number> Максимальное количество сохраняемых строк истории. Чтобы отключить историю, задайте этому значению 0. Этот параметр имеет смысл, только если пользователь установил terminal в true или если такая настройка задана внутренней проверкой output; в противном случае механизм кэширования истории вообще не инициализируется. По умолчанию: 30.
  • removeHistoryDuplicates <boolean> Если true, при добавлении в список истории новой строки ввода, дублирующей более старую, старая строка удаляется из списка. По умолчанию: false.
  • prompt <string> Строка подсказки. По умолчанию: '> '.
  • crlfDelay <number> Если задержка между \r и \n превышает crlfDelay миллисекунд, \r и \n будут рассматриваться как отдельные символы конца строки. Значение crlfDelay будет приведено к числу не меньше 100. Ему можно задать значение Infinity; в этом случае \r, за которым следует \n, всегда будет считаться одним символом новой строки (это может быть удобно при чтении файлов с разделителем строк \r\n). По умолчанию: 100.
  • escapeCodeTimeout <number> Время, в течение которого readline ожидает символ (при чтении неоднозначной последовательности клавиш, которая по уже считанному вводу может как образовать полную последовательность, так и потребовать дополнительных символов для завершения более длинной последовательности). По умолчанию: 500.
  • tabSize <integer> Количество пробелов, эквивалентное табуляции (не менее 1). По умолчанию: 8.
  • signal <AbortSignal> Позволяет закрыть интерфейс с помощью AbortSignal. При отмене сигнала для интерфейса будет внутренне вызван close.
• Возвращает: <readline.Interface>

Метод readline.createInterface() создаёт новый экземпляр readline.Interface.

import { createInterface } from 'node:readline';
import { stdin, stdout } from 'node:process';
const rl = createInterface({
  input: stdin,
  output: stdout,
});

const { createInterface } = require('node:readline');
const rl = createInterface({
  input: process.stdin,
  output: process.stdout,
});

После создания экземпляра readline.Interface в большинстве случаев следует отслеживать событие 'line':

rl.on('line', (line) => {
  console.log(`Received: ${line}`);
}); copy

Если для этого экземпляра terminal задано значение true, поток output будет наиболее совместимым, если в нём определено свойство output.columns и при изменении количества столбцов отправляется событие 'resize' для output (process.stdout выполняет это автоматически, если является TTY).

При создании readline.Interface с использованием stdin в качестве ввода программа не завершится, пока не получит символ EOF. Чтобы выйти, не дожидаясь ввода пользователя, вызовите process.stdin.unref().

function completer(line) {
  const completions = '.help .error .exit .quit .q'.split(' ');
  const hits = completions.filter((c) => c.startsWith(line));
  // Show all completions if none found
  return [hits.length ? hits : completions, line];
} copy

function completer(linePartial, callback) {
  callback(null, [['123'], linePartial]);
} copy

readline.cursorTo(stream, x[, y][, callback])

• stream <stream.Writable>
• x <number>
• y <number>
• callback <Function> Вызывается после завершения операции.
• Возвращает: <boolean> false, если stream хочет, чтобы вызывающий код дождался отправки события 'drain', прежде чем продолжить запись дополнительных данных; в противном случае — true.

Метод readline.cursorTo() перемещает курсор в заданную позицию в указанном потоке TTY stream.

readline.moveCursor(stream, dx, dy[, callback])

• stream <stream.Writable>
• dx <number>
• dy <number>
• callback <Function> Вызывается после завершения операции.
• Возвращает: <boolean> false, если stream хочет, чтобы вызывающий код дождался отправки события 'drain', прежде чем продолжить запись дополнительных данных; в противном случае — true.

Метод readline.moveCursor() перемещает курсор относительно его текущего положения в указанном потоке TTY stream.