Описание и возможности

Модуль node:repl экспортирует класс repl.REPLServer. Во время работы экземпляры класса repl.REPLServer принимают отдельные строки пользовательского ввода, обрабатывают их в соответствии с определенной пользователем функцией вычисления и выводят результат. Ввод и вывод могут происходить из stdin и stdout, соответственно, или могут быть подключены к любому потоку Node.js stream.

Экземпляры repl.REPLServer поддерживают автоматическое дополнение ввода, предварительный просмотр дополнений, простую редактирование строк в стиле Emacs, многострочный ввод, поиск по истории в стиле ZSH, поиск по подстрокам в истории в стиле ZSH, вывод в формате ANSI, сохранение и восстановление текущего состояния REPL, восстановление после ошибок и настраиваемые функции вычисления. Терминалы, которые не поддерживают стили ANSI и редактирование строк в стиле Emacs, автоматически переключаются на ограниченный набор функций.

Команды и специальные клавиши

Следующие специальные команды поддерживаются всеми экземплярами REPL:

• .break: При вводе многострочного выражения, используйте команду .break (или нажмите Ctrl+C), чтобы прервать ввод или обработку выражения.
• .clear: Сбрасывает состояние REPL context до пустого объекта и очищает любой многострочный ввод.
• .exit: Закрывает поток ввода-вывода, что приводит к выходу REPL.
• .help: Показать этот список специальных команд.
• .save: Сохранить текущее состояние сессии REPL в файл: > .save ./file/to/save.js
• .load: Загрузить файл в текущую сессию REPL. > .load ./file/to/load.js
• .editor: Перейти в режим редактора (Ctrl+D для завершения, Ctrl+C для отмены).

> .editor
// Entering editor mode (^D to finish, ^C to cancel)
function welcome(name) {
  return `Hello ${name}!`;
}

welcome('Node.js User');

// ^D
'Hello Node.js User!'
> copy

Следующие сочетания клавиш в REPL имеют следующие специальные эффекты:

• Ctrl+C: При нажатии один раз имеет тот же эффект, что и команда .break. При двойном нажатии на пустой строке имеет тот же эффект, что и команда .exit.
• Ctrl+D: Имеет тот же эффект, что и команда .exit.
• Tab: При нажатии на пустой строке отображает глобальные и локальные переменные (области видимости). При нажатии во время ввода других данных отображает соответствующие варианты автозаполнения.

Связанные с поиском по истории сочетания клавиш см. в разделе reverse-i-search. Все остальные сочетания клавиш см. в разделе Сочетания клавиш для TTY.

По умолчанию

По умолчанию все экземпляры repl.REPLServer используют функцию вычисления, которая оценивает выражения JavaScript и предоставляет доступ к встроенным модулям Node.js. Это поведение по умолчанию может быть переопределено путем передачи альтернативной функции вычисления при создании экземпляра repl.REPLServer.

Выражения JavaScript

По умолчанию интерпретатор поддерживает прямое вычисление выражений JavaScript:

> 1 + 1
2
> const m = 2
undefined
> m + 1
3 copy

Если не указано иное в блоках или функциях, переменные, объявленные явно или с помощью ключевых слов const, let, или var, объявляются на глобальном уровне.

Глобальная и локальная область видимости

По умолчанию интерпретатор предоставляет доступ ко всем переменным, существующим в глобальной области видимости. Можно явно предоставить переменную REPL, назначив ее объекту context, связанному с каждым экземпляром REPLServer:

const repl = require('node:repl');
const msg = 'message';

repl.start('> ').context.m = msg; copy

Свойства объекта context отображаются как локальные в REPL:

$ node repl_test.js
> m
'message' copy

Свойства контекста по умолчанию не являются только для чтения. Для указания глобальных значений только для чтения свойства контекста должны быть определены с использованием Object.defineProperty():

const repl = require('node:repl');
const msg = 'message';

const r = repl.start('> ');
Object.defineProperty(r.context, 'm', {
  configurable: false,
  enumerable: true,
  value: msg,
}); copy

Доступ к основным модулям Node.js

По умолчанию интерпретатор автоматически загружает основные модули Node.js в среду REPL при использовании. Например, выражение fs будет вычисляться по требованию как global.fs = require('node:fs').

