Skip to content

doc: document REPL custom eval arguments #57690

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 1, 2025
Merged

doc: document REPL custom eval arguments #57690

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 28 additions & 6 deletions doc/api/repl.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -303,7 +303,19 @@ When a new [`repl.REPLServer`][] is created, a custom evaluation function may be
provided. This can be used, for instance, to implement fully customized REPL
applications.

The following illustrates an example of a REPL that squares a given number:
An evaluation function accepts the following four arguments:

* `code` {string} The code to be executed (e.g. `1 + 1`).
* `context` {Object} The context in which the code is executed. This can either be the JavaScript `global`
context or a context specific to the REPL instance, depending on the `useGlobal` option.
* `replResourceName` {string} An identifier for the REPL resource associated with the current code
evaluation. This can be useful for debugging purposes.
* `callback` {Function} A function to invoke once the code evaluation is complete. The callback takes two parameters:
* An error object to provide if an error occurred during evaluation, or `null`/`undefined` if no error occurred.
* The result of the code evaluation (this is not relevant if an error is provided).

The following illustrates an example of a REPL that squares a given number, an error is instead printed
if the provided input is not actually a number:

```mjs
import repl from 'node:repl';
Expand All @@ -312,8 +324,12 @@ function byThePowerOfTwo(number) {
return number * number;
}

function myEval(cmd, context, filename, callback) {
callback(null, byThePowerOfTwo(cmd));
function myEval(code, context, replResourceName, callback) {
if (isNaN(code)) {
callback(new Error(`${code.trim()} is not a number`));
} else {
callback(null, byThePowerOfTwo(code));
}
}

repl.start({ prompt: 'Enter a number: ', eval: myEval });
Expand All @@ -326,8 +342,12 @@ function byThePowerOfTwo(number) {
return number * number;
}

function myEval(cmd, context, filename, callback) {
callback(null, byThePowerOfTwo(cmd));
function myEval(code, context, replResourceName, callback) {
if (isNaN(code)) {
callback(new Error(`${code.trim()} is not a number`));
} else {
callback(null, byThePowerOfTwo(code));
}
}

repl.start({ prompt: 'Enter a number: ', eval: myEval });
Expand Down Expand Up @@ -691,7 +711,8 @@ changes:
* `eval` {Function} The function to be used when evaluating each given line
of input. **Default:** an async wrapper for the JavaScript `eval()`
function. An `eval` function can error with `repl.Recoverable` to indicate
the input was incomplete and prompt for additional lines.
the input was incomplete and prompt for additional lines. See the
[custom evaluation functions][] section for more details.
* `useColors` {boolean} If `true`, specifies that the default `writer`
function should include ANSI color styling to REPL output. If a custom
`writer` function is provided then this has no effect. **Default:** checking
Expand Down Expand Up @@ -914,4 +935,5 @@ avoiding open network interfaces.
[`repl.start()`]: #replstartoptions
[`reverse-i-search`]: #reverse-i-search
[`util.inspect()`]: util.md#utilinspectobject-options
[custom evaluation functions]: #custom-evaluation-functions
[stream]: stream.md
Loading