BlueGit

blue-star danique-bot

Files

danique-bot / node_modules / byline / README.md

README.md

Import template
timfa Tim · pushed by timfa · 4 years ago
c788ad20 History
README.md 3.3 KiB Download Raw

byline — buffered stream for reading lines

npm package

byline is a simple module providing a LineStream.

  • node v0.10 streams2 (transform stream)
  • supports pipe
  • supports both UNIX and Windows line endings
  • 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:

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

var stream = byline(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'),	
    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).

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:

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.

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:

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:

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