@@ -309,6 +309,43 @@ rl.write(null, { ctrl: true, name: 'u' });
309
309
The ` rl.write() ` method will write the data to the ` readline ` ` Interface ` 's
310
310
` input ` * as if it were provided by the user* .
311
311
312
+ ### rl\[ Symbol.asyncIterator\] ()
313
+ <!-- YAML
314
+ added: REPLACEME
315
+ -->
316
+
317
+ > Stability: 1 - Experimental
318
+
319
+ * Returns: {AsyncIterator}
320
+
321
+ Create an ` AsyncIterator ` object that iterates through each line in the input
322
+ stream as a string. This method allows asynchronous iteration of
323
+ ` readline.Interface ` objects through ` for ` -` await ` -` of ` loops.
324
+
325
+ Errors in the input stream are not forwarded.
326
+
327
+ If the loop is terminated with ` break ` , ` throw ` , or ` return ` ,
328
+ [ ` rl.close() ` ] [ ] will be called. In other words, iterating over a
329
+ ` readline.Interface ` will always consume the input stream fully.
330
+
331
+ A caveat with using this experimental API is that the performance is
332
+ currently not on par with the traditional ` 'line' ` event API, and thus it is
333
+ not recommended for performance-sensitive applications. We expect this
334
+ situation to improve in the future.
335
+
336
+ ``` js
337
+ async function processLineByLine () {
338
+ const rl = readline .createInterface ({
339
+ // ...
340
+ });
341
+
342
+ for await (const line of rl ) {
343
+ // Each line in the readline input will be successively available here as
344
+ // `line`.
345
+ }
346
+ }
347
+ ```
348
+
312
349
## readline.clearLine(stream, dir)
313
350
<!-- YAML
314
351
added: v0.7.7
@@ -517,12 +554,38 @@ rl.on('line', (line) => {
517
554
518
555
## Example: Read File Stream Line-by-Line
519
556
520
- A common use case for ` readline ` is to consume input from a filesystem
521
- [ Readable] [ ] stream one line at a time:
557
+ A common use case for ` readline ` is to consume an input file one line at a
558
+ time. The easiest way to do so is leveraging the [ ` fs.ReadStream ` ] [ ] API as
559
+ well as a ` for ` -` await ` -` of ` loop:
522
560
523
561
``` js
562
+ const fs = require (' fs' );
524
563
const readline = require (' readline' );
564
+
565
+ async function processLineByLine () {
566
+ const fileStream = fs .createReadStream (' input.txt' );
567
+
568
+ const rl = readline .createInterface ({
569
+ input: fileStream,
570
+ crlfDelay: Infinity
571
+ });
572
+ // Note: we use the crlfDelay option to recognize all instances of CR LF
573
+ // ('\r\n') in input.txt as a single line break.
574
+
575
+ for await (const line of rl ) {
576
+ // Each line in input.txt will be successively available here as `line`.
577
+ console .log (` Line from file: ${ line} ` );
578
+ }
579
+ }
580
+
581
+ processLineByLine ();
582
+ ```
583
+
584
+ Alternatively, one could use the [ ` 'line' ` ] [ ] event:
585
+
586
+ ``` js
525
587
const fs = require (' fs' );
588
+ const readline = require (' readline' );
526
589
527
590
const rl = readline .createInterface ({
528
591
input: fs .createReadStream (' sample.txt' ),
@@ -536,8 +599,11 @@ rl.on('line', (line) => {
536
599
537
600
[ `'SIGCONT'` ] : readline.html#readline_event_sigcont
538
601
[ `'SIGTSTP'` ] : readline.html#readline_event_sigtstp
602
+ [ `'line'` ] : #readline_event_line
603
+ [ `fs.ReadStream` ] : fs.html#fs_class_fs_readstream
539
604
[ `process.stdin` ] : process.html#process_process_stdin
540
605
[ `process.stdout` ] : process.html#process_process_stdout
606
+ [ `rl.close()` ] : #readline_rl_close
541
607
[ Readable ] : stream.html#stream_readable_streams
542
608
[ TTY ] : tty.html
543
609
[ Writable ] : stream.html#stream_writable_streams
0 commit comments