repl.d.ts (19511B)
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 * import repl from 'node:repl'; 8 * ``` 9 * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/repl.js) 10 */ 11 declare module "repl" { 12 import { AsyncCompleter, Completer, Interface } 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 = ( 103 this: REPLServer, 104 evalCmd: string, 105 context: Context, 106 file: string, 107 cb: (err: Error | null, result: any) => void, 108 ) => void; 109 type REPLWriter = (this: REPLServer, obj: any) => string; 110 /** 111 * This is the default "writer" value, if none is passed in the REPL options, 112 * and it can be overridden by custom print functions. 113 */ 114 const writer: REPLWriter & { 115 options: InspectOptions; 116 }; 117 type REPLCommandAction = (this: REPLServer, text: string) => void; 118 interface REPLCommand { 119 /** 120 * Help text to be displayed when `.help` is entered. 121 */ 122 help?: string | undefined; 123 /** 124 * The function to execute, optionally accepting a single string argument. 125 */ 126 action: REPLCommandAction; 127 } 128 /** 129 * Instances of `repl.REPLServer` are created using the {@link start} method 130 * or directly using the JavaScript `new` keyword. 131 * 132 * ```js 133 * import repl from 'node:repl'; 134 * 135 * const options = { useColors: true }; 136 * 137 * const firstInstance = repl.start(options); 138 * const secondInstance = new repl.REPLServer(options); 139 * ``` 140 * @since v0.1.91 141 */ 142 class REPLServer extends Interface { 143 /** 144 * The `vm.Context` provided to the `eval` function to be used for JavaScript 145 * evaluation. 146 */ 147 readonly context: Context; 148 /** 149 * @deprecated since v14.3.0 - Use `input` instead. 150 */ 151 readonly inputStream: NodeJS.ReadableStream; 152 /** 153 * @deprecated since v14.3.0 - Use `output` instead. 154 */ 155 readonly outputStream: NodeJS.WritableStream; 156 /** 157 * The `Readable` stream from which REPL input will be read. 158 */ 159 readonly input: NodeJS.ReadableStream; 160 /** 161 * The `Writable` stream to which REPL output will be written. 162 */ 163 readonly output: NodeJS.WritableStream; 164 /** 165 * The commands registered via `replServer.defineCommand()`. 166 */ 167 readonly commands: NodeJS.ReadOnlyDict<REPLCommand>; 168 /** 169 * A value indicating whether the REPL is currently in "editor mode". 170 * 171 * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_commands_and_special_keys 172 */ 173 readonly editorMode: boolean; 174 /** 175 * A value indicating whether the `_` variable has been assigned. 176 * 177 * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable 178 */ 179 readonly underscoreAssigned: boolean; 180 /** 181 * The last evaluation result from the REPL (assigned to the `_` variable inside of the REPL). 182 * 183 * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable 184 */ 185 readonly last: any; 186 /** 187 * A value indicating whether the `_error` variable has been assigned. 188 * 189 * @since v9.8.0 190 * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable 191 */ 192 readonly underscoreErrAssigned: boolean; 193 /** 194 * The last error raised inside the REPL (assigned to the `_error` variable inside of the REPL). 195 * 196 * @since v9.8.0 197 * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable 198 */ 199 readonly lastError: any; 200 /** 201 * Specified in the REPL options, this is the function to be used when evaluating each 202 * given line of input. If not specified in the REPL options, this is an async wrapper 203 * for the JavaScript `eval()` function. 204 */ 205 readonly eval: REPLEval; 206 /** 207 * Specified in the REPL options, this is a value indicating whether the default 208 * `writer` function should include ANSI color styling to REPL output. 209 */ 210 readonly useColors: boolean; 211 /** 212 * Specified in the REPL options, this is a value indicating whether the default `eval` 213 * function will use the JavaScript `global` as the context as opposed to creating a new 214 * separate context for the REPL instance. 215 */ 216 readonly useGlobal: boolean; 217 /** 218 * Specified in the REPL options, this is a value indicating whether the default `writer` 219 * function should output the result of a command if it evaluates to `undefined`. 220 */ 221 readonly ignoreUndefined: boolean; 222 /** 223 * Specified in the REPL options, this is the function to invoke to format the output of 224 * each command before writing to `outputStream`. If not specified in the REPL options, 225 * this will be a wrapper for `util.inspect`. 226 */ 227 readonly writer: REPLWriter; 228 /** 229 * Specified in the REPL options, this is the function to use for custom Tab auto-completion. 230 */ 231 readonly completer: Completer | AsyncCompleter; 232 /** 233 * Specified in the REPL options, this is a flag that specifies whether the default `eval` 234 * function should execute all JavaScript commands in strict mode or default (sloppy) mode. 235 * Possible values are: 236 * - `repl.REPL_MODE_SLOPPY` - evaluates expressions in sloppy mode. 237 * - `repl.REPL_MODE_STRICT` - evaluates expressions in strict mode. This is equivalent to 238 * prefacing every repl statement with `'use strict'`. 239 */ 240 readonly replMode: typeof REPL_MODE_SLOPPY | typeof REPL_MODE_STRICT; 241 /** 242 * NOTE: According to the documentation: 243 * 244 * > Instances of `repl.REPLServer` are created using the `repl.start()` method and 245 * > _should not_ be created directly using the JavaScript `new` keyword. 246 * 247 * `REPLServer` cannot be subclassed due to implementation specifics in NodeJS. 248 * 249 * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_class_replserver 250 */ 251 private constructor(); 252 /** 253 * The `replServer.defineCommand()` method is used to add new `.`\-prefixed commands 254 * 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 255 * properties: 256 * 257 * The following example shows two new commands added to the REPL instance: 258 * 259 * ```js 260 * import repl from 'node:repl'; 261 * 262 * const replServer = repl.start({ prompt: '> ' }); 263 * replServer.defineCommand('sayhello', { 264 * help: 'Say hello', 265 * action(name) { 266 * this.clearBufferedCommand(); 267 * console.log(`Hello, ${name}!`); 268 * this.displayPrompt(); 269 * } 270 * }); 271 * replServer.defineCommand('saybye', function saybye() { 272 * console.log('Goodbye!'); 273 * this.close(); 274 * }); 275 * ``` 276 * 277 * The new commands can then be used from within the REPL instance: 278 * 279 * ```console 280 * > .sayhello Node.js User 281 * Hello, Node.js User! 282 * > .saybye 283 * Goodbye! 284 * ``` 285 * @since v0.3.0 286 * @param keyword The command keyword (*without* a leading `.` character). 287 * @param cmd The function to invoke when the command is processed. 288 */ 289 defineCommand(keyword: string, cmd: REPLCommandAction | REPLCommand): void; 290 /** 291 * The `replServer.displayPrompt()` method readies the REPL instance for input 292 * from the user, printing the configured `prompt` to a new line in the `output` and resuming the `input` to accept new input. 293 * 294 * When multi-line input is being entered, an ellipsis is printed rather than the 295 * 'prompt'. 296 * 297 * When `preserveCursor` is `true`, the cursor placement will not be reset to `0`. 298 * 299 * The `replServer.displayPrompt` method is primarily intended to be called from 300 * within the action function for commands registered using the`replServer.defineCommand()` method. 301 * @since v0.1.91 302 */ 303 displayPrompt(preserveCursor?: boolean): void; 304 /** 305 * The `replServer.clearBufferedCommand()` method clears any command that has been 306 * buffered but not yet executed. This method is primarily intended to be 307 * called from within the action function for commands registered using the`replServer.defineCommand()` method. 308 * @since v9.0.0 309 */ 310 clearBufferedCommand(): void; 311 /** 312 * Initializes a history log file for the REPL instance. When executing the 313 * Node.js binary and using the command-line REPL, a history file is initialized 314 * by default. However, this is not the case when creating a REPL 315 * programmatically. Use this method to initialize a history log file when working 316 * with REPL instances programmatically. 317 * @since v11.10.0 318 * @param historyPath the path to the history file 319 * @param callback called when history writes are ready or upon error 320 */ 321 setupHistory(path: string, callback: (err: Error | null, repl: this) => void): void; 322 /** 323 * events.EventEmitter 324 * 1. close - inherited from `readline.Interface` 325 * 2. line - inherited from `readline.Interface` 326 * 3. pause - inherited from `readline.Interface` 327 * 4. resume - inherited from `readline.Interface` 328 * 5. SIGCONT - inherited from `readline.Interface` 329 * 6. SIGINT - inherited from `readline.Interface` 330 * 7. SIGTSTP - inherited from `readline.Interface` 331 * 8. exit 332 * 9. reset 333 */ 334 addListener(event: string, listener: (...args: any[]) => void): this; 335 addListener(event: "close", listener: () => void): this; 336 addListener(event: "line", listener: (input: string) => void): this; 337 addListener(event: "pause", listener: () => void): this; 338 addListener(event: "resume", listener: () => void): this; 339 addListener(event: "SIGCONT", listener: () => void): this; 340 addListener(event: "SIGINT", listener: () => void): this; 341 addListener(event: "SIGTSTP", listener: () => void): this; 342 addListener(event: "exit", listener: () => void): this; 343 addListener(event: "reset", listener: (context: Context) => void): this; 344 emit(event: string | symbol, ...args: any[]): boolean; 345 emit(event: "close"): boolean; 346 emit(event: "line", input: string): boolean; 347 emit(event: "pause"): boolean; 348 emit(event: "resume"): boolean; 349 emit(event: "SIGCONT"): boolean; 350 emit(event: "SIGINT"): boolean; 351 emit(event: "SIGTSTP"): boolean; 352 emit(event: "exit"): boolean; 353 emit(event: "reset", context: Context): boolean; 354 on(event: string, listener: (...args: any[]) => void): this; 355 on(event: "close", listener: () => void): this; 356 on(event: "line", listener: (input: string) => void): this; 357 on(event: "pause", listener: () => void): this; 358 on(event: "resume", listener: () => void): this; 359 on(event: "SIGCONT", listener: () => void): this; 360 on(event: "SIGINT", listener: () => void): this; 361 on(event: "SIGTSTP", listener: () => void): this; 362 on(event: "exit", listener: () => void): this; 363 on(event: "reset", listener: (context: Context) => void): this; 364 once(event: string, listener: (...args: any[]) => void): this; 365 once(event: "close", listener: () => void): this; 366 once(event: "line", listener: (input: string) => void): this; 367 once(event: "pause", listener: () => void): this; 368 once(event: "resume", listener: () => void): this; 369 once(event: "SIGCONT", listener: () => void): this; 370 once(event: "SIGINT", listener: () => void): this; 371 once(event: "SIGTSTP", listener: () => void): this; 372 once(event: "exit", listener: () => void): this; 373 once(event: "reset", listener: (context: Context) => void): this; 374 prependListener(event: string, listener: (...args: any[]) => void): this; 375 prependListener(event: "close", listener: () => void): this; 376 prependListener(event: "line", listener: (input: string) => void): this; 377 prependListener(event: "pause", listener: () => void): this; 378 prependListener(event: "resume", listener: () => void): this; 379 prependListener(event: "SIGCONT", listener: () => void): this; 380 prependListener(event: "SIGINT", listener: () => void): this; 381 prependListener(event: "SIGTSTP", listener: () => void): this; 382 prependListener(event: "exit", listener: () => void): this; 383 prependListener(event: "reset", listener: (context: Context) => void): this; 384 prependOnceListener(event: string, listener: (...args: any[]) => void): this; 385 prependOnceListener(event: "close", listener: () => void): this; 386 prependOnceListener(event: "line", listener: (input: string) => void): this; 387 prependOnceListener(event: "pause", listener: () => void): this; 388 prependOnceListener(event: "resume", listener: () => void): this; 389 prependOnceListener(event: "SIGCONT", listener: () => void): this; 390 prependOnceListener(event: "SIGINT", listener: () => void): this; 391 prependOnceListener(event: "SIGTSTP", listener: () => void): this; 392 prependOnceListener(event: "exit", listener: () => void): this; 393 prependOnceListener(event: "reset", listener: (context: Context) => void): this; 394 } 395 /** 396 * A flag passed in the REPL options. Evaluates expressions in sloppy mode. 397 */ 398 const REPL_MODE_SLOPPY: unique symbol; 399 /** 400 * A flag passed in the REPL options. Evaluates expressions in strict mode. 401 * This is equivalent to prefacing every repl statement with `'use strict'`. 402 */ 403 const REPL_MODE_STRICT: unique symbol; 404 /** 405 * The `repl.start()` method creates and starts a {@link REPLServer} instance. 406 * 407 * If `options` is a string, then it specifies the input prompt: 408 * 409 * ```js 410 * import repl from 'node:repl'; 411 * 412 * // a Unix style prompt 413 * repl.start('$ '); 414 * ``` 415 * @since v0.1.91 416 */ 417 function start(options?: string | ReplOptions): REPLServer; 418 /** 419 * Indicates a recoverable error that a `REPLServer` can use to support multi-line input. 420 * 421 * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_recoverable_errors 422 */ 423 class Recoverable extends SyntaxError { 424 err: Error; 425 constructor(err: Error); 426 } 427 } 428 declare module "node:repl" { 429 export * from "repl"; 430 }