aboutsummaryrefslogtreecommitdiff
path: root/doc/ltn12.html
diff options
context:
space:
mode:
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-13 13:53:10 +0000