Mercurial > luasocket

comparison doc/ltn12.html @ 0:4b915342e2a8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
LuaSocket 2.0.2 + CMake build description.
author Eric Wing <ewing . public |-at-| gmail . com>
date Tue, 26 Aug 2008 18:40:01 -0700
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:4b915342e2a8
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3 <html>
4
5 <head>
6 <meta name="description" content="LuaSocket: LTN12 support">
7 <meta name="keywords" content="Lua, LuaSocket, Filters, Source, Sink,
8 Pump, Support, Library">
9 <title>LuaSocket: LTN12 module</title>
10 <link rel="stylesheet" href="reference.css" type="text/css">
11 </head>
12
13 <body>
14
15 <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
16
17 <div class=header>
18 <hr>
19 <center>
20 <table summary="LuaSocket logo">
21 <tr><td align=center><a href="http://www.lua.org">
22 <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
23 </a></td></tr>
24 <tr><td align=center valign=top>Network support for the Lua language
25 </td></tr>
26 </table>
27 <p class=bar>
28 <a href="home.html">home</a> &middot;
29 <a href="home.html#download">download</a> &middot;
30 <a href="installation.html">installation</a> &middot;
31 <a href="introduction.html">introduction</a> &middot;
32 <a href="reference.html">reference</a>
33 </p>
34 </center>
35 <hr>
36 </div>
37
38 <!-- ltn12 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
40 <h2 id=ltn12>LTN12</h2>
41
42 <p> The <tt>ltn12</tt> namespace implements the ideas described in
43 <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
44 LTN012, Filters sources and sinks</a>. This manual simply describes the
45 functions. Please refer to the LTN for a deeper explanation of the
46 functionality provided by this module.
47 </p>
48
49 <p>
50 To obtain the <tt>ltn12</tt> namespace, run:
51 </p>
52
53 <pre class=example>
54 -- loads the LTN21 module
55 local ltn12 = require("ltn12")
56 </pre>
57
58 <!-- filters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
59
60 <h3 id="filter">Filters</h3>
61
62 <!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
63
64 <p class=name id="filter.chain">
65 ltn12.filter.<b>chain(</b>filter<sub>1</sub>, filter<sub>2</sub>
66 [, ... filter<sub>N</sub>]<b>)</b>
67 </p>
68
69 <p class=description>
70 Returns a filter that passes all data it receives through each of a
71 series of given filters.
72 </p>
73
74 <p class=parameters>
75 <tt>Filter<sub>1</sub></tt> to <tt>filter<sub>N</sub></tt> are simple
76 filters.
77 </p>
78
79 <p class=return>
80 The function returns the chained filter.
81 </p>
82
83 <p class=note>
84 The nesting of filters can be arbitrary. For instance, the useless filter
85 below doesn't do anything but return the data that was passed to it,
86 unaltered.
87 </p>
88
89 <pre class=example>
90 -- load required modules
91 local ltn12 = require("ltn12")
92 local mime = require("mime")
93
94 -- create a silly identity filter
95 id = ltn12.filter.chain(
96 mime.encode("quoted-printable"),
97 mime.encode("base64"),
98 mime.decode("base64"),
99 mime.decode("quoted-printable")
100 )
101 </pre>
102
103 <!-- cycle ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
104
105 <p class=name id="filter.cycle">
106 ltn12.filter.<b>cycle(</b>low [, ctx, extra]<b>)</b>
107 </p>
108
109 <p class=description>
110 Returns a high-level filter that cycles though a low-level filter by
111 passing it each chunk and updating a context between calls.
112 </p>
113
114 <p class=parameters>
115 <tt>Low</tt> is the low-level filter to be cycled,
116 <tt>ctx</tt> is the initial context and <tt>extra</tt> is any extra
117 argument the low-level filter might take.
118 </p>
119
120 <p class=return>
121 The function returns the high-level filter.
122 </p>
123
124 <pre class=example>
125 -- load the ltn12 module
126 local ltn12 = require("ltn12")
127
128 -- the base64 mime filter factory
129 encodet['base64'] = function()
130 return ltn12.filter.cycle(b64, "")
131 end
132 </pre>
133
134 <!-- pumps ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
135
136 <h3 id="pump">Pumps</h3>
137
138 <!-- all ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
139
140 <p class=name id="pump.all">
141 ltn12.pump.<b>all(</b>source, sink<b>)</b>
142 </p>
143
144 <p class=description>
145 Pumps <em>all</em> data from a <tt>source</tt> to a <tt>sink</tt>.
146 </p>
147
148 <p class=return>
149 If successful, the function returns a value that evaluates to
150 <b><tt>true</tt></b>. In case
151 of error, the function returns a <b><tt>false</tt></b> value, followed by an error message.
152 </p>
153
154 <!-- step +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
155
156 <p class=name id="pump.step">
157 ltn12.pump.<b>step(</b>source, sink<b>)</b>
158 </p>
159
160 <p class=description>
161 Pumps <em>one</em> chunk of data from a <tt>source</tt> to a <tt>sink</tt>.
162 </p>
163
164 <p class=return>
165 If successful, the function returns a value that evaluates to
166 <b><tt>true</tt></b>. In case
167 of error, the function returns a <b><tt>false</tt></b> value, followed by an error message.
168 </p>
169
170 <!-- sinks ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
171
172 <h3 id="sink">Sinks</h3>
173
174 <!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
175
176 <p class=name id="sink.chain">
177 ltn12.sink.<b>chain(</b>filter, sink<b>)</b>
178 </p>
179
180 <p class=description>
181 Creates and returns a new sink that passes data through a <tt>filter</tt> before sending it to a given <tt>sink</tt>.
182 </p>
183
184 <!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
185
186 <p class=name id="sink.error">
187 ltn12.sink.<b>error(</b>message<b>)</b>
188 </p>
189
190 <p class=description>
191 Creates and returns a sink that aborts transmission with the error
192 <tt>message</tt>.
193 </p>
194
195 <!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
196
197 <p class=name id="sink.file">
198 ltn12.sink.<b>file(</b>handle, message<b>)</b>
199 </p>
200
201 <p class=description>
202 Creates a sink that sends data to a file.
203 </p>
204
205 <p class=parameters>
206 <tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>,
207 <tt>message</tt> should give the reason for failure.
208 </p>
209
210 <p class=return>
211 The function returns a sink that sends all data to the given <tt>handle</tt>
212 and closes the file when done, or a sink that aborts the transmission with
213 the error <tt>message</tt>
214 </p>
215
216 <p class=note>
217 In the following example, notice how the prototype is designed to
218 fit nicely with the <tt>io.open</tt> function.
219 </p>
220
221 <pre class=example>
222 -- load the ltn12 module
223 local ltn12 = require("ltn12")
224
225 -- copy a file
226 ltn12.pump.all(
227 ltn12.source.file(io.open("original.png")),
228 ltn12.sink.file(io.open("copy.png"))
229 )
230 </pre>
231
232 <!-- null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
233
234 <p class=name id="sink.null">
235 ltn12.sink.<b>null()</b>
236 </p>
237
238 <p class=description>
239 Returns a sink that ignores all data it receives.
240 </p>
241
242 <!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
243
244 <p class=name id="sink.simplify">
245 ltn12.sink.<b>simplify(</b>sink<b>)</b>
246 </p>
247
248 <p class=description>
249 Creates and returns a simple sink given a fancy <tt>sink</tt>.
250 </p>
251
252 <!-- table ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
253
254 <p class=name id="sink.table">
255 ltn12.sink.<b>table(</b>[table]<b>)</b>
256 </p>
257
258 <p class=description>
259 Creates a sink that stores all chunks in a table. The chunks can later be
260 efficiently concatenated into a single string.
261 </p>
262
263 <p class=parameters>
264 <tt>Table</tt> is used to hold the chunks. If
265 <tt><b>nil</b></tt>, the function creates its own table.
266 </p>
267
268 <p class=return>
269 The function returns the sink and the table used to store the chunks.
270 </p>
271
272 <pre class=example>
273 -- load needed modules
274 local http = require("socket.http")
275 local ltn12 = require("ltn12")
276
277 -- a simplified http.get function
278 function http.get(u)
279 local t = {}
280 local respt = request{
281 url = u,
282 sink = ltn12.sink.table(t)
283 }
284 return table.concat(t), respt.headers, respt.code
285 end
286 </pre>
287
288 <!-- sinks ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
289
290 <h3 id="source">Sources</h3>
291
292 <!-- cat ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
293
294 <p class=name id="source.cat">
295 ltn12.source.<b>cat(</b>source<sub>1</sub> [, source<sub>2</sub>, ...,
296 source<sub>N</sub>]<b>)</b>
297 </p>
298
299 <p class=description>
300 Creates a new source that produces the concatenation of the data produced
301 by a number of sources.
302 </p>
303
304 <p class=parameters>
305 <tt>Source<sub>1</sub></tt> to <tt>source<sub>N</sub></tt> are the original
306 sources.
307 </p>
308
309 <p class=return>
310 The function returns the new source.
311 </p>
312
313 <!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
314
315 <p class=name id="source.chain">
316 ltn12.source.<b>chain(</b>source, filter<b>)</b>
317 </p>
318
319 <p class=description>
320 Creates a new <tt>source</tt> that passes data through a <tt>filter</tt>
321 before returning it.
322 </p>
323
324 <p class=return>
325 The function returns the new source.
326 </p>
327
328 <!-- empty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
329
330 <p class=name id="source.empty">
331 ltn12.source.<b>empty()</b>
332 </p>
333
334 <p class=description>
335 Creates and returns an empty source.
336 </p>
337
338 <!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
339
340 <p class=name id="source.error">
341 ltn12.source.<b>error(</b>message<b>)</b>
342 </p>
343
344 <p class=description>
345 Creates and returns a source that aborts transmission with the error
346 <tt>message</tt>.
347 </p>
348
349 <!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
350
351 <p class=name id="source.file">
352 ltn12.source.<b>file(</b>handle, message<b>)</b>
353 </p>
354
355 <p class=description>
356 Creates a source that produces the contents of a file.
357 </p>
358
359 <p class=parameters>
360 <tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>,
361 <tt>message</tt> should give the reason for failure.
362 </p>
363
364 <p class=return>
365 The function returns a source that reads chunks of data from
366 given <tt>handle</tt> and returns it to the user,
367 closing the file when done, or a source that aborts the transmission with
368 the error <tt>message</tt>
369 </p>
370
371 <p class=note>
372 In the following example, notice how the prototype is designed to
373 fit nicely with the <tt>io.open</tt> function.
374 </p>
375
376 <pre class=example>
377 -- load the ltn12 module
378 local ltn12 = require("ltn12")
379
380 -- copy a file
381 ltn12.pump.all(
382 ltn12.source.file(io.open("original.png")),
383 ltn12.sink.file(io.open("copy.png"))
384 )
385 </pre>
386
387 <!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
388
389 <p class=name id="source.simplify">
390 ltn12.source.<b>simplify(</b>source<b>)</b>
391 </p>
392
393 <p class=description>
394 Creates and returns a simple source given a fancy <tt>source</tt>.
395 </p>
396
397 <!-- string +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
398
399 <p class=name id="source.string">
400 ltn12.source.<b>string(</b>string<b>)</b>
401 </p>
402
403 <p class=description>
404 Creates and returns a source that produces the contents of a
405 <tt>string</tt>, chunk by chunk.
406 </p>
407
408 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
409
410 <div class=footer>
411 <hr>
412 <center>
413 <p class=bar>
414 <a href="home.html">home</a> &middot;
415 <a href="home.html#down">download</a> &middot;
416 <a href="installation.html">installation</a> &middot;
417 <a href="introduction.html">introduction</a> &middot;
418 <a href="reference.html">reference</a>
419 </p>
420 <p>
421 <small>
422 Last modified by Diego Nehab on <br>
423 Thu Apr 20 00:25:41 EDT 2006
424 </small>
425 </p>
426 </center>
427 </div>
428
429 </body>
430 </html>