aboutsummaryrefslogtreecommitdiff
path: root/doc/ltn12.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ltn12.html')
-rw-r--r--doc/ltn12.html430
1 files changed, 0 insertions, 430 deletions
diff --git a/doc/ltn12.html b/doc/ltn12.html
deleted file mode 100644
index 54e66fb..0000000
--- a/doc/ltn12.html
+++ /dev/null
@@ -1,430 +0,0 @@
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,
8Pump, 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="index.html">home</a> &middot;
29<a href="index.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">
44LTN012, Filters sources and sinks</a>. This manual simply describes the
45functions. Please refer to the LTN for a deeper explanation of the
46functionality provided by this module.
47</p>
48
49<p>
50To obtain the <tt>ltn12</tt> namespace, run:
51</p>
52
53<pre class=example>
54-- loads the LTN21 module
55local 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">
65ltn12.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>
70Returns a filter that passes all data it receives through each of a
71series 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
76filters.
77</p>
78
79<p class=return>
80The function returns the chained filter.
81</p>
82
83<p class=note>
84The nesting of filters can be arbitrary. For instance, the useless filter
85below doesn't do anything but return the data that was passed to it,
86unaltered.
87</p>
88
89<pre class=example>
90-- load required modules
91local ltn12 = require("ltn12")
92local mime = require("mime")
93
94-- create a silly identity filter
95id = 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">
106ltn12.filter.<b>cycle(</b>low [, ctx, extra]<b>)</b>
107</p>
108
109<p class=description>
110Returns a high-level filter that cycles though a low-level filter by
111passing 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
117argument the low-level filter might take.
118</p>
119
120<p class=return>
121The function returns the high-level filter.
122</p>
123
124<pre class=example>
125-- load the ltn12 module
126local ltn12 = require("ltn12")
127
128-- the base64 mime filter factory
129encodet['base64'] = function()
130 return ltn12.filter.cycle(b64, "")
131end
132</pre>
133
134<!-- pumps ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
135
136<h3 id="pump">Pumps</h3>
137
138<!-- all ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
139
140<p class=name id="pump.all">
141ltn12.pump.<b>all(</b>source, sink<b>)</b>
142</p>
143
144<p class=description>
145Pumps <em>all</em> data from a <tt>source</tt> to a <tt>sink</tt>.
146</p>
147
148<p class=return>
149If successful, the function returns a value that evaluates to
150<b><tt>true</tt></b>. In case
151of 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">
157ltn12.pump.<b>step(</b>source, sink<b>)</b>
158</p>
159
160<p class=description>
161Pumps <em>one</em> chunk of data from a <tt>source</tt> to a <tt>sink</tt>.
162</p>
163
164<p class=return>
165If successful, the function returns a value that evaluates to
166<b><tt>true</tt></b>. In case
167of 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">
177ltn12.sink.<b>chain(</b>filter, sink<b>)</b>
178</p>
179
180<p class=description>
181Creates 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">
187ltn12.sink.<b>error(</b>message<b>)</b>
188</p>
189
190<p class=description>
191Creates 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">
198ltn12.sink.<b>file(</b>handle, message<b>)</b>
199</p>
200
201<p class=description>
202Creates 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>
211The function returns a sink that sends all data to the given <tt>handle</tt>
212and closes the file when done, or a sink that aborts the transmission with
213the error <tt>message</tt>
214</p>
215
216<p class=note>
217In the following example, notice how the prototype is designed to
218fit nicely with the <tt>io.open</tt> function.
219</p>
220
221<pre class=example>
222-- load the ltn12 module
223local ltn12 = require("ltn12")
224
225-- copy a file
226ltn12.pump.all(
227 ltn12.source.file(io.open("original.png", "rb")),
228 ltn12.sink.file(io.open("copy.png", "wb"))
229)
230</pre>
231
232<!-- null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
233
234<p class=name id="sink.null">
235ltn12.sink.<b>null()</b>
236</p>
237
238<p class=description>
239Returns a sink that ignores all data it receives.
240</p>
241
242<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
243
244<p class=name id="sink.simplify">
245ltn12.sink.<b>simplify(</b>sink<b>)</b>
246</p>
247
248<p class=description>
249Creates and returns a simple sink given a fancy <tt>sink</tt>.
250</p>
251
252<!-- table ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
253
254<p class=name id="sink.table">
255ltn12.sink.<b>table(</b>[table]<b>)</b>
256</p>
257
258<p class=description>
259Creates a sink that stores all chunks in a table. The chunks can later be
260efficiently 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>
269The function returns the sink and the table used to store the chunks.
270</p>
271
272<pre class=example>
273-- load needed modules
274local http = require("socket.http")
275local ltn12 = require("ltn12")
276
277-- a simplified http.get function
278function 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
285end
286</pre>
287
288<!-- sinks ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
289
290<h3 id="source">Sources</h3>
291
292<!-- cat ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
293
294<p class=name id="source.cat">
295ltn12.source.<b>cat(</b>source<sub>1</sub> [, source<sub>2</sub>, ...,
296source<sub>N</sub>]<b>)</b>
297</p>
298
299<p class=description>
300Creates a new source that produces the concatenation of the data produced
301by 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
306sources.
307</p>
308
309<p class=return>
310The function returns the new source.
311</p>
312
313<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
314
315<p class=name id="source.chain">
316ltn12.source.<b>chain(</b>source, filter<b>)</b>
317</p>
318
319<p class=description>
320Creates a new <tt>source</tt> that passes data through a <tt>filter</tt>
321before returning it.
322</p>
323
324<p class=return>
325The function returns the new source.
326</p>
327
328<!-- empty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
329
330<p class=name id="source.empty">
331ltn12.source.<b>empty()</b>
332</p>
333
334<p class=description>
335Creates and returns an empty source.
336</p>
337
338<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
339
340<p class=name id="source.error">
341ltn12.source.<b>error(</b>message<b>)</b>
342</p>
343
344<p class=description>
345Creates 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">
352ltn12.source.<b>file(</b>handle, message<b>)</b>
353</p>
354
355<p class=description>
356Creates 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>
365The function returns a source that reads chunks of data from
366given <tt>handle</tt> and returns it to the user,
367closing the file when done, or a source that aborts the transmission with
368the error <tt>message</tt>
369</p>
370
371<p class=note>
372In the following example, notice how the prototype is designed to
373fit nicely with the <tt>io.open</tt> function.
374</p>
375
376<pre class=example>
377-- load the ltn12 module
378local ltn12 = require("ltn12")
379
380-- copy a file
381ltn12.pump.all(
382 ltn12.source.file(io.open("original.png", "rb")),
383 ltn12.sink.file(io.open("copy.png", "wb"))
384)
385</pre>
386
387<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
388
389<p class=name id="source.simplify">
390ltn12.source.<b>simplify(</b>source<b>)</b>
391</p>
392
393<p class=description>
394Creates and returns a simple source given a fancy <tt>source</tt>.
395</p>
396
397<!-- string +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
398
399<p class=name id="source.string">
400ltn12.source.<b>string(</b>string<b>)</b>
401</p>
402
403<p class=description>
404Creates 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="index.html">home</a> &middot;
415<a href="index.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>
422Last modified by Diego Nehab on <br>
423Thu Apr 20 00:25:41 EDT 2006
424</small>
425</p>
426</center>
427</div>
428
429</body>
430</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-04-04 22:35:10 +0000