Класс: Interface

• Расширяет: <EventEmitter>

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

Событие: 'close'

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

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

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

Экземпляр readline.Interface завершён, когда генерируется событие 'close'.

Событие: 'line'

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

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

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

Событие: 'pause'

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

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

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

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

Событие: 'resume'

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

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

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

Событие: 'SIGCONT'

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

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

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

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

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

Событие: 'SIGINT'

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

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

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

Событие: 'SIGTSTP'

Событие 'SIGTSTP' генерируется, когда поток input получает вход Ctrl+Z, обычно известный как SIGTSTP. Если нет обработчиков события 'SIGTSTP' зарегистрированы, когда поток input получает 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.');
});

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

rl.close()

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

Вызов rl.close() немедленно не останавливает другие события (включая 'line'), которые могут генерироваться экземпляром readline.Interface.

rl.pause()

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

Вызов rl.pause() немедленно не приостанавливает другие события (включая 'line'), которые могут генерироваться экземпляром readline.Interface.

rl.prompt([preserveCursor])

• preserveCursor <boolean> Если true, предотвращает сброс позиции курсора до 0.

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

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

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

rl.question(query, callback)

• query <string> Текст для отображения пользователю, добавляемый к приглашению.
• callback <Function> Функция-обработчик, которая вызывается с вводом пользователя в ответ на query.

Метод rl.question() отображает query путём записи его в output, ожидает ввода пользователя в input, затем вызывает функцию callback, передавая полученный ввод в качестве первого аргумента.

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

Если экземпляр readline.Interface был создан с output равным null или undefined, query не будет выведен.

Пример использования:

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

Функция callback, переданная в rl.question(), не следует типичной структуре, принимая в качестве первого аргумента объект Error или null. Функция callback вызывается с предоставленным ответом в качестве единственного аргумента.

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() запишет либо data , либо последовательность клавиш, идентифицированную по key, в output. Аргумент key поддерживается только если output является текстовым терминалом TTY. Список комбинаций клавиш см. в разделе Комбинации клавиш TTY.

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

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

Если readline.Interface был создан с 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' });

Метод rl.write() запишет данные в readline Interface в input как будто они были введены пользователем.

rl[Symbol.asyncIterator]()

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

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

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

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

Производительность не соответствует традиционному 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`.
  }
}

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

rl.line

• <строка> | <undefined>

Текущие обрабатываемые данные ввода, получаемые node.

Это можно использовать при сборе ввода из потока 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();
});

rl.cursor

• <число> | <undefined>

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

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

rl.getCursorPos()

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

Возвращает фактическое положение курсора относительно приглашения для ввода + строки. Длинные строки ввода (перенос) и многострочные приглашения включены в вычисления.

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

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

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

readline.clearScreenDown(stream[, callback])

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

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

readline.createInterface(options)

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

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

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

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

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

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

При создании экземпляра readline.Interface с использованием stdin в качестве входного потока программа не завершится, пока не получит EOF (Ctrl+D в Linux/macOS, Ctrl+Z за которым следует Возврат в Windows). Если вы хотите, чтобы ваша программа завершилась без ожидания пользовательского ввода, вы можете unref() стандартный поток ввода:

process.stdin.unref();

Использование функции completer

Функция completer принимает текущую строку, введённую пользователем, в качестве аргумента и возвращает массив Array с 2 элементами:

• Массив Array с совпадающими элементами для автодополнения.
• Подстрока, которая использовалась для сопоставления.

Например: [[substr1, substr2, ...], originalsubstring].

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];
}

Функция completer может вызываться асинхронно, если она принимает два аргумента:

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

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

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

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

readline.emitKeypressEvents(stream[, interface])

• stream <stream.Readable>
• interface <readline.Interface>

Метод readline.emitKeypressEvents() заставляет заданный поток Readable начать генерировать события 'keypress' соответствующие полученному вводу.

Необязательно, interface указывает экземпляр readline.Interface для которого автодополнение отключено при обнаружении вставленного ввода.

Если stream является TTY, то он должен быть в режиме raw.

Это автоматически вызывается любым экземпляром readline при его input если input является терминалом. Закрытие экземпляра readline не останавливает input от генерирования событий 'keypress'.

readline.emitKeypressEvents(process.stdin);
if (process.stdin.isTTY)
  process.stdin.setRawMode(true);

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

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

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

Пример: Tiny CLI

Следующий пример демонстрирует использование класса readline.Interface для реализации небольшого командного интерфейса:

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

rl.prompt();

rl.on('line', (line) => {
  switch (line.trim()) {
    case 'hello':
      console.log('world!');
      break;
    default:
      console.log(`Say what? I might have heard '${line.trim()}'`);
      break;
  }
  rl.prompt();
}).on('close', () => {
  console.log('Have a great day!');
  process.exit(0);
});

Пример: Чтение потока файла построчно

Часто используемым случаем для readline является потребление входного файла по одной строке за раз. Самый простой способ сделать это — использовать API fs.ReadStream, а также цикл for await...of.

const fs = require('fs');
const readline = require('readline');

async function processLineByLine() {
  const fileStream = fs.createReadStream('input.txt');

  const rl = readline.createInterface({
    input: fileStream,
    crlfDelay: Infinity
  });
  // Note: we use the crlfDelay option to recognize all instances of CR LF
  // ('\r\n') in input.txt as a single line break.

  for await (const line of rl) {
    // Each line in input.txt will be successively available here as `line`.
    console.log(`Line from file: ${line}`);
  }
}

processLineByLine();

В качестве альтернативы можно использовать событие 'line'.

const fs = require('fs');
const readline = require('readline');

const rl = readline.createInterface({
  input: fs.createReadStream('sample.txt'),
  crlfDelay: Infinity
});

rl.on('line', (line) => {
  console.log(`Line from file: ${line}`);
});

В настоящее время цикл for await...of может быть немного медленнее. Если async / await поток и скорость имеют первостепенное значение, можно применить смешанный подход.

const { once } = require('events');
const { createReadStream } = require('fs');
const { createInterface } = require('readline');

(async function processLineByLine() {
  try {
    const rl = createInterface({
      input: createReadStream('big-file.txt'),
      crlfDelay: Infinity
    });

    rl.on('line', (line) => {
      // Process the line.
    });

    await once(rl, 'close');

    console.log('File processed.');
  } catch (err) {
    console.error(err);
  }
})();

Сочетания клавиш для терминала