readline: document emitKeypressEvents()

doc/api/readline.markdown

@@ -354,6 +354,11 @@ a `'resize'` event on the `output` if/when the columns ever change
 
 Move cursor to the specified position in a given TTY stream.
 
+## readline.emitKeypressEvents(stream)
+
+Causes `stream` to begin emitting `'keypress'` events corresponding to its
+input.
+
 ## readline.moveCursor(stream, dx, dy)
 
 Move cursor relative to it's current position in a given TTY stream.

lib/internal/readline.js

@@ -384,9 +384,8 @@ function* emitKeys(stream) {
       stream.emit('keypress', escaped ? undefined : s, key);
     } else if (s.length === 1) {
       /* Single unnamed character, e.g. "." */
-      stream.emit('keypress', s);
-    } else {
-      /* Unrecognized or broken escape sequence, don't emit anything */
+      stream.emit('keypress', s, key);
     }
+    /* Unrecognized or broken escape sequence, don't emit anything */
   }
 }

test/parallel/test-readline-emit-keypress-events.js

@@ -0,0 +1,30 @@
+'use strict';
+// emitKeypressEvents is thoroughly tested in test-readline-keys.js.
+// However, that test calls it implicitly. This is just a quick sanity check
+// to verify that it works when called explicitly.
+
+require('../common');
+const assert = require('assert');
+const readline = require('readline');
+const PassThrough = require('stream').PassThrough;
+const stream = new PassThrough();
+const sequence = [];
+const keys = [];
+
+readline.emitKeypressEvents(stream);
+
+stream.on('keypress', (s, k) => {
+  sequence.push(s);
+  keys.push(k);
+});
+
+stream.write('foo');
+
+process.on('exit', () => {
+  assert.deepStrictEqual(sequence, ['f', 'o', 'o']);
+  assert.deepStrictEqual(keys, [
+    { sequence: 'f', name: 'f', ctrl: false, meta: false, shift: false },
+    { sequence: 'o', name: 'o', ctrl: false, meta: false, shift: false },
+    { sequence: 'o', name: 'o', ctrl: false, meta: false, shift: false }
+  ]);
+});

test/parallel/test-readline-keys.js

@@ -48,7 +48,7 @@ function addTest(sequences, expectedKeys) {
 addTest('io.JS', [
   { name: 'i', sequence: 'i' },
   { name: 'o', sequence: 'o' },
-  undefined, // emitted as `emit('keypress', '.', undefined)`
+  { name: undefined, sequence: '.' },
   { name: 'j', sequence: 'J', shift: true },
   { name: 's', sequence: 'S', shift: true },
 ]);