summaryrefslogtreecommitdiff
path: root/deps/npm/node_modules/byline/README.md
diff options
context:
space:
mode:
authorRebecca Turner <me@re-becca.org>2018-04-20 18:26:37 -0700
committerMichaël Zasso <targos@protonmail.com>2018-05-25 14:03:01 +0200
commitd0cdcb61fe3a237be7d905cecc9ff1b95dbfdfa3 (patch)
tree9100e1f9c144368752be8c448d65bcd2bc8001a5 /deps/npm/node_modules/byline/README.md
parent1f3eb1cc1ec74b514f6e54fa88537818472bcb4d (diff)
downloadnode-new-d0cdcb61fe3a237be7d905cecc9ff1b95dbfdfa3.tar.gz
deps: upgrade npm to 6.1.0
PR-URL: https://github.com/nodejs/node/pull/20190 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com>
Diffstat (limited to 'deps/npm/node_modules/byline/README.md')
-rw-r--r--deps/npm/node_modules/byline/README.md147
1 files changed, 147 insertions, 0 deletions
diff --git a/deps/npm/node_modules/byline/README.md b/deps/npm/node_modules/byline/README.md
new file mode 100644
index 0000000000..f5a0644095
--- /dev/null
+++ b/deps/npm/node_modules/byline/README.md
@@ -0,0 +1,147 @@
+# byline — buffered stream for reading lines
+
+![npm package](https://nodei.co/npm/byline.png?downloads=true&downloadRank=true)
+
+`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