aboutsummaryrefslogtreecommitdiff
path: root/docs/ltn12.html
diff options
context:
space:
mode:
authorCaleb Maclennan <caleb@alerque.com>2023-11-10 09:12:04 +0300
committerCaleb Maclennan <caleb@alerque.com>2023-11-10 09:12:04 +0300
commit5c4fc93d5f4137bf4c22ddf1a048c907a4a26727 (patch)
treea9a68e1f6a9c3bfe2b64fa1c3a4098865b7d3b5d /docs/ltn12.html
parentccef3bc4e2aa6ee5b997a80aabb58f4ff0b0e98f (diff)
parent43a97b7f0053313b43906371dbdc226271e6c8ab (diff)
downloadluasocket-hjelmeland-patch-1.tar.gz
luasocket-hjelmeland-patch-1.tar.bz2
luasocket-hjelmeland-patch-1.zip
Merge branch 'master' into hjelmeland-patch-1hjelmeland-patch-1
Diffstat (limited to 'docs/ltn12.html')
-rw-r--r--docs/ltn12.html440
1 files changed, 440 insertions, 0 deletions
diff --git a/docs/ltn12.html b/docs/ltn12.html
new file mode 100644
index 0000000..fe3e3a0
--- /dev/null
+++ b/docs/ltn12.html
@@ -0,0 +1,440 @@
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<!-- table +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
409
410<p class="name" id="source.table">
411ltn12.source.<b>table(</b>table<b>)</b>
412</p>
413
414<p class="description">
415Creates and returns a source that produces the numerically-indexed values of a <tt>table</tt> successively beginning at 1. The source returns nil (end-of-stream) whenever a nil value is produced by the current index, which proceeds forward regardless.
416</p>
417
418<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
419
420<div class="footer">
421<hr>
422<center>
423<p class="bar">
424<a href="index.html">home</a> &middot;
425<a href="index.html#down">download</a> &middot;
426<a href="installation.html">installation</a> &middot;
427<a href="introduction.html">introduction</a> &middot;
428<a href="reference.html">reference</a>
429</p>
430<p>
431<small>
432Last modified by Diego Nehab on <br>
433Thu Apr 20 00:25:41 EDT 2006
434</small>
435</p>
436</center>
437</div>
438
439</body>
440</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-12-13 23:46:22 +0000