Commit aed296546588b191b7ccaee7e796bfba8f574606
sources.md
Dominic Tarr committed on 3/23/2013, 4:40:07 AMParent: 7f7ed243bb9288007c7cdc6476b2fa647b6c19cb
Files changed
docs/sources.js | added |
docs/sources.js | ||
---|---|---|
@@ -1,0 +1,86 @@ | ||
1 | +# Sources | |
2 | + | |
3 | +A source is a stream that is not writable. | |
4 | +You *must* have a source at one end of a pipeline | |
5 | +for data to move through. | |
6 | + | |
7 | +in general | |
8 | + | |
9 | +``` js | |
10 | +source() | |
11 | + .pipe(through()) //optional | |
12 | + .pipe(sink()) | |
13 | +``` | |
14 | + | |
15 | +## readArray (array) | |
16 | + | |
17 | +create a SourceStream that from an array and then stops. | |
18 | + | |
19 | + | |
20 | +## count (max) | |
21 | + | |
22 | +create a stream that outputs `0 ... max`. | |
23 | +by default, `max = Infinity`, see | |
24 | +[take](https://github.com/dominictarr/pull-stream/blob/master/docs/throughs.md#take_test) | |
25 | + | |
26 | +## infinite (generator) | |
27 | + | |
28 | +create an unending stream by repeatedly calling a generator | |
29 | +function (by default, `Math.random`) | |
30 | +see | |
31 | +[take](https://github.com/dominictarr/pull-stream/blob/master/docs/throughs.md#take_test) | |
32 | + | |
33 | +## defer | |
34 | + | |
35 | +create a false source-stream that will be attached to a | |
36 | +real source-stream later. Use when you must do an async | |
37 | +operation before you can create the stream. | |
38 | + | |
39 | + | |
40 | +``` js | |
41 | +function ls (dir) { | |
42 | + var ds = pull.defer() | |
43 | + fs.readdir(dir, function (err, ls) { | |
44 | + if(err) return ds.abort(err) | |
45 | + return ds.resolve(readArray(ls) | |
46 | + .pipe(pull.map(function (file) { | |
47 | + return path.resolve(dir, file) | |
48 | + }) | |
49 | + }) | |
50 | + return ds | |
51 | +} | |
52 | +``` | |
53 | + | |
54 | +### pushable | |
55 | + | |
56 | +Create a false source stream with a `.push(data, cb?)` | |
57 | +property. Use when you really need a push api, | |
58 | +or need to adapt pull-stream to some other push api. | |
59 | + | |
60 | +``` js | |
61 | +function ls (dir) { | |
62 | + var ps = pull.pushable() | |
63 | + fs.readdir(dir, function (err, ls) { | |
64 | + if(err) return ps.end(err) | |
65 | + ls.forEach(function (file) { | |
66 | + ps.push(path.resolve(dir, file)) | |
67 | + }) | |
68 | + ps.end() | |
69 | + }) | |
70 | + return ps | |
71 | +} | |
72 | +``` | |
73 | + | |
74 | +### depthFirst, widthFirst, leafFirst (start, createStream) | |
75 | + | |
76 | +Traverse a tree structure. `start` is a value that represents | |
77 | +a node. `createStream` is a function that returns | |
78 | +a pull-stream of the children of a node. | |
79 | +`start` must be the same type output by `createStream`. | |
80 | + | |
81 | +``` js | |
82 | +//passing in the `ls` function from the `defer` example. | |
83 | +pull.widthFirst(process.cwd(), ls) | |
84 | + .pipe(pull.log()) | |
85 | +``` | |
86 | + |
Built with git-ssb-web