148 lines
3.4 KiB
Markdown
148 lines
3.4 KiB
Markdown
# 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](http://www.unicode.org/reports/tr18/#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:
|
|
|
|
```javascript
|
|
var fs = require('fs'),
|
|
byline = require('byline');
|
|
|
|
var stream = byline(fs.createReadStream('sample.txt', { encoding: 'utf8' }));
|
|
```
|
|
|
|
The `data` event then emits lines:
|
|
|
|
```javascript
|
|
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`.
|
|
|
|
```javascript
|
|
var fs = require('fs'),
|
|
byline = require('byline');
|
|
|
|
var stream = fs.createReadStream('sample.txt');
|
|
stream = byline.createStream(stream);
|
|
|
|
stream.on('data', function(line) {
|
|
console.log(line);
|
|
});
|
|
```
|
|
|
|
# Piping
|
|
|
|
`byline` supports `pipe` (though it strips the line endings, of course).
|
|
|
|
```javascript
|
|
var stream = fs.createReadStream('sample.txt');
|
|
stream = byline.createStream(stream);
|
|
stream.pipe(fs.createWriteStream('nolines.txt'));
|
|
```
|
|
|
|
Alternatively, you can create a readable/writable "through-stream" which doesn't wrap any specific
|
|
stream:
|
|
|
|
```javascript
|
|
var stream = fs.createReadStream('sample.txt');
|
|
stream = byline.createStream(stream);
|
|
stream.pipe(fs.createWriteStream('nolines.txt'));
|
|
|
|
var input = fs.createReadStream('LICENSE');
|
|
var lineStream = byline.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.
|
|
|
|
```javascript
|
|
var stream = fs.createReadStream('sample.txt');
|
|
stream = byline.createStream(stream);
|
|
|
|
stream.on('readable', function() {
|
|
var line;
|
|
while (null !== (line = stream.read())) {
|
|
console.log(line);
|
|
}
|
|
});
|
|
```
|
|
|
|
# Transform Stream
|
|
|
|
The `byline` transform stream can be directly manipulated like so:
|
|
|
|
```javascript
|
|
var LineStream = require('byline').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 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`:
|
|
|
|
```javascript
|
|
"dependencies": {
|
|
"byline": ">=2.1.0 <3.0.0"
|
|
},
|
|
```
|
|
|
|
# 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
|