feat: add support for auto-closing brackets/quotations in the REPL

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

@@ -61,6 +61,7 @@ var onVars = require( './commands/vars.js' );
 var onVarsWorkspace = require( './commands/vars_workspace.js' );
 var onWorkspace = require( './commands/workspace.js' );
 var onWorkspaces = require( './commands/workspaces.js' );
+var onSettings = require( './commands/settings.js' );
 
 
 // MAIN //
@@ -122,6 +123,7 @@ function commands( repl ) {
 	cmds.push( [ 'rerequire', onRerequire( repl ), false ] );
 	cmds.push( [ 'rerun', onRerun( repl ), false ] );
 	cmds.push( [ 'reset', onReset( repl ), false ] );
+	cmds.push( [ 'settings', onSettings( repl ), false ] );
 	cmds.push( [ 'tutorial', onTutorial( repl ), false ] );
 	cmds.push( [ 'userDoc', onUserDoc( repl ), false ] );
 	cmds.push( [ 'vars', onVars( repl ), false ] );

lib/node_modules/@stdlib/repl/lib/commands/settings.js

@@ -0,0 +1,136 @@
+/**
+* @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-underscore-dangle */
+
+'use strict';
+
+// MODULES //
+
+var logger = require( 'debug' );
+var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
+var isBoolean = require( '@stdlib/assert/is-boolean' );
+var hasOwnProp = require( '@stdlib/assert/has-own-property' );
+var objectKeys = require( '@stdlib/utils/keys' );
+var format = require( '@stdlib/string/format' );
+
+
+// VARIABLES //
+
+var debug = logger( 'repl:command:settings' );
+var SETTINGS = {
+	'autoCloseSymbols': {
+		'desc': 'Auto-close brackets and quotations.'
+	}
+};
+
+
+// FUNCTIONS //
+
+/**
+* Returns settings help text.
+*
+* @private
+* @returns {string} settings help text
+*/
+function help() {
+	var HELP_TEXT;
+	var names;
+	var o;
+	var i;
+
+	names = objectKeys( SETTINGS );
+	HELP_TEXT = '\n';
+	for ( i = 0; i < names.length; i++ ) {
+		o = SETTINGS[ names[ i ] ];
+		HELP_TEXT += names[ i ] + '\n';
+		HELP_TEXT += '    ';
+		if ( o.desc ) {
+			HELP_TEXT += SETTINGS[ names[ i ] ].desc;
+		} else {
+			HELP_TEXT += '(no description available)';
+		}
+		HELP_TEXT += '\n\n';
+	}
+	return HELP_TEXT;
+}
+
+
+// MAIN //
+
+/**
+* Returns a callback to be invoked upon calling the `settings` command.
+*
+* @private
+* @param {REPL} repl - REPL instance
+* @returns {Function} callback
+*/
+function command( repl ) {
+	return onCommand;
+
+	/**
+	 * Manages REPL settings.
+	 *
+	 * If no arguments are given, it prints all settings with their description.
+	 * If one argument is given, it fetches the value of the setting with the given name and prints it.
+	 * If two arguments are given, it updates the value of the given setting name to the given value.
+	 *
+	 * @private
+	 * @param {string} [name] - Setting name
+	 * @param {boolean} [value] - New setting value
+	 * @throws {TypeError} First argument must be a string
+	 * @throws {Error} Must recognize setting name
+	 * @throws {TypeError} Second argument must be a boolean
+	 */
+	function onCommand( name, value ) {
+		var err;
+		if ( arguments.length === 0 ) {
+			repl._ostream.write( help() );
+			return;
+		}
+		if ( !isString( name ) ) {
+			err = new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', name ) );
+			debug( 'Error: %s', err.message );
+			repl._ostream.write( format( 'Error: %s\n.', err.message ) );
+			return;
+		}
+		if ( !hasOwnProp( SETTINGS, name ) ) {
+			err = new Error( format( 'invalid argument. Unrecognized setting. Value: `%s`.', name ) );
+			debug( 'Error: %s', err.message );
+			repl._ostream.write( format( 'Error: %s\n.', err.message ) );
+			return;
+		}
+		if (arguments.length === 1) {
+			repl._ostream.write('\n'+repl._settings[name]+'\n\n');
+			return;
+		}
+		if ( !isBoolean(value) ) {
+			err = new TypeError( format( 'invalid argument. Second argument must be a boolean. Value: `%s`.', name ) );
+			debug( 'Error: %s', err.message );
+			repl._ostream.write( format( 'Error: %s\n.', err.message ) );
+			return;
+		}
+		repl._settings[name] = value;
+		repl._ostream.write( format( '\nUpdated setting %s to %s.\n\n', name, ( value ) ? 'true' : 'false' ) );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = command;

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

@@ -71,6 +71,10 @@ var MSG = [
 	'    userDoc()               Add user-defined documentation.',
 	'    clearUserDocs()         Clear user-defined documentation.',
 	'',
+	'    settings()              List REPL settings.',
+	'    settings(name)          Get setting\'s value.',
+	'    settings(name,value)    Update setting with the new value.',
+	'',
 	'    clearHistory()          Clear the REPL history.',
 	'',
 	'    clear()                 Clear the entire REPL screen and scrollback history.',

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

@@ -37,6 +37,7 @@
 var properties = require( '@stdlib/utils/properties' );
 var append = require( '@stdlib/utils/append' );
 var format = require( '@stdlib/string/format' );
+var repeat = require( '@stdlib/string/repeat' );
 var Boolean = require( '@stdlib/boolean/ctor' );
 var cwd = require( '@stdlib/process/cwd' );
 var readFileSync = require( '@stdlib/fs/read-file' ).sync;
@@ -202,8 +203,18 @@
 	// Define the current workspace:
 	setNonEnumerable( this, '_currentWorkspace', 'base' );
 
-	// Initialize an internal flag indicating whether a user is entering a multi-line command:
-	setNonEnumerable( this, '_multiline_mode', false );
+	// Initialize an internal object storing user settings:
+	setNonEnumerable( this, '_settings', {} );
+	setNonEnumerable( this._settings, 'autoCloseSymbols', true );
+
+	// Initialize an internal status object for controlling multi-line mode:
+	setNonEnumerable( this, '_multiline_mode', {} );
+	setNonEnumerable( this._multiline_mode, 'status', false );
+	setNonEnumerable( this._multiline_mode, 'manual', false );
+	setNonEnumerable( this._multiline_mode, 'buffer', '' );
+
+	// Initialize an internal flag indicating whether auto closing symbols is in progress
+	setNonEnumerable( this, '_auto_close_status', false );
 
 	// Initialize an internal flag indicating whether the REPL has been closed:
 	setNonEnumerable( this, '_closed', false );
@@ -235,6 +246,7 @@
 	this._rli.on( 'close', onClose );
 	this._rli.on( 'line', onLine );
 	this._rli.on( 'SIGINT', onSIGINT );
+	this._rli.input.on( 'keypress', onKeypress );
 
 	// Add listener for "command" events:
 	this.on( 'command', onCommand );
@@ -242,9 +254,9 @@
 	// Write a welcome message:
 	this._ostream.write( opts.welcome );
 
 	// TODO: check whether to synchronously initialize a REPL history file
 
 	// TODO: check whether to synchronously initialize a REPL log file
 
 	// Check whether to load and execute a JavaScript file (e.g., prior REPL history) upon startup...
 	if ( opts.load ) {
@@ -268,6 +280,72 @@
 		}
 	}
 
+	/**
+	* Callback invoked upon a readline interface "keypress" event.
+	*
+	* @private
+	* @param {string} chunk - character pressed by the user
+	* @param {Object} key - keypress event information
+	*/
+	function onKeypress( chunk, key ) {
+		var charsAfterCursor;
+		var codeAfterCursor;
+		var symbols = {
+			'{': '}',
+			'[': ']',
+			'(': ')',
+			'\'': '\'',
+			'"': '"',
+			'`': '`'
+		};
+
+		// For ALT+ENTER keypress, manually enter multi-line mode:
+		if ( key && key.name === 'return' && key.meta ) {
+			charsAfterCursor = self._rli.line.length - self._rli.cursor;
+			codeAfterCursor = self._rli.line.substring( self._rli.cursor );
+
+			// Update flag
+			self._multiline_mode.manual = true;
+
+			// Store code after cursor in buffer for next line
+			self._multiline_mode.buffer = codeAfterCursor;
+			self._ostream.write( repeat( '\x1b[C', charsAfterCursor ) + repeat( '\b \b', charsAfterCursor ) );
+			self._rli.line = self._rli.line.substring( 0, self._rli.cursor );
+
+			// Simulate `line` event
+			self._rli.write( null, {
+				'name': 'return'
+			});
+		}
+
+		// For a bracket/quotation input, append corresponding closing symbol
+		if ( self._settings.autoCloseSymbols && symbols[chunk] ) {
+			self._rli.write( symbols[chunk] );
+			self._rli.write( null, {
+				'ctrl': true,
+				'name': 'b'
+			} );
+			self._auto_close_status = true;
+			return;
+		}
+
+		// Handle instinctive closing symbols
+		if ( self._auto_close_status ) {
+			if (
+				typeof chunk !== 'undefined' &&
+				symbols[ self._rli.line[ self._rli.cursor - 2 ] ] === chunk
+			) {
+				self._rli.write( null, {
+					'name': 'backspace'
+				} );
+				self._rli.write( null, {
+					'name': 'right'
+				} );
+			}
+			self._auto_close_status = false;
+		}
+	}
+
 	/**
 	* Callback invoked upon a readline interface "close" event.
 	*
@@ -337,9 +415,9 @@
 		// Update the internal command history buffer: [..., <id>, <cmd>, <success>, ...]
 		self._history.push( self._count, cmd, success );
 
 		// TODO: if successful and if necessary, (asynchronously?) write the command to a history file (question: do we only want to write successful commands to the history file? maybe we need to option for limiting to successful commands?)
 
 		// TODO: if necessary, (asynchronously?) write the command and result to a log file (JSON serialization?)
 	}
 }
 
@@ -473,7 +551,7 @@
 
 	// Before creating a new execution context in a non-sandboxed environment, remove current workspace variables in order to allow garbage collection and avoid memory leaks (e.g., variables/functions declared during a REPL session which might remain bound to the environment `global` after clearing a REPL):
 	if ( this._sandbox === false ) {
 		// WARNING: in a non-sandboxed environment, if a global variable is externally introduced during a REPL session (i.e., introduced via a mechanism outside of the REPL environment), we will delete that global variable, which means the following logic may introduce unintended side-effects for this particular edge case (e.g., application code may expect the presence of the subsequently deleted global variable). While not ideal, (a) user applications should not be introducing globals to begin with and (b) the probability of a user running a REPL session, a user clearing that REPL session, AND a global variable being introduced between starting a REPL and clearing the REPL should be negligible.
 		tmp = this._context.vars();
 		for ( i = 0; i < tmp.length; i++ ) {
 			if ( isConfigurableProperty( this._context, tmp[ i ] ) ) {
@@ -593,7 +671,7 @@
 * // TODO
 */
 setNonEnumerableReadOnly( REPL.prototype, 'load', function load( fpath, clbk ) {
 	var self;
 	var file;
 	var len;
 	var i;
@@ -866,9 +944,9 @@
 	// Clear the command queue:
 	this._queue.clear();
 
 	// TODO: ensure REPL history is saved (flushed) to file before closing the REPL (see https://github.com/nodejs/node/blob/b21e7c7bcf23a2715951e4cd96180e4dbf1dcd4d/lib/repl.js#L805)
 
 	// TODO: ensure REPL log is saved (flushed) to file before closing the REPL
 
 	nextTick( onTick );
 
@@ -891,7 +969,7 @@
 
 		// If this is a non-sandboxed REPL, remove global variables/properties which were introduced during context creation and by a user during a REPL session...
 		if ( self._sandbox === false ) {
 			// WARNING: in a non-sandboxed environment, if a global variable is externally introduced during a REPL session (i.e., introduced via a mechanism outside of the REPL environment), we will delete that global variable, which means the following logic may introduce unintended side-effects for this particular edge case (e.g., application code may expect the presence of the subsequently deleted global variable). While not ideal, (a) user applications should not be introducing globals to begin with and (b) the probability of a user running a REPL session, a user closing that REPL session, AND a global variable being introduced between starting a REPL and closing the REPL should be negligible.
 			tmp = self._context.vars(); // current workspace variables
 			for ( i = 0; i < tmp.length; i++ ) {
 				if ( isConfigurableProperty( self._context, tmp[ i ] ) ) {

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

@@ -25,6 +25,7 @@
 var logger = require( 'debug' );
 var Parser = require( 'acorn' ).Parser;
 var parseLoose = require( 'acorn-loose' ).parse;
+var repeat = require( '@stdlib/string/repeat' );
 var displayPrompt = require( './display_prompt.js' );
 var drain = require( './drain.js' );
 var multilinePlugin = require( './acorn_detect_multiline_input.js' );
@@ -62,9 +63,21 @@ function processLine( repl, line ) {
 	var tmp;
 
 	debug( 'Line: %s', line );
-	repl._multiline_mode = false; // false until proven otherwise
+	repl._multiline_mode.status = false; // false until proven otherwise
 
 	cmd = repl._cmd.join( '\n' ) + line;
+	if ( repl._multiline_mode.manual ) {
+		debug( 'Detected multi-line input via modifier-key. Waiting for additional lines...' );
+		repl._cmd.push( line );
+		repl._multiline_mode.status = true;
+		repl._multiline_mode.manual = false;
+		displayPrompt( repl, false );
+		repl._ostream.write( repl._multiline_mode.buffer );
+		repl._ostream.write(repeat('\x1b[D', repl._multiline_mode.buffer.length));
+		repl._rli.line = repl._multiline_mode.buffer;
+		repl._multiline_mode.buffer = ''; // empty buffer
+		return;
+	}
 	if ( RE_WHITESPACE.test( cmd ) ) {
 		displayPrompt( repl, false );
 		return;
@@ -83,7 +96,7 @@ function processLine( repl, line ) {
 			if ( hasMultilineError( cmd, AOPTS ) ) {
 				debug( 'Detected multi-line input. Waiting for additional lines...' );
 				repl._cmd.push( line );
-				repl._multiline_mode = true;
+				repl._multiline_mode.status = true;
 				displayPrompt( repl, false );
 				return;
 			}
@@ -97,7 +110,7 @@ function processLine( repl, line ) {
 				if ( hasMultilineError( tmp, AOPTS ) ) {
 					debug( 'Detected multi-line input. Waiting for additional lines...' );
 					repl._cmd.push( line );
-					repl._multiline_mode = true;
+					repl._multiline_mode.status = true;
 					displayPrompt( repl, false );
 					return;
 				}