> fs.createReadStream('./some/file'); copy

Глобальные непредвиденные исключения

REPL использует модуль domain для перехвата всех непредвиденных исключений для данной сессии REPL.

Это использование модуля domain в REPL имеет следующие побочные эффекты:

• Непредвиденные исключения генерируют только событие 'uncaughtException' в автономном REPL. Добавление обработчика этого события в REPL внутри другой программы Node.js приводит к ошибке ERR_INVALID_REPL_INPUT.

  const r = repl.start();
  
  r.write('process.on("uncaughtException", () => console.log("Foobar"));\n');
  // Output stream includes:
  //   TypeError [ERR_INVALID_REPL_INPUT]: Listeners for `uncaughtException`
  //   cannot be used in the REPL
  
  r.close(); copy

• Попытка использования process.setUncaughtExceptionCaptureCallback() генерирует ошибку ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE.

Назначение переменной _ (подчеркивание)

По умолчанию интерпретатор назначает результат последнего вычисленного выражения специальной переменной _ (подчеркивание). Явное присвоение значения переменной _ отключит это поведение.

> [ 'a', 'b', 'c' ]
[ 'a', 'b', 'c' ]
> _.length
3
> _ += 1
Expression assignment to _ now disabled.
4
> 1 + 1
2
> _
4 copy

Аналогично, _error будет ссылаться на последнюю ошибку, если таковая имела место. Явное присвоение значения переменной _error отключит это поведение.

> throw new Error('foo');
Uncaught Error: foo
> _error.message
'foo' copy

await ключевое слово

Поддержка ключевого слова await включена на верхнем уровне.

> await Promise.resolve(123)
123
> await Promise.reject(new Error('REPL await'))
Uncaught Error: REPL await
    at REPL2:1:54
> const timeout = util.promisify(setTimeout);
undefined
> const old = Date.now(); await timeout(1000); console.log(Date.now() - old);
1002
undefined copy

Одним из известных ограничений использования ключевого слова await в REPL является то, что оно аннулирует лексическое определение области видимости ключевых слов const и let.

Например:

> const m = await Promise.resolve(123)
undefined
> m
123
> const m = await Promise.resolve(234)
undefined
> m
234 copy

--no-experimental-repl-await отключит ожидаемый ввод на верхнем уровне в REPL.

Поиск по истории

REPL поддерживает двусторонний поиск по истории, аналогичный поиску в ZSH. Он запускается нажатием Ctrl+R для поиска назад и Ctrl+S для поиска вперед.

Дублированные записи в истории будут пропущены.

Записи принимаются, как только нажимается любая клавиша, не относящаяся к поиску по истории. Отмена возможна при нажатии Esc или Ctrl+C.

Изменение направления немедленно ищет следующую запись в ожидаемом направлении от текущей позиции.

Пользовательские функции вычисления

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

Ниже приведен гипотетический пример REPL, который выполняет перевод текста с одного языка на другой:

const repl = require('node:repl');
const { Translator } = require('translator');

const myTranslator = new Translator('en', 'fr');

function myEval(cmd, context, filename, callback) {
  callback(null, myTranslator.translate(cmd));
}

repl.start({ prompt: '> ', eval: myEval }); copy

Восстанавливаемые ошибки

В REPL при нажатии Enter текущая строка ввода отправляется функции eval. Для поддержки многострочного ввода функция eval может вернуть экземпляр repl.Recoverable предоставленной функции обратного вызова:

function myEval(cmd, context, filename, callback) {
  let result;
  try {
    result = vm.runInThisContext(cmd);
  } catch (e) {
    if (isRecoverableError(e)) {
      return callback(new repl.Recoverable(e));
    }
  }
  callback(null, result);
}

function isRecoverableError(error) {
  if (error.name === 'SyntaxError') {
    return /^(Unexpected end of input|Unexpected token)/.test(error.message);
  }
  return false;
} copy

Настройка вывода REPL

По умолчанию экземпляры repl.REPLServer форматируют вывод с помощью метода util.inspect() перед записью вывода в предоставленный поток Writable (по умолчанию process.stdout). Опция инспекции showProxy устанавливается по умолчанию в true, а опция colors устанавливается в true в зависимости от опции useColors REPL.

