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

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

• .break: При вводе многострочного выражения введите команду .break (или нажмите Ctrl+C), чтобы отменить дальнейший ввод или обработку этого выражения.
• .clear: Сбрасывает context REPL в пустой объект и очищает вводимое многострочное выражение.
• .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.

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

import repl from 'node:repl';
const msg = 'message';

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

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

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

$ node repl_test.js
> m
'message' copy

import repl from 'node:repl';
const msg = 'message';

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

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

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

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

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

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

> 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

> const m = await Promise.resolve(123)
undefined
> m
123
> m = await Promise.resolve(234)
234
// redeclaring the constant does error
> const m = await Promise.resolve(345)
Uncaught SyntaxError: Identifier 'm' has already been declared copy

Обратный поиск

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

Повторяющиеся записи истории пропускаются.

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

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

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

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

Функция вычисления принимает следующие четыре аргумента:

• code <string> Код для выполнения (например, 1 + 1).
• context <Object> Контекст, в котором выполняется код. Это может быть контекст JavaScript global или контекст, специфичный для экземпляра REPL, в зависимости от параметра useGlobal.
• replResourceName <string> Идентификатор ресурса REPL, связанного с текущим вычислением кода. Может быть полезен для отладки.
• callback <Function> Функция, вызываемая после завершения вычисления кода. Функция обратного вызова принимает два параметра:
  • Объект ошибки, передаваемый в случае возникновения ошибки при вычислении, или null/undefined, если ошибки не произошло.
  • Результат вычисления кода (не имеет значения, если передана ошибка).

В следующем примере показан REPL, который возводит заданное число в квадрат; если введённое значение не является числом, вместо этого выводится ошибка:

import repl from 'node:repl';

function byThePowerOfTwo(number) {
  return number * number;
}

function myEval(code, context, replResourceName, callback) {
  if (isNaN(code)) {
    callback(new Error(`${code.trim()} is not a number`));
  } else {
    callback(null, byThePowerOfTwo(code));
  }
}

repl.start({ prompt: 'Enter a number: ', eval: myEval });

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

function byThePowerOfTwo(number) {
  return number * number;
}

function myEval(code, context, replResourceName, callback) {
  if (isNaN(code)) {
    callback(new Error(`${code.trim()} is not a number`));
  } else {
    callback(null, byThePowerOfTwo(code));
  }
}

repl.start({ prompt: 'Enter a number: ', eval: myEval });

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 при создании. Например, в следующем примере любой введённый текст просто преобразуется в верхний регистр:

import repl from '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();
}

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();
}

Событие: '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 в заранее определённое состояние:

import repl from 'node:repl';

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

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

r.on('reset', initializeContext);

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

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

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

r.on('reset', initializeContext);

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

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

replServer.defineCommand(keyword, cmd)

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

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

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

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

import repl from '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();
});

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();
});

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

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

replServer.displayPrompt([preserveCursor])

• preserveCursor <boolean>

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

Во время ввода многострочных данных вместо «приглашения» выводится символ канала '|'.

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

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

replServer.clearBufferedCommand()

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

replServer.setupHistory(historyConfig, callback)

• historyConfig <Object> | <string> путь к файлу истории. Если это строка, она задаёт путь к файлу истории. Если это объект, он может содержать следующие свойства:
  • filePath <string> путь к файлу истории
  • size <number> Максимальное количество сохраняемых строк истории. Чтобы отключить историю, задайте этому значению 0. Этот параметр имеет смысл только в том случае, если пользователь или внутренняя проверка output установили terminal в значение true; в противном случае механизм кэширования истории вообще не инициализируется. По умолчанию: 30.
  • removeHistoryDuplicates <boolean> Если значение true, при добавлении в список истории новой строки ввода, дублирующей более раннюю, старая строка удаляется из списка. По умолчанию: false.
  • onHistoryFileLoaded <Function> вызывается, когда запись истории готова или произошла ошибка
    • err <Error>
    • repl <repl.REPLServer>
