byoneline — buffered stream for reading lines

This is based on 'byline' transform by @jahewson that includes changes from pull request by lfdoherty.

byoneline 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 = byoneline(stream);

Install

npm install byoneline

or from source:

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

Convenience API

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

var fs = require('fs'),
    byoneline = require('byoneline');

var stream = byoneline(fs.createReadStream('sample.txt', { encoding: 'utf8' }));

The data event then emits lines:

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

Standard API

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

var fs = require('fs'),	
    byoneline = require('byoneline');

var stream = fs.createReadStream('sample.txt');
stream = byoneline.createStream(stream);

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

Piping

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

var stream = fs.createReadStream('sample.txt');
stream = byoneline.createStream(stream);
stream.pipe(fs.createWriteStream('nolines.txt'));

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

var stream = fs.createReadStream('sample.txt');
stream = byoneline.createStream(stream);
stream.pipe(fs.createWriteStream('nolines.txt'));
	
var input = fs.createReadStream('LICENSE');
var lineStream = byoneline.createStream();
input.pipe(lineStream);

var output = fs.createWriteStream('test.txt');
lineStream.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.

var stream = fs.createReadStream('sample.txt');
stream = byoneline.createStream(stream);

stream.on('readable', function() {
  var line;
  while (null !== (line = stream.read())) {
    console.log(line);
  }
});

Transform Stream

The byoneline transform stream can be directly manipulated like so:

var LineStream = require('byoneline').LineStream;

var input = fs.createReadStream('sample.txt');
var output = fs.createWriteStream('nolines.txt');

var lineStream = new LineStream();
input.pipe(lineStream);
lineStream.pipe(output);

Empty Lines

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

Tests

npm test

Simple

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

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