doc/api/repl.markdown

   1 # REPL
   2
   3     Stability: 3 - Stable
   4
   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.
   9
  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.
  12
  13     mjr:~$ node
  14     Type '.help' for options.
  15     > a = [ 1, 2, 3];
  16     [ 1, 2, 3 ]
  17     > a.forEach(function (v) {
  18     ...   console.log(v);
  19     ...   });
  20     1
  21     2
  22     3
  23
  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`.
  27
  28 For example, you could add this to your bashrc file:
  29
  30     alias node="env NODE_NO_READLINE=1 rlwrap node"
  31
  32
  33 ## repl.start(options)
  34
  35 Returns and starts a `REPLServer` instance. Accepts an "options" Object that
  36 takes the following values:
  37
  38  - `prompt` - the prompt and `stream` for all I/O. Defaults to `> `.
  39
  40  - `input` - the readable stream to listen to. Defaults to `process.stdin`.
  41
  42  - `output` - the writable stream to write readline data to. Defaults to
  43    `process.stdout`.
  44
  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.
  48
  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`.
  51
  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.
  55
  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`.
  58
  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`.
  61
  62  - `writer` - the function to invoke for each command that gets evaluated which
  63    returns the formatting (including coloring) to display. Defaults to
  64    `util.inspect`.
  65
  66 You can use your own `eval` function if it has following signature:
  67
  68     function eval(cmd, context, filename, callback) {
  69       callback(null, result);
  70     }
  71
  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.
  74
  75 Here is an example that starts a REPL on stdin, a Unix socket, and a TCP socket:
  76
  77     var net = require("net"),
  78         repl = require("repl");
  79
  80     connections = 0;
  81
  82     repl.start({
  83       prompt: "node via stdin> ",
  84       input: process.stdin,
  85       output: process.stdout
  86     });
  87
  88     net.createServer(function (socket) {
  89       connections += 1;
  90       repl.start({
  91         prompt: "node via Unix socket> ",
  92         input: socket,
  93         output: socket
  94       }).on('exit', function() {
  95         socket.end();
  96       })
  97     }).listen("/tmp/node-repl-sock");
  98
  99     net.createServer(function (socket) {
 100       connections += 1;
 101       repl.start({
 102         prompt: "node via TCP socket> ",
 103         input: socket,
 104         output: socket
 105       }).on('exit', function() {
 106         socket.end();
 107       });
 108     }).listen(5001);
 109
 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
 113 TCP sockets.
 114
 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.
 117
 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
 120
 121 For an example of running a REPL instance over `curl(1)`,
 122 see: https://gist.github.com/2053342
 123
 124 ### Event: 'exit'
 125
 126 `function () {}`
 127
 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.
 131
 132 Example of listening for `exit`:
 133
 134     r.on('exit', function () {
 135       console.log('Got "exit" event from repl!');
 136       process.exit();
 137     });
 138
 139
 140 ### Event: 'reset'
 141
 142 `function (context) {}`
 143
 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
 146 be emitted.
 147
 148 Example of listening for `reset`:
 149
 150     // Extend the initial repl context.
 151     r = repl.start({ options ... });
 152     someExtension.extend(r.context);
 153
 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);
 158     });
 159
 160
 161 ## REPL Features
 162
 163 <!-- type=misc -->
 164
 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.
 167
 168 The special variable `_` (underscore) contains the result of the last expression.
 169
 170     > [ "a", "b", "c" ]
 171     [ 'a', 'b', 'c' ]
 172     > _.length
 173     3
 174     > _ += 1
 175     4
 176
 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:
 180
 181     // repl_test.js
 182     var repl = require("repl"),
 183         msg = "message";
 184
 185     repl.start("> ").context.m = msg;
 186
 187 Things in the `context` object appear as local within the REPL:
 188
 189     mjr:~$ node repl_test.js
 190     > m
 191     'message'
 192
 193 There are a few special REPL commands:
 194
 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
 205
 206 The following key combinations in the REPL have these special effects:
 207
 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.
 211