repl: deprecate REPLServer.parseREPLKeyword

This method does not need to be visible to user code. It has been
undocumented since it was introduced which was perhaps v0.8.9.

The motivation for this change is that the method is simply an
implementation detail of the REPLServer behavior, and does
not need to be exposed to user code.

This change adds documentation of the method with a deprecation
warning, and a test that the method is actually documented.

PR-RUL: #14223
Refs: #7619
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

doc/api/deprecations.md

@@ -663,6 +663,14 @@ function for [`util.inspect()`][] is deprecated. Use [`util.inspect.custom`][]
 instead. For backwards compatibility with Node.js prior to version 6.4.0, both
 may be specified.
 
+<a id="DEP0075"></a>
+### DEP0075: REPLServer.parseREPLKeyword()
+
+Type: Runtime
+
+`REPLServer.parseREPLKeyword()` was removed from userland visibility.
+
+
 [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
 [`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array
 [`Buffer.from(buffer)`]: buffer.html#buffer_class_method_buffer_from_buffer

doc/api/repl.md

@@ -377,6 +377,30 @@ The `replServer.displayPrompt` method is primarily intended to be called from
 within the action function for commands registered using the
 `replServer.defineCommand()` method.
 
+### replServer.clearBufferedCommand()
+<!-- YAML
+added: REPLACEME
+-->
+
+The `replServer.clearBufferedComand()` method clears any command that has been
+buffered but not yet executed. This method is primarily intended to be
+called from within the action function for commands registered using the
+`replServer.defineCommand()` method.
+
+### replServer.parseREPLKeyword(keyword, [rest])
+<!-- YAML
+added: v0.8.9
+deprecated: REPLACEME
+-->
+
+* `keyword` {string} the potential keyword to parse and execute
+* `rest` {any} any parameters to the keyword command
+
+> Stability: 0 - Deprecated.
+
+An internal method used to parse and execute `REPLServer` keywords.
+Returns `true` if `keyword` is a valid keyword, otherwise `false`.
+
 ## repl.start([options])
 <!-- YAML
 added: v0.1.91

lib/repl.js

@@ -365,6 +365,20 @@ function REPLServer(prompt,
     };
   }
 
+  function _parseREPLKeyword(keyword, rest) {
+    var cmd = this.commands[keyword];
+    if (cmd) {
+      cmd.action.call(this, rest);
+      return true;
+    }
+    return false;
+  }
+
+  self.parseREPLKeyword = util.deprecate(
+    _parseREPLKeyword,
+    'REPLServer.parseREPLKeyword() is deprecated',
+    'DEP0075');
+
   self.on('close', function emitExit() {
     self.emit('exit');
   });
@@ -424,7 +438,7 @@ function REPLServer(prompt,
         const matches = trimmedCmd.match(/^\.([^\s]+)\s*(.*)$/);
         const keyword = matches && matches[1];
         const rest = matches && matches[2];
-        if (self.parseREPLKeyword(keyword, rest) === true) {
+        if (_parseREPLKeyword.call(self, keyword, rest) === true) {
           return;
         }
         if (!self.bufferedCommand) {
@@ -1050,22 +1064,6 @@ REPLServer.prototype.completeOnEditorMode = (callback) => (err, results) => {
   callback(null, [[`${completeOn}${longestCommonPrefix(data)}`], completeOn]);
 };
 
-/**
- * Used to parse and execute the Node REPL commands.
- *
- * @param {keyword} keyword The command entered to check.
- * @return {Boolean} If true it means don't continue parsing the command.
- */
-REPLServer.prototype.parseREPLKeyword = function(keyword, rest) {
-  var cmd = this.commands[keyword];
-  if (cmd) {
-    cmd.action.call(this, rest);
-    return true;
-  }
-  return false;
-};
-
-
 REPLServer.prototype.defineCommand = function(keyword, cmd) {
   if (typeof cmd === 'function') {
     cmd = { action: cmd };

test/parallel/test-repl-deprecations.js

@@ -0,0 +1,16 @@
+'use strict';
+const common = require('../common');
+const assert = require('assert');
+const repl = require('repl');
+
+testParseREPLKeyword();
+
+function testParseREPLKeyword() {
+  const server = repl.start({ prompt: '> ' });
+  const warn = 'REPLServer.parseREPLKeyword() is deprecated';
+
+  common.expectWarning('DeprecationWarning', warn);
+  assert.ok(server.parseREPLKeyword('clear'));
+  assert.ok(!server.parseREPLKeyword('tacos'));
+  server.close();
+}