1 | /**
|
2 | * The `repl` module provides a Read-Eval-Print-Loop (REPL) implementation that
|
3 | * is available both as a standalone program or includible in other applications.
|
4 | * It can be accessed using:
|
5 | *
|
6 | * ```js
|
7 | * const repl = require('repl');
|
8 | * ```
|
9 | * @see [source](https://github.com/nodejs/node/blob/v16.4.2/lib/repl.js)
|
10 | */
|
11 | declare module 'repl' {
|
12 | import { Interface, Completer, AsyncCompleter } from 'node:readline';
|
13 | import { Context } from 'node:vm';
|
14 | import { InspectOptions } from 'node:util';
|
15 | interface ReplOptions {
|
16 | /**
|
17 | * The input prompt to display.
|
18 | * @default "> "
|
19 | */
|
20 | prompt?: string | undefined;
|
21 | /**
|
22 | * The `Readable` stream from which REPL input will be read.
|
23 | * @default process.stdin
|
24 | */
|
25 | input?: NodeJS.ReadableStream | undefined;
|
26 | /**
|
27 | * The `Writable` stream to which REPL output will be written.
|
28 | * @default process.stdout
|
29 | */
|
30 | output?: NodeJS.WritableStream | undefined;
|
31 | /**
|
32 | * If `true`, specifies that the output should be treated as a TTY terminal, and have
|
33 | * ANSI/VT100 escape codes written to it.
|
34 | * Default: checking the value of the `isTTY` property on the output stream upon
|
35 | * instantiation.
|
36 | */
|
37 | terminal?: boolean | undefined;
|
38 | /**
|
39 | * The function to be used when evaluating each given line of input.
|
40 | * Default: an async wrapper for the JavaScript `eval()` function. An `eval` function can
|
41 | * error with `repl.Recoverable` to indicate the input was incomplete and prompt for
|
42 | * additional lines.
|
43 | *
|
44 | * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_default_evaluation
|
45 | * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_custom_evaluation_functions
|
46 | */
|
47 | eval?: REPLEval | undefined;
|
48 | /**
|
49 | * Defines if the repl prints output previews or not.
|
50 | * @default `true` Always `false` in case `terminal` is falsy.
|
51 | */
|
52 | preview?: boolean | undefined;
|
53 | /**
|
54 | * If `true`, specifies that the default `writer` function should include ANSI color
|
55 | * styling to REPL output. If a custom `writer` function is provided then this has no
|
56 | * effect.
|
57 | * Default: the REPL instance's `terminal` value.
|
58 | */
|
59 | useColors?: boolean | undefined;
|
60 | /**
|
61 | * If `true`, specifies that the default evaluation function will use the JavaScript
|
62 | * `global` as the context as opposed to creating a new separate context for the REPL
|
63 | * instance. The node CLI REPL sets this value to `true`.
|
64 | * Default: `false`.
|
65 | */
|
66 | useGlobal?: boolean | undefined;
|
67 | /**
|
68 | * If `true`, specifies that the default writer will not output the return value of a
|
69 | * command if it evaluates to `undefined`.
|
70 | * Default: `false`.
|
71 | */
|
72 | ignoreUndefined?: boolean | undefined;
|
73 | /**
|
74 | * The function to invoke to format the output of each command before writing to `output`.
|
75 | * Default: a wrapper for `util.inspect`.
|
76 | *
|
77 | * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_customizing_repl_output
|
78 | */
|
79 | writer?: REPLWriter | undefined;
|
80 | /**
|
81 | * An optional function used for custom Tab auto completion.
|
82 | *
|
83 | * @see https://nodejs.org/dist/latest-v11.x/docs/api/readline.html#readline_use_of_the_completer_function
|
84 | */
|
85 | completer?: Completer | AsyncCompleter | undefined;
|
86 | /**
|
87 | * A flag that specifies whether the default evaluator executes all JavaScript commands in
|
88 | * strict mode or default (sloppy) mode.
|
89 | * Accepted values are:
|
90 | * - `repl.REPL_MODE_SLOPPY` - evaluates expressions in sloppy mode.
|
91 | * - `repl.REPL_MODE_STRICT` - evaluates expressions in strict mode. This is equivalent to
|
92 | * prefacing every repl statement with `'use strict'`.
|
93 | */
|
94 | replMode?: typeof REPL_MODE_SLOPPY | typeof REPL_MODE_STRICT | undefined;
|
95 | /**
|
96 | * Stop evaluating the current piece of code when `SIGINT` is received, i.e. `Ctrl+C` is
|
97 | * pressed. This cannot be used together with a custom `eval` function.
|
98 | * Default: `false`.
|
99 | */
|
100 | breakEvalOnSigint?: boolean | undefined;
|
101 | }
|
102 | type REPLEval = (this: REPLServer, evalCmd: string, context: Context, file: string, cb: (err: Error | null, result: any) => void) => void;
|
103 | type REPLWriter = (this: REPLServer, obj: any) => string;
|
104 | /**
|
105 | * This is the default "writer" value, if none is passed in the REPL options,
|
106 | * and it can be overridden by custom print functions.
|
107 | */
|
108 | const writer: REPLWriter & {
|
109 | options: InspectOptions;
|
110 | };
|
111 | type REPLCommandAction = (this: REPLServer, text: string) => void;
|
112 | interface REPLCommand {
|
113 | /**
|
114 | * Help text to be displayed when `.help` is entered.
|
115 | */
|
116 | help?: string | undefined;
|
117 | /**
|
118 | * The function to execute, optionally accepting a single string argument.
|
119 | */
|
120 | action: REPLCommandAction;
|
121 | }
|
122 | /**
|
123 | * Instances of `repl.REPLServer` are created using the {@link start} method
|
124 | * or directly using the JavaScript `new` keyword.
|
125 | *
|
126 | * ```js
|
127 | * const repl = require('repl');
|
128 | *
|
129 | * const options = { useColors: true };
|
130 | *
|
131 | * const firstInstance = repl.start(options);
|
132 | * const secondInstance = new repl.REPLServer(options);
|
133 | * ```
|
134 | * @since v0.1.91
|
135 | */
|
136 | class REPLServer extends Interface {
|
137 | /**
|
138 | * The `vm.Context` provided to the `eval` function to be used for JavaScript
|
139 | * evaluation.
|
140 | */
|
141 | readonly context: Context;
|
142 | /**
|
143 | * @deprecated since v14.3.0 - Use `input` instead.
|
144 | */
|
145 | readonly inputStream: NodeJS.ReadableStream;
|
146 | /**
|
147 | * @deprecated since v14.3.0 - Use `output` instead.
|
148 | */
|
149 | readonly outputStream: NodeJS.WritableStream;
|
150 | /**
|
151 | * The `Readable` stream from which REPL input will be read.
|
152 | */
|
153 | readonly input: NodeJS.ReadableStream;
|
154 | /**
|
155 | * The `Writable` stream to which REPL output will be written.
|
156 | */
|
157 | readonly output: NodeJS.WritableStream;
|
158 | /**
|
159 | * The commands registered via `replServer.defineCommand()`.
|
160 | */
|
161 | readonly commands: NodeJS.ReadOnlyDict<REPLCommand>;
|
162 | /**
|
163 | * A value indicating whether the REPL is currently in "editor mode".
|
164 | *
|
165 | * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_commands_and_special_keys
|
166 | */
|
167 | readonly editorMode: boolean;
|
168 | /**
|
169 | * A value indicating whether the `_` variable has been assigned.
|
170 | *
|
171 | * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
|
172 | */
|
173 | readonly underscoreAssigned: boolean;
|
174 | /**
|
175 | * The last evaluation result from the REPL (assigned to the `_` variable inside of the REPL).
|
176 | *
|
177 | * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
|
178 | */
|
179 | readonly last: any;
|
180 | /**
|
181 | * A value indicating whether the `_error` variable has been assigned.
|
182 | *
|
183 | * @since v9.8.0
|
184 | * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
|
185 | */
|
186 | readonly underscoreErrAssigned: boolean;
|
187 | /**
|
188 | * The last error raised inside the REPL (assigned to the `_error` variable inside of the REPL).
|
189 | *
|
190 | * @since v9.8.0
|
191 | * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
|
192 | */
|
193 | readonly lastError: any;
|
194 | /**
|
195 | * Specified in the REPL options, this is the function to be used when evaluating each
|
196 | * given line of input. If not specified in the REPL options, this is an async wrapper
|
197 | * for the JavaScript `eval()` function.
|
198 | */
|
199 | readonly eval: REPLEval;
|
200 | /**
|
201 | * Specified in the REPL options, this is a value indicating whether the default
|
202 | * `writer` function should include ANSI color styling to REPL output.
|
203 | */
|
204 | readonly useColors: boolean;
|
205 | /**
|
206 | * Specified in the REPL options, this is a value indicating whether the default `eval`
|
207 | * function will use the JavaScript `global` as the context as opposed to creating a new
|
208 | * separate context for the REPL instance.
|
209 | */
|
210 | readonly useGlobal: boolean;
|
211 | /**
|
212 | * Specified in the REPL options, this is a value indicating whether the default `writer`
|
213 | * function should output the result of a command if it evaluates to `undefined`.
|
214 | */
|
215 | readonly ignoreUndefined: boolean;
|
216 | /**
|
217 | * Specified in the REPL options, this is the function to invoke to format the output of
|
218 | * each command before writing to `outputStream`. If not specified in the REPL options,
|
219 | * this will be a wrapper for `util.inspect`.
|
220 | */
|
221 | readonly writer: REPLWriter;
|
222 | /**
|
223 | * Specified in the REPL options, this is the function to use for custom Tab auto-completion.
|
224 | */
|
225 | readonly completer: Completer | AsyncCompleter;
|
226 | /**
|
227 | * Specified in the REPL options, this is a flag that specifies whether the default `eval`
|
228 | * function should execute all JavaScript commands in strict mode or default (sloppy) mode.
|
229 | * Possible values are:
|
230 | * - `repl.REPL_MODE_SLOPPY` - evaluates expressions in sloppy mode.
|
231 | * - `repl.REPL_MODE_STRICT` - evaluates expressions in strict mode. This is equivalent to
|
232 | * prefacing every repl statement with `'use strict'`.
|
233 | */
|
234 | readonly replMode: typeof REPL_MODE_SLOPPY | typeof REPL_MODE_STRICT;
|
235 | /**
|
236 | * NOTE: According to the documentation:
|
237 | *
|
238 | * > Instances of `repl.REPLServer` are created using the `repl.start()` method and
|
239 | * > _should not_ be created directly using the JavaScript `new` keyword.
|
240 | *
|
241 | * `REPLServer` cannot be subclassed due to implementation specifics in NodeJS.
|
242 | *
|
243 | * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_class_replserver
|
244 | */
|
245 | private constructor();
|
246 | /**
|
247 | * The `replServer.defineCommand()` method is used to add new `.`\-prefixed commands
|
248 | * to the REPL instance. Such commands are invoked by typing a `.` followed by the`keyword`. The `cmd` is either a `Function` or an `Object` with the following
|
249 | * properties:
|
250 | *
|
251 | * The following example shows two new commands added to the REPL instance:
|
252 | *
|
253 | * ```js
|
254 | * const repl = require('repl');
|
255 | *
|
256 | * const replServer = repl.start({ prompt: '> ' });
|
257 | * replServer.defineCommand('sayhello', {
|
258 | * help: 'Say hello',
|
259 | * action(name) {
|
260 | * this.clearBufferedCommand();
|
261 | * console.log(`Hello, ${name}!`);
|
262 | * this.displayPrompt();
|
263 | * }
|
264 | * });
|
265 | * replServer.defineCommand('saybye', function saybye() {
|
266 | * console.log('Goodbye!');
|
267 | * this.close();
|
268 | * });
|
269 | * ```
|
270 | *
|
271 | * The new commands can then be used from within the REPL instance:
|
272 | *
|
273 | * ```console
|
274 | * > .sayhello Node.js User
|
275 | * Hello, Node.js User!
|
276 | * > .saybye
|
277 | * Goodbye!
|
278 | * ```
|
279 | * @since v0.3.0
|
280 | * @param keyword The command keyword (*without* a leading `.` character).
|
281 | * @param cmd The function to invoke when the command is processed.
|
282 | */
|
283 | defineCommand(keyword: string, cmd: REPLCommandAction | REPLCommand): void;
|
284 | /**
|
285 | * The `replServer.displayPrompt()` method readies the REPL instance for input
|
286 | * from the user, printing the configured `prompt` to a new line in the `output`and resuming the `input` to accept new input.
|
287 | *
|
288 | * When multi-line input is being entered, an ellipsis is printed rather than the
|
289 | * 'prompt'.
|
290 | *
|
291 | * When `preserveCursor` is `true`, the cursor placement will not be reset to `0`.
|
292 | *
|
293 | * The `replServer.displayPrompt` method is primarily intended to be called from
|
294 | * within the action function for commands registered using the`replServer.defineCommand()` method.
|
295 | * @since v0.1.91
|
296 | */
|
297 | displayPrompt(preserveCursor?: boolean): void;
|
298 | /**
|
299 | * The `replServer.clearBufferedCommand()` method clears any command that has been
|
300 | * buffered but not yet executed. This method is primarily intended to be
|
301 | * called from within the action function for commands registered using the`replServer.defineCommand()` method.
|
302 | * @since v9.0.0
|
303 | */
|
304 | clearBufferedCommand(): void;
|
305 | /**
|
306 | * Initializes a history log file for the REPL instance. When executing the
|
307 | * Node.js binary and using the command-line REPL, a history file is initialized
|
308 | * by default. However, this is not the case when creating a REPL
|
309 | * programmatically. Use this method to initialize a history log file when working
|
310 | * with REPL instances programmatically.
|
311 | * @since v11.10.0
|
312 | * @param historyPath the path to the history file
|
313 | * @param callback called when history writes are ready or upon error
|
314 | */
|
315 | setupHistory(path: string, callback: (err: Error | null, repl: this) => void): void;
|
316 | /**
|
317 | * events.EventEmitter
|
318 | * 1. close - inherited from `readline.Interface`
|
319 | * 2. line - inherited from `readline.Interface`
|
320 | * 3. pause - inherited from `readline.Interface`
|
321 | * 4. resume - inherited from `readline.Interface`
|
322 | * 5. SIGCONT - inherited from `readline.Interface`
|
323 | * 6. SIGINT - inherited from `readline.Interface`
|
324 | * 7. SIGTSTP - inherited from `readline.Interface`
|
325 | * 8. exit
|
326 | * 9. reset
|
327 | */
|
328 | addListener(event: string, listener: (...args: any[]) => void): this;
|
329 | addListener(event: 'close', listener: () => void): this;
|
330 | addListener(event: 'line', listener: (input: string) => void): this;
|
331 | addListener(event: 'pause', listener: () => void): this;
|
332 | addListener(event: 'resume', listener: () => void): this;
|
333 | addListener(event: 'SIGCONT', listener: () => void): this;
|
334 | addListener(event: 'SIGINT', listener: () => void): this;
|
335 | addListener(event: 'SIGTSTP', listener: () => void): this;
|
336 | addListener(event: 'exit', listener: () => void): this;
|
337 | addListener(event: 'reset', listener: (context: Context) => void): this;
|
338 | emit(event: string | symbol, ...args: any[]): boolean;
|
339 | emit(event: 'close'): boolean;
|
340 | emit(event: 'line', input: string): boolean;
|
341 | emit(event: 'pause'): boolean;
|
342 | emit(event: 'resume'): boolean;
|
343 | emit(event: 'SIGCONT'): boolean;
|
344 | emit(event: 'SIGINT'): boolean;
|
345 | emit(event: 'SIGTSTP'): boolean;
|
346 | emit(event: 'exit'): boolean;
|
347 | emit(event: 'reset', context: Context): boolean;
|
348 | on(event: string, listener: (...args: any[]) => void): this;
|
349 | on(event: 'close', listener: () => void): this;
|
350 | on(event: 'line', listener: (input: string) => void): this;
|
351 | on(event: 'pause', listener: () => void): this;
|
352 | on(event: 'resume', listener: () => void): this;
|
353 | on(event: 'SIGCONT', listener: () => void): this;
|
354 | on(event: 'SIGINT', listener: () => void): this;
|
355 | on(event: 'SIGTSTP', listener: () => void): this;
|
356 | on(event: 'exit', listener: () => void): this;
|
357 | on(event: 'reset', listener: (context: Context) => void): this;
|
358 | once(event: string, listener: (...args: any[]) => void): this;
|
359 | once(event: 'close', listener: () => void): this;
|
360 | once(event: 'line', listener: (input: string) => void): this;
|
361 | once(event: 'pause', listener: () => void): this;
|
362 | once(event: 'resume', listener: () => void): this;
|
363 | once(event: 'SIGCONT', listener: () => void): this;
|
364 | once(event: 'SIGINT', listener: () => void): this;
|
365 | once(event: 'SIGTSTP', listener: () => void): this;
|
366 | once(event: 'exit', listener: () => void): this;
|
367 | once(event: 'reset', listener: (context: Context) => void): this;
|
368 | prependListener(event: string, listener: (...args: any[]) => void): this;
|
369 | prependListener(event: 'close', listener: () => void): this;
|
370 | prependListener(event: 'line', listener: (input: string) => void): this;
|
371 | prependListener(event: 'pause', listener: () => void): this;
|
372 | prependListener(event: 'resume', listener: () => void): this;
|
373 | prependListener(event: 'SIGCONT', listener: () => void): this;
|
374 | prependListener(event: 'SIGINT', listener: () => void): this;
|
375 | prependListener(event: 'SIGTSTP', listener: () => void): this;
|
376 | prependListener(event: 'exit', listener: () => void): this;
|
377 | prependListener(event: 'reset', listener: (context: Context) => void): this;
|
378 | prependOnceListener(event: string, listener: (...args: any[]) => void): this;
|
379 | prependOnceListener(event: 'close', listener: () => void): this;
|
380 | prependOnceListener(event: 'line', listener: (input: string) => void): this;
|
381 | prependOnceListener(event: 'pause', listener: () => void): this;
|
382 | prependOnceListener(event: 'resume', listener: () => void): this;
|
383 | prependOnceListener(event: 'SIGCONT', listener: () => void): this;
|
384 | prependOnceListener(event: 'SIGINT', listener: () => void): this;
|
385 | prependOnceListener(event: 'SIGTSTP', listener: () => void): this;
|
386 | prependOnceListener(event: 'exit', listener: () => void): this;
|
387 | prependOnceListener(event: 'reset', listener: (context: Context) => void): this;
|
388 | }
|
389 | /**
|
390 | * A flag passed in the REPL options. Evaluates expressions in sloppy mode.
|
391 | */
|
392 | const REPL_MODE_SLOPPY: unique symbol;
|
393 | /**
|
394 | * A flag passed in the REPL options. Evaluates expressions in strict mode.
|
395 | * This is equivalent to prefacing every repl statement with `'use strict'`.
|
396 | */
|
397 | const REPL_MODE_STRICT: unique symbol;
|
398 | /**
|
399 | * The `repl.start()` method creates and starts a { REPLServer} instance.
|
400 | *
|
401 | * If `options` is a string, then it specifies the input prompt:
|
402 | *
|
403 | * ```js
|
404 | * const repl = require('repl');
|
405 | *
|
406 | * // a Unix style prompt
|
407 | * repl.start('$ ');
|
408 | * ```
|
409 | * .1.91
v0 |
410 | */
|
411 | function start(options?: string | ReplOptions): REPLServer;
|
412 | /**
|
413 | * Indicates a recoverable error that a `REPLServer` can use to support multi-line input.
|
414 | *
|
415 | * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_recoverable_errors
|
416 | */
|
417 | class Recoverable extends SyntaxError {
|
418 | err: Error;
|
419 | constructor(err: Error);
|
420 | }
|
421 | }
|
422 | declare module 'node:repl' {
|
423 | export * from 'repl';
|
424 | }
|