← Back to branch summary

~cyphermox/cordova-cli/flatten

« back to all changes in this revision

Viewing changes to node_modules/cordova/_vendor/combined-stream/0.0.4/Readme.md

  • Committer: Mathieu Trudel-Lapierre
  • Date: 2013-12-12 05:26:53 UTC
  • Revision ID: mathieu-tl@ubuntu.com-20131212052653-eatjt8zguqua5qmq
testing the flattenage, yo

Show diffs side-by-side

added added

removed removed

Lines of Context:
node_modules/cordova/_vendor/combined-stream/0.0.4/Readme.md
 
1
# combined-stream
 
2
 
 
3
A stream that emits multiple other streams one after another.
 
4
 
 
5
## Installation
 
6
 
 
7
``` bash
 
8
npm install combined-stream
 
9
```
 
10
 
 
11
## Usage
 
12
 
 
13
Here is a simple example that shows how you can use combined-stream to combine
 
14
two files into one:
 
15
 
 
16
``` javascript
 
17
var CombinedStream = require('combined-stream');
 
18
var fs = require('fs');
 
19
 
 
20
var combinedStream = CombinedStream.create();
 
21
combinedStream.append(fs.createReadStream('file1.txt'));
 
22
combinedStream.append(fs.createReadStream('file2.txt'));
 
23
 
 
24
combinedStream.pipe(fs.createWriteStream('combined.txt'));
 
25
```
 
26
 
 
27
While the example above works great, it will pause all source streams until
 
28
they are needed. If you don't want that to happen, you can set `pauseStreams`
 
29
to `false`:
 
30
 
 
31
``` javascript
 
32
var CombinedStream = require('combined-stream');
 
33
var fs = require('fs');
 
34
 
 
35
var combinedStream = CombinedStream.create({pauseStreams: false});
 
36
combinedStream.append(fs.createReadStream('file1.txt'));
 
37
combinedStream.append(fs.createReadStream('file2.txt'));
 
38
 
 
39
combinedStream.pipe(fs.createWriteStream('combined.txt'));
 
40
```
 
41
 
 
42
However, what if you don't have all the source streams yet, or you don't want
 
43
to allocate the resources (file descriptors, memory, etc.) for them right away?
 
44
Well, in that case you can simply provide a callback that supplies the stream
 
45
by calling a `next()` function:
 
46
 
 
47
``` javascript
 
48
var CombinedStream = require('combined-stream');
 
49
var fs = require('fs');
 
50
 
 
51
var combinedStream = CombinedStream.create();
 
52
combinedStream.append(function(next) {
 
53
  next(fs.createReadStream('file1.txt'));
 
54
});
 
55
combinedStream.append(function(next) {
 
56
  next(fs.createReadStream('file2.txt'));
 
57
});
 
58
 
 
59
combinedStream.pipe(fs.createWriteStream('combined.txt'));
 
60
```
 
61
 
 
62
## API
 
63
 
 
64
### CombinedStream.create([options])
 
65
 
 
66
Returns a new combined stream object. Available options are:
 
67
 
 
68
* `maxDataSize`
 
69
* `pauseStreams`
 
70
 
 
71
The effect of those options is described below.
 
72
 
 
73
### combinedStream.pauseStreams = true
 
74
 
 
75
Whether to apply back pressure to the underlaying streams. If set to `false`,
 
76
the underlaying streams will never be paused. If set to `true`, the
 
77
underlaying streams will be paused right after being appended, as well as when
 
78
`delayedStream.pipe()` wants to throttle.
 
79
 
 
80
### combinedStream.maxDataSize = 2 * 1024 * 1024
 
81
 
 
82
The maximum amount of bytes (or characters) to buffer for all source streams.
 
83
If this value is exceeded, `combinedStream` emits an `'error'` event.
 
84
 
 
85
### combinedStream.dataSize = 0
 
86
 
 
87
The amount of bytes (or characters) currently buffered by `combinedStream`.
 
88
 
 
89
### combinedStream.append(stream)
 
90
 
 
91
Appends the given `stream` to the combinedStream object. If `pauseStreams` is
 
92
set to `true, this stream will also be paused right away.
 
93
 
 
94
`streams` can also be a function that takes one parameter called `next`. `next`
 
95
is a function that must be invoked in order to provide the `next` stream, see
 
96
example above.
 
97
 
 
98
Regardless of how the `stream` is appended, combined-stream always attaches an
 
99
`'error'` listener to it, so you don't have to do that manually.
 
100
 
 
101
Special case: `stream` can also be a String or Buffer.
 
102
 
 
103
### combinedStream.write(data)
 
104
 
 
105
You should not call this, `combinedStream` takes care of piping the appended
 
106
streams into itself for you.
 
107
 
 
108
### combinedStream.resume()
 
109
 
 
110
Causes `combinedStream` to start drain the streams it manages. The function is
 
111
idempotent, and also emits a `'resume'` event each time which usually goes to
 
112
the stream that is currently being drained.
 
113
 
 
114
### combinedStream.pause();
 
115
 
 
116
If `combinedStream.pauseStreams` is set to `false`, this does nothing.
 
117
Otherwise a `'pause'` event is emitted, this goes to the stream that is
 
118
currently being drained, so you can use it to apply back pressure.
 
119
 
 
120
### combinedStream.end();
 
121
 
 
122
Sets `combinedStream.writable` to false, emits an `'end'` event, and removes
 
123
all streams from the queue.
 
124
 
 
125
### combinedStream.destroy();
 
126
 
 
127
Same as `combinedStream.end()`, except it emits a `'close'` event instead of
 
128
`'end'`.
 
129
 
 
130
## License
 
131
 
 
132
combined-stream is licensed under the MIT license.