From 766506a2e947b297926e046051841eae78705b92 Mon Sep 17 00:00:00 2001
From: Lance Ball <lball@redhat.com>
Date: Thu, 13 Jul 2017 14:17:33 -0400
Subject: [PATCH] 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: https://github.com/nodejs/node/pull/14223
Refs: https://github.com/nodejs/node/issues/7619
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
---
 doc/api/deprecations.md                 |  8 +++++++
 doc/api/repl.md                         | 14 +++++++++++
 lib/repl.js                             | 32 ++++++++++++-------------
 test/parallel/test-repl-deprecations.js | 16 +++++++++++++
 4 files changed, 53 insertions(+), 17 deletions(-)
 create mode 100644 test/parallel/test-repl-deprecations.js

diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index f6c51217e0eae3..c34f4e04d97923 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -653,6 +653,14 @@ Type: Runtime
 The `REPLServer.bufferedCommand` property was deprecated in favor of
 [`REPLServer.clearBufferedCommand()`][].
 
+<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
diff --git a/doc/api/repl.md b/doc/api/repl.md
index 7a9c1f81e56309..4ed95f61116b11 100644
--- a/doc/api/repl.md
+++ b/doc/api/repl.md
@@ -385,6 +385,20 @@ 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
diff --git a/lib/repl.js b/lib/repl.js
index 00d1172c36ecc3..4a5bc8637b7aeb 100644
--- a/lib/repl.js
+++ b/lib/repl.js
@@ -374,6 +374,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');
   });
@@ -434,7 +448,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[kBufferedCommandSymbol]) {
@@ -1064,22 +1078,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 };
diff --git a/test/parallel/test-repl-deprecations.js b/test/parallel/test-repl-deprecations.js
new file mode 100644
index 00000000000000..c2a97ad7aca8ed
--- /dev/null
+++ b/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();
+}