repl: docs-only deprecation of magic mode

Author: TimothyGu

doc/api/deprecations.md

@@ -534,6 +534,20 @@ deprecated. Please use `ServerResponse.prototype.writeHead()` instead.
 *Note*: The `ServerResponse.prototype.writeHeader()` method was never documented
 as an officially supported API.
 
+<a id="DEP00XX"></a>
+### DEP00XX: repl.REPL_MODE_MAGIC and NODE_REPL_MODE=magic
+
+Type: Documentation-only
+
+The `repl` module's `REPL_MODE_MAGIC` constant, used for `replMode` option, has
+been deprecated. Its behavior has been functionally identical to that of
+`REPL_MODE_SLOPPY` since Node.js v6.0.0, when V8 5.0 was imported. Please use
+`REPL_MODE_SLOPPY` instead.
+
+The `NODE_REPL_MODE` environment variable is used to set the underlying
+`replMode` of an interactive `node` session. Its default value, `magic`, is
+similarly deprecated in favor of `sloppy`.
+
 [alloc]: buffer.html#buffer_class_method_buffer_alloc_size_fill_encoding
 [alloc_unsafe_size]: buffer.html#buffer_class_method_buffer_allocunsafe_size
 [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size

doc/api/repl.md

@@ -408,14 +408,15 @@ changes:
      command before writing to `output`. Defaults to [`util.inspect()`][].
   * `completer` {Function} An optional function used for custom Tab auto
      completion. See [`readline.InterfaceCompleter`][] for an example.
-  * `replMode` - A flag that specifies whether the default evaluator executes
-    all JavaScript commands in strict mode, default mode, or a hybrid mode
-    ("magic" mode.) Acceptable values are:
+  * `replMode` {symbol} A flag that specifies whether the default evaluator
+    executes all JavaScript commands in strict mode or default (sloppy) mode.
+    Acceptable values are:
     * `repl.REPL_MODE_SLOPPY` - evaluates expressions in sloppy mode.
     * `repl.REPL_MODE_STRICT` - evaluates expressions in strict mode. This is
       equivalent to prefacing every repl statement with `'use strict'`.
-    * `repl.REPL_MODE_MAGIC` - attempt to evaluates expressions in default
-      mode.  If expressions fail to parse, re-try in strict mode.
+    * `repl.REPL_MODE_MAGIC` - This value is **deprecated**, since enhanced
+      spec compliance in V8 has rendered magic mode unnecessary. It is now
+      equivalent to `repl.REPL_MODE_SLOPPY` (documented above).
   * `breakEvalOnSigint` - Stop evaluating the current piece of code when
     `SIGINT` is received, i.e. `Ctrl+C` is pressed. This cannot be used together
     with a custom `eval` function. Defaults to `false`.
@@ -461,8 +462,8 @@ environment variables:
  - `NODE_REPL_HISTORY_SIZE` - Defaults to `1000`. Controls how many lines of
    history will be persisted if history is available. Must be a positive number.
  - `NODE_REPL_MODE` - May be any of `sloppy`, `strict`, or `magic`. Defaults
-   to `magic`, which will automatically run "strict mode only" statements in
-   strict mode.
+   to `sloppy`, which will allow non-strict mode code to be run. `magic` is
+   **deprecated** and treated as an alias of `sloppy`.
 
 ### Persistent History
 

lib/internal/repl.js

@@ -39,12 +39,11 @@ function createRepl(env, opts, cb) {
 
   opts.replMode = {
     'strict': REPL.REPL_MODE_STRICT,
-    'sloppy': REPL.REPL_MODE_SLOPPY,
-    'magic': REPL.REPL_MODE_MAGIC
+    'sloppy': REPL.REPL_MODE_SLOPPY
   }[String(env.NODE_REPL_MODE).toLowerCase().trim()];
 
   if (opts.replMode === undefined) {
-    opts.replMode = REPL.REPL_MODE_MAGIC;
+    opts.replMode = REPL.REPL_MODE_SLOPPY;
   }
 
   const historySize = Number(env.NODE_REPL_HISTORY_SIZE);

lib/repl.js

@@ -633,7 +633,7 @@ exports.REPLServer = REPLServer;
 
 exports.REPL_MODE_SLOPPY = Symbol('repl-sloppy');
 exports.REPL_MODE_STRICT = Symbol('repl-strict');
-exports.REPL_MODE_MAGIC = Symbol('repl-magic');
+exports.REPL_MODE_MAGIC = exports.REPL_MODE_SLOPPY;
 
 // prompt is a string to print on each line for the prompt,
 // source is a stream to use for I/O, defaulting to stdin/stdout.