• callback <Function> вызывается, когда запись истории готова или произошла ошибка (необязательный параметр, если указан как onHistoryFileLoaded в historyConfig)
  • err <Error>
  • repl <repl.REPLServer>

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

Параметры переменных окружения

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

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

Сохранение истории

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

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

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

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

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

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

Можно создать и запустить несколько экземпляров REPL в одном запущенном экземпляре Node.js, которые будут использовать один объект global (задав для параметра useGlobal значение true), но иметь отдельные интерфейсы ввода-вывода.

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

import net from 'node:net';
import repl from 'node:repl';
import process from 'node:process';
import fs from 'node:fs';

let connections = 0;

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

const unixSocketPath = '/tmp/node-repl-sock';

// If the socket file already exists let's remove it
fs.rmSync(unixSocketPath, { force: true });

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

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

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

let connections = 0;

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

const unixSocketPath = '/tmp/node-repl-sock';

// If the socket file already exists let's remove it
fs.rmSync(unixSocketPath, { force: true });

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

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

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

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

Примеры

// repl-server.js
import repl from 'node:repl';
import net from 'node:net';

net
  .createServer((socket) => {
    const r = repl.start({
      prompt: `socket ${socket.remoteAddress}:${socket.remotePort}> `,
      input: socket,
      output: socket,
      terminal: true,
      useGlobal: false,
    });
    r.on('exit', () => {
      socket.end();
    });
    r.context.socket = socket;
  })
  .listen(1337);

// repl-server.js
const repl = require('node:repl');
const net = require('node:net');

net
  .createServer((socket) => {
    const r = repl.start({
      prompt: `socket ${socket.remoteAddress}:${socket.remotePort}> `,
      input: socket,
      output: socket,
      terminal: true,
      useGlobal: false,
    });
    r.on('exit', () => {
      socket.end();
    });
    r.context.socket = socket;
  })
  .listen(1337);

// repl-client.js
import net from 'node:net';
import process from 'node:process';

const sock = net.connect(1337);

process.stdin.pipe(sock);
sock.pipe(process.stdout);

sock.on('connect', () => {
  process.stdin.resume();
  process.stdin.setRawMode(true);
});

sock.on('close', () => {
  process.stdin.setRawMode(false);
  process.stdin.pause();
  sock.removeListener('close', done);
});

process.stdin.on('end', () => {
  sock.destroy();
  console.log();
});

process.stdin.on('data', (b) => {
  if (b.length === 1 && b[0] === 4) {
    process.stdin.emit('end');
  }
});

// repl-client.js
const net = require('node:net');

const sock = net.connect(1337);

process.stdin.pipe(sock);
sock.pipe(process.stdout);

sock.on('connect', () => {
  process.stdin.resume();
  process.stdin.setRawMode(true);
});

sock.on('close', () => {
  process.stdin.setRawMode(false);
  process.stdin.pause();
  sock.removeListener('close', done);
});

process.stdin.on('end', () => {
  sock.destroy();
  console.log();
});

process.stdin.on('data', (b) => {
  if (b.length === 1 && b[0] === 4) {
    process.stdin.emit('end');
  }
});

import http from 'node:http';
import repl from 'node:repl';

const server = http.createServer((req, res) => {
  res.setHeader('content-type', 'multipart/octet-stream');

  repl.start({
    prompt: 'curl repl> ',
    input: req,
    output: res,
    terminal: false,
    useColors: true,
    useGlobal: false,
  });
});

server.listen(8000);

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

const server = http.createServer((req, res) => {
  res.setHeader('content-type', 'multipart/octet-stream');

  repl.start({
    prompt: 'curl repl> ',
    input: req,
    output: res,
    terminal: false,
    useColors: true,
    useGlobal: false,
  });
});

server.listen(8000);