5 A Read-Eval-Print-Loop (REPL) is available both as a standalone program and
6 easily includable in other programs. The REPL provides a way to interactively
7 run JavaScript and see the results. It can be used for debugging, testing, or
8 just trying things out.
10 By executing `node` without any arguments from the command-line you will be
11 dropped into the REPL. It has simplistic emacs line-editing.
14 Type '.help' for options.
17 > a.forEach(function (v) {
24 For advanced line-editors, start node with the environmental variable
25 `NODE_NO_READLINE=1`. This will start the main and debugger REPL in canonical
26 terminal settings which will allow you to use with `rlwrap`.
28 For example, you could add this to your bashrc file:
30 alias node="env NODE_NO_READLINE=1 rlwrap node"
33 ## repl.start(options)
35 Returns and starts a `REPLServer` instance. Accepts an "options" Object that
36 takes the following values:
38 - `prompt` - the prompt and `stream` for all I/O. Defaults to `> `.
40 - `input` - the readable stream to listen to. Defaults to `process.stdin`.
42 - `output` - the writable stream to write readline data to. Defaults to
45 - `terminal` - pass `true` if the `stream` should be treated like a TTY, and
46 have ANSI/VT100 escape codes written to it. Defaults to checking `isTTY`
47 on the `output` stream upon instantiation.
49 - `eval` - function that will be used to eval each given line. Defaults to
50 an async wrapper for `eval()`. See below for an example of a custom `eval`.
52 - `useColors` - a boolean which specifies whether or not the `writer` function
53 should output colors. If a different `writer` function is set then this does
54 nothing. Defaults to the repl's `terminal` value.
56 - `useGlobal` - if set to `true`, then the repl will use the `global` object,
57 instead of running scripts in a separate context. Defaults to `false`.
59 - `ignoreUndefined` - if set to `true`, then the repl will not output the
60 return value of command if it's `undefined`. Defaults to `false`.
62 - `writer` - the function to invoke for each command that gets evaluated which
63 returns the formatting (including coloring) to display. Defaults to
66 You can use your own `eval` function if it has following signature:
68 function eval(cmd, context, filename, callback) {
69 callback(null, result);
72 Multiple REPLs may be started against the same running instance of node. Each
73 will share the same global object but will have unique I/O.
75 Here is an example that starts a REPL on stdin, a Unix socket, and a TCP socket:
77 var net = require("net"),
78 repl = require("repl");
83 prompt: "node via stdin> ",
85 output: process.stdout
88 net.createServer(function (socket) {
91 prompt: "node via Unix socket> ",
94 }).on('exit', function() {
97 }).listen("/tmp/node-repl-sock");
99 net.createServer(function (socket) {
102 prompt: "node via TCP socket> ",
105 }).on('exit', function() {
110 Running this program from the command line will start a REPL on stdin. Other
111 REPL clients may connect through the Unix socket or TCP socket. `telnet` is useful
112 for connecting to TCP sockets, and `socat` can be used to connect to both Unix and
115 By starting a REPL from a Unix socket-based server instead of stdin, you can
116 connect to a long-running node process without restarting it.
118 For an example of running a "full-featured" (`terminal`) REPL over
119 a `net.Server` and `net.Socket` instance, see: https://gist.github.com/2209310
121 For an example of running a REPL instance over `curl(1)`,
122 see: https://gist.github.com/2053342
128 Emitted when the user exits the REPL in any of the defined ways. Namely, typing
129 `.exit` at the repl, pressing Ctrl+C twice to signal SIGINT, or pressing Ctrl+D
130 to signal "end" on the `input` stream.
132 Example of listening for `exit`:
134 r.on('exit', function () {
135 console.log('Got "exit" event from repl!');
142 `function (context) {}`
144 Emitted when the REPL's context is reset. This happens when you type `.clear`.
145 If you start the repl with `{ useGlobal: true }` then this event will never
148 Example of listening for `reset`:
150 // Extend the initial repl context.
151 r = repl.start({ options ... });
152 someExtension.extend(r.context);
154 // When a new context is created extend it as well.
155 r.on('reset', function (context) {
156 console.log('repl has a new context');
157 someExtension.extend(context);
165 Inside the REPL, Control+D will exit. Multi-line expressions can be input.
166 Tab completion is supported for both global and local variables.
168 The special variable `_` (underscore) contains the result of the last expression.
177 The REPL provides access to any variables in the global scope. You can expose
178 a variable to the REPL explicitly by assigning it to the `context` object
179 associated with each `REPLServer`. For example:
182 var repl = require("repl"),
185 repl.start("> ").context.m = msg;
187 Things in the `context` object appear as local within the REPL:
189 mjr:~$ node repl_test.js
193 There are a few special REPL commands:
195 - `.break` - While inputting a multi-line expression, sometimes you get lost
196 or just don't care about completing it. `.break` will start over.
197 - `.clear` - Resets the `context` object to an empty object and clears any
198 multi-line expression.
199 - `.exit` - Close the I/O stream, which will cause the REPL to exit.
200 - `.help` - Show this list of special commands.
201 - `.save` - Save the current REPL session to a file
202 >.save ./file/to/save.js
203 - `.load` - Load a file into the current REPL session.
204 >.load ./file/to/load.js
206 The following key combinations in the REPL have these special effects:
208 - `<ctrl>C` - Similar to the `.break` keyword. Terminates the current
209 command. Press twice on a blank line to forcibly exit.
210 - `<ctrl>D` - Similar to the `.exit` keyword.