Событие: 'close'

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

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

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

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

Событие: 'error'

Событие 'error' генерируется при возникновении ошибки в потоке input, связанном с node:readline Interface.

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

Событие: '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 и записывать в них escape-коды 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> Время, в течение которого 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[]> Начальный список строк истории. Этот параметр имеет смысл только в том случае, если пользователь или внутренняя проверка 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> Время, в течение которого 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 и при изменении числа столбцов для output будет генерироваться событие 'resize' (ссылка 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.