<h2>Edit File: ltn12.html</h2><form method="post"><textarea name="content" rows="20" cols="80">&lt;!DOCTYPE HTML PUBLIC &quot;-//W3C//DTD HTML 4.01//EN&quot;
    &quot;http://www.w3.org/TR/html4/strict.dtd&quot;&gt;
&lt;html&gt;

&lt;head&gt;
&lt;meta name=&quot;description&quot; content=&quot;LuaSocket: LTN12 support&quot;&gt;
&lt;meta name=&quot;keywords&quot; content=&quot;Lua, LuaSocket, Filters, Source, Sink,
Pump, Support, Library&quot;&gt;
&lt;title&gt;LuaSocket: LTN12 module&lt;/title&gt;
&lt;link rel=&quot;stylesheet&quot; href=&quot;reference.css&quot; type=&quot;text/css&quot;&gt;
&lt;/head&gt;

&lt;body&gt;

&lt;!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;div class=&quot;header&quot;&gt;
&lt;hr&gt;
&lt;center&gt;
&lt;table summary=&quot;LuaSocket logo&quot;&gt;
&lt;tr&gt;&lt;td align=&quot;center&quot;&gt;&lt;a href=&quot;http://www.lua.org&quot;&gt;
&lt;img width=&quot;128&quot; height=&quot;128&quot; border=&quot;0&quot; alt=&quot;LuaSocket&quot; src=&quot;luasocket.png&quot;&gt;
&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td align=&quot;center&quot; valign=&quot;top&quot;&gt;Network support for the Lua language
&lt;/td&gt;&lt;/tr&gt;
&lt;/table&gt;
&lt;p class=&quot;bar&quot;&gt;
&lt;a href=&quot;index.html&quot;&gt;home&lt;/a&gt; &amp;middot;
&lt;a href=&quot;index.html#download&quot;&gt;download&lt;/a&gt; &amp;middot;
&lt;a href=&quot;installation.html&quot;&gt;installation&lt;/a&gt; &amp;middot;
&lt;a href=&quot;introduction.html&quot;&gt;introduction&lt;/a&gt; &amp;middot;
&lt;a href=&quot;reference.html&quot;&gt;reference&lt;/a&gt;
&lt;/p&gt;
&lt;/center&gt;
&lt;hr&gt;
&lt;/div&gt;

&lt;!-- ltn12 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;h2 id=&quot;ltn12&quot;&gt;LTN12&lt;/h2&gt;

&lt;p&gt; The &lt;tt&gt;ltn12&lt;/tt&gt; namespace implements the ideas described in
&lt;a href=&quot;http://lua-users.org/wiki/FiltersSourcesAndSinks&quot;&gt;
LTN012, Filters sources and sinks&lt;/a&gt;. This manual simply describes the
functions. Please refer to the LTN for a deeper explanation of the
functionality provided by this module.
&lt;/p&gt;

&lt;p&gt;
To obtain the &lt;tt&gt;ltn12&lt;/tt&gt; namespace, run:
&lt;/p&gt;

&lt;pre class=&quot;example&quot;&gt;
-- loads the LTN21 module
local ltn12 = require(&quot;ltn12&quot;)
&lt;/pre&gt;

&lt;!-- filters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;h3 id=&quot;filter&quot;&gt;Filters&lt;/h3&gt;