Логическое значение useColors может быть указано при создании, чтобы указать, что по умолчанию писатель должен использовать коды стиля ANSI для раскрашивания вывода метода util.inspect().

Если REPL запущен как автономная программа, можно также изменить значения по умолчанию для инспекции REPL изнутри REPL, используя свойство inspect.replDefaults, которое отражает значение defaultOptions из util.inspect().

> util.inspect.replDefaults.compact = false;
false
> [1]
[
  1
]
> copy

Для полной настройки вывода экземпляра repl.REPLServer передайте новую функцию для опции writer при создании. Например, следующий пример просто преобразует любой введенный текст в верхний регистр:

const repl = require('node:repl');

const r = repl.start({ prompt: '> ', eval: myEval, writer: myWriter });

function myEval(cmd, context, filename, callback) {
  callback(null, cmd);
}

function myWriter(output) {
  return output.toUpperCase();
} copy

Класс: REPLServer

• options <Объект> | <строка> См. repl.start()
• Расширяет: <readline.Interface>

Экземпляры repl.REPLServer создаются с помощью метода repl.start() или напрямую с помощью ключевого слова JavaScript new.

const repl = require('node:repl');

const options = { useColors: true };

const firstInstance = repl.start(options);
const secondInstance = new repl.REPLServer(options); copy

Событие: 'exit'

Событие 'exit' генерируется при выходе из REPL, либо путем ввода команды .exit, либо при двойном нажатии Ctrl+C для сигнализации о SIGINT, либо при нажатии Ctrl+D для сигнализации о 'end' в потоке ввода. Обработчик события вызывается без аргументов.

replServer.on('exit', () => {
  console.log('Received "exit" event from repl!');
  process.exit();
}); copy

Событие: 'reset'

Событие 'reset' генерируется при сбросе контекста REPL. Это происходит при вводе команды .clear, за исключением случаев, когда REPL использует стандартный оценщик и экземпляр repl.REPLServer был создан с параметром useGlobal установленным в значение true. Обработчик события будет вызван со ссылкой на объект context в качестве единственного аргумента.

Это может использоваться в основном для повторной инициализации контекста REPL до определенного предварительно заданного состояния:

const repl = require('node:repl');

function initializeContext(context) {
  context.m = 'test';
}

const r = repl.start({ prompt: '> ' });
initializeContext(r.context);

r.on('reset', initializeContext); copy

При выполнении этого кода глобальная переменная 'm' может быть изменена, а затем сброшена до начального значения с помощью команды .clear.

$ ./node example.js
> m
'test'
> m = 1
1
> m
1
> .clear
Clearing context...
> m
'test'
> copy

replServer.defineCommand(keyword, cmd)

• keyword <строка> Ключевое слово команды (без ведущего символа .).
• cmd <Объект> | <Функция> Функция, которая вызывается при обработке команды.

Метод replServer.defineCommand() используется для добавления новых команд, начинающихся с ., в экземпляр REPL. Такие команды вызываются вводом . за которым следует keyword. cmd — это либо Function, либо Object, с последующими свойствами:

• help <строка> Текст справки, который будет отображаться при вводе .help (Необязательно).
• action <Функция> Функция для выполнения, которая необязательно принимает один строковый аргумент.

Следующий пример демонстрирует добавление двух новых команд в экземпляр REPL:

const repl = require('node:repl');

const replServer = repl.start({ prompt: '> ' });
replServer.defineCommand('sayhello', {
  help: 'Say hello',
  action(name) {
    this.clearBufferedCommand();
    console.log(`Hello, ${name}!`);
    this.displayPrompt();
  },
});
replServer.defineCommand('saybye', function saybye() {
  console.log('Goodbye!');
  this.close();
}); copy

Новые команды затем могут быть использованы внутри экземпляра REPL:

> .sayhello Node.js User
Hello, Node.js User!
> .saybye
Goodbye! copy

replServer.displayPrompt([preserveCursor])

• preserveCursor <булево>

Метод replServer.displayPrompt() подготавливает экземпляр REPL для ввода от пользователя, печатает настроенный prompt на новой строке в output и возобновляет input для приема нового ввода.

