repl: exports Recoverable

Allow REPL consumers to callback with a `Recoverable` error instance and trigger multi-line REPL prompts. Fixes: #2939 PR-URL: #3488 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]>

Author: blakeembrey

doc/api/repl.md

@@ -262,8 +262,10 @@ the following values:
  have ANSI/VT100 escape codes written to it. Defaults to checking `isTTY`
  on the `output` stream upon instantiation.
 
--`eval` - function that will be used to eval each given line. Defaults to
- an async wrapper for `eval()`. See below for an example of a custom `eval`.
+-`eval` - a function that will be used to eval each given line. Defaults to
+ an async wrapper for `eval()`. An `eval` function can error with
+`repl.Recoverable` to indicate the code was incomplete and prompt for more
+ lines. See below for an example of a custom `eval`.
 
 -`useColors` - a boolean which specifies whether or not the `writer` function
  should output colors. If a different `writer` function is set then this does
@@ -287,11 +289,28 @@ the following values:
 *`repl.REPL_MODE_MAGIC` - attempt to run commands in default mode. If they
  fail to parse, re-try in strict mode.
 
-You can use your own`eval` function if it has following signature:
+It is possible to use a custom`eval` function as illustrated below:
 
-function eval(cmd, context, filename, callback){
- callback(null, result);
+```js
+functioneval(cmd, context, filename, callback){
+var result;
+try{
+ result =vm.runInThisContext(cmd);
+ } catch (e){
+if (isRecoverableError(e)){
+returncallback(newrepl.Recoverable(e));
  }
+ }
+callback(null, result);
+}
+
+functionisRecoverableError(error){
+if (error.name==='SyntaxError'){
+return/^(Unexpected end of input|Unexpected token)/.test(error.message);
+ }
+returnfalse;
+}
+```
 
 On tab completion, `eval` will be called with `.scope` as an input string. It
 is expected to return an array of scope names to be used for the auto-completion.

lib/repl.js

@@ -1177,3 +1177,4 @@ function Recoverable(err){
 this.err=err;
 }
 inherits(Recoverable,SyntaxError);
+exports.Recoverable=Recoverable;

test/parallel/test-repl-recoverable.js

@@ -0,0 +1,40 @@
+'use strict';
+
+constcommon=require('../common');
+constassert=require('assert');
+constrepl=require('repl');
+
+letevalCount=0;
+letrecovered=false;
+letrendered=false;
+
+functioncustomEval(code,context,file,cb){
+evalCount++;
+
+returncb(evalCount===1 ? newrepl.Recoverable() : null,true);
+}
+
+constputIn=newcommon.ArrayStream();
+
+putIn.write=function(msg){
+if(msg==='... '){
+recovered=true;
+}
+
+if(msg==='true\n'){
+rendered=true;
+}
+};
+
+repl.start('',putIn,customEval);
+
+// https://github.com/nodejs/node/issues/2939
+// Expose recoverable errors to the consumer.
+putIn.emit('data','1\n');
+putIn.emit('data','2\n');
+
+process.on('exit',function(){
+assert(recovered,'REPL never recovered');
+assert(rendered,'REPL never rendered the result');
+assert.strictEqual(evalCount,2);
+});