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 на экземпляре 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.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, запрос не будет выведен.

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

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.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.

Если 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 <number>
  • -1 - влево от курсора
  • 1 - вправо от курсора
  • 0 - вся строка

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

readline.clearScreenDown(stream)

• stream <stream.Writable>

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

Метод 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 <number>
• dy <number>

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

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

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

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