Skip to content

Commit

Permalink
repl: implement reverse search
Browse files Browse the repository at this point in the history
Add a reverse search that works similar to the ZSH one. It is
triggered with <ctrl> + r and <ctrl> + s. It skips duplicated history
entries and works with multiline statements. Matching entries indicate
the search parameter with an underscore and cancelling with <ctrl> + c
or escape brings back the original line.
Multiple matches in a single history entry work as well and are
matched in the order of the current search direction. The cursor is
positioned at the current match position of the history entry.
Changing the direction immediately checks for the next entry in the
expected direction from the current position on.
Entries are accepted as soon any button is pressed that doesn't
correspond with the reverse search.
The behavior is deactivated for simple terminals. They do not support
most ANSI escape codes that are necessary for this feature.

PR-URL: #31006
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: Anto Aravinth <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
  • Loading branch information
BridgeAR committed Jan 3, 2020
1 parent 925dd8e commit 09ca8be
Show file tree
Hide file tree
Showing 7 changed files with 652 additions and 13 deletions.
27 changes: 24 additions & 3 deletions doc/api/repl.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,11 @@ result. Input and output may be from `stdin` and `stdout`, respectively, or may
be connected to any Node.js [stream][].

Instances of [`repl.REPLServer`][] support automatic completion of inputs,
simplistic Emacs-style line editing, multi-line inputs, ANSI-styled output,
saving and restoring current REPL session state, error recovery, and
customizable evaluation functions.
completion preview, simplistic Emacs-style line editing, multi-line inputs,
[ZSH][] like reverse-i-search, ANSI-styled output, saving and restoring current
REPL session state, error recovery, and customizable evaluation functions.
Terminals that do not support ANSI-styles and Emacs-style line editing
automatically fall back to a limited feature set.

### Commands and Special Keys

