Permalink
Browse files

Add docs for new REPL options and fill out description of commands.

  • Loading branch information...
1 parent 3510669 commit 39464b498fcd805d4e2d56861702ae4380f7dc71 @mranney mranney committed with ry Apr 16, 2010
Showing with 118 additions and 27 deletions.
  1. +117 −26 doc/api.markdown
  2. +1 −1 lib/repl.js
View
@@ -444,7 +444,7 @@ This will generate:
$ node process-2.js one two=three four
0: node
- 1: /Users/mjr/work/node_docs/data/v0.1.31/examples/process-2.js
+ 1: /Users/mjr/work/node/process-2.js
2: one
3: two=three
4: four
@@ -2239,38 +2239,129 @@ The unescape function used by `querystring.parse`, provided so that it could be
## REPL
A Read-Eval-Print-Loop is available both as a standalone program and easily
-includable in other programs.
+includable in other programs. REPL provides a way to interactively run
+JavaScript and see the results. It can be used for debugging, testing, or
+just trying things out.
The standalone REPL is called `node-repl` and is installed at
-`$PREFIX/bin/node-repl`. It's recommended to use it with the program
-`rlwrap` for a better user interface. I set
+`$PREFIX/bin/node-repl`.
- alias node-repl='rlwrap node-repl'
+ mjr:~$ /usr/local/bin/node-repl
+ Welcome to the Node.js REPL.
+ Enter ECMAScript at the prompt.
+ Tip 1: Use 'rlwrap node-repl' for a better interface
+ Tip 2: Type Control-D to exit.
+ Type '.help' for options.
+ node> a = [ 1, 2, 3];
+ [ 1, 2, 3 ]
+ node> a.forEach(function (v) {
+ ... sys.puts(v);
+ ... });
+ 1
+ 2
+ 3
-in my zsh configuration.
-Inside the REPL, Control+D will exit. The special variable `_` (underscore) contains the
-result of the last expression.
+### repl.start(prompt, stream)
-The library is called `/repl.js` and it can be used like this:
+Starts a REPL with `prompt` as the prompt and `stream` for all I/O. `pomrpt`
+is optional and defaults to `node> `. `stream` is optional and defaults to
+`process.openStdin()`.
- var sys = require('sys'),
- net = require('net'),
- repl = require('repl');
- nconnections = 0;
- net.createServer(function (c) {
- sys.error('Connection!');
- nconnections += 1;
- c.end();
- }).listen(5000);
- repl.start('simple tcp server> ');
-
-The repl provides access to any variables in the global scope. You can expose a variable
-to the repl explicitly by assigning it to the `repl.scope` object:
-
- var count = 5;
- repl.start();
- repl.scope.count = count;
+Multiple REPLs may be started against the same running instance of node. Each
+will share the same global object but will have unique I/O.
+
+Here is an example that starts a REPL on stdin, a Unix socket, and a TCP socket:
+
+ var sys = require("sys"),
+ net = require("net"),
+ repl = require("repl");
+
+ connections = 0;
+
+ repl.start("node via stdin> ");
+
+ net.createServer(function (socket) {
+ connections += 1;
+ repl.start("node via Unix socket> ", socket);
+ }).listen("/tmp/node-repl-sock");
+
+ net.createServer(function (socket) {
+ connections += 1;
+ repl.start("node via TCP socket> ", socket);
+ }).listen(5001);
+
+Running this program from the command line will start a REPL on stdin. Other
+REPL clients may connect through the Unix socket or TCP socket. `telnet` is useful
+for connecting to TCP sockets, and `socat` can be used to connect to both Unix and
+TCP sockets.
+
+By starting a REPL from a Unix socket-based server instead of stdin, you can
+connect to a long-running node process without restarting it.
+
+
+### readline support
+
+Interactive command history for REPL is available from external programs like `rlwrap`
+or `socat`. These programs are available from many Unix package managers.
+
+To start the standalone REPL with `rlwrap`:
+
+ rlwarp node-repl
+
+It might be convenient to use this alias in your shell configuration:
+
+ alias repl='rlwrap node-repl'
+
+Using `socat` to connect to a Unix socket:
+
+ socat READLINE UNIX-CONNECT:/tmp/node-repl-sock
+
+Using `socat` to connect to a TCP socket on localhost:
+
+ socat READLINE TCP-CONNECT:localhost:5001
+
+
+### REPL Features
+
+Inside the REPL, Control+D will exit. Multi-line expressions can be input.
+
+The special variable `_` (underscore) contains the result of the last expression.
+
+ node> [ "a", "b", "c" ]
+ [ 'a', 'b', 'c' ]
+ node> _.length
+ 3
+ node> _ += 1
+ 4
+
+The REPL provides access to any variables in the global scope. You can expose a variable
+to the REPL explicitly by assigning it to the `scope` object associated with each
+`REPLServer`. For example:
+
+ // repl_test.js
+ var repl = require("repl"),
+ message = "message";
+
+ repl.start().scope.m = message;
+
+Things in the `scope` object appear as local within the REPL:
+
+ mjr:~$ node repl_test.js
+ node> m
+ 'message'
+
+There are a few special REPL commands:
+
+ - `.break` - While inputting a multi-line expression, sometimes you get lost or just don't care
+ about completing it. `.break` will start over.
+
+ - `.clear` - Resets the `scope` object to an empty object and clears any multi-line expression.
+
+ - `.exit` - Close the I/O stream, which will cause the REPL to exit.
+
+ - `.help` - Show this list of special commands.
+
## Addons
View
@@ -111,7 +111,7 @@ REPLServer.prototype.parseREPLKeyword = function (cmd) {
self.displayPrompt();
return true;
case ".exit":
- self.stream.close();
+ self.stream.end();
return true;
case ".help":
self.stream.write(".break\tSometimes you get stuck in a place you can't get out... This will get you out.\n");

0 comments on commit 39464b4

Please sign in to comment.