1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
|
<html>
<head>
<title>stream-utils API reference (clojure-contrib)</title>
<link href="../static/favicon.png" rel="icon" />
<link href="../static/favicon.png" rel="shortcut icon" />
<link media="all" type="text/css" href="../static/clojure.css" rel="stylesheet" />
<link media="all" type="text/css" href="../static/wiki.css" rel="stylesheet" />
<link media="all" type="text/css" href="../static/internal.css" rel="stylesheet" />
<!-- TODO: are we using these (from clojure.org)? If so, add the files -->
<script src="file/view/code_highlighter.js" type="text/javascript"></script>
<script src="file/view/clojure.js" type="text/javascript"></script>
<style>.menuWrapper{height: 36px;}</style>
<!--[if lte IE 6]>
<link rel="stylesheet" href="http://www.wikispaces.com/_/2009051601/s/internal_ie.css" type="text/css" />
<![endif]-->
</head>
<!--
This document was auto-generated from the source by the clojure autodoc system.
To report errors or ask questions about the overall documentation structure, formatting,
etc., contact Tom Faulhaber (google mail name: tomfaulhaber).
For errors in the documentation of a particular namespace, contact the author of that
namespace.
-->
<body>
<div id="AllContentContainer">
<div id="Header">
<a id="Logo" href="index.html"><img alt="Clojure" height="100" width="100" src="../static/clojure-icon.gif" /></a>
<h1><a title="page header title" id="page-header" href="index.html">Clojure-contrib API Reference</a></h1>
</div>
<div id="leftcolumn"><div style="text-align: center;"></div>
<div class="menu">
<div class="WikiCustomNav WikiElement wiki">
<div class="BranchTOC">
<a class="wiki_link" href="#">Branches</a>
<ul id="left-sidebar-branch-list">
<li><a href="../index.html" class="wiki_link">master</a></li><li><a href="../branch-1.1.x/index.html" class="wiki_link">1.1.x</a></li>
</ul>
</div>
<a class="wiki_link" href="index.html">Overview</a><br />
<a class="wiki_link" href="api-index.html">API Index</a><br />
<a class="wiki_link" href="#">Namespaces:</a>
<ul id="left-sidebar-list">
<li><a href="accumulators-api.html" class="wiki_link">accumulators</a></li><li><a href="agent-utils-api.html" class="wiki_link">agent-utils</a></li><li><a href="apply-macro-api.html" class="wiki_link">apply-macro</a></li><li><a href="base64-api.html" class="wiki_link">base64</a></li><li><a href="classpath-api.html" class="wiki_link">classpath</a></li><li><a href="combinatorics-api.html" class="wiki_link">combinatorics</a></li><li><a href="command-line-api.html" class="wiki_link">command-line</a></li><li><a href="complex-numbers-api.html" class="wiki_link">complex-numbers</a></li><li><a href="cond-api.html" class="wiki_link">cond</a></li><li><a href="condition-api.html" class="wiki_link">condition</a></li><li><a href="core-api.html" class="wiki_link">core</a></li><li><a href="dataflow-api.html" class="wiki_link">dataflow</a></li><li><a href="datalog-api.html" class="wiki_link">datalog</a></li><li><a href="def-api.html" class="wiki_link">def</a></li><li><a href="duck-streams-api.html" class="wiki_link">duck-streams</a></li><li><a href="error-kit-api.html" class="wiki_link">error-kit</a></li><li><a href="except-api.html" class="wiki_link">except</a></li><li><a href="fcase-api.html" class="wiki_link">fcase</a></li><li><a href="find-namespaces-api.html" class="wiki_link">find-namespaces</a></li><li><a href="fnmap-api.html" class="wiki_link">fnmap</a></li><li><a href="gen-html-docs-api.html" class="wiki_link">gen-html-docs</a></li><li><a href="generic.arithmetic-api.html" class="wiki_link">generic.arithmetic</a></li><li><a href="generic.collection-api.html" class="wiki_link">generic.collection</a></li><li><a href="generic.comparison-api.html" class="wiki_link">generic.comparison</a></li><li><a href="generic.functor-api.html" class="wiki_link">generic.functor</a></li><li><a href="generic.math-functions-api.html" class="wiki_link">generic.math-functions</a></li><li><a href="graph-api.html" class="wiki_link">graph</a></li><li><a href="greatest-least-api.html" class="wiki_link">greatest-least</a></li><li><a href="http.agent-api.html" class="wiki_link">http.agent</a></li><li><a href="http.connection-api.html" class="wiki_link">http.connection</a></li><li><a href="import-static-api.html" class="wiki_link">import-static</a></li><li><a href="jar-api.html" class="wiki_link">jar</a></li><li><a href="java-utils-api.html" class="wiki_link">java-utils</a></li><li><a href="javadoc.browse-api.html" class="wiki_link">javadoc.browse</a></li><li><a href="jmx-api.html" class="wiki_link">jmx</a></li><li><a href="json.read-api.html" class="wiki_link">json.read</a></li><li><a href="json.write-api.html" class="wiki_link">json.write</a></li><li><a href="lazy-seqs-api.html" class="wiki_link">lazy-seqs</a></li><li><a href="lazy-xml-api.html" class="wiki_link">lazy-xml</a></li><li><a href="logging-api.html" class="wiki_link">logging</a></li><li><a href="macro-utils-api.html" class="wiki_link">macro-utils</a></li><li><a href="macros-api.html" class="wiki_link">macros</a></li><li><a href="map-utils-api.html" class="wiki_link">map-utils</a></li><li><a href="math-api.html" class="wiki_link">math</a></li><li><a href="miglayout-api.html" class="wiki_link">miglayout</a></li><li><a href="mmap-api.html" class="wiki_link">mmap</a></li><li><a href="mock-api.html" class="wiki_link">mock</a></li><li><a href="monadic-io-streams-api.html" class="wiki_link">monadic-io-streams</a></li><li><a href="monads-api.html" class="wiki_link">monads</a></li><li><a href="ns-utils-api.html" class="wiki_link">ns-utils</a></li><li><a href="pprint-api.html" class="wiki_link">pprint</a></li><li><a href="probabilities.finite-distributions-api.html" class="wiki_link">probabilities.finite-distributions</a></li><li><a href="probabilities.monte-carlo-api.html" class="wiki_link">probabilities.monte-carlo</a></li><li><a href="probabilities.random-numbers-api.html" class="wiki_link">probabilities.random-numbers</a></li><li><a href="profile-api.html" class="wiki_link">profile</a></li><li><a href="prxml-api.html" class="wiki_link">prxml</a></li><li><a href="repl-ln-api.html" class="wiki_link">repl-ln</a></li><li><a href="repl-utils-api.html" class="wiki_link">repl-utils</a></li><li><a href="seq-utils-api.html" class="wiki_link">seq-utils</a></li><li><a href="server-socket-api.html" class="wiki_link">server-socket</a></li><li><a href="set-api.html" class="wiki_link">set</a></li><li><a href="shell-out-api.html" class="wiki_link">shell-out</a></li><li><a href="singleton-api.html" class="wiki_link">singleton</a></li><li><a href="sql-api.html" class="wiki_link">sql</a></li><li><a href="str-utils-api.html" class="wiki_link">str-utils</a></li><li><a href="str-utils2-api.html" class="wiki_link">str-utils2</a></li><li><a href="stream-utils-api.html" class="wiki_link">stream-utils</a></li><li><a href="swing-utils-api.html" class="wiki_link">swing-utils</a></li><li><a href="test-is-api.html" class="wiki_link">test-is</a></li><li><a href="trace-api.html" class="wiki_link">trace</a></li><li><a href="types-api.html" class="wiki_link">types</a></li><li><a href="with-ns-api.html" class="wiki_link">with-ns</a></li><li><a href="zip-filter-api.html" class="wiki_link">zip-filter</a></li>
</ul>
</div>
</div>
</div>
<div id="rightcolumn">
<div id="Content">
<div class="contentBox"><div class="innerContentBox">
<div id="content_view" class="wiki wikiPage">
<div id="right-sidebar"><div id="toc">
<h1 class="nopad">Table of Contents</h1>
<div style="margin-left: 1em;" class="toc-section">
<a href="#toc0">Overview</a>
<div style="margin-left: 1em;" class="toc-entry">
<a href="#clojure.contrib.stream-utils/defst">defst</a>
</div><div style="margin-left: 1em;" class="toc-entry">
<a href="#clojure.contrib.stream-utils/defstream">defstream</a>
</div><div style="margin-left: 1em;" class="toc-entry">
<a href="#clojure.contrib.stream-utils/pick">pick</a>
</div><div style="margin-left: 1em;" class="toc-entry">
<a href="#clojure.contrib.stream-utils/pick-all">pick-all</a>
</div><div style="margin-left: 1em;" class="toc-entry">
<a href="#clojure.contrib.stream-utils/stream-drop">stream-drop</a>
</div><div style="margin-left: 1em;" class="toc-entry">
<a href="#clojure.contrib.stream-utils/stream-filter">stream-filter</a>
</div><div style="margin-left: 1em;" class="toc-entry">
<a href="#clojure.contrib.stream-utils/stream-flatten">stream-flatten</a>
</div><div style="margin-left: 1em;" class="toc-entry">
<a href="#clojure.contrib.stream-utils/stream-m">stream-m</a>
</div><div style="margin-left: 1em;" class="toc-entry">
<a href="#clojure.contrib.stream-utils/stream-map">stream-map</a>
</div><div style="margin-left: 1em;" class="toc-entry">
<a href="#clojure.contrib.stream-utils/stream-next">stream-next</a>
</div><div style="margin-left: 1em;" class="toc-entry">
<a href="#clojure.contrib.stream-utils/stream-seq">stream-seq</a>
</div><div style="margin-left: 1em;" class="toc-entry">
<a href="#clojure.contrib.stream-utils/stream-type">stream-type</a>
</div>
<br />
</div>
</div>
</div>
<div id="content-tag"><h1 id="overview">API for <span id="namespace-name">stream-utils</span>
<span id="branch-name">(1.1.x branch)</span></h1>
by <span id="author">Konrad Hinsen</span><br />
<br />Usage:
<pre>
(ns your-namespace
(:require <span id="long-name">clojure.contrib.stream-utils</span>))
</pre><pre>
</pre><h2>Overview</h2>
<pre id="namespace-docstr">Functions for setting up computational pipelines via data streams.
NOTE: This library is experimental. It may change significantly
with future release.
This library defines:
- an abstract stream type, whose interface consists of the
multimethod stream-next
- a macro for implementing streams
- implementations of stream for
1) Clojure sequences, and vectors
2) nil, representing an empty stream
- tools for writing stream transformers, including the
monad stream-m
- various utility functions for working with streams
Streams are building blocks in the construction of computational
pipelines. A stream is represented by its current state plus
a function that takes a stream state and obtains the next item
in the stream as well as the new stream state. The state is
implemented as a Java class or a Clojure type (as defined by the
function clojure.core/type), and the function is provided as an
implementation of the multimethod stream-next for this class or type.
While setting up pipelines using this mechanism is somewhat more
cumbersome than using Clojure's lazy seq mechanisms, there are a
few advantages:
- The state of a stream can be stored in any Clojure data structure,
and the stream can be re-generated from it any number of times.
Any number of states can be stored this way.
- The elements of the stream are never cached, so keeping a reference
to a stream state does not incur an uncontrollable memory penalty.
Note that the stream mechanism is thread-safe as long as the
concrete stream implementations do not use any mutable state.
Stream transformers take any number of input streams and produce one
output stream. They are typically written using the stream-m
monad. In the definition of a stream transformer, (pick s) returns
the next value of stream argument s, whereas pick-all returns the
next value of all stream arguments in the form of a vector.</pre>
<br />
<h2>Public Variables and Functions</h2>
<div id="var-entry">
<br />
<hr />
<h2 id="clojure.contrib.stream-utils/defst">defst</h2>
<span id="var-type">macro</span><br />
<pre id="var-usage">Usage: (defst name args streams & body)
</pre>
<pre id="var-docstr">Define the stream transformer name by body.
The non-stream arguments args and the stream arguments streams
are given separately, with args being possibly empty.</pre>
<a href="http://github.com/richhickey/clojure-contrib/blob/09d39aca5a69a83f4326ffb0d4ba8f9fc15c9861/src/clojure/contrib/stream_utils.clj#L183" id="var-source">Source</a>
</div><div id="var-entry">
<br />
<hr />
<h2 id="clojure.contrib.stream-utils/defstream">defstream</h2>
<span id="var-type">macro</span><br />
<pre id="var-usage">Usage: (defstream type-tag args & body)
</pre>
<pre id="var-docstr">Define object of the given type as a stream whose implementation
of stream-next is defined by args and body. This macro adds
a type-specific method for stream-next and derives type
from stream-type.</pre>
<a href="http://github.com/richhickey/clojure-contrib/blob/09d39aca5a69a83f4326ffb0d4ba8f9fc15c9861/src/clojure/contrib/stream_utils.clj#L73" id="var-source">Source</a>
</div><div id="var-entry">
<br />
<hr />
<h2 id="clojure.contrib.stream-utils/pick">pick</h2>
<span id="var-type">function</span><br />
<pre id="var-usage">Usage: (pick n)
</pre>
<pre id="var-docstr">Return the next value of stream argument n inside a stream
transformer. When used inside of defst, the name of the stream
argument can be used instead of its index n.</pre>
<a href="http://github.com/richhickey/clojure-contrib/blob/09d39aca5a69a83f4326ffb0d4ba8f9fc15c9861/src/clojure/contrib/stream_utils.clj#L149" id="var-source">Source</a>
</div><div id="var-entry">
<br />
<hr />
<h2 id="clojure.contrib.stream-utils/pick-all">pick-all</h2>
<span id="var-type">function</span><br />
<pre id="var-usage">Usage: (pick-all streams)
</pre>
<pre id="var-docstr">Return a vector containing the next value of each stream argument
inside a stream transformer.</pre>
<a href="http://github.com/richhickey/clojure-contrib/blob/09d39aca5a69a83f4326ffb0d4ba8f9fc15c9861/src/clojure/contrib/stream_utils.clj#L160" id="var-source">Source</a>
</div><div id="var-entry">
<br />
<hr />
<h2 id="clojure.contrib.stream-utils/stream-drop">stream-drop</h2>
<span id="var-type">function</span><br />
<pre id="var-usage">Usage: (stream-drop n stream)
</pre>
<pre id="var-docstr">Return a stream containing all but the first n elements of stream.</pre>
<a href="http://github.com/richhickey/clojure-contrib/blob/09d39aca5a69a83f4326ffb0d4ba8f9fc15c9861/src/clojure/contrib/stream_utils.clj#L201" id="var-source">Source</a>
</div><div id="var-entry">
<br />
<hr />
<h2 id="clojure.contrib.stream-utils/stream-filter">stream-filter</h2>
<span id="var-type">multimethod</span><br />
<pre id="var-usage">Usage: (stream-filter p stream)
</pre>
<pre id="var-docstr">Return a new stream that contrains the elements of stream
that satisfy the predicate p.</pre>
<a href="http://github.com/richhickey/clojure-contrib/blob/09d39aca5a69a83f4326ffb0d4ba8f9fc15c9861/src/clojure/contrib/stream_utils.clj#L243" id="var-source">Source</a>
</div><div id="var-entry">
<br />
<hr />
<h2 id="clojure.contrib.stream-utils/stream-flatten">stream-flatten</h2>
<span id="var-type">function</span><br />
<pre id="var-usage">Usage: (stream-flatten s)
</pre>
<pre id="var-docstr">Converts a stream of sequences into a stream of the elements of the
sequences. Flattening is not recursive, only one level of nesting
will be removed.</pre>
<a href="http://github.com/richhickey/clojure-contrib/blob/09d39aca5a69a83f4326ffb0d4ba8f9fc15c9861/src/clojure/contrib/stream_utils.clj#L271" id="var-source">Source</a>
</div><div id="var-entry">
<br />
<hr />
<h2 id="clojure.contrib.stream-utils/stream-m">stream-m</h2>
<span id="var-type">var</span><br />
<pre id="var-usage"></pre>
<pre id="var-docstr">Monad describing stream computations. The monadic values can be
of any type handled by stream-next.</pre>
<a href="http://github.com/richhickey/clojure-contrib/blob/09d39aca5a69a83f4326ffb0d4ba8f9fc15c9861/src/clojure/contrib/stream_utils.clj#L135" id="var-source">Source</a>
</div><div id="var-entry">
<br />
<hr />
<h2 id="clojure.contrib.stream-utils/stream-map">stream-map</h2>
<span id="var-type">multimethod</span><br />
<pre id="var-usage">Usage: (stream-map f stream)
</pre>
<pre id="var-docstr">Return a new stream by mapping the function f on the given stream.</pre>
<a href="http://github.com/richhickey/clojure-contrib/blob/09d39aca5a69a83f4326ffb0d4ba8f9fc15c9861/src/clojure/contrib/stream_utils.clj#L219" id="var-source">Source</a>
</div><div id="var-entry">
<br />
<hr />
<h2 id="clojure.contrib.stream-utils/stream-next">stream-next</h2>
<span id="var-type">multimethod</span><br />
<pre id="var-usage">Usage: (stream-next stream-state)
</pre>
<pre id="var-docstr">Returns a vector [next-value new-state] where next-value is the next
item in the data stream defined by stream-state and new-state
is the new state of the stream. At the end of the stream,
next-value and new-state are nil.</pre>
<a href="http://github.com/richhickey/clojure-contrib/blob/09d39aca5a69a83f4326ffb0d4ba8f9fc15c9861/src/clojure/contrib/stream_utils.clj#L91" id="var-source">Source</a>
</div><div id="var-entry">
<br />
<hr />
<h2 id="clojure.contrib.stream-utils/stream-seq">stream-seq</h2>
<span id="var-type">function</span><br />
<pre id="var-usage">Usage: (stream-seq s)
</pre>
<pre id="var-docstr">Return a lazy seq on the stream. Also accessible via
clojure.contrib.seq-utils/seq-on and
clojure.contrib.generic.collection/seq for streams.</pre>
<a href="http://github.com/richhickey/clojure-contrib/blob/09d39aca5a69a83f4326ffb0d4ba8f9fc15c9861/src/clojure/contrib/stream_utils.clj#L113" id="var-source">Source</a>
</div><div id="var-entry">
<br />
<hr />
<h2 id="clojure.contrib.stream-utils/stream-type">stream-type</h2>
<span id="var-type">var</span><br />
<pre id="var-usage"></pre>
<pre id="var-docstr">The root type for the stream hierarchy. For each stream type,
add a derivation from this type.</pre>
<a href="http://github.com/richhickey/clojure-contrib/blob/09d39aca5a69a83f4326ffb0d4ba8f9fc15c9861/src/clojure/contrib/stream_utils.clj#L69" id="var-source">Source</a>
</div>
</div>
</div>
</div>
</div>
</div>
<div id="foot">
<div style="text-align: center;" id="copyright">Copyright 2007-2009 by Rich Hickey and the various contributors</div>
</div>
</div>
<div id="DesignedBy">Logo & site design by <a title="Visit Tom Hickey's website." href="http://www.tomhickey.com">Tom Hickey</a>.<br />
Clojure auto-documentation system by Tom Faulhaber.</div>
</div>
<!-- /AllContentContainer -->
</body>
</html>
|
