@@ -303,7 +303,19 @@ When a new [`repl.REPLServer`][] is created, a custom evaluation function may be |
303 | 303 | provided. This can be used, for instance, to implement fully customized REPL |
304 | 304 | applications. |
305 | 305 |
|
306 | | -The following illustrates an example of a REPL that squares a given number: |
| 306 | +An evaluation function accepts the following four arguments: |
| 307 | + |
| 308 | +* `code` {string} The code to be executed (e.g. `1 + 1`). |
| 309 | +* `context` {Object} The context in which the code is executed. This can either be the JavaScript `global` |
| 310 | + context or a context specific to the REPL instance, depending on the `useGlobal` option. |
| 311 | +* `replResourceName` {string} An identifier for the REPL resource associated with the current code |
| 312 | + evaluation. This can be useful for debugging purposes. |
| 313 | +* `callback` {Function} A function to invoke once the code evaluation is complete. The callback takes two parameters: |
| 314 | + * An error object to provide if an error occurred during evaluation, or `null`/`undefined` if no error occurred. |
| 315 | + * The result of the code evaluation (this is not relevant if an error is provided). |
| 316 | + |
| 317 | +The following illustrates an example of a REPL that squares a given number, an error is instead printed |
| 318 | +if the provided input is not actually a number: |
307 | 319 |
|
308 | 320 | ```mjs |
309 | 321 | import repl from 'node:repl'; |
@@ -312,8 +324,12 @@ function byThePowerOfTwo(number) { |
312 | 324 | return number * number; |
313 | 325 | } |
314 | 326 |
|
315 | | -function myEval(cmd, context, filename, callback) { |
316 | | - callback(null, byThePowerOfTwo(cmd)); |
| 327 | +function myEval(code, context, replResourceName, callback) { |
| 328 | + if (isNaN(code)) { |
| 329 | + callback(new Error(`${code.trim()} is not a number`)); |
| 330 | + } else { |
| 331 | + callback(null, byThePowerOfTwo(code)); |
| 332 | + } |
317 | 333 | } |
318 | 334 |
|
319 | 335 | repl.start({ prompt: 'Enter a number: ', eval: myEval }); |
@@ -326,8 +342,12 @@ function byThePowerOfTwo(number) { |
326 | 342 | return number * number; |
327 | 343 | } |
328 | 344 |
|
329 | | -function myEval(cmd, context, filename, callback) { |
330 | | - callback(null, byThePowerOfTwo(cmd)); |
| 345 | +function myEval(code, context, replResourceName, callback) { |
| 346 | + if (isNaN(code)) { |
| 347 | + callback(new Error(`${code.trim()} is not a number`)); |
| 348 | + } else { |
| 349 | + callback(null, byThePowerOfTwo(code)); |
| 350 | + } |
331 | 351 | } |
332 | 352 |
|
333 | 353 | repl.start({ prompt: 'Enter a number: ', eval: myEval }); |
@@ -691,7 +711,8 @@ changes: |
691 | 711 | * `eval` {Function} The function to be used when evaluating each given line |
692 | 712 | of input. **Default:** an async wrapper for the JavaScript `eval()` |
693 | 713 | function. An `eval` function can error with `repl.Recoverable` to indicate |
694 | | - the input was incomplete and prompt for additional lines. |
| 714 | + the input was incomplete and prompt for additional lines. See the |
| 715 | + [custom evaluation functions][] section for more details. |
695 | 716 | * `useColors` {boolean} If `true`, specifies that the default `writer` |
696 | 717 | function should include ANSI color styling to REPL output. If a custom |
697 | 718 | `writer` function is provided then this has no effect. **Default:** checking |
@@ -914,4 +935,5 @@ avoiding open network interfaces. |
914 | 935 | [`repl.start()`]: #replstartoptions |
915 | 936 | [`reverse-i-search`]: #reverse-i-search |
916 | 937 | [`util.inspect()`]: util.md#utilinspectobject-options |
| 938 | +[custom evaluation functions]: #custom-evaluation-functions |
917 | 939 | [stream]: stream.md |