feat: add APIs, commands and tests for syntax-highlighting in the REPL

lib/node_modules/@stdlib/repl/README.md

@@ -71,6 +71,7 @@ The function accepts the following `options`:
 -   **outputPrompt**: output prompt. If the output prompt includes the character sequence `%d`, the output prompt includes line numbers. Default: `'Out[%d]: '`.
 -   **welcome**: welcome message.
 -   **padding**: number of empty lines between consecutive commands. Default: `1`.
+-   **themes**: table mapping of color themes to load for syntax highlighting.
 -   **load**: file path specifying a JavaScript file to load and evaluate line-by-line (e.g., a previous REPL history file).
 -   **save**: file path specifying where to save REPL command history.
 -   **log**: file path specifying where to save REPL commands and printed output.
@@ -83,6 +84,28 @@ The function supports specifying the following settings:
 -   **autoDeletePairs**: boolean indicating whether to automatically delete adjacent matching brackets, parentheses, and quotes. Default: `true`.
 -   **autoPage**: boolean indicating whether to automatically page return values having a display size exceeding the visible screen. When streams are TTY, the default is `true`; otherwise, the default is `false`.
 -   **completionPreviews**: boolean indicating whether to display completion previews for auto-completion. When streams are TTY, the default is `true`; otherwise, the default is `false`.
+-   **syntaxHighlighting**: boolean indicating whether to enable syntax highlighting of the input. When streams are TTY, the default is `true`; otherwise, the default is `false`.
+-   **theme**: initial color theme for syntax highlighting. Default: `default`.
+-   **defaultTheme**: default theme for syntax highlighting. Default: `default`.
+
+#### REPL.prototype.viewport()
+
+Returns the REPL viewport.
+
+```javascript
+var debug = require( '@stdlib/streams/node/debug-sink' );
+
+// Create a new REPL:
+var repl = new REPL({
+    'output': debug()
+});
+
+// Query the REPL viewport:
+var v = repl.viewport();
+
+// Close the REPL:
+repl.close();
+```
 
 #### REPL.prototype.createContext()
 
