feat: add auto-completion preview for REPL

lib/node_modules/@stdlib/repl/lib/complete_expression.js

@@ -25,6 +25,7 @@ var logger = require( 'debug' );
 var parse = require( 'acorn-loose' ).parse;
 var objectKeys = require( '@stdlib/utils/keys' );
 var trim = require( '@stdlib/string/trim' );
+var trimRight = require( '@stdlib/string/right-trim' );
 var hasOwnProp = require( '@stdlib/assert/has-own-property' );
 var propertyNamesIn = require( '@stdlib/utils/property-names-in' );
 var filterByPrefix = require( './filter_by_prefix.js' );
@@ -93,6 +94,10 @@ function complete( out, context, expression ) {
 	}
 	// Case: `foo<|>` (completing an identifier at the top-level)
 	if ( node.type === 'ExpressionStatement' && node.expression.type === 'Identifier' ) {
+		// Case: `conso <|>`
+		if ( trimRight( expression ) !== expression ) {
+			return '';
+		}
 		filter = node.expression.name;
 		debug( 'Identifier auto-completion. Filter: %s', filter );
 		out = filterByPrefix( out, RESERVED_KEYWORDS_COMMON, filter );
@@ -204,6 +209,10 @@ function complete( out, context, expression ) {
 		}
 		// Case: `foo.bar<|>`
 		else {
+			// Case: `foo.bar  <|>`
+			if ( trimRight( expression ) !== expression ) {
+				return '';
+			}
 			filter = node.property.name;
 		}
 		debug( 'Property auto-completion. Filter: %s', filter );

lib/node_modules/@stdlib/repl/lib/complete_walk_find_last.js

@@ -124,6 +124,10 @@ function walk( node ) { // eslint-disable-line max-lines-per-function
 			break;
 		case 'ArrayExpression':
 			// `[ <|>` || `[ foo<|>` || `[ 1, 2, <|>` || `[ 1, 2, foo<|>` || etc
+			if ( node.elements.length === 0 ) {
+				FLG = false;
+				break;
+			}
 			node = node.elements[ node.elements.length-1 ];
 			break;
 		case 'ForStatement':
@@ -374,13 +378,23 @@ function walk( node ) { // eslint-disable-line max-lines-per-function
 			node = node.handler.body;
 			break;
 		case 'TemplateLiteral':
+			// ``<|>
+			if ( node.expressions.length === 0 ) {
+				FLG = false;
+				break;
+			}
 			node = node.expressions[ node.expressions.length-1 ];
 			break;
 		case 'SpreadElement':
 			// `[...<|>` || `[...foo<|>`
 			node = node.argument;
 			break;
 		case 'ObjectExpression':
+			// `{<|>`
+			if ( node.properties.length === 0 ) {
+				FLG = false;
+				break;
+			}
 			// `{ 'a': 1, ...<|>` || `{ 'a': 1, ...foo<|>`
 			node = node.properties[ node.properties.length-1 ];
 			break;

lib/node_modules/@stdlib/repl/lib/completer_preview.js

@@ -0,0 +1,222 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/* eslint-disable no-restricted-syntax,  no-underscore-dangle, no-invalid-this */
+
+'use strict';
+
+// MODULES //
+
+var readline = require( 'readline' );
+var logger = require( 'debug' );
+var setNonEnumerableReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' );
+var repeat = require( '@stdlib/string/repeat' );
+var commonPrefix = require( './longest_common_prefix.js' );
+
+
+// VARIABLES //
+
+var debug = logger( 'repl:completer:preview' );
+
+
+// MAIN //
+
+/**
+* Constructor for creating a preview completer.
+*
+* @private
+* @constructor
+* @param {Object} rli - readline instance
+* @param {Function} completer - function for generating possible completions
+* @param {WritableStream} ostream - writable stream
+* @returns {PreviewCompleter} completer instance
+*/
+function PreviewCompleter( rli, completer, ostream ) {
+	if ( !(this instanceof PreviewCompleter) ) {
+		return new PreviewCompleter( rli, completer, ostream );
+	}
+	debug( 'Creating a preview completer...' );
+
+	// Cache a reference to the provided readline interface:
+	this._rli = rli;
+
+	// Cache a reference to the output writable stream:
+	this._ostream = ostream;
+
+	// Cache a reference to the provided completer:
+	this._completer = completer;
+
+	// Create a callback for processing potential completion previews:
+	this._onCompletions = this._completionCallback();
+
+	// Initialize a buffer containing the currently displayed completion preview:
+	this._preview = '';
+
+	return this;
+}
+
+/**
+* Returns a callback for processing potential completion previews.
+*
+* @private
+* @name _completionCallback
+* @memberof PreviewCompleter.prototype
+* @returns {Function} completion callback
+*/
+setNonEnumerableReadOnly( PreviewCompleter.prototype, '_completionCallback', function completionCallback() {
+	var self = this;
+	return clbk;
+
+	/**
+	* Callback invoked upon resolving potential completion previews.
+	*
+	* @private
+	* @param {(Error|null)} error - error object
+	* @param {Array} completions - completion results
+	* @returns {void}
+	*/
+	function clbk( error, completions ) {
+		var prefix;
+		var list;
+		var N;
+
+		// Check whether we encountered an error when generating completions...
+		if ( error ) {
+			debug( 'Encountered an error when generating completions. Unable to display a completion preview.' );
+			return;
+		}
+		list = completions[ 0 ];
+		if ( list.length === 0 ) {
+			debug( 'Unable to display a completion preview. No completion preview candidates.' );
+			self.clear();
+			return;
+		}
+		// Resolve a common prefix from the completion results:
+		prefix = commonPrefix( list ); // e.g., [ 'back', 'background', 'backward' ] => 'back'
+
+		// If the completion candidates do not have a common prefix, no completion preview to display, as we do not have a criteria for choosing one candidate over another...
+		if ( prefix === '' ) {
+			debug( 'Unable to display a completion preview. Completion candidates have no common prefix.' );
+			return;
+		}
+		// Extract the completion preview substring (e.g., if the current line is 'ba', preview should be 'ck'):
+		self._preview = prefix.substring( commonPrefix( prefix, completions[ 1 ] ).length ); // eslint-disable-line max-len
+
+		// If the substring is empty, nothing to display...
+		if ( self._preview === '' ) {
+			debug( 'Unable to display a completion preview. Exact match.' );
+			return;
+		}
+		debug( 'Completion preview: %s', self._preview );
+
+		// Compute the number of characters until the end of the line from the current cursor position:
+		N = self._rli.line.length - self._rli.cursor;
+
+		// Move the cursor to the end of the line:
+		readline.moveCursor( self._ostream, N );
+
+		// Append the completion preview to the current line (using ASCII color escape codes for displaying grey text):
+		self._ostream.write( '\u001b[90m' + self._preview + '\u001b[0m' );
+
+		// Move the cursor back to previous position:
+		readline.moveCursor( self._ostream, -self._preview.length-N );
+	}
+});
+
+/**
+* Clears a completion preview.
+*
+* @name clear
+* @memberof PreviewCompleter.prototype
+* @returns {void}
+*/
+setNonEnumerableReadOnly( PreviewCompleter.prototype, 'clear', function clear() {
+	var preview;
+	var N;
+
+	preview = this._preview;
+
+	// If no preview currently displayed, nothing to clear...
+	if ( preview === '' ) {
+		return;
+	}
+	debug( 'Clearing completion preview...' );
+
+	// Compute the number of character until the end of the line from the current cursor position:
+	N = this._rli.line.length - this._rli.cursor;
+
+	// Move the cursor to the end of the line:
+	readline.moveCursor( this._ostream, N );
+
+	// Replace the current display text with whitespace:
+	this._ostream.write( repeat( ' ', preview.length ) );
+
+	// Reset the cursor:
+	readline.moveCursor( this._ostream, -preview.length-N );
+
+	// Reset the completion preview buffer:
+	this._preview = '';
+});
+
+/**
+* Callback for handling a "keypress" event.
+*
+* @name onKeypress
+* @memberof PreviewCompleter.prototype
+* @param {string} data - input data
+* @param {Object} key - key object
+* @returns {void}
+*/
+setNonEnumerableReadOnly( PreviewCompleter.prototype, 'onKeypress', function onKeypress() {
+	this._completer( this._rli.line, this._onCompletions );
+});
+
+/**
+* Callback which should be invoked **before** a "keypress" event is processed by a readline interface.
+*
+* @name beforeKeypress
+* @memberof PreviewCompleter.prototype
+* @param {string} data - input data
+* @param {Object} key - key object
+* @returns {void}
+*/
+setNonEnumerableReadOnly( PreviewCompleter.prototype, 'beforeKeypress', function beforeKeypress( data, key ) {
+	if ( !key || this._preview === '' ) {
+		return;
+	}
+	// Handle the case where the user is not at the end of the line...
+	if ( this._rli.cursor !== this._rli.line.length ) {
+		// If a user is in the middle of a line and presses ENTER, clear the preview string, as the preview was not accepted prior to executing the expression...
+		if ( key.name === 'return' || key.name === 'enter' ) {
+			debug( 'Received an ENTER keypress event while in the middle of the line.' );
+			return this.clear();
+		}
+		return;
+	}
+	// When the user is at the end of the line, auto-complete the line with the completion preview when a user presses RETURN or the RIGHT arrow key (note: pressing ENTER will result in both completion AND execution)...
+	if ( key.name === 'return' || key.name === 'enter' || key.name === 'right' ) {
+		debug( 'Completion preview accepted. Performing auto-completion...' );
+		this._rli.write( this._preview );
+		this._preview = '';
+	}
+});
+
+
+// EXPORTS //
+
+module.exports = PreviewCompleter;