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