1# byline — buffered stream for reading lines 2 3![npm package](https://nodei.co/npm/byline.png?downloads=true&downloadRank=true) 4 5`byline` is a simple module providing a `LineStream`. 6 7- node v0.10 `streams2` (transform stream) 8- supports `pipe` 9- supports both UNIX and Windows line endings 10- supports [Unicode UTS #18 line boundaries](http://www.unicode.org/reports/tr18/#Line_Boundaries) 11- can wrap any readable stream 12- can be used as a readable-writable "through-stream" (transform stream) 13- super-simple: `stream = byline(stream);` 14 15## Install 16 17 npm install byline 18 19or from source: 20 21 git clone git://github.com/jahewson/node-byline.git 22 cd node-byline 23 npm link 24 25# Convenience API 26 27The `byline` module can be used as a function to quickly wrap a readable stream: 28 29```javascript 30var fs = require('fs'), 31 byline = require('byline'); 32 33var stream = byline(fs.createReadStream('sample.txt', { encoding: 'utf8' })); 34``` 35 36The `data` event then emits lines: 37 38```javascript 39stream.on('data', function(line) { 40 console.log(line); 41}); 42``` 43 44# Standard API 45 46You just need to add one line to wrap your readable `Stream` with a `LineStream`. 47 48```javascript 49var fs = require('fs'), 50 byline = require('byline'); 51 52var stream = fs.createReadStream('sample.txt'); 53stream = byline.createStream(stream); 54 55stream.on('data', function(line) { 56 console.log(line); 57}); 58``` 59 60# Piping 61 62`byline` supports `pipe` (though it strips the line endings, of course). 63 64```javascript 65var stream = fs.createReadStream('sample.txt'); 66stream = byline.createStream(stream); 67stream.pipe(fs.createWriteStream('nolines.txt')); 68``` 69 70Alternatively, you can create a readable/writable "through-stream" which doesn't wrap any specific 71stream: 72 73```javascript 74var stream = fs.createReadStream('sample.txt'); 75stream = byline.createStream(stream); 76stream.pipe(fs.createWriteStream('nolines.txt')); 77 78var input = fs.createReadStream('LICENSE'); 79var lineStream = byline.createStream(); 80input.pipe(lineStream); 81 82var output = fs.createWriteStream('test.txt'); 83lineStream.pipe(output); 84``` 85 86# Streams2 API 87 88Node v0.10 added a new streams2 API. This allows the stream to be used in non-flowing mode and is 89preferred over the legacy pause() and resume() methods. 90 91```javascript 92var stream = fs.createReadStream('sample.txt'); 93stream = byline.createStream(stream); 94 95stream.on('readable', function() { 96 var line; 97 while (null !== (line = stream.read())) { 98 console.log(line); 99 } 100}); 101``` 102 103# Transform Stream 104 105The `byline` transform stream can be directly manipulated like so: 106 107```javascript 108var LineStream = require('byline').LineStream; 109 110var input = fs.createReadStream('sample.txt'); 111var output = fs.createWriteStream('nolines.txt'); 112 113var lineStream = new LineStream(); 114input.pipe(lineStream); 115lineStream.pipe(output); 116 117``` 118 119# Empty Lines 120 121By default byline skips empty lines, if you want to keep them, pass the `keepEmptyLines` option in 122the call to `byline.createStream(stream, options)` or `byline(stream, options)`. 123 124# Tests 125 126 npm test 127 128# v0.8 129 130If you want to use `node-byline` with node v0.8 then you can use the 2.1.x series. Simply use the 131following in your `package.json`: 132 133```javascript 134 "dependencies": { 135 "byline": ">=2.1.0 <3.0.0" 136}, 137``` 138 139# Simple 140Unlike other modules (of which there are many), `byline` contains no: 141 142- monkeypatching 143- dependencies 144- non-standard 'line' events which break `pipe` 145- limitations to only file streams 146- CoffeeScript 147- unnecessary code 148