doc/api/repl.markdown

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