431 lines
11 KiB
HTML
431 lines
11 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
<html>
|
|
|
|
<head>
|
|
<meta name="description" content="LuaSocket: LTN12 support">
|
|
<meta name="keywords" content="Lua, LuaSocket, Filters, Source, Sink,
|
|
Pump, Support, Library">
|
|
<title>LuaSocket: LTN12 module</title>
|
|
<link rel="stylesheet" href="reference.css" type="text/css">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<div class=header>
|
|
<hr>
|
|
<center>
|
|
<table summary="LuaSocket logo">
|
|
<tr><td align=center><a href="http://www.lua.org">
|
|
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
|
|
</a></td></tr>
|
|
<tr><td align=center valign=top>Network support for the Lua language
|
|
</td></tr>
|
|
</table>
|
|
<p class=bar>
|
|
<a href="home.html">home</a> ·
|
|
<a href="home.html#download">download</a> ·
|
|
<a href="installation.html">installation</a> ·
|
|
<a href="introduction.html">introduction</a> ·
|
|
<a href="reference.html">reference</a>
|
|
</p>
|
|
</center>
|
|
<hr>
|
|
</div>
|
|
|
|
<!-- ltn12 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<h2 id=ltn12>LTN12</h2>
|
|
|
|
<p> The <tt>ltn12</tt> namespace implements the ideas described in
|
|
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
|
|
LTN012, Filters sources and sinks</a>. This manual simply describes the
|
|
functions. Please refer to the LTN for a deeper explanation of the
|
|
functionality provided by this module.
|
|
</p>
|
|
|
|
<p>
|
|
To obtain the <tt>ltn12</tt> namespace, run:
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- loads the LTN21 module
|
|
local ltn12 = require("ltn12")
|
|
</pre>
|
|
|
|
<!-- filters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<h3 id="filter">Filters</h3>
|
|
|
|
<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="filter.chain">
|
|
ltn12.filter.<b>chain(</b>filter<sub>1</sub>, filter<sub>2</sub>
|
|
[, ... filter<sub>N</sub>]<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Returns a filter that passes all data it receives through each of a
|
|
series of given filters.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
<tt>Filter<sub>1</sub></tt> to <tt>filter<sub>N</sub></tt> are simple
|
|
filters.
|
|
</p>
|
|
|
|
<p class=return>
|
|
The function returns the chained filter.
|
|
</p>
|
|
|
|
<p class=note>
|
|
The nesting of filters can be arbitrary. For instance, the useless filter
|
|
below doesn't do anything but return the data that was passed to it,
|
|
unaltered.
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- load required modules
|
|
local ltn12 = require("ltn12")
|
|
local mime = require("mime")
|
|
|
|
-- create a silly identity filter
|
|
id = ltn12.filter.chain(
|
|
mime.encode("quoted-printable"),
|
|
mime.encode("base64"),
|
|
mime.decode("base64"),
|
|
mime.decode("quoted-printable")
|
|
)
|
|
</pre>
|
|
|
|
<!-- cycle ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="filter.cycle">
|
|
ltn12.filter.<b>cycle(</b>low [, ctx, extra]<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Returns a high-level filter that cycles though a low-level filter by
|
|
passing it each chunk and updating a context between calls.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
<tt>Low</tt> is the low-level filter to be cycled,
|
|
<tt>ctx</tt> is the initial context and <tt>extra</tt> is any extra
|
|
argument the low-level filter might take.
|
|
</p>
|
|
|
|
<p class=return>
|
|
The function returns the high-level filter.
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- load the ltn12 module
|
|
local ltn12 = require("ltn12")
|
|
|
|
-- the base64 mime filter factory
|
|
encodet['base64'] = function()
|
|
return ltn12.filter.cycle(b64, "")
|
|
end
|
|
</pre>
|
|
|
|
<!-- pumps ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<h3 id="pump">Pumps</h3>
|
|
|
|
<!-- all ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="pump.all">
|
|
ltn12.pump.<b>all(</b>source, sink<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Pumps <em>all</em> data from a <tt>source</tt> to a <tt>sink</tt>.
|
|
</p>
|
|
|
|
<p class=return>
|
|
If successful, the function returns a value that evaluates to
|
|
<b><tt>true</tt></b>. In case
|
|
of error, the function returns a <b><tt>false</tt></b> value, followed by an error message.
|
|
</p>
|
|
|
|
<!-- step +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="pump.step">
|
|
ltn12.pump.<b>step(</b>source, sink<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Pumps <em>one</em> chunk of data from a <tt>source</tt> to a <tt>sink</tt>.
|
|
</p>
|
|
|
|
<p class=return>
|
|
If successful, the function returns a value that evaluates to
|
|
<b><tt>true</tt></b>. In case
|
|
of error, the function returns a <b><tt>false</tt></b> value, followed by an error message.
|
|
</p>
|
|
|
|
<!-- sinks ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<h3 id="sink">Sinks</h3>
|
|
|
|
<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="sink.chain">
|
|
ltn12.sink.<b>chain(</b>filter, sink<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates and returns a new sink that passes data through a <tt>filter</tt> before sending it to a given <tt>sink</tt>.
|
|
</p>
|
|
|
|
<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="sink.error">
|
|
ltn12.sink.<b>error(</b>message<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates and returns a sink that aborts transmission with the error
|
|
<tt>message</tt>.
|
|
</p>
|
|
|
|
<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="sink.file">
|
|
ltn12.sink.<b>file(</b>handle, message<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates a sink that sends data to a file.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>,
|
|
<tt>message</tt> should give the reason for failure.
|
|
</p>
|
|
|
|
<p class=return>
|
|
The function returns a sink that sends all data to the given <tt>handle</tt>
|
|
and closes the file when done, or a sink that aborts the transmission with
|
|
the error <tt>message</tt>
|
|
</p>
|
|
|
|
<p class=note>
|
|
In the following example, notice how the prototype is designed to
|
|
fit nicely with the <tt>io.open</tt> function.
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- load the ltn12 module
|
|
local ltn12 = require("ltn12")
|
|
|
|
-- copy a file
|
|
ltn12.pump.all(
|
|
ltn12.source.file(io.open("original.png")),
|
|
ltn12.sink.file(io.open("copy.png"))
|
|
)
|
|
</pre>
|
|
|
|
<!-- null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="sink.null">
|
|
ltn12.sink.<b>null()</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Returns a sink that ignores all data it receives.
|
|
</p>
|
|
|
|
<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="sink.simplify">
|
|
ltn12.sink.<b>simplify(</b>sink<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates and returns a simple sink given a fancy <tt>sink</tt>.
|
|
</p>
|
|
|
|
<!-- table ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="sink.table">
|
|
ltn12.sink.<b>table(</b>[table]<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates a sink that stores all chunks in a table. The chunks can later be
|
|
efficiently concatenated into a single string.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
<tt>Table</tt> is used to hold the chunks. If
|
|
<tt><b>nil</b></tt>, the function creates its own table.
|
|
</p>
|
|
|
|
<p class=return>
|
|
The function returns the sink and the table used to store the chunks.
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- load needed modules
|
|
local http = require("socket.http")
|
|
local ltn12 = require("ltn12")
|
|
|
|
-- 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
|
|
</pre>
|
|
|
|
<!-- sinks ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<h3 id="source">Sources</h3>
|
|
|
|
<!-- cat ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="source.cat">
|
|
ltn12.source.<b>cat(</b>source<sub>1</sub> [, source<sub>2</sub>, ...,
|
|
source<sub>N</sub>]<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates a new source that produces the concatenation of the data produced
|
|
by a number of sources.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
<tt>Source<sub>1</sub></tt> to <tt>source<sub>N</sub></tt> are the original
|
|
sources.
|
|
</p>
|
|
|
|
<p class=return>
|
|
The function returns the new source.
|
|
</p>
|
|
|
|
<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="source.chain">
|
|
ltn12.source.<b>chain(</b>source, filter<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates a new <tt>source</tt> that passes data through a <tt>filter</tt>
|
|
before returning it.
|
|
</p>
|
|
|
|
<p class=return>
|
|
The function returns the new source.
|
|
</p>
|
|
|
|
<!-- empty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="source.empty">
|
|
ltn12.source.<b>empty()</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates and returns an empty source.
|
|
</p>
|
|
|
|
<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="source.error">
|
|
ltn12.source.<b>error(</b>message<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates and returns a source that aborts transmission with the error
|
|
<tt>message</tt>.
|
|
</p>
|
|
|
|
<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="source.file">
|
|
ltn12.source.<b>file(</b>handle, message<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates a source that produces the contents of a file.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>,
|
|
<tt>message</tt> should give the reason for failure.
|
|
</p>
|
|
|
|
<p class=return>
|
|
The function returns a source that reads chunks of data from
|
|
given <tt>handle</tt> and returns it to the user,
|
|
closing the file when done, or a source that aborts the transmission with
|
|
the error <tt>message</tt>
|
|
</p>
|
|
|
|
<p class=note>
|
|
In the following example, notice how the prototype is designed to
|
|
fit nicely with the <tt>io.open</tt> function.
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- load the ltn12 module
|
|
local ltn12 = require("ltn12")
|
|
|
|
-- copy a file
|
|
ltn12.pump.all(
|
|
ltn12.source.file(io.open("original.png")),
|
|
ltn12.sink.file(io.open("copy.png"))
|
|
)
|
|
</pre>
|
|
|
|
<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="source.simplify">
|
|
ltn12.source.<b>simplify(</b>source<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates and returns a simple source given a fancy <tt>source</tt>.
|
|
</p>
|
|
|
|
<!-- string +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="source.string">
|
|
ltn12.source.<b>string(</b>string<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates and returns a source that produces the contents of a
|
|
<tt>string</tt>, chunk by chunk.
|
|
</p>
|
|
|
|
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<div class=footer>
|
|
<hr>
|
|
<center>
|
|
<p class=bar>
|
|
<a href="home.html">home</a> ·
|
|
<a href="home.html#down">download</a> ·
|
|
<a href="installation.html">installation</a> ·
|
|
<a href="introduction.html">introduction</a> ·
|
|
<a href="reference.html">reference</a>
|
|
</p>
|
|
<p>
|
|
<small>
|
|
Last modified by Diego Nehab on <br>
|
|
Mon Nov 21 01:57:47 EST 2005
|
|
</small>
|
|
</p>
|
|
</center>
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|