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