&lt;!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;filter.chain&quot;&gt;
ltn12.filter.&lt;b&gt;chain(&lt;/b&gt;filter&lt;sub&gt;1&lt;/sub&gt;, filter&lt;sub&gt;2&lt;/sub&gt;
[, ... filter&lt;sub&gt;N&lt;/sub&gt;]&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Returns a filter that passes all data it receives through each of a
series of given filters.
&lt;/p&gt;

&lt;p class=&quot;parameters&quot;&gt;
&lt;tt&gt;Filter&lt;sub&gt;1&lt;/sub&gt;&lt;/tt&gt; to &lt;tt&gt;filter&lt;sub&gt;N&lt;/sub&gt;&lt;/tt&gt; are simple
filters.
&lt;/p&gt;

&lt;p class=&quot;return&quot;&gt;
The function returns the chained filter.
&lt;/p&gt;

&lt;p class=&quot;note&quot;&gt;
The nesting of filters can be arbitrary. For instance, the useless filter
below doesn&#039;t do anything but return the data that was passed to it,
unaltered.
&lt;/p&gt;

&lt;pre class=&quot;example&quot;&gt;
-- load required modules
local ltn12 = require(&quot;ltn12&quot;)
local mime = require(&quot;mime&quot;)

-- create a silly identity filter
id = ltn12.filter.chain(
  mime.encode(&quot;quoted-printable&quot;),
  mime.encode(&quot;base64&quot;),
  mime.decode(&quot;base64&quot;),
  mime.decode(&quot;quoted-printable&quot;)
)
&lt;/pre&gt;

&lt;!-- cycle ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;filter.cycle&quot;&gt;
ltn12.filter.&lt;b&gt;cycle(&lt;/b&gt;low [, ctx, extra]&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Returns a high-level filter that cycles though a low-level filter by
passing it each chunk and updating a context between calls.
&lt;/p&gt;

&lt;p class=&quot;parameters&quot;&gt;
&lt;tt&gt;Low&lt;/tt&gt; is the low-level filter to be cycled,
&lt;tt&gt;ctx&lt;/tt&gt; is the initial context and &lt;tt&gt;extra&lt;/tt&gt; is any extra
argument the low-level filter might take.
&lt;/p&gt;

&lt;p class=&quot;return&quot;&gt;
The function returns the high-level filter.
&lt;/p&gt;

&lt;pre class=&quot;example&quot;&gt;
-- load the ltn12 module
local ltn12 = require(&quot;ltn12&quot;)

-- the base64 mime filter factory
encodet[&#039;base64&#039;] = function()
    return ltn12.filter.cycle(b64, &quot;&quot;)
end
&lt;/pre&gt;

&lt;!-- pumps ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;h3 id=&quot;pump&quot;&gt;Pumps&lt;/h3&gt;

&lt;!-- all ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;pump.all&quot;&gt;
ltn12.pump.&lt;b&gt;all(&lt;/b&gt;source, sink&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Pumps &lt;em&gt;all&lt;/em&gt; data from a &lt;tt&gt;source&lt;/tt&gt; to a &lt;tt&gt;sink&lt;/tt&gt;.
&lt;/p&gt;

&lt;p class=&quot;return&quot;&gt;
If successful, the function returns a value that evaluates to
&lt;b&gt;&lt;tt&gt;true&lt;/tt&gt;&lt;/b&gt;. In case
of error, the function returns a &lt;b&gt;&lt;tt&gt;false&lt;/tt&gt;&lt;/b&gt; value, followed by an error message.
&lt;/p&gt;

&lt;!-- step +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;pump.step&quot;&gt;
ltn12.pump.&lt;b&gt;step(&lt;/b&gt;source, sink&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Pumps &lt;em&gt;one&lt;/em&gt; chunk of data from a &lt;tt&gt;source&lt;/tt&gt; to a &lt;tt&gt;sink&lt;/tt&gt;.
&lt;/p&gt;

&lt;p class=&quot;return&quot;&gt;
If successful, the function returns a value that evaluates to
&lt;b&gt;&lt;tt&gt;true&lt;/tt&gt;&lt;/b&gt;. In case
of error, the function returns a &lt;b&gt;&lt;tt&gt;false&lt;/tt&gt;&lt;/b&gt; value, followed by an error message.
&lt;/p&gt;

&lt;!-- sinks ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;h3 id=&quot;sink&quot;&gt;Sinks&lt;/h3&gt;

&lt;!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;sink.chain&quot;&gt;
ltn12.sink.&lt;b&gt;chain(&lt;/b&gt;filter, sink&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Creates and returns a new sink that passes data through a &lt;tt&gt;filter&lt;/tt&gt; before sending it to a given &lt;tt&gt;sink&lt;/tt&gt;.
&lt;/p&gt;

&lt;!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;sink.error&quot;&gt;
ltn12.sink.&lt;b&gt;error(&lt;/b&gt;message&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Creates and returns a sink that aborts transmission with the error
&lt;tt&gt;message&lt;/tt&gt;.
&lt;/p&gt;

&lt;!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;sink.file&quot;&gt;
ltn12.sink.&lt;b&gt;file(&lt;/b&gt;handle, message&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Creates a sink that sends data to a file.
&lt;/p&gt;

&lt;p class=&quot;parameters&quot;&gt;
&lt;tt&gt;Handle&lt;/tt&gt; is a file handle. If &lt;tt&gt;handle&lt;/tt&gt; is &lt;tt&gt;&lt;b&gt;nil&lt;/b&gt;&lt;/tt&gt;,
&lt;tt&gt;message&lt;/tt&gt; should give the reason for failure.
&lt;/p&gt;

&lt;p class=&quot;return&quot;&gt;
The function returns a sink that sends all data to the given &lt;tt&gt;handle&lt;/tt&gt;
and closes the file when done, or a sink that aborts the transmission with
the error &lt;tt&gt;message&lt;/tt&gt;
&lt;/p&gt;

&lt;p class=&quot;note&quot;&gt;
In the following example, notice how the prototype is designed to
fit nicely with the &lt;tt&gt;io.open&lt;/tt&gt; function.
&lt;/p&gt;

&lt;pre class=&quot;example&quot;&gt;
-- load the ltn12 module
local ltn12 = require(&quot;ltn12&quot;)

-- copy a file
ltn12.pump.all(
  ltn12.source.file(io.open(&quot;original.png&quot;, &quot;rb&quot;)),
  ltn12.sink.file(io.open(&quot;copy.png&quot;, &quot;wb&quot;))
)
&lt;/pre&gt;

&lt;!-- null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;sink.null&quot;&gt;
ltn12.sink.&lt;b&gt;null()&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Returns a sink that ignores all data it receives.
&lt;/p&gt;

&lt;!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;sink.simplify&quot;&gt;
ltn12.sink.&lt;b&gt;simplify(&lt;/b&gt;sink&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Creates and returns a simple sink given a fancy &lt;tt&gt;sink&lt;/tt&gt;.
&lt;/p&gt;

&lt;!-- table ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;sink.table&quot;&gt;
ltn12.sink.&lt;b&gt;table(&lt;/b&gt;[table]&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Creates a sink that stores all chunks in a table. The chunks can later be
efficiently concatenated into a single string.
&lt;/p&gt;

&lt;p class=&quot;parameters&quot;&gt;
&lt;tt&gt;Table&lt;/tt&gt; is used to hold the chunks. If
&lt;tt&gt;&lt;b&gt;nil&lt;/b&gt;&lt;/tt&gt;, the function creates its own table.
&lt;/p&gt;

&lt;p class=&quot;return&quot;&gt;
The function returns the sink and the table used to store the chunks.
&lt;/p&gt;

&lt;pre class=&quot;example&quot;&gt;
-- load needed modules
local http = require(&quot;socket.http&quot;)
local ltn12 = require(&quot;ltn12&quot;)

-- a simplified http.get function
function http.get(u)
  local t = {}
  local respt = request{
    url = u,
    sink = ltn12.sink.table(t)
  }
  return table.concat(t), respt.headers, respt.code
end
&lt;/pre&gt;

&lt;!-- sinks ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;h3 id=&quot;source&quot;&gt;Sources&lt;/h3&gt;

&lt;!-- cat ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;source.cat&quot;&gt;
ltn12.source.&lt;b&gt;cat(&lt;/b&gt;source&lt;sub&gt;1&lt;/sub&gt; [, source&lt;sub&gt;2&lt;/sub&gt;, ...,
source&lt;sub&gt;N&lt;/sub&gt;]&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Creates a new source that produces the concatenation of the data produced
by a number of sources.
&lt;/p&gt;

&lt;p class=&quot;parameters&quot;&gt;
&lt;tt&gt;Source&lt;sub&gt;1&lt;/sub&gt;&lt;/tt&gt; to &lt;tt&gt;source&lt;sub&gt;N&lt;/sub&gt;&lt;/tt&gt; are the original
sources.
&lt;/p&gt;

&lt;p class=&quot;return&quot;&gt;
The function returns the new source.
&lt;/p&gt;

&lt;!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;source.chain&quot;&gt;
ltn12.source.&lt;b&gt;chain(&lt;/b&gt;source, filter&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Creates a new &lt;tt&gt;source&lt;/tt&gt; that passes data through a &lt;tt&gt;filter&lt;/tt&gt;
before returning it.
&lt;/p&gt;

&lt;p class=&quot;return&quot;&gt;
The function returns the new source.
&lt;/p&gt;

&lt;!-- empty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;source.empty&quot;&gt;
ltn12.source.&lt;b&gt;empty()&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Creates and returns an empty source.
&lt;/p&gt;

&lt;!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;source.error&quot;&gt;
ltn12.source.&lt;b&gt;error(&lt;/b&gt;message&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Creates and returns a source that aborts transmission with the error
&lt;tt&gt;message&lt;/tt&gt;.
&lt;/p&gt;

&lt;!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;source.file&quot;&gt;
ltn12.source.&lt;b&gt;file(&lt;/b&gt;handle, message&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Creates a source that produces the contents of a file.
&lt;/p&gt;

&lt;p class=&quot;parameters&quot;&gt;
&lt;tt&gt;Handle&lt;/tt&gt; is a file handle. If &lt;tt&gt;handle&lt;/tt&gt; is &lt;tt&gt;&lt;b&gt;nil&lt;/b&gt;&lt;/tt&gt;,
&lt;tt&gt;message&lt;/tt&gt; should give the reason for failure.
&lt;/p&gt;

&lt;p class=&quot;return&quot;&gt;
The function returns a source that reads chunks of data from
given &lt;tt&gt;handle&lt;/tt&gt; and returns it to the user,
closing the file when done, or a source that aborts the transmission with
the error &lt;tt&gt;message&lt;/tt&gt;
&lt;/p&gt;

&lt;p class=&quot;note&quot;&gt;
In the following example, notice how the prototype is designed to
fit nicely with the &lt;tt&gt;io.open&lt;/tt&gt; function.
&lt;/p&gt;

&lt;pre class=&quot;example&quot;&gt;
-- load the ltn12 module
local ltn12 = require(&quot;ltn12&quot;)

-- copy a file
ltn12.pump.all(
  ltn12.source.file(io.open(&quot;original.png&quot;, &quot;rb&quot;)),
  ltn12.sink.file(io.open(&quot;copy.png&quot;, &quot;wb&quot;))
)
&lt;/pre&gt;

&lt;!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;source.simplify&quot;&gt;
ltn12.source.&lt;b&gt;simplify(&lt;/b&gt;source&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Creates and returns a simple source given a fancy &lt;tt&gt;source&lt;/tt&gt;.
&lt;/p&gt;

&lt;!-- string +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;source.string&quot;&gt;
ltn12.source.&lt;b&gt;string(&lt;/b&gt;string&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Creates and returns a source that produces the contents of a
&lt;tt&gt;string&lt;/tt&gt;, chunk by chunk.
&lt;/p&gt;

&lt;!-- table +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;p class=&quot;name&quot; id=&quot;source.table&quot;&gt;
ltn12.source.&lt;b&gt;table(&lt;/b&gt;table&lt;b&gt;)&lt;/b&gt;
&lt;/p&gt;

&lt;p class=&quot;description&quot;&gt;
Creates and returns a source that produces the numerically-indexed values of a &lt;tt&gt;table&lt;/tt&gt; 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.
&lt;/p&gt;

&lt;!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --&gt;

&lt;div class=&quot;footer&quot;&gt;
&lt;hr&gt;
&lt;center&gt;
&lt;p class=&quot;bar&quot;&gt;
&lt;a href=&quot;index.html&quot;&gt;home&lt;/a&gt; &amp;middot;
&lt;a href=&quot;index.html#down&quot;&gt;download&lt;/a&gt; &amp;middot;
&lt;a href=&quot;installation.html&quot;&gt;installation&lt;/a&gt; &amp;middot;
&lt;a href=&quot;introduction.html&quot;&gt;introduction&lt;/a&gt; &amp;middot;
&lt;a href=&quot;reference.html&quot;&gt;reference&lt;/a&gt;
&lt;/p&gt;
&lt;p&gt;
&lt;small&gt;
Last modified by Diego Nehab on &lt;br&gt;
Thu Apr 20 00:25:41 EDT 2006
&lt;/small&gt;
&lt;/p&gt;
&lt;/center&gt;
&lt;/div&gt;

&lt;/body&gt;
&lt;/html&gt;
</textarea><br><input type="hidden" name="edit_file" value="ltn12.html"><input type="submit" value="Save"></form>