Readline

Модуль readline предоставляет интерфейс для чтения данных из потока Readable (например, из process.stdin) по одной строке за раз. К нему можно обратиться с помощью:

const readline = require('readline');

Следующий простой пример демонстрирует основное использование модуля readline.

const readline = require('readline');

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

rl.question('What do you think of Node.js? ', (answer) => {
  // TODO: Log the answer in a database
  console.log(`Thank you for your valuable feedback: ${answer}`);

  rl.close();
});

Примечание После вызова этого кода приложение Node.js не завершится до тех пор, пока поток readline.Interface не будет закрыт, так как интерфейс ожидает получения данных из потока input.

Класс: Интерфейс

Экземпляры класса readline.Interface создаются с помощью метода readline.createInterface(). Каждый экземпляр связан с одним потоком input Readable и одним потоком output 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(1).

Если поток 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(1), события '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.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> Текст или вопрос для записи в output, добавленный перед приглашением.
• callback <Функция> Функция-обработчик, которая вызывается с вводом пользователя в ответ на 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 <строка>

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

rl.write(data[, key])

• data <строка>
• key <Объект>
  • ctrl <булево> true для указания <ctrl> ключа.
  • meta <булево> true для указания <Meta> ключа.
  • shift <булево> true для указания <Shift> ключа.
  • name <строка> Название ключа.

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

readline.clearLine(stream, dir)

• stream <stream.Writable>
• dir <число>
  • -1 - влево от курсора
  • 1 - вправо от курсора
  • 0 - вся строка

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

readline.clearScreenDown(stream)

• stream <stream.Writable>

Метод 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. По умолчанию 30. Этот параметр имеет смысл только если terminal установлен в true пользователем или внутренним проверочным output механизмом, в противном случае механизм кэширования истории не инициализируется.
  • prompt - строка приглашения. По умолчанию: '> '
  • crlfDelay <число> Если задержка между \r и \n превышает crlfDelay миллисекунд, \r и \n будут обрабатываться как отдельные входные данные конца строки. По умолчанию 100 миллисекунд. crlfDelay будет приведено к числу не меньше 100. Может быть установлено в Infinity, в таком случае \r и за ним \n всегда будут считаться одной новой строкой.
  • removeHistoryDuplicates <булево> Если true, когда новая строка ввода добавляется в список истории и дублирует старую, эта старая строка удаляется из списка. По умолчанию false.

Метод 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).

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

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

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

Например: [[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)

• stream <stream.Writable>
• x <число>
• y <число>

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

readline.emitKeypressEvents(stream[, interface])

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

Метод readline.emitKeypressEvents() заставляет заданный читаемый поток Readable stream начать испускание событий '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)

• stream <stream.Writable>
• dx <число>
• dy <число>

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

Пример: Мини-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 — потребление ввода из потока Readable файла по одной строке за раз, как показано в следующем примере:

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

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

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