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 containing color themes 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,27 @@ 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 entered input expressions. When streams are TTY, the default is `true`; otherwise, the default is `false`.
+-   **theme**: initial color theme for syntax highlighting. Default: `stdlib-ansi-basic`.
+
+#### 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()
 
@@ -153,7 +175,7 @@ repl.clearHistory();
 repl.close();
 ```
 
-#### Repl.prototype.clearUserDocs()
+#### REPL.prototype.clearUserDocs()
 
 Clears user-defined documentation.
 
@@ -176,6 +198,167 @@ repl.clearUserDocs();
 repl.close();
 ```
 
+#### REPL.prototype.themes()
+
+Returns a list of all available themes for syntax highlighting.
+
+```javascript
+var debug = require( '@stdlib/streams/node/debug-sink' );
+
+// Create a new REPL:
+var repl = new REPL({
+    'output': debug()
+});
+
+// ...
+
+// Fetch all available themes:
+var themes = repl.themes();
+// returns [...]
+
+// ...
+
+// Close the REPL:
+repl.close();
+```
+
+#### REPL.prototype.getTheme( name )
+
+Returns a theme's color palette for syntax highlighting.
+
+```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'
+});
+
+// Get a theme's color palette:
+var theme = repl.getTheme( 'myTheme' );
+// returns { 'keyword': 'red' }
+
+// ...
+
+// Close the REPL:
+repl.close();
+```
+
+#### REPL.prototype.addTheme( name, theme )
+
+Adds a syntax highlighting theme.
+
+```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();
+```
+
+The syntax-highlighter supports the following tokens and associated theme fields:
+
+-   **keyword**: keywords (e.g., `var`, `function`, `let`, `const`, `in`, and `class`).
+-   **control**: control flow keywords (e.g., `if`, `else`, `try`, `catch`, and `return`).
+-   **specialIdentifier**: special identifiers (e.g., `this` and `super`).
+-   **string**: string and template literals.
+-   **number**: numeric literals.
+-   **literal**: reserved literals (e.g., `true`, `false`, `null`, and `undefined`).
+-   **regexp**: regular expressions.
+-   **command**: built-in REPL commands.
+-   **function**: function identifiers.
+-   **object**: object identifiers.
+-   **variable**: literal identifiers.
+-   **name**: variable names.
+-   **comment**: line comments.
+-   **punctuation**: punctuation symbols (e.g., `;`, `[`, `{`, `,`, and `?`).
+-   **operator**: operator symbols (e.g., `+`, `-`, `*`, `=`, `++`, `>=`, and `&&`).
+
+#### REPL.prototype.deleteTheme( name )
+
+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()
+});
+
+// ...
+
+// Add a user-defined theme:
+repl.addTheme( 'myTheme', {
+    'keyword': 'red',
+    'variable': 'green'
+
+    // ...
+});
+
+// Delete the added theme:
+repl.deleteTheme( 'myTheme' );
+
+// ...
+
+// Close the REPL:
+repl.close();
+```
+
+#### REPL.prototype.renameTheme( oldName, newName )
+
+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()
+});
+
+// ...
+
+// Add a user-defined theme:
+repl.addTheme( 'myTheme', {
+    'keyword': 'red',
+    'variable': 'green'
+
+    // ...
+});
+
+// Rename the added theme:
+repl.renameTheme( 'myTheme', 'yourTheme' );
+
+// ...
+
+// Close the REPL:
+repl.close();
+```
+
 #### REPL.prototype.load( fpath, clbk )
 
 Loads and evaluates a JavaScript file line-by-line.
@@ -386,6 +569,19 @@ repl.close();
 
 REPL instances support the following commands...
 
+#### addTheme( name, theme )
+
+Adds a syntax highlighting color theme.
+
+```text
+// Add color theme:
+In [1]: addTheme( 'myTheme', { 'keyword': 'red' } )
+
+// Check updated list of themes:
+In [2]: themes()
+Out[2]: [ 'stdlib-ansi-basic', 'myTheme' ]
+```
+
 #### alias2pkg( arg )
 
 Returns the package name associated with a provided alias or class instance.
@@ -597,6 +793,26 @@ In [1]: currentWorkspace
 Out[1]: 'base'
 ```
 
+#### deleteTheme( name )
+
+Deletes a syntax highlighting color theme.
+
+```text
+// Add a color theme:
+In [1]: addTheme( 'myTheme', { 'keyword': 'red' } )
+
+// Check list of themes:
+In [2]: themes()
+Out[2]: [ 'stdlib-ansi-basic', 'myTheme' ]
+
+// Delete the added theme:
+In [3]: deleteTheme( 'myTheme' )
+
+// Check updated list of themes:
+In [4]: themes()
+Out[4]: [ 'stdlib-ansi-basic' ]
+```
+
 #### deeprerequire( id )
 
 Re-imports a module, JSON, or local file and all of its associated module dependencies.
@@ -695,6 +911,21 @@ In [1]: example( base.sin )
 
 **Note**: only direct instances of documented built-in constructors are supported.
 
+#### getTheme( \[name] )
+
+Returns a syntax highlighting color theme.
+
+```text
+// Add a color theme:
+In [1]: addTheme( 'myTheme', { 'keyword': 'red' } )
+
+// Get the color theme:
+In [2]: getTheme( 'myTheme' )
+Out[2]: { 'keyword': 'red' }
+```
+
+**Note**: if no theme name is provided, the current theme is returned.
+
 #### help( \[arg] )
 
 Prints help text.
@@ -876,6 +1107,26 @@ Exits the REPL.
 In [1]: quit()
 ```
 
+#### renameTheme( oldName, newName )
+
+Renames a syntax highlighting color theme.
+
+```text
+// Add a color theme:
+In [1]: addTheme( 'myTheme', { 'keyword': 'red' } )
+
+// Check list of themes:
+In [2]: themes()
+Out[2]: [ 'stdlib-ansi-basic', 'myTheme' ]
+
+// Rename the added theme:
+In [3]: getTheme( 'myTheme', 'yourTheme' )
+
+// Check updated list of themes:
+In [4]: themes()
+Out[4]: [ 'stdlib-ansi-basic', 'yourTheme' ]
+```
+
 #### renameWorkspace( oldName, newName )
 
 Renames a workspace.
@@ -1059,6 +1310,19 @@ To update a specific setting, provide a `value` argument.
 In [1]: settings( 'autoClosePairs', false )
 ```
 
+#### themes()
+
+Returns a list of all available syntax highlighting color themes.
+
+```text
+// Add a color theme:
+In [1]: addTheme( 'myTheme', { 'keyword': 'red' } )
+
+// Check list of themes:
+In [2]: themes()
+Out[2]: [ 'stdlib-ansi-basic', 'myTheme' ]
+```
+
 #### tutorial( \[name, \[options]] )
 
 Starts a tutorial.