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