Auto-generated commit

CHANGELOG.md

@@ -4,7 +4,7 @@
 
 <section class="release" id="unreleased">
 
-## Unreleased (2024-06-07)
+## Unreleased (2024-06-08)
 
 <section class="packages">
 
@@ -20,6 +20,7 @@
 
 ##### Features
 
+-   [`b4c12b7`](https://github.com/stdlib-js/stdlib/commit/b4c12b7c4a76cfa71164d1b01fcbfca0426abbb3) - add APIs, commands, and tests for REPL syntax-highlighting [(#2291)](https://github.com/stdlib-js/stdlib/pull/2291)
 -   [`24f4a8f`](https://github.com/stdlib-js/stdlib/commit/24f4a8f24c08dd25686afc4cfb78be2e0045e844) - add syntax highlighting in the REPL
 -   [`0f9acd1`](https://github.com/stdlib-js/stdlib/commit/0f9acd17de012dfe755c98b602d6bb3dbe1e8117) - add `BooleanArray` to namespace
 -   [`3c31c1f`](https://github.com/stdlib-js/stdlib/commit/3c31c1f54ab8e1148fd9104490245c60cc540280) - add REPL pager [(#2162)](https://github.com/stdlib-js/stdlib/pull/2162)
@@ -255,6 +256,7 @@ A total of 10 people contributed to this release. Thank you to the following con
 
 <details>
 
+-   [`b4c12b7`](https://github.com/stdlib-js/stdlib/commit/b4c12b7c4a76cfa71164d1b01fcbfca0426abbb3) - **feat:** add APIs, commands, and tests for REPL syntax-highlighting [(#2291)](https://github.com/stdlib-js/stdlib/pull/2291) _(by Snehil Shah, Athan Reines)_
 -   [`f85ed2a`](https://github.com/stdlib-js/stdlib/commit/f85ed2aafc393cfbac360ad14b97af0ee28d450b) - **docs:** update REPL namespace documentation [(#2313)](https://github.com/stdlib-js/stdlib/pull/2313) _(by stdlib-bot, Athan Reines)_
 -   [`f10aaf2`](https://github.com/stdlib-js/stdlib/commit/f10aaf243f4873488bf04be4bad5c3d256415a41) - **docs:** update REPL namespace documentation [(#2311)](https://github.com/stdlib-js/stdlib/pull/2311) _(by stdlib-bot, Athan Reines)_
 -   [`34ef42e`](https://github.com/stdlib-js/stdlib/commit/34ef42e798ec33e1f3a62a15a460dd46ae7c693c) - **docs:** update REPL namespace documentation [(#2246)](https://github.com/stdlib-js/stdlib/pull/2246) _(by stdlib-bot, Athan Reines)_

README.md

@@ -94,6 +94,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.
@@ -106,6 +107,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()
 
@@ -176,7 +198,7 @@ repl.clearHistory();
 repl.close();
 ```
 
-#### Repl.prototype.clearUserDocs()
+#### REPL.prototype.clearUserDocs()
 
 Clears user-defined documentation.
 
@@ -199,6 +221,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.
@@ -409,6 +592,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.
@@ -620,6 +816,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.
@@ -718,6 +934,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.
@@ -899,6 +1130,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.
@@ -1082,6 +1333,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.