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

Все экземпляры 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(historyPath, callback)

• historyPath <string> путь к файлу истории
• callback <Function> вызывается, когда запись истории готова или произошла ошибка
  • 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 в stdin. Другие клиенты REPL могут подключаться через сокет Unix или сокет TCP. Например, telnet удобно использовать для подключения к сокетам TCP, а socat можно использовать для подключения как к сокетам Unix, так и к сокетам TCP.

Запустив REPL на сервере, использующем сокет Unix, вместо stdin, можно подключиться к длительно работающему процессу 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);