From 1640a2fc80fc2f268d87726ea50524249616ca88 Mon Sep 17 00:00:00 2001
From: Bryan English <bryan@bryanenglish.com>
Date: Tue, 10 Nov 2015 22:33:28 -0800
Subject: [PATCH] doc: repl: add defineComand and displayPrompt

Also some minor edits so the additions make sense.
---
 doc/api/repl.markdown | 62 ++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 55 insertions(+), 7 deletions(-)

diff --git a/doc/api/repl.markdown b/doc/api/repl.markdown
index f298266ccb5d73..55a77416ab09f4 100644
--- a/doc/api/repl.markdown
+++ b/doc/api/repl.markdown
@@ -138,10 +138,6 @@ and try to print `obj` in REPL, it will invoke the custom `inspect()` function:
     > obj
     { bar: 'baz' }
 
-[Readline Interface]: readline.html#readline_class_interface
-[util.inspect()]: util.html#util_util_inspect_object_options
-[here]: util.html#util_custom_inspect_function_on_objects
-
 ## repl.start(options)
 
 Returns and starts a `REPLServer` instance, that inherits from
@@ -244,6 +240,10 @@ a `net.Server` and `net.Socket` instance, see: https://gist.github.com/2209310
 For an example of running a REPL instance over `curl(1)`,
 see: https://gist.github.com/2053342
 
+## Class: REPLServer
+
+This inherits from [Readline Interface][] with the following events:
+
 ### Event: 'exit'
 
 `function () {}`
@@ -254,7 +254,7 @@ to signal "end" on the `input` stream.
 
 Example of listening for `exit`:
 
-    r.on('exit', function () {
+    replServer.on('exit', function () {
       console.log('Got "exit" event from repl!');
       process.exit();
     });
@@ -271,11 +271,59 @@ be emitted.
 Example of listening for `reset`:
 
     // Extend the initial repl context.
-    var r = repl.start({ options ... });
+    var replServer = repl.start({ options ... });
     someExtension.extend(r.context);
 
     // When a new context is created extend it as well.
-    r.on('reset', function (context) {
+    replServer.on('reset', function (context) {
       console.log('repl has a new context');
       someExtension.extend(context);
     });
+
+### replServer.defineCommand(keyword, cmd)
+
+* `keyword` {String}
+* `cmd` {Object|Function}
+
+Makes a command available in the REPL. The command is invoked by typing a `.`
+followed by the keyword. The `cmd` is an object with the following values:
+
+ - `help` - help text to be displayed when `.help` is entered (Optional).
+ - `action` - a function to execute, potentially taking in a string argument,
+   when the command is invoked, bound to the REPLServer instance (Required).
+
+If a function is provided instead of an object for `cmd`, it is treated as the
+`action`.
+
+Example of defining a command:
+
+    // repl_test.js
+    var repl = require('repl');
+
+    var replServer = repl.start();
+    replServer.defineCommand('sayhello', {
+      help: 'Say hello',
+      action: function(name) {
+        this.write('Hello, ' + name + '!\n');
+        this.displayPrompt();
+      }
+    });
+
+Example of invoking that command from the REPL:
+
+    > .sayhello Node.js User
+    Hello, Node.js User!
+
+### replServer.displayPrompt([preserveCursor])
+
+* `preserveCursor` {Boolean}
+
+Like [readline.prompt][] except also adding indents with ellipses when inside
+blocks. The `preserveCursor` argument is passed to [readline.prompt][]. This is
+used primarily with `defineCommand`. It's also used internally to render each
+prompt line.
+
+[Readline Interface]: readline.html#readline_class_interface
+[readline.prompt]: readline.html#readline_rl_prompt_preservecursor
+[util.inspect()]: util.html#util_util_inspect_object_options
+[here]: util.html#util_custom_inspect_function_on_objects