```js

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)

```js

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

```js

> 1 + 1

undefined

> m + 1

3

```

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`. For example:

```js

const repl = require('repl');

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

```

```js

$ node repl_test.js

> m

'message'

```

It is important to note that context properties are *not* read-only by default.

To specify read-only globals, context properties must be defined using

`Object.defineProperty()`:

```js

const repl = require('repl');

configurable: false,

enumerable: true,

value: msg

});

```

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')`.

```js

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

```

The default evaluator will, by default, assign the result of the most recently

evaluated expression to the special variable `_` (underscore).

> [ 'a', 'b', 'c' ]

[ 'a', 'b', 'c' ]

> _.length

3

> _ += 1

Expression assignment to _ now disabled.

4

> 1 + 1

2

> _

4

```

### Custom Evaluation Functions

When a new `repl.REPLServer` is created, a custom evaluation function may be

provided. This can be used, for instance, to implement fully customized REPL

applications.

The following illustrates a hypothetical example of a REPL that performs

translation of text from one language to another:

```js

const repl = require('repl');

function myEval(cmd, context, filename, callback) {

callback(null, myTranslator.translate(cmd));

}

As a user is typing input into the REPL prompt, pressing the `<enter>` key will

send the current line of input to the `eval` function. In order to support

multi-line input, the eval function can return an instance of `repl.Recoverable`

to the provided callback function:

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;

}

```

By default, `repl.REPLServer` instances format output using the

[`util.inspect()`][] method before writing the output to the provided Writable

stream (`process.stdout` by default). The `useColors` boolean option can be

specified at construction to instruct the default writer to use ANSI style

codes to colorize the output from the `util.inspect()` method.

It is possible to fully customize the output of a `repl.REPLServer` instance

by passing a new function in using the `writer` option on construction. The

following example, for instance, simply converts any input text to upper case:

```js

const repl = require('repl');

function myWriter(output) {

return output.toUpperCase();

}

<!-- YAML

added: v0.1.91

-->

The `repl.REPLServer` class inherits from the [`readline.Interface`][] class.

Instances of `repl.REPLServer` are created using the `repl.start()` method and

*should not* be created directly using the JavaScript `new` keyword.

### Event: 'exit'

<!-- YAML

added: v0.7.7

-->

The `'exit'` event is emitted when the REPL is exited either by receiving the

`.exit` command as input, the user pressing `<ctrl>-C` twice to signal `SIGINT`,

or by pressing `<ctrl>-D` to signal `'end'` on the input stream. The listener

callback is invoked without any arguments.

```js

replServer.on('exit', () => {

process.exit();

});

```

### Event: 'reset'

<!-- YAML

added: v0.11.0

-->

The `'reset'` event is emitted when the REPL's context is reset. This occurs

whenever the `.clear` command is received as input *unless* the REPL is using

the default evaluator and the `repl.REPLServer` instance was created with the

`useGlobal` option set to `true`. The listener callback will be called with a

reference to the `context` object as the only argument.

This can be used primarily to re-initialize REPL context to some pre-defined

state as illustrated in the following simple example:

```js

const repl = require('repl');

function initializeContext(context) {

context.m = 'test';

}

initializeContext(r.context);

r.on('reset', initializeContext);

```

When this code is executed, the global `'m'` variable can be modified but then

reset to its initial value using the `.clear` command:

'test'

>

### replServer.defineCommand(keyword, cmd)

<!-- YAML

added: v0.3.0

-->

The `replServer.defineCommand()` method is used to add new `.`-prefixed commands

to the REPL instance. Such commands are invoked by typing a `.` followed by the

`keyword`. The `cmd` is either a Function or an object with the following

properties:

* `action` {Function} The function to execute, optionally accepting a single

string argument.

```js

const repl = require('repl');

replServer.defineCommand('sayhello', {

help: 'Say hello',

this.lineParser.reset();

this.bufferedCommand = '';

this.displayPrompt();

}

});

this.close();

});

> .sayhello Node.js User

Hello, Node.js User!

> .saybye

Goodbye!

### replServer.displayPrompt([preserveCursor])

<!-- YAML

added: v0.1.91

-->

The `replServer.displayPrompt()` method readies the REPL instance for input

from the user, printing the configured `prompt` to a new line in the `output`

and resuming the `input` to accept new input.

When multi-line input is being entered, an ellipsis is printed rather than the

'prompt'.

When `preserveCursor` is `true`, the cursor placement will not be reset to `0`.

The `replServer.displayPrompt` method is primarily intended to be called from

within the action function for commands registered using the

`replServer.defineCommand()` method.

<!-- YAML

added: v0.1.91

changes:

- version: v5.8.0

pr-url: https://github.com/nodejs/node/pull/5388

description: The `options` parameter is optional now.

* `input` {Readable} The Readable stream from which REPL input will be read.

Defaults to `process.stdin`.

* `output` {Writable} The Writable stream to which REPL output will be

written. Defaults to `process.stdout`.

* `terminal` {boolean} If `true`, specifies that the `output` should be

treated as a a TTY terminal, and have ANSI/VT100 escape codes written to it.

Defaults to checking the value of the `isTTY` property on the `output`

stream upon instantiation.

* `eval` {Function} The function to be used when evaluating each given line

of input. Defaults to an async wrapper for the JavaScript `eval()`

function. An `eval` function can error with `repl.Recoverable` to indicate

the input was incomplete and prompt for additional lines.

* `useColors` {boolean} If `true`, specifies that the default `writer`

function should include ANSI color styling to REPL output. If a custom

`writer` function is provided then this has no effect. Defaults to the

REPL instances `terminal` value.

* `useGlobal` {boolean} If `true`, specifies that the default evaluation

function will use the JavaScript `global` as the context as opposed to

creating a new separate context for the REPL instance. Defaults to `false`.

* `ignoreUndefined` {boolean} If `true`, specifies that the default writer

will not output the return value of a command if it evaluates to

`undefined`. Defaults to `false`.

* `writer` {Function} The function to invoke to format the output of each

command before writing to `output`. Defaults to [`util.inspect()`][].

* `completer` {Function} An optional function used for custom Tab auto

completion. See [`readline.InterfaceCompleter`][] for an example.

* `replMode` {symbol} A flag that specifies whether the default evaluator

executes all JavaScript commands in strict mode or default (sloppy) mode.

Acceptable values are:

* `repl.REPL_MODE_SLOPPY` - evaluates expressions in sloppy mode.

* `repl.REPL_MODE_STRICT` - evaluates expressions in strict mode. This is

equivalent to prefacing every repl statement with `'use strict'`.

* `repl.REPL_MODE_MAGIC` - This value is **deprecated**, since enhanced

spec compliance in V8 has rendered magic mode unnecessary. It is now

equivalent to `repl.REPL_MODE_SLOPPY` (documented above).

* `breakEvalOnSigint` - Stop evaluating the current piece of code when

`SIGINT` is received, i.e. `Ctrl+C` is pressed. This cannot be used together

with a custom `eval` function. Defaults to `false`.

The `repl.start()` method creates and starts a `repl.REPLServer` instance.

If `options` is a string, then it specifies the input prompt:

```js

const repl = require('repl');

// a Unix style prompt

repl.start('$ ');

```

## The Node.js REPL

Node.js itself uses the `repl` module to provide its own interactive interface

for executing JavaScript. This can be used by executing the Node.js binary

without passing any arguments (or by passing the `-i` argument):

```js

$ node

[ 1, 2, 3 ]

> a.forEach((v) => {

... console.log(v);

... });

1

2