git ssb

2+

Dominic / pull-stream



Commit aed296546588b191b7ccaee7e796bfba8f574606

sources.md

Dominic Tarr committed on 3/23/2013, 4:40:07 AM
Parent: 7f7ed243bb9288007c7cdc6476b2fa647b6c19cb

Files changed

docs/sources.jsadded
docs/sources.jsView
@@ -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