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 `iojs` 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 io.js 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 iojs="env NODE_NO_READLINE=1 rlwrap iojs"
32 The built-in repl (invoked by running `iojs` or `iojs -i`) may be controlled
33 via the following environment variables:
35 - `NODE_REPL_HISTORY_FILE` - if given, must be a path to a user-writable,
36 user-readable file. When a valid path is given, persistent history support
37 is enabled: REPL history will persist across `iojs` repl sessions.
38 - `NODE_REPL_HISTORY_SIZE` - defaults to `1000`. In conjunction with
39 `NODE_REPL_HISTORY_FILE`, controls how many lines of history will be
40 persisted. Must be a positive number.
41 - `NODE_REPL_MODE` - may be any of `sloppy`, `strict`, or `magic`. Defaults
42 to `magic`, which will automatically run "strict mode only" statements in
45 ## repl.start(options)
47 Returns and starts a `REPLServer` instance, that inherits from
48 [Readline Interface][]. Accepts an "options" Object that takes
51 - `prompt` - the prompt and `stream` for all I/O. Defaults to `> `.
53 - `input` - the readable stream to listen to. Defaults to `process.stdin`.
55 - `output` - the writable stream to write readline data to. Defaults to
58 - `terminal` - pass `true` if the `stream` should be treated like a TTY, and
59 have ANSI/VT100 escape codes written to it. Defaults to checking `isTTY`
60 on the `output` stream upon instantiation.
62 - `eval` - function that will be used to eval each given line. Defaults to
63 an async wrapper for `eval()`. See below for an example of a custom `eval`.
65 - `useColors` - a boolean which specifies whether or not the `writer` function
66 should output colors. If a different `writer` function is set then this does
67 nothing. Defaults to the repl's `terminal` value.
69 - `useGlobal` - if set to `true`, then the repl will use the `global` object,
70 instead of running scripts in a separate context. Defaults to `false`.
72 - `ignoreUndefined` - if set to `true`, then the repl will not output the
73 return value of command if it's `undefined`. Defaults to `false`.
75 - `writer` - the function to invoke for each command that gets evaluated which
76 returns the formatting (including coloring) to display. Defaults to
79 - `replMode` - controls whether the repl runs all commands in strict mode,
80 default mode, or a hybrid mode ("magic" mode.) Acceptable values are:
81 * `repl.REPL_MODE_SLOPPY` - run commands in sloppy mode.
82 * `repl.REPL_MODE_STRICT` - run commands in strict mode. This is equivalent to
83 prefacing every repl statement with `'use strict'`.
84 * `repl.REPL_MODE_MAGIC` - attempt to run commands in default mode. If they
85 fail to parse, re-try in strict mode.
87 You can use your own `eval` function if it has following signature:
89 function eval(cmd, context, filename, callback) {
90 callback(null, result);
93 Multiple REPLs may be started against the same running instance of io.js. Each
94 will share the same global object but will have unique I/O.
96 Here is an example that starts a REPL on stdin, a Unix socket, and a TCP socket:
98 var net = require("net"),
99 repl = require("repl");
104 prompt: "io.js via stdin> ",
105 input: process.stdin,
106 output: process.stdout
109 net.createServer(function (socket) {
112 prompt: "io.js via Unix socket> ",
115 }).on('exit', function() {
118 }).listen("/tmp/iojs-repl-sock");
120 net.createServer(function (socket) {
123 prompt: "io.js via TCP socket> ",
126 }).on('exit', function() {
131 Running this program from the command line will start a REPL on stdin. Other
132 REPL clients may connect through the Unix socket or TCP socket. `telnet` is useful
133 for connecting to TCP sockets, and `socat` can be used to connect to both Unix and
136 By starting a REPL from a Unix socket-based server instead of stdin, you can
137 connect to a long-running io.js process without restarting it.
139 For an example of running a "full-featured" (`terminal`) REPL over
140 a `net.Server` and `net.Socket` instance, see: https://gist.github.com/2209310
142 For an example of running a REPL instance over `curl(1)`,
143 see: https://gist.github.com/2053342
149 Emitted when the user exits the REPL in any of the defined ways. Namely, typing
150 `.exit` at the repl, pressing Ctrl+C twice to signal SIGINT, or pressing Ctrl+D
151 to signal "end" on the `input` stream.
153 Example of listening for `exit`:
155 r.on('exit', function () {
156 console.log('Got "exit" event from repl!');
163 `function (context) {}`
165 Emitted when the REPL's context is reset. This happens when you type `.clear`.
166 If you start the repl with `{ useGlobal: true }` then this event will never
169 Example of listening for `reset`:
171 // Extend the initial repl context.
172 r = repl.start({ options ... });
173 someExtension.extend(r.context);
175 // When a new context is created extend it as well.
176 r.on('reset', function (context) {
177 console.log('repl has a new context');
178 someExtension.extend(context);
186 Inside the REPL, Control+D will exit. Multi-line expressions can be input.
187 Tab completion is supported for both global and local variables.
189 Core modules will be loaded on-demand into the environment. For example,
190 accessing `fs` will `require()` the `fs` module as `global.fs`.
192 The special variable `_` (underscore) contains the result of the last expression.
201 The REPL provides access to any variables in the global scope. You can expose
202 a variable to the REPL explicitly by assigning it to the `context` object
203 associated with each `REPLServer`. For example:
206 var repl = require("repl"),
209 repl.start("> ").context.m = msg;
211 Things in the `context` object appear as local within the REPL:
213 mjr:~$ iojs repl_test.js
217 There are a few special REPL commands:
219 - `.break` - While inputting a multi-line expression, sometimes you get lost
220 or just don't care about completing it. `.break` will start over.
221 - `.clear` - Resets the `context` object to an empty object and clears any
222 multi-line expression.
223 - `.exit` - Close the I/O stream, which will cause the REPL to exit.
224 - `.help` - Show this list of special commands.
225 - `.save` - Save the current REPL session to a file
226 >.save ./file/to/save.js
227 - `.load` - Load a file into the current REPL session.
228 >.load ./file/to/load.js
230 The following key combinations in the REPL have these special effects:
232 - `<ctrl>C` - Similar to the `.break` keyword. Terminates the current
233 command. Press twice on a blank line to forcibly exit.
234 - `<ctrl>D` - Similar to the `.exit` keyword.