Table of Contents

• REPL

  • Design and Features

    • Commands and Special Keys

    • Default Evaluation

      • JavaScript Expressions
      • Global and Local Scope
      • Accessing Core Node.js Modules
      • Global Uncaught Exceptions
      • Assignment of the _ (underscore) variable
      • await keyword

    • Custom Evaluation Functions

      • Recoverable Errors
    • Customizing REPL Output

  • Class: REPLServer

    • Event: 'exit'
    • Event: 'reset'
    • replServer.defineCommand(keyword, cmd)
    • replServer.displayPrompt([preserveCursor])
    • replServer.clearBufferedCommand()
    • replServer.parseREPLKeyword(keyword[, rest])
    • replServer.setupHistory(historyPath, callback)
  • repl.start([options])

  • The Node.js REPL

    • Environment Variable Options
    • Persistent History
    • Using the Node.js REPL with advanced line-editors
    • Starting multiple REPL instances against a single running instance

REPL#

The repl module provides a Read-Eval-Print-Loop (REPL) implementation that is available both as a standalone program or includible in other applications. It can be accessed using:

const repl = require('repl');

Design and Features#

The repl module exports the repl.REPLServer class. While running, instances of repl.REPLServer will accept individual lines of user input, evaluate those according to a user-defined evaluation function, then output the result. Input and output may be from stdin and stdout, respectively, or may be connected to any Node.js stream.

Instances of repl.REPLServer support automatic completion of inputs, simplistic Emacs-style line editing, multi-line inputs, ANSI-styled output, saving and restoring current REPL session state, error recovery, and customizable evaluation functions.

Commands and Special Keys#

The following special commands are supported by all REPL instances:

• .break - When in the process of inputting a multi-line expression, entering the .break command (or pressing the <ctrl>-C key combination) will abort further input or processing of that expression.
• .clear - Resets the REPL context to an empty object and clears any multi-line expression currently being input.
• .exit - Close the I/O stream, causing the REPL to exit.
• .help - Show this list of special commands.
• .save - Save the current REPL session to a file: > .save ./file/to/save.js
• .load - Load a file into the current REPL session. > .load ./file/to/load.js
• .editor - Enter editor mode (<ctrl>-D to finish, <ctrl>-C to cancel).

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

The following key combinations in the REPL have these special effects:

• <ctrl>-C - When pressed once, has the same effect as the .break command. When pressed twice on a blank line, has the same effect as the .exit command.
• <ctrl>-D - Has the same effect as the .exit command.
• <tab> - When pressed on a blank line, displays global and local (scope) variables. When pressed while entering other input, displays relevant autocompletion options.

Default Evaluation#

By default, all instances of repl.REPLServer use an evaluation function that evaluates JavaScript expressions and provides access to Node.js' built-in modules. This default behavior can be overridden by passing in an alternative evaluation function when the repl.REPLServer instance is created.

JavaScript Expressions#

The default evaluator supports direct evaluation of JavaScript expressions:

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

Unless otherwise scoped within blocks or functions, variables declared either implicitly or using the const, let, or var keywords are declared at the global scope.

Global and Local Scope#

The default evaluator provides access to any variables that exist in the global scope. It is possible to expose a variable to the REPL explicitly by assigning it to the context object associated with each REPLServer:

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

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

Properties in the context object appear as local within the REPL:

$ node repl_test.js
> m
'message'

Context properties are not read-only by default. To specify read-only globals, context properties must be defined using Object.defineProperty():

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

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

Accessing Core Node.js Modules#

The default evaluator will automatically load Node.js core modules into the REPL environment when used. For instance, unless otherwise declared as a global or scoped variable, the input fs will be evaluated on-demand as global.fs = require('fs').

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

Global Uncaught Exceptions#

The REPL uses the domain module to catch all uncaught exceptions for that REPL session.

This use of the domain module in the REPL has these side effects:

• Uncaught exceptions do not emit the 'uncaughtException' event.
• Trying to use process.setUncaughtExceptionCaptureCallback() throws an ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE error.

Assignment of the _ (underscore) variable#

The default evaluator will, by default, assign the result of the most recently evaluated expression to the special variable _ (underscore). Explicitly setting _ to a value will disable this behavior.

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

Similarly, _error will refer to the last seen error, if there was any. Explicitly setting _error to a value will disable this behavior.

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

await keyword#