byline — buffered stream for reading lines

byline is a simple module providing a LineStream.

• node v0.10 streams2 (transform stream)
• supports pipe
• supports both UNIX and Windows line endings
• supports Unicode UTS #18 line boundaries
• can wrap any readable stream
• can be used as a readable-writable "through-stream" (transform stream)
• super-simple: stream = byline(stream);

Install

npm install byline

or from source:

git clone git://github.com/jahewson/node-byline.git
cd node-byline
npm link

Convenience API

The byline module can be used as a function to quickly wrap a readable stream:

1var fs = require('fs'),
2    byline = require('byline');
3
4var stream = byline(fs.createReadStream('sample.txt', { encoding: 'utf8' }));

The data event then emits lines:

1stream.on('data', function(line) {
2  console.log(line);
3});

Standard API

You just need to add one line to wrap your readable Stream with a LineStream.

1var fs = require('fs'),	
2    byline = require('byline');
3
4var stream = fs.createReadStream('sample.txt');
5stream = byline.createStream(stream);
6
7stream.on('data', function(line) {
8  console.log(line);
9});

Piping

byline supports pipe (though it strips the line endings, of course).

1var stream = fs.createReadStream('sample.txt');
2stream = byline.createStream(stream);
3stream.pipe(fs.createWriteStream('nolines.txt'));

Alternatively, you can create a readable/writable "through-stream" which doesn't wrap any specific stream:

1var stream = fs.createReadStream('sample.txt');
2stream = byline.createStream(stream);
3stream.pipe(fs.createWriteStream('nolines.txt'));
4	
5var input = fs.createReadStream('LICENSE');
6var lineStream = byline.createStream();
7input.pipe(lineStream);
8
9var output = fs.createWriteStream('test.txt');
10lineStream.pipe(output);

Streams2 API

Node v0.10 added a new streams2 API. This allows the stream to be used in non-flowing mode and is preferred over the legacy pause() and resume() methods.

1var stream = fs.createReadStream('sample.txt');
2stream = byline.createStream(stream);
3
4stream.on('readable', function() {
5  var line;
6  while (null !== (line = stream.read())) {
7    console.log(line);
8  }
9});

Transform Stream

The byline transform stream can be directly manipulated like so:

1var LineStream = require('byline').LineStream;
2
3var input = fs.createReadStream('sample.txt');
4var output = fs.createWriteStream('nolines.txt');
5
6var lineStream = new LineStream();
7input.pipe(lineStream);
8lineStream.pipe(output);
9

Empty Lines

By default byline skips empty lines, if you want to keep them, pass the keepEmptyLines option in the call to byline.createStream(stream, options) or byline(stream, options).

Tests

npm test

v0.8

If you want to use node-byline with node v0.8 then you can use the 2.1.x series. Simply use the following in your package.json:

1  "dependencies": {
2  "byline": ">=2.1.0 <3.0.0"
3},

Simple

Unlike other modules (of which there are many), byline contains no:

• monkeypatching
• dependencies
• non-standard 'line' events which break pipe
• limitations to only file streams
• CoffeeScript
• unnecessary code