mirror of
https://github.com/lunarmodules/luasocket.git
synced 2024-07-03 11:49:47 +02:00
58096449c6
Implemented new distribution scheme. Select is now purely C. HTTP reimplemented seems faster dunno why. LTN12 functions that coroutines fail gracefully.
422 lines
10 KiB
HTML
422 lines
10 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
<html>
|
|
|
|
<head>
|
|
<title>LuaSocket: Network support for the Lua language</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 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="introduction.html">introduction</a> ·
|
|
<a href="reference.html">reference</a>
|
|
</p>
|
|
</center>
|
|
<hr>
|
|
</div>
|
|
|
|
<!-- ltn12 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<h2 id=ltn12>LTN12</h2>
|
|
|
|
<p> The LTN12 module implements the ideas described in
|
|
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
|
|
LTN012, Filters sources and sinks</a>. This manual simply describe the
|
|
functions. Please refer to the LTN for a deeper explanation of the
|
|
functionality provided by this module.
|
|
</p>
|
|
|
|
<!-- 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 arbritrary. 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
|
|
ltn12 = require("ltn12")
|
|
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 a new sink that passes data through a <tt>filter</tt> before sending
|
|
it to a given <tt>sink</tt>.
|
|
</p>
|
|
|
|
<p class=return>
|
|
The function returns the new sink.
|
|
</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 an 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
|
|
an 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.
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- load needed modules
|
|
local http = require("http")
|
|
local ltn12 = require("ltn12")
|
|
|
|
-- the http.get function
|
|
function get(u)
|
|
local t = {}
|
|
local respt = request{
|
|
url = u,
|
|
sink = ltn12.sink.table(t)
|
|
}
|
|
return table.concat(t), respt.headers, respt.code, respt.error
|
|
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 an 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
|
|
an 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="introduction.html">introduction</a> ·
|
|
<a href="reference.html">reference</a>
|
|
</p>
|
|
<p>
|
|
<small>
|
|
Last modified by Diego Nehab on <br>
|
|
Sat Aug 9 01:00:41 PDT 2003
|
|
</small>
|
|
</p>
|
|
</center>
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|