@@ -176,6 +199,126 @@ repl.clearUserDocs();
 repl.close();
 ```
 
+#### Repl.prototype.themes()
+
+Returns all available themes in the syntax-highlighter.
+
+```javascript
+var debug = require( '@stdlib/streams/node/debug-sink' );
+
+// Create a new REPL:
+var repl = new REPL({
+    'output': debug()
+});
+
+// ...
+
+// Fetch all available themes:
+repl.themes();
+
+// ...
+
+// Close the REPL:
+repl.close();
+```
+
+#### Repl.prototype.getTheme()
+
+Returns a theme's color palette from the syntax-highlighter.
+
+```javascript
+var debug = require( '@stdlib/streams/node/debug-sink' );
+
+// Create a new REPL:
+var repl = new REPL({
+    'output': debug()
+});
+
+// ...
+
+// Fetch all available themes:
+repl.themes();
+
+// ...
+
+// Close the REPL:
+repl.close();
+```
+
+#### Repl.prototype.addTheme()
+
+Adds a color theme to the syntax-highlighter.
+
+```javascript
+var debug = require( '@stdlib/streams/node/debug-sink' );
+
+// Create a new REPL:
+var repl = new REPL({
+    'output': debug()
+});
+
+// ...
+
+// Add a user-defined theme:
+repl.addTheme( 'myTheme', {
+    'keyword': 'red',
+    'variable': 'green'
+
+    // ...
+});
+
+// ...
+
+// Close the REPL:
+repl.close();
+```
+
+#### Repl.prototype.deleteTheme()
+
+Deletes a specified theme from the syntax-highlighter.
+
+```javascript
+var debug = require( '@stdlib/streams/node/debug-sink' );
+
+// Create a new REPL:
+var repl = new REPL({
+    'output': debug()
+});
+
+// ...
+
+// Delete an existing theme:
+repl.deleteTheme( 'myTheme' );
+
+// ...
+
+// Close the REPL:
+repl.close();
+```
+
+#### Repl.prototype.renameTheme()
+
+Renames a specified theme in the syntax-highlighter.
+
+```javascript
+var debug = require( '@stdlib/streams/node/debug-sink' );
+
+// Create a new REPL:
+var repl = new REPL({
+    'output': debug()
+});
+
+// ...
+
+// Rename an existing theme:
+repl.renameTheme( 'myTheme', 'yourTheme' );
+
+// ...
+
+// Close the REPL:
+repl.close();
+```
+
 #### REPL.prototype.load( fpath, clbk )
 
 Loads and evaluates a JavaScript file line-by-line.

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

@@ -20,6 +20,7 @@
 
 // MODULES //
 
+var onAddTheme = require( './commands/add_theme.js' );
 var onAlias2Pkg = require( './commands/alias2pkg.js' );
 var onAlias2Related = require( './commands/alias2related.js' );
 var onAns = require( './commands/ans.js' );
@@ -35,12 +36,14 @@ var onContributors = require( './commands/contributor.js' );
 var onCopyright = require( './commands/copyright.js' );
 var onCredits = require( './commands/credits.js' );
 var onCurrentWorkspace = require( './commands/current_workspace.js' );
+var onDeleteTheme = require( './commands/delete_theme.js' );
 var onDeleteWorkspace = require( './commands/delete_workspace.js' );
 var onDeeprerequire = require( './commands/deeprerequire.js' );
 var onDonate = require( './commands/donate.js' );
 var onDone = require( './commands/__done__.js' );
 var onEvalin = require( './commands/evalin.js' );
 var onExample = require( './commands/example.js' );
+var onGetTheme = require( './commands/get_theme.js' );
 var onHelp = require( './commands/help.js' );
 var onInfo = require( './commands/info.js' );
 var isWorkspace = require( './commands/is_workspace.js' );
@@ -52,11 +55,13 @@ var onPager = require( './commands/pager.js' );
 var onPresentationStart = require( './commands/presentation_start.js' );
 var onPresentationStop = require( './commands/presentation_stop.js' );
 var onQuit = require( './commands/quit.js' );
+var onRenameTheme = require( './commands/rename_theme.js' );
 var onRenameWorkspace = require( './commands/rename_workspace.js' );
 var onRerequire = require( './commands/rerequire.js' );
 var onRerun = require( './commands/rerun.js' );
 var onReset = require( './commands/reset.js' );
 var onSettings = require( './commands/settings.js' );
+var onThemes = require( './commands/themes.js' );
 var onTutorial = require( './commands/tutorial.js' );
 var onUserDoc = require( './commands/user_doc.js' );
 var onVars = require( './commands/vars.js' );
@@ -90,6 +95,7 @@ function commands( repl ) {
 	// Define a list of REPL-specific commands (NOTE: keep in alphabetical order):
 	cmds = [];
 	cmds.push( [ '__done__', onDone( repl ), false ] );
+	cmds.push( [ 'addTheme', onAddTheme( repl ), false ] );
 	cmds.push( [ 'alias2pkg', onAlias2Pkg( repl ), false ] );
 	cmds.push( [ 'alias2related', onAlias2Related( repl, cmds ), false ] );
 	cmds.push( [ 'ans', onAns( repl ), true ] );
@@ -105,11 +111,13 @@ function commands( repl ) {
 	cmds.push( [ 'copyright', onCopyright( repl ), false ] );
 	cmds.push( [ 'credits', onCredits( repl ), false ] );
 	cmds.push( [ 'currentWorkspace', onCurrentWorkspace( repl ), true ] );
+	cmds.push( [ 'deleteTheme', onDeleteTheme( repl ), false ] );
 	cmds.push( [ 'deleteWorkspace', onDeleteWorkspace( repl ), false ] );
 	cmds.push( [ 'deeprerequire', onDeeprerequire( repl ), false ] );
 	cmds.push( [ 'donate', onDonate( repl ), false ] );
 	cmds.push( [ 'evalin', onEvalin( repl, cmds ), false ] );
 	cmds.push( [ 'example', onExample( repl, cmds ), false ] );
+	cmds.push( [ 'getTheme', onGetTheme( repl ), false ] );
 	cmds.push( [ 'help', onHelp( repl, cmds ), false ] );
 	cmds.push( [ 'info', onInfo( repl, cmds ), false ] );
 	cmds.push( [ 'isKeyword', isKeyword( repl ), false ] );
@@ -121,11 +129,13 @@ function commands( repl ) {
 	cmds.push( [ 'presentationStart', onPresentationStart( repl ), false ] );
 	cmds.push( [ 'presentationStop', onPresentationStop( repl ), false ] );
 	cmds.push( [ 'quit', onQuit( repl ), false ] );
+	cmds.push( [ 'renameTheme', onRenameTheme( repl ), false ] );
 	cmds.push( [ 'renameWorkspace', onRenameWorkspace( repl ), false ] );
 	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( [ 'themes', onThemes( 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/add_theme.js

@@ -0,0 +1,74 @@
+/**
+* @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 format = require( '@stdlib/string/format' );
+var log = require( './../log.js' );
+
+
+// MAIN //
+
+/**
+* Returns a callback to be invoked upon calling the `addTheme` command.
+*
+* @private
+* @param {REPL} repl - REPL instance
+* @returns {Function} callback
+*/
+function command( repl ) {
+	return onCommand;
+
+	/**
+	* Adds a color theme to the syntax-highlighter.
+	*
+	* @private
+	* @param {string} [name] - theme name
+	* @param {Object} [theme] - theme object
+	* @returns {void}
+	*/
+	function onCommand() {
+		var theme;
+		var nargs;
+		var name;
+
+		nargs = arguments.length;
+		if ( nargs < 2 ) {
+			repl._ostream.write( 'Error: invalid operation. Provide a theme to add.\n' );
+			return;
+		}
+		name = arguments[ 0 ];
+		theme = arguments[ 1 ];
+		try {
+			repl.addTheme( name, theme );
+		} catch ( err ) {
+			repl._ostream.write( format( 'Error: %s\n', err.message ) );
+			return;
+		}
+		log( repl, format( '\nSuccessfully added theme `%s`.', name ) );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = command;

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

@@ -0,0 +1,71 @@
+/**
+* @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 format = require( '@stdlib/string/format' );
+var log = require( './../log.js' );
+
+
+// MAIN //
+
+/**
+* Returns a callback to be invoked upon calling the `deleteTheme` command.
+*
+* @private
+* @param {REPL} repl - REPL instance
+* @returns {Function} callback
+*/
+function command( repl ) {
+	return onCommand;
+
+	/**
+	* Deletes a color theme from the syntax-highlighter.
+	*
+	* @private
+	* @param {string} [name] - theme name
+	* @returns {void}
+	*/
+	function onCommand() {
+		var nargs;
+		var name;
+
+		nargs = arguments.length;
+		if ( nargs === 0 ) {
+			repl._ostream.write( 'Error: invalid operation. Provide a theme name to delete.\n' );
+			return;
+		}
+		name = arguments[ 0 ];
+		try {
+			repl.deleteTheme( name );
+		} catch ( err ) {
+			repl._ostream.write( format( 'Error: %s\n', err.message ) );
+			return;
+		}
+		log( repl, format( '\nSuccessfully deleted theme `%s`.', name ) );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = command;