При вводе многострочного ввода вместо «prompt» печатается многоточие.

Если preserveCursor равно true, позиция курсора не будет сброшена к значению 0.

Метод replServer.displayPrompt предназначен в первую очередь для вызова из функции действия команд, зарегистрированных с помощью метода replServer.defineCommand().

replServer.clearBufferedCommand()

Метод replServer.clearBufferedCommand() очищает любую команду, которая была в буфере, но еще не выполнена. Этот метод в первую очередь предназначен для вызова из функции действия команд, зарегистрированных с помощью метода replServer.defineCommand().

replServer.parseREPLKeyword(keyword[, rest])

• keyword <строка> потенциальное ключевое слово для разбора и выполнения
• rest <любое> любые параметры к команде ключевого слова
• Возвращает: <булево>

Внутренний метод для разбора и выполнения ключевых слов REPLServer. Возвращает true, если keyword является допустимым ключевым словом, в противном случае false.

replServer.setupHistory(historyPath, callback)

• historyPath <строка> путь к файлу истории
• callback <Функция> вызывается при готовности записи истории или при ошибке
  • err <Ошибка>
  • repl <repl.REPLServer>

Инициализирует файл журнала истории для экземпляра REPL. При выполнении бинарника Node.js и использовании REPL командной строки файл истории инициализируется по умолчанию. Однако этого не происходит при программном создании REPL. Используйте этот метод для инициализации файла журнала истории при работе с экземплярами REPL программно.

repl.builtinModules

• <массив строк>

Список имён всех модулей Node.js, например, 'http'.

repl.start([options])

• options <Объект> | <строка>
  • prompt <строка> Приглашение для ввода. По умолчанию: '> ' (с trailing пробелом).
  • input <stream.Readable> Поток Readable для чтения входных данных REPL. По умолчанию: process.stdin.
  • output <stream.Writable> Поток Writable для записи вывода REPL. По умолчанию: process.stdout.
  • terminal <логическое_значение> Если true, указывает, что output должен обрабатываться как терминал TTY. По умолчанию: проверка значения свойства isTTY в потоке output при создании.
  • eval <Функция> Функция для вычисления каждой строки ввода. По умолчанию: асинхронная обертка для JavaScript-функции eval() . Функция eval может возвращать ошибку repl.Recoverable для указания неполного ввода и запроса дополнительных строк.
  • useColors <логическое_значение> Если true, указывает, что функция по умолчанию writer должна включать форматирование ANSI-цветов для вывода REPL. Если предоставлена пользовательская функция writer, то это не имеет эффекта. По умолчанию: проверка поддержки цвета в потоке output если значение terminal экземпляра REPL равно true.
  • useGlobal <логическое_значение> Если true, указывает, что функция вычисления по умолчанию будет использовать JavaScript global в качестве контекста вместо создания нового отдельного контекста для экземпляра REPL. Node CLI REPL устанавливает это значение в true. По умолчанию: false.
  • ignoreUndefined <логическое_значение> Если true, указывает, что функция вывода по умолчанию не будет выводить результат команды, если он равен undefined. По умолчанию: false.
  • writer <Функция> Функция для форматирования вывода каждой команды перед записью в output. По умолчанию: util.inspect().
  • completer <Функция> Необязательная функция для пользовательской автодополнения Tab. См. readline.InterfaceCompleter для примера.
  • replMode <символ> Флаг, указывающий, выполняет ли функция вычисления по умолчанию все команды JavaScript в строгом режиме или по умолчанию (нестрогом). Допустимые значения:
    • repl.REPL_MODE_SLOPPY для вычисления выражений в нестрогом режиме.
    • repl.REPL_MODE_STRICT для вычисления выражений в строгом режиме. Это эквивалентно добавлению префикса 'use strict' к каждой строке REPL.
  • breakEvalOnSigint <логическое_значение> Останавливает вычисление текущего блока кода при получении SIGINT, например, при нажатии Ctrl+C. Не может использоваться вместе с пользовательской функцией eval. По умолчанию: false.
  • preview <логическое_значение> Определяет, будет ли REPL выводить подсказки автодополнения и предварительные просмотры вывода или нет. По умолчанию: true для функции вычисления по умолчанию и false в случае использования пользовательской функции вычисления. Если terminal ложно, то предварительные просмотры отсутствуют, и значение preview не имеет эффекта.
