source/texk/web2c/luatexdir/luasocket/doc/ltn12.html

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