Expand Down Expand Up @@ -232,6 +234,24 @@ undefined
undefined
```

### Reverse-i-search
<!-- YAML
added: REPLACEME
-->

The REPL supports bi-directional reverse-i-search similar to [ZSH][]. It is
triggered with `<ctrl> + R` to search backwards and `<ctrl> + S` to search
forwards.

Duplicated history entires will be skipped.

Entries are accepted as soon as any button is pressed that doesn't correspond
with the reverse search. Cancelling is possible by pressing `escape` or
`<ctrl> + C`.

Changing the direction immediately searches for the next entry in the expected
direction from the current position on.

### Custom Evaluation Functions

When a new [`repl.REPLServer`][] is created, a custom evaluation function may be
Expand Down Expand Up @@ -695,6 +715,7 @@ a `net.Server` and `net.Socket` instance, see:
For an example of running a REPL instance over [curl(1)][], see:
<https://gist.github.com/TooTallNate/2053342>.

[ZSH]: https://en.wikipedia.org/wiki/Z_shell
[`'uncaughtException'`]: process.html#process_event_uncaughtexception
[`--experimental-repl-await`]: cli.html#cli_experimental_repl_await
[`ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE`]: errors.html#errors_err_domain_cannot_set_uncaught_exception_capture
Expand Down
245 changes: 243 additions & 2 deletions lib/internal/repl/utils.js
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ const {

const {
clearLine,
clearScreenDown,
cursorTo,
moveCursor,
} = require('readline');
Expand All @@ -42,7 +43,13 @@ const inspectOptions = {
compact: true,
breakLength: Infinity
};
const inspectedOptions = inspect(inspectOptions, { colors: false });
// Specify options that might change the output in a way that it's not a valid
// stringified object anymore.
const inspectedOptions = inspect(inspectOptions, {
depth: 1,
colors: false,
showHidden: false
});

// If the error is that we've unexpectedly ended the input,
// then let the user try to recover by adding more input.
Expand Down Expand Up @@ -393,8 +400,242 @@ function setupPreview(repl, contextSymbol, bufferSymbol, active) {
return { showPreview, clearPreview };
}

function setupReverseSearch(repl) {
// Simple terminals can't use reverse search.
if (process.env.TERM === 'dumb') {
return { reverseSearch() { return false; } };
}

const alreadyMatched = new Set();
const labels = {
r: 'bck-i-search: ',
s: 'fwd-i-search: '
};
let isInReverseSearch = false;
let historyIndex = -1;
let input = '';
let cursor = -1;
let dir = 'r';
let lastMatch = -1;
let lastCursor = -1;
let promptPos;

function checkAndSetDirectionKey(keyName) {
if (!labels[keyName]) {
return false;
}
if (dir !== keyName) {
// Reset the already matched set in case the direction is changed. That
// way it's possible to find those entries again.
alreadyMatched.clear();
}
dir = keyName;
return true;
}

function goToNextHistoryIndex() {
// Ignore this entry for further searches and continue to the next
// history entry.
alreadyMatched.add(repl.history[historyIndex]);
historyIndex += dir === 'r' ? 1 : -1;
cursor = -1;
}

function search() {
// Just print an empty line in case the user removed the search parameter.
if (input === '') {
print(repl.line, `${labels[dir]}_`);
return;
}
// Fix the bounds in case the direction has changed in the meanwhile.
if (dir === 'r') {
if (historyIndex < 0) {
historyIndex = 0;
}
} else if (historyIndex >= repl.history.length) {
historyIndex = repl.history.length - 1;
}
// Check the history entries until a match is found.
while (historyIndex >= 0 && historyIndex < repl.history.length) {
let entry = repl.history[historyIndex];
// Visualize all potential matches only once.
if (alreadyMatched.has(entry)) {
historyIndex += dir === 'r' ? 1 : -1;
continue;
}
// Match the next entry either from the start or from the end, depending
// on the current direction.
if (dir === 'r') {
// Update the cursor in case it's necessary.
if (cursor === -1) {
cursor = entry.length;
}
cursor = entry.lastIndexOf(input, cursor - 1);
} else {
cursor = entry.indexOf(input, cursor + 1);
}
// Match not found.
if (cursor === -1) {
goToNextHistoryIndex();
// Match found.
} else {
if (repl.useColors) {
const start = entry.slice(0, cursor);
const end = entry.slice(cursor + input.length);
entry = `${start}\x1B[4m${input}\x1B[24m${end}`;
}
print(entry, `${labels[dir]}${input}_`, cursor);
lastMatch = historyIndex;
lastCursor = cursor;
// Explicitly go to the next history item in case no further matches are
// possible with the current entry.
if ((dir === 'r' && cursor === 0) ||
(dir === 's' && entry.length === cursor + input.length)) {
goToNextHistoryIndex();
}
return;
}
}
print(repl.line, `failed-${labels[dir]}${input}_`);
}

function print(outputLine, inputLine, cursor = repl.cursor) {
// TODO(BridgeAR): Resizing the terminal window hides the overlay. To fix
// that, readline must be aware of this information. It's probably best to
// add a couple of properties to readline that allow to do the following:
// 1. Add arbitrary data to the end of the current line while not counting
// towards the line. This would be useful for the completion previews.
// 2. Add arbitrary extra lines that do not count towards the regular line.
// This would be useful for both, the input preview and the reverse
// search. It might be combined with the first part?
// 3. Add arbitrary input that is "on top" of the current line. That is
// useful for the reverse search.
// 4. To trigger the line refresh, functions should be used to pass through
// the information. Alternatively, getters and setters could be used.
// That might even be more elegant.
// The data would then be accounted for when calling `_refreshLine()`.
// This function would then look similar to:
// repl.overlay(outputLine);
// repl.addTrailingLine(inputLine);
// repl.setCursor(cursor);
// More potential improvements: use something similar to stream.cork().
// Multiple cursor moves on the same tick could be prevented in case all
// writes from the same tick are combined and the cursor is moved at the
// tick end instead of after each operation.
let rows = 0;
if (lastMatch !== -1) {
const line = repl.history[lastMatch].slice(0, lastCursor);
rows = repl._getDisplayPos(`${repl._prompt}${line}`).rows;
cursorTo(repl.output, promptPos.cols);
} else if (isInReverseSearch && repl.line !== '') {
rows = repl._getCursorPos().rows;
cursorTo(repl.output, promptPos.cols);
}
if (rows !== 0)
moveCursor(repl.output, 0, -rows);

if (isInReverseSearch) {
clearScreenDown(repl.output);
repl.output.write(`${outputLine}\n${inputLine}`);
} else {
repl.output.write(`\n${inputLine}`);
}

lastMatch = -1;

// To know exactly how many rows we have to move the cursor back we need the
// cursor rows, the output rows and the input rows.
const prompt = repl._prompt;
const cursorLine = `${prompt}${outputLine.slice(0, cursor)}`;
const cursorPos = repl._getDisplayPos(cursorLine);
const outputPos = repl._getDisplayPos(`${prompt}${outputLine}`);
const inputPos = repl._getDisplayPos(inputLine);
const inputRows = inputPos.rows - (inputPos.cols === 0 ? 1 : 0);

rows = -1 - inputRows - (outputPos.rows - cursorPos.rows);

moveCursor(repl.output, 0, rows);
cursorTo(repl.output, cursorPos.cols);
}

function reset(string) {
isInReverseSearch = string !== undefined;

// In case the reverse search ends and a history entry is found, reset the
// line to the found entry.
if (!isInReverseSearch) {
if (lastMatch !== -1) {
repl.line = repl.history[lastMatch];
repl.cursor = lastCursor;
repl.historyIndex = lastMatch;
}

lastMatch = -1;

// Clear screen and write the current repl.line before exiting.
cursorTo(repl.output, promptPos.cols);
if (promptPos.rows !== 0)
moveCursor(repl.output, 0, promptPos.rows);
clearScreenDown(repl.output);
if (repl.line !== '') {
repl.output.write(repl.line);
if (repl.line.length !== repl.cursor) {
const { cols, rows } = repl._getCursorPos();
cursorTo(repl.output, cols);
if (rows !== 0)
moveCursor(repl.output, 0, rows);
}
}
}

input = string || '';
cursor = -1;
historyIndex = repl.historyIndex;
alreadyMatched.clear();
}

function reverseSearch(string, key) {
if (!isInReverseSearch) {
if (key.ctrl && checkAndSetDirectionKey(key.name)) {
historyIndex = repl.historyIndex;
promptPos = repl._getDisplayPos(`${repl._prompt}`);
print(repl.line, `${labels[dir]}_`);
isInReverseSearch = true;
}
} else if (key.ctrl && checkAndSetDirectionKey(key.name)) {
search();
} else if (key.name === 'backspace' ||
(key.ctrl && (key.name === 'h' || key.name === 'w'))) {
reset(input.slice(0, input.length - 1));
search();
// Special handle <ctrl> + c and escape. Those should only cancel the
// reverse search. The original line is visible afterwards again.
} else if ((key.ctrl && key.name === 'c') || key.name === 'escape') {
lastMatch = -1;
reset();
return true;
// End search in case either enter is pressed or if any non-reverse-search
// key (combination) is pressed.
} else if (key.ctrl ||
key.meta ||
key.name === 'return' ||
key.name === 'enter' ||
typeof string !== 'string' ||
string === '') {
reset();
} else {
reset(`${input}${string}`);
search();
}
return isInReverseSearch;
}

return { reverseSearch };
}

module.exports = {
isRecoverableError,
kStandaloneREPL: Symbol('kStandaloneREPL'),
setupPreview
setupPreview,
setupReverseSearch
};
12 changes: 10 additions & 2 deletions lib/repl.js
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,7 @@ const {
isRecoverableError,
kStandaloneREPL,
setupPreview,
setupReverseSearch,
} = require('internal/repl/utils');
const {
getOwnNonIndexProperties,
Expand Down Expand Up @@ -810,6 +811,8 @@ function REPLServer(prompt,
}
});

const { reverseSearch } = setupReverseSearch(this);

const {
clearPreview,
showPreview
Expand All @@ -835,8 +838,10 @@ function REPLServer(prompt,
self.clearLine();
}
clearPreview();
ttyWrite(d, key);
showPreview();
if (!reverseSearch(d, key)) {
ttyWrite(d, key);
showPreview();
}
return;
}

Expand Down Expand Up @@ -1081,6 +1086,9 @@ REPLServer.prototype.complete = function() {
this.completer.apply(this, arguments);
};

// TODO: Native module names should be auto-resolved.
// That improves the auto completion.

// Provide a list of completions for the given leading text. This is
// given to the readline interface for handling tab completion.
//
Expand Down
2 changes: 1 addition & 1 deletion test/parallel/test-repl-history-navigation.js
Original file line number Diff line number Diff line change
Expand Up @@ -340,7 +340,7 @@ function runTest() {
const output = chunk.toString();

if (!opts.showEscapeCodes &&
output.charCodeAt(0) === 27 || /^[\r\n]+$/.test(output)) {
(output[0] === '\x1B' || /^[\r\n]+$/.test(output))) {
return next();
}

Expand Down
Loading

0 comments on commit 09ca8be

Please sign in to comment.