Skip to content
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.

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

doc: add esm examples to node:readline #55335

Merged
merged 3 commits into from
Dec 14, 2024
Merged
Changes from 2 commits
Commits
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
158 changes: 131 additions & 27 deletions doc/api/readline.md
Original file line number Diff line number Diff line change
Expand Up @@ -703,14 +703,21 @@ added: v17.0.0
The `readlinePromises.createInterface()` method creates a new `readlinePromises.Interface`
instance.

```js
const readlinePromises = require('node:readline/promises');
const rl = readlinePromises.createInterface({
input: process.stdin,
output: process.stdout,
```mjs
import { createInterface } from 'node:readline/promises';
import { stdin, stdout } from 'node:process';
const rl = createInterface({
input: stdin,
output: stdout,
});
```

```cjs
const { createInterface } = require('node:readline/promises');
const { stdin: input, stdout: output } = require('node:process');
const rl = createInterface({ input, output });
Copy link
Member

@avivkeller avivkeller Oct 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This example and the MJS example should be as close to identical as possible, except for the import.

However, you don't need to require process in CJS

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In other words, the examples should look exactly the same (except the import + process). That way, users can ensure consistency

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

Thank you for taking the time to review the changes and give feedback to me 🙏 !

```

Once the `readlinePromises.Interface` instance is created, the most common case
is to listen for the `'line'` event:

Expand Down Expand Up @@ -960,14 +967,21 @@ changes:
The `readline.createInterface()` method creates a new `readline.Interface`
instance.

```js
const readline = require('node:readline');
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout,
```mjs
import { createInterface } from 'node:readline';
import { stdin, stdout } from 'node:process';
const rl = createInterface({
input: stdin,
output: stdout,
});
```

```cjs
const { createInterface } = require('node:readline');
const { stdin: input, stdout: output } = require('node:process');
const rl = createInterface({ input, output });
```

Once the `readline.Interface` instance is created, the most common case is to
listen for the `'line'` event:

Expand Down Expand Up @@ -1098,11 +1112,39 @@ if (process.stdin.isTTY)
The following example illustrates the use of `readline.Interface` class to
implement a small command-line interface:

```js
const readline = require('node:readline');
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout,
```mjs
import { createInterface } from 'node:readline';
import { exit, stdin, stdout } from 'node:process';
const rl = createInterface({
input: stdin,
output: stdout,
prompt: 'OHAI> ',
});

rl.prompt();

rl.on('line', (line) => {
switch (line.trim()) {
case 'hello':
console.log('world!');
break;
default:
console.log(`Say what? I might have heard '${line.trim()}'`);
break;
}
rl.prompt();
}).on('close', () => {
console.log('Have a great day!');
exit(0);
});
```

```cjs
const { createInterface } = require('node:readline');
const { exit, stdin, stdout } = require('node:process');
const rl = createInterface({
input: stdin,
output: stdout,
prompt: 'OHAI> ',
});

Expand All @@ -1120,7 +1162,7 @@ rl.on('line', (line) => {
rl.prompt();
}).on('close', () => {
console.log('Have a great day!');
process.exit(0);
exit(0);
});
```

Expand All @@ -1130,14 +1172,37 @@ A common use case for `readline` is to consume an input file one line at a
time. The easiest way to do so is leveraging the [`fs.ReadStream`][] API as
well as a `for await...of` loop:

```js
const fs = require('node:fs');
const readline = require('node:readline');
```mjs
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';

async function processLineByLine() {
const fileStream = fs.createReadStream('input.txt');
const fileStream = createReadStream('input.txt');

const rl = readline.createInterface({
const rl = createInterface({
input: fileStream,
crlfDelay: Infinity,
});
// Note: we use the crlfDelay option to recognize all instances of CR LF
// ('\r\n') in input.txt as a single line break.

for await (const line of rl) {
// Each line in input.txt will be successively available here as `line`.
console.log(`Line from file: ${line}`);
}
}

processLineByLine();
```

```cjs
const { createReadStream } = require('node:fs');
const { createInterface } = require('node:readline');

async function processLineByLine() {
const fileStream = createReadStream('input.txt');

const rl = createInterface({
input: fileStream,
crlfDelay: Infinity,
});
Expand All @@ -1155,12 +1220,26 @@ processLineByLine();

Alternatively, one could use the [`'line'`][] event:

```js
const fs = require('node:fs');
const readline = require('node:readline');
```mjs
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';

const rl = readline.createInterface({
input: fs.createReadStream('sample.txt'),
const rl = createInterface({
input: createReadStream('sample.txt'),
crlfDelay: Infinity,
});

rl.on('line', (line) => {
console.log(`Line from file: ${line}`);
});
```

```cjs
const { createReadStream } = require('node:fs');
const { createInterface } = require('node:readline');

const rl = createInterface({
input: createReadStream('sample.txt'),
crlfDelay: Infinity,
});

Expand All @@ -1172,7 +1251,32 @@ rl.on('line', (line) => {
Currently, `for await...of` loop can be a bit slower. If `async` / `await`
flow and speed are both essential, a mixed approach can be applied:

```js
```mjs
import { once } from 'node:events';
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';

(async function processLineByLine() {
try {
const rl = createInterface({
input: createReadStream('big-file.txt'),
crlfDelay: Infinity,
});

rl.on('line', (line) => {
// Process the line.
});

await once(rl, 'close');

console.log('File processed.');
} catch (err) {
console.error(err);
}
})();
```

```cjs
const { once } = require('node:events');
const { createReadStream } = require('node:fs');
const { createInterface } = require('node:readline');
Expand Down
Loading