Skip to content

Commit b4c12b7

Browse files
Snehil-Shahkgryte
Snehil-Shah
and
kgryte
authored
feat: add APIs, commands, and tests for REPL syntax-highlighting
PR-URL: #2291 Ref: #2254 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com> Signed-off-by: Snehil Shah <snehilshah.989@gmail.com> Signed-off-by: Athan Reines <kgryte@gmail.com>
1 parent cc5d91f commit b4c12b7

37 files changed

+1407
-62
lines changed

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

Lines changed: 265 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ The function accepts the following `options`:
7171
- **outputPrompt**: output prompt. If the output prompt includes the character sequence `%d`, the output prompt includes line numbers. Default: `'Out[%d]: '`.
7272
- **welcome**: welcome message.
7373
- **padding**: number of empty lines between consecutive commands. Default: `1`.
74+
- **themes**: table containing color themes for syntax highlighting.
7475
- **load**: file path specifying a JavaScript file to load and evaluate line-by-line (e.g., a previous REPL history file).
7576
- **save**: file path specifying where to save REPL command history.
7677
- **log**: file path specifying where to save REPL commands and printed output.
@@ -83,6 +84,27 @@ The function supports specifying the following settings:
8384
- **autoDeletePairs**: boolean indicating whether to automatically delete adjacent matching brackets, parentheses, and quotes. Default: `true`.
8485
- **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`.
8586
- **completionPreviews**: boolean indicating whether to display completion previews for auto-completion. When streams are TTY, the default is `true`; otherwise, the default is `false`.
87+
- **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`.
88+
- **theme**: initial color theme for syntax highlighting. Default: `stdlib-ansi-basic`.
89+
90+
#### REPL.prototype.viewport()
91+
92+
Returns the REPL viewport.
93+
94+
```javascript
95+
var debug = require( '@stdlib/streams/node/debug-sink' );
96+
97+
// Create a new REPL:
98+
var repl = new REPL({
99+
'output': debug()
100+
});
101+
102+
// Query the REPL viewport:
103+
var v = repl.viewport();
104+
105+
// Close the REPL:
106+
repl.close();
107+
```
86108

87109
#### REPL.prototype.createContext()
88110

@@ -153,7 +175,7 @@ repl.clearHistory();
153175
repl.close();
154176
```
155177

156-
#### Repl.prototype.clearUserDocs()
178+
#### REPL.prototype.clearUserDocs()
157179

158180
Clears user-defined documentation.
159181

@@ -176,6 +198,167 @@ repl.clearUserDocs();
176198
repl.close();
177199
```
178200

201+
#### REPL.prototype.themes()
202+
203+
Returns a list of all available themes for syntax highlighting.
204+
205+
```javascript
206+
var debug = require( '@stdlib/streams/node/debug-sink' );
207+
208+
// Create a new REPL:
209+
var repl = new REPL({
210+
'output': debug()
211+
});
212+
213+
// ...
214+
215+
// Fetch all available themes:
216+
var themes = repl.themes();
217+
// returns [...]
218+
219+
// ...
220+
221+
// Close the REPL:
222+
repl.close();
223+
```
224+
225+
#### REPL.prototype.getTheme( name )
226+
227+
Returns a theme's color palette for syntax highlighting.
228+
229+
```javascript
230+
var debug = require( '@stdlib/streams/node/debug-sink' );
231+
232+
// Create a new REPL:
233+
var repl = new REPL({
234+
'output': debug()
235+
});
236+
237+
// ...
238+
239+
// Add a user-defined theme:
240+
repl.addTheme( 'myTheme', {
241+
'keyword': 'red'
242+
});
243+
244+
// Get a theme's color palette:
245+
var theme = repl.getTheme( 'myTheme' );
246+
// returns { 'keyword': 'red' }
247+
248+
// ...
249+
250+
// Close the REPL:
251+
repl.close();
252+
```
253+
254+
#### REPL.prototype.addTheme( name, theme )
255+
256+
Adds a syntax highlighting theme.
257+
258+
```javascript
259+
var debug = require( '@stdlib/streams/node/debug-sink' );
260+
261+
// Create a new REPL:
262+
var repl = new REPL({
263+
'output': debug()
264+
});
265+
266+
// ...
267+
268+
// Add a user-defined theme:
269+
repl.addTheme( 'myTheme', {
270+
'keyword': 'red',
271+
'variable': 'green'
272+
273+
// ...
274+
});
275+
276+
// ...
277+
278+
// Close the REPL:
279+
repl.close();
280+
```
281+
282+
The syntax-highlighter supports the following tokens and associated theme fields:
283+
284+
- **keyword**: keywords (e.g., `var`, `function`, `let`, `const`, `in`, and `class`).
285+
- **control**: control flow keywords (e.g., `if`, `else`, `try`, `catch`, and `return`).
286+
- **specialIdentifier**: special identifiers (e.g., `this` and `super`).
287+
- **string**: string and template literals.
288+
- **number**: numeric literals.
289+
- **literal**: reserved literals (e.g., `true`, `false`, `null`, and `undefined`).
290+
- **regexp**: regular expressions.
291+
- **command**: built-in REPL commands.
292+
- **function**: function identifiers.
293+
- **object**: object identifiers.
294+
- **variable**: literal identifiers.
295+
- **name**: variable names.
296+
- **comment**: line comments.
297+
- **punctuation**: punctuation symbols (e.g., `;`, `[`, `{`, `,`, and `?`).
298+
- **operator**: operator symbols (e.g., `+`, `-`, `*`, `=`, `++`, `>=`, and `&&`).
299+
300+
#### REPL.prototype.deleteTheme( name )
301+
302+
Deletes a specified theme from the syntax-highlighter.
303+
304+
```javascript
305+
var debug = require( '@stdlib/streams/node/debug-sink' );
306+
307+
// Create a new REPL:
308+
var repl = new REPL({
309+
'output': debug()
310+
});
311+
312+
// ...
313+
314+
// Add a user-defined theme:
315+
repl.addTheme( 'myTheme', {
316+
'keyword': 'red',
317+
'variable': 'green'
318+
319+
// ...
320+
});
321+
322+
// Delete the added theme:
323+
repl.deleteTheme( 'myTheme' );
324+
325+
// ...
326+
327+
// Close the REPL:
328+
repl.close();
329+
```
330+
331+
#### REPL.prototype.renameTheme( oldName, newName )
332+
333+
Renames a specified theme in the syntax-highlighter.
334+
335+
```javascript
336+
var debug = require( '@stdlib/streams/node/debug-sink' );
337+
338+
// Create a new REPL:
339+
var repl = new REPL({
340+
'output': debug()
341+
});
342+
343+
// ...
344+
345+
// Add a user-defined theme:
346+
repl.addTheme( 'myTheme', {
347+
'keyword': 'red',
348+
'variable': 'green'
349+
350+
// ...
351+
});
352+
353+
// Rename the added theme:
354+
repl.renameTheme( 'myTheme', 'yourTheme' );
355+
356+
// ...
357+
358+
// Close the REPL:
359+
repl.close();
360+
```
361+
179362
#### REPL.prototype.load( fpath, clbk )
180363