• Возвращает: <repl.REPLServer>

Метод repl.start() создает и запускает экземпляр repl.REPLServer.

Если options является строкой, то это указывает приглашение для ввода:

const repl = require('node:repl');

// a Unix style prompt
repl.start('$ '); copy

Интерактивная оболочка Node.js (REPL)

Сам Node.js использует модуль node:repl для предоставления собственного интерактивного интерфейса для выполнения JavaScript. Это можно сделать, выполнив бинарный файл Node.js без аргументов (или передав аргумент -i)

$ node
> const a = [1, 2, 3];
undefined
> a
[ 1, 2, 3 ]
> a.forEach((v) => {
...   console.log(v);
...   });
1
2
3 copy

Настройки переменных среды

Различные параметры поведения интерактивной оболочки Node.js (REPL) можно настроить с помощью следующих переменных среды:

• NODE_REPL_HISTORY: Если задан допустимый путь, постоянная история REPL будет сохранена в указанном файле вместо .node_repl_history в домашней директории пользователя. Установка этого значения в '' (пустая строка) отключит постоянную историю REPL. Пробелы в значении будут удалены. В Windows переменные среды с пустыми значениями недопустимы, поэтому установите это значение как один или несколько пробелов, чтобы отключить постоянную историю REPL.
• NODE_REPL_HISTORY_SIZE: Управляет тем, сколько строк истории будет сохранено, если история доступна. Должно быть положительным числом. По умолчанию: 1000.
• NODE_REPL_MODE: Может быть либо 'sloppy', либо 'strict'. По умолчанию: 'sloppy', что позволит запускать код в нестрогом режиме.

Постоянная история

По умолчанию интерактивная оболочка Node.js (REPL) сохранит историю между сеансами REPL, сохраняя ввод в файл .node_repl_history в домашней директории пользователя. Это можно отключить, установив переменную среды NODE_REPL_HISTORY=''.

Использование интерактивной оболочки Node.js (REPL) с расширенными редакторами строк

Для работы с расширенными редакторами строк запустите Node.js с переменной среды NODE_NO_READLINE=1. Это запустит основную и отладочную интерактивные оболочки (REPL) в стандартных терминальных настройках, что позволит использовать их с rlwrap.

Например, следующее можно добавить в файл .bashrc:

alias node="env NODE_NO_READLINE=1 rlwrap node" copy

Запуск нескольких экземпляров REPL на одном работающем экземпляре

Возможна создание и запуск нескольких экземпляров REPL на одном работающем экземпляре Node.js, которые используют один объект global, но имеют отдельные интерфейсы ввода-вывода.

Например, следующий пример предоставляет отдельные REPL на stdin, сокете Unix и сокете TCP:

const net = require('node:net');
const repl = require('node:repl');
let connections = 0;

repl.start({
  prompt: 'Node.js via stdin> ',
  input: process.stdin,
  output: process.stdout,
});

net.createServer((socket) => {
  connections += 1;
  repl.start({
    prompt: 'Node.js via Unix socket> ',
    input: socket,
    output: socket,
  }).on('exit', () => {
    socket.end();
  });
}).listen('/tmp/node-repl-sock');

net.createServer((socket) => {
  connections += 1;
  repl.start({
    prompt: 'Node.js via TCP socket> ',
    input: socket,
    output: socket,
  }).on('exit', () => {
    socket.end();
  });
}).listen(5001); copy

Запуск этого приложения из командной строки запустит REPL на стандартном потоке ввода. Другие клиенты REPL могут подключиться через сокет Unix или сокет TCP. telnet, например, полезен для подключения к сокетам TCP, в то время как socat можно использовать для подключения к сокетам Unix и TCP.

Запуская REPL из сервера на основе сокета Unix вместо стандартного потока ввода, можно подключиться к долгоработающему процессу Node.js без его перезапуска.

Для примера запуска "полноценного" (terminal) REPL по net.Server и экземпляру net.Socket, см.: https://gist.github.com/TooTallNate/2209310.

Для примера запуска экземпляра REPL по curl(1), см.: https://gist.github.com/TooTallNate/2053342.