181364
Loads and evaluates a JavaScript file line-by-line.
@@ -386,6 +569,19 @@ repl.close();
386569

387570
REPL instances support the following commands...
388571

572+
#### addTheme( name, theme )
573+
574+
Adds a syntax highlighting color theme.
575+
576+
```text
577+
// Add color theme:
578+
In [1]: addTheme( 'myTheme', { 'keyword': 'red' } )
579+
580+
// Check updated list of themes:
581+
In [2]: themes()
582+
Out[2]: [ 'stdlib-ansi-basic', 'myTheme' ]
583+
```
584+
389585
#### alias2pkg( arg )
390586

391587
Returns the package name associated with a provided alias or class instance.
@@ -597,6 +793,26 @@ In [1]: currentWorkspace
597793
Out[1]: 'base'
598794
```
599795

796+
#### deleteTheme( name )
797+
798+
Deletes a syntax highlighting color theme.
799+
800+
```text
801+
// Add a color theme:
802+
In [1]: addTheme( 'myTheme', { 'keyword': 'red' } )
803+
804+
// Check list of themes:
805+
In [2]: themes()
806+
Out[2]: [ 'stdlib-ansi-basic', 'myTheme' ]
807+
808+
// Delete the added theme:
809+
In [3]: deleteTheme( 'myTheme' )
810+
811+
// Check updated list of themes:
812+
In [4]: themes()
813+
Out[4]: [ 'stdlib-ansi-basic' ]
814+
```
815+
600816
#### deeprerequire( id )
601817

602818
Re-imports a module, JSON, or local file and all of its associated module dependencies.
@@ -695,6 +911,21 @@ In [1]: example( base.sin )
695911

696912
**Note**: only direct instances of documented built-in constructors are supported.
697913

914+
#### getTheme( \[name] )
915+
916+
Returns a syntax highlighting color theme.
917+
918+
```text
919+
// Add a color theme:
920+
In [1]: addTheme( 'myTheme', { 'keyword': 'red' } )
921+
922+
// Get the color theme:
923+
In [2]: getTheme( 'myTheme' )
924+
Out[2]: { 'keyword': 'red' }
925+
```
926+
927+
**Note**: if no theme name is provided, the current theme is returned.
928+
698929
#### help( \[arg] )
699930

700931
Prints help text.
@@ -876,6 +1107,26 @@ Exits the REPL.
8761107
In [1]: quit()
8771108
```
8781109

1110+
#### renameTheme( oldName, newName )
1111+
1112+
Renames a syntax highlighting color theme.
1113+
1114+
```text
1115+
// Add a color theme:
1116+
In [1]: addTheme( 'myTheme', { 'keyword': 'red' } )
1117+
1118+
// Check list of themes:
1119+
In [2]: themes()
1120+
Out[2]: [ 'stdlib-ansi-basic', 'myTheme' ]
1121+
1122+
// Rename the added theme:
1123+
In [3]: getTheme( 'myTheme', 'yourTheme' )
1124+
1125+
// Check updated list of themes:
1126+
In [4]: themes()
1127+
Out[4]: [ 'stdlib-ansi-basic', 'yourTheme' ]
1128+
```
1129+
8791130
#### renameWorkspace( oldName, newName )
8801131

8811132
Renames a workspace.
@@ -1059,6 +1310,19 @@ To update a specific setting, provide a `value` argument.
10591310
In [1]: settings( 'autoClosePairs', false )
10601311
```
10611312

1313+
#### themes()
1314+
1315+
Returns a list of all available syntax highlighting color themes.
1316+
1317+
```text
1318+
// Add a color theme:
1319+
In [1]: addTheme( 'myTheme', { 'keyword': 'red' } )
1320+
1321+
// Check list of themes:
1322+
In [2]: themes()
1323+
Out[2]: [ 'stdlib-ansi-basic', 'myTheme' ]
1324+
```
1325+
10621326
#### tutorial( \[name, \[options]] )
10631327

10641328
Starts a tutorial.

0 commit comments

Comments
 (0)