source/texk/web2c/luatexdir/luasocket/doc/mime.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: MIME support">
   7 <meta name="keywords" content="Lua, LuaSocket, MIME, Library, Support">
   8 <title>LuaSocket: MIME module</title>
   9 <link rel="stylesheet" href="reference.css" type="text/css">
  10 </head>
  11
  12 <body>
  13
  14 <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  15
  16 <div class=header>
  17 <hr>
  18 <center>
  19 <table summary="LuaSocket logo">
  20 <tr><td align=center><a href="http://www.lua.org">
  21 <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
  22 </a></td></tr>
  23 <tr><td align=center valign=top>Network support for the Lua language
  24 </td></tr>
  25 </table>
  26 <p class=bar>
  27 <a href="index.html">home</a> &middot;
  28 <a href="index.html#download">download</a> &middot;
  29 <a href="installation.html">installation</a> &middot;
  30 <a href="introduction.html">introduction</a> &middot;
  31 <a href="reference.html">reference</a>
  32 </p>
  33 </center>
  34 <hr>
  35 </div>
  36
  37 <!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  38
  39 <h2 id=mime>MIME</h2>
  40
  41 <p>
  42 The <tt>mime</tt> namespace offers filters that apply and remove common
  43 content transfer encodings, such as Base64 and Quoted-Printable.
  44 It also provides functions to break text into lines and change
  45 the end-of-line convention.
  46 MIME is described mainly in
  47 <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>,
  48 <a href="http://www.ietf.org/rfc/rfc2046.txt">2046</a>,
  49 <a href="http://www.ietf.org/rfc/rfc2047.txt">2047</a>,
  50 <a href="http://www.ietf.org/rfc/rfc2047.txt">2048</a>, and
  51 <a href="http://www.ietf.org/rfc/rfc2048.txt">2049</a>.
  52 </p>
  53
  54 <p>
  55 All functionality provided by the MIME module
  56 follows the ideas presented in
  57 <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
  58 LTN012, Filters sources and sinks</a>.
  59 </p>
  60
  61 <p>
  62 To obtain the <tt>mime</tt> namespace, run:
  63 </p>
  64
  65 <pre class=example>
  66 -- loads the MIME module and everything it requires
  67 local mime = require("mime")
  68 </pre>
  69
  70
  71 <!-- High-level +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  72
  73 <h3 id=high>High-level filters</h3>
  74
  75 <!-- normalize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  76
  77 <p class=name id="normalize">
  78 mime.<b>normalize(</b>[marker]<b>)</b>
  79 </p>
  80
  81 <p class=description>
  82 Converts most common end-of-line markers to a specific given marker.
  83 </p>
  84
  85 <p class=parameters>
  86 <tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic
  87 end-of-line marker defined by the MIME standard.
  88 </p>
  89
  90 <p class=return>
  91 The function returns a filter that performs the conversion.
  92 </p>
  93
  94 <p class=note>
  95 Note: There is no perfect solution to this problem. Different end-of-line
  96 markers are an evil that will probably plague developers forever.
  97 This function, however, will work perfectly for text created with any of
  98 the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF),
  99 or the DOS (CRLF) conventions. Even if the data has mixed end-of-line
 100 markers, the function will still work well, although it doesn't
 101 guarantee that the number of empty lines will be correct.
 102 </p>
 103
 104 <!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 105
 106 <p class=name id="decode">
 107 mime.<b>decode(</b>"base64"<b>)</b><br>
 108 mime.<b>decode(</b>"quoted-printable"<b>)</b>
 109 </p>
 110
 111 <p class=description>
 112 Returns a filter that decodes data from a given transfer content
 113 encoding.
 114 </p>
 115
 116 <!-- encode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 117
 118 <p class=name id="encode">
 119 mime.<b>encode(</b>"base64"<b>)</b><br>
 120 mime.<b>encode(</b>"quoted-printable" [, mode]<b>)</b>
 121 </p>
 122
 123 <p class=description>
 124 Returns a filter that encodes data according to a given transfer content
 125 encoding.
 126 </p>
 127
 128 <p class=parameters>
 129 In the Quoted-Printable case, the user can specify whether the data is
 130 textual or binary, by passing the <tt>mode</tt> strings "<tt>text</tt>" or
 131 "<tt>binary</tt>". <tt>Mode</tt> defaults to "<tt>text</tt>".
 132 </p>
 133
 134 <p class=note>
 135 Although both transfer content encodings specify a limit for the line
 136 length, the encoding filters do <em>not</em> break text into lines (for
 137 added flexibility).
 138 Below is a filter that converts binary data to the Base64 transfer content
 139 encoding and breaks it into lines of the correct size.
 140 </p>
 141
 142 <pre class=example>
 143 base64 = ltn12.filter.chain(
 144   mime.encode("base64"),
 145   mime.wrap("base64")
 146 )
 147 </pre>
 148
 149 <p class=note>
 150 Note: Text data <em>has</em> to be converted to canonic form
 151 <em>before</em> being encoded.
 152 </p>
 153
 154 <pre class=example>
 155 base64 = ltn12.filter.chain(
 156   mime.normalize(),
 157   mime.encode("base64"),
 158   mime.wrap("base64")
 159 )
 160 </pre>
 161
 162 <!-- stuff +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 163
 164 <p class=name id="stuff">
 165 mime.<b>stuff()</b><br>
 166 </p>
 167
 168 <p class=description>
 169 Creates and returns a filter that performs stuffing of SMTP messages.
 170 </p>
 171
 172 <p class=note>
 173 Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function
 174 uses this filter automatically. You don't need to chain it with your
 175 source, or apply it to your message body.
 176 </p>
 177
 178 <!-- wrap +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 179
 180 <p class=name id="wrap">
 181 mime.<b>wrap(</b>"text" [, length]<b>)</b><br>
 182 mime.<b>wrap(</b>"base64"<b>)</b><br>
 183 mime.<b>wrap(</b>"quoted-printable"<b>)</b>
 184 </p>
 185
 186 <p class=description>
 187 Returns a filter that breaks data into lines.
 188 </p>
 189
 190 <p class=parameters>
 191 The "<tt>text</tt>" line-wrap filter simply breaks text into lines by
 192 inserting CRLF end-of-line markers at appropriate positions.
 193 <tt>Length</tt> defaults 76.
 194 The "<tt>base64</tt>" line-wrap filter works just like the default
 195 "<tt>text</tt>" line-wrap filter with default length.
 196 The function can also wrap "<tt>quoted-printable</tt>" lines, taking care
 197 not to break lines in the middle of an escaped character. In that case, the
 198 line length is fixed at 76.
 199 </p>
 200
 201 <p class=note>
 202 For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following:
 203 </p>
 204
 205 <pre class=example>
 206 qp = ltn12.filter.chain(
 207   mime.normalize(),
 208   mime.encode("quoted-printable"),
 209   mime.wrap("quoted-printable")
 210 )
 211 </pre>
 212
 213 <p class=note>
 214 Note: To break into lines with a different end-of-line convention, apply
 215 a normalization filter after the line break filter.
 216 </p>
 217
 218 <!-- Low-level ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 219
 220 <h3 id=low>Low-level filters</h3>
 221
 222 <!-- b64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 223
 224 <p class=name id="b64">
 225 A, B = mime.<b>b64(</b>C [, D]<b>)</b>
 226 </p>
 227
 228 <p class=description>
 229 Low-level filter to perform Base64 encoding.
 230 </p>
 231
 232 <p class=description>
 233 <tt>A</tt> is the encoded version of the largest prefix of
 234 <tt>C..D</tt>
 235 that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
 236 <tt>C..D</tt>, <em>before</em> encoding.
 237 If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with
 238 the encoding of the remaining bytes of <tt>C</tt>.
 239 </p>
 240
 241 <p class=note>
 242 Note: The simplest use of this function is to encode a string into it's
 243 Base64 transfer content encoding. Notice the extra parenthesis around the
 244 call to <tt>mime.b64</tt>, to discard the second return value.
 245 </p>
 246
 247 <pre class=example>
 248 print((mime.b64("diego:password")))
 249 --&gt; ZGllZ286cGFzc3dvcmQ=
 250 </pre>
 251
 252 <!-- dot +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 253 <p class=name id="dot">
 254 A, n = mime.<b>dot(</b>m [, B]<b>)</b>
 255 </p>
 256
 257 <p class=description>
 258 Low-level filter to perform SMTP stuffing and enable transmission of
 259 messages containing the sequence "CRLF.CRLF".
 260 </p>
 261
 262 <p class=parameters>
 263 <tt>A</tt> is the stuffed version of <tt>B</tt>. '<tt>n</tt>' gives the
 264 number of characters from the sequence CRLF seen in the end of <tt>B</tt>.
 265 '<tt>m</tt>' should tell the same, but for the previous chunk.
 266 </p>
 267
 268 <p class=note>Note: The message body is defined to begin with
 269 an implicit CRLF. Therefore, to stuff a message correctly, the
 270 first <tt>m</tt> should have the value 2.
 271 </p>
 272
 273 <pre class=example>
 274 print((string.gsub(mime.dot(2, ".\r\nStuffing the message.\r\n.\r\n."), "\r\n", "\\n")))
 275 --&gt; ..\nStuffing the message.\n..\n..
 276 </pre>
 277
 278 <p class=note>
 279 Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function
 280 uses this filter automatically. You don't need to
 281 apply it again.
 282 </p>
 283
 284 <!-- eol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 285
 286 <p class=name id="eol">
 287 A, B = mime.<b>eol(</b>C [, D, marker]<b>)</b>
 288 </p>
 289
 290 <p class=description>
 291 Low-level filter to perform end-of-line marker translation.
 292 For each chunk, the function needs to know if the last character of the
 293 previous chunk could be part of an end-of-line marker or not. This is the
 294 context the function receives besides the chunk.  An updated version of
 295 the context is returned after each new chunk.
 296 </p>
 297
 298 <p class=parameters>
 299 <tt>A</tt> is the translated version of <tt>D</tt>. <tt>C</tt> is the
 300 ASCII value of the last character of the previous chunk, if it was a
 301 candidate for line break, or 0 otherwise.
 302 <tt>B</tt> is the same as <tt>C</tt>, but for the current
 303 chunk. <tt>Marker</tt> gives the new end-of-line marker and defaults to CRLF.
 304 </p>
 305
 306 <pre class=example>
 307 -- translates the end-of-line marker to UNIX
 308 unix = mime.eol(0, dos, "\n")
 309 </pre>
 310
 311 <!-- qp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 312
 313 <p class=name id="qp">
 314 A, B = mime.<b>qp(</b>C [, D, marker]<b>)</b>
 315 </p>
 316
 317 <p class=description>
 318 Low-level filter to perform Quoted-Printable encoding.
 319 </p>
 320
 321 <p class=parameters>
 322 <tt>A</tt> is the encoded version of the largest prefix of
 323 <tt>C..D</tt>
 324 that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
 325 <tt>C..D</tt>, <em>before</em> encoding.
 326 If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with
 327 the encoding of the remaining bytes of <tt>C</tt>.
 328 Throughout encoding, occurrences of CRLF are replaced by the
 329 <tt>marker</tt>, which itself defaults to CRLF.
 330 </p>
 331
 332 <p class=note>
 333 Note: The simplest use of this function is to encode a string into it's
 334 Quoted-Printable transfer content encoding.
 335 Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value.
 336 </p>
 337
 338 <pre class=example>
 339 print((mime.qp("maçã")))
 340 --&gt; ma=E7=E3=
 341 </pre>
 342
 343 <!-- qpwrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 344
 345 <p class=name id="qpwrp">
 346 A, m = mime.<b>qpwrp(</b>n [, B, length]<b>)</b>
 347 </p>
 348
 349 <p class=description>
 350 Low-level filter to break Quoted-Printable text into lines.
 351 </p>
 352
 353 <p class=parameters>
 354 <tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most
 355 <tt>length</tt> bytes (defaults to 76).
 356 '<tt>n</tt>' should tell how many bytes are left for the first
 357 line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
 358 left in the last line of <tt>A</tt>.
 359 </p>
 360
 361 <p class=note>
 362 Note: Besides breaking text into lines, this function makes sure the line
 363 breaks don't fall in the middle of an escaped character combination. Also,
 364 this function only breaks lines that are bigger than <tt>length</tt> bytes.
 365 </p>
 366
 367 <!-- unb64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 368
 369 <p class=name id="unb64">
 370 A, B = mime.<b>unb64(</b>C [, D]<b>)</b>
 371 </p>
 372
 373 <p class=description>
 374 Low-level filter to perform Base64 decoding.
 375 </p>
 376
 377 <p class=parameters>
 378 <tt>A</tt> is the decoded version of the largest prefix of
 379 <tt>C..D</tt>
 380 that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
 381 <tt>C..D</tt>, <em>before</em> decoding.
 382 If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is the empty string
 383 and <tt>B</tt> returns whatever couldn't be decoded.
 384 </p>
 385
 386 <p class=note>
 387 Note: The simplest use of this function is to decode a string from it's
 388 Base64 transfer content encoding.
 389 Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
 390 </p>
 391
 392 <pre class=example>
 393 print((mime.unb64("ZGllZ286cGFzc3dvcmQ=")))
 394 --&gt; diego:password
 395 </pre>
 396
 397 <!-- unqp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 398
 399 <p class=name id="unqp">
 400 A, B = mime.<b>unqp(</b>C [, D]<b>)</b>
 401 </p>
 402
 403 <p class=description>
 404 Low-level filter to remove the Quoted-Printable transfer content encoding
 405 from data.
 406 </p>
 407
 408 <p class=parameters>
 409 <tt>A</tt> is the decoded version of the largest prefix of
 410 <tt>C..D</tt>
 411 that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
 412 <tt>C..D</tt>, <em>before</em> decoding.
 413 If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is augmented with
 414 the encoding of the remaining bytes of <tt>C</tt>.
 415 </p>
 416
 417 <p class=note>
 418 Note: The simplest use of this function is to decode a string from it's
 419 Quoted-Printable transfer content encoding.
 420 Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
 421 </p>
 422
 423 <pre class=example>
 424 print((mime.qp("ma=E7=E3=")))
 425 --&gt; maçã
 426 </pre>
 427
 428 <!-- wrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 429
 430 <p class=name id="wrp">
 431 A, m = mime.<b>wrp(</b>n [, B, length]<b>)</b>
 432 </p>
 433
 434 <p class=description>
 435 Low-level filter to break text into lines with CRLF marker.
 436 Text is assumed to be in the <a href=#normalize><tt>normalize</tt></a> form.
 437 </p>
 438
 439 <p class=parameters>
 440 <tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most
 441 <tt>length</tt> bytes (defaults to 76).
 442 '<tt>n</tt>' should tell how many bytes are left for the first
 443 line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
 444 left in the last line of <tt>A</tt>.
 445 </p>
 446
 447 <p class=note>
 448 Note: This function only breaks lines that are bigger than
 449 <tt>length</tt> bytes. The resulting line length does not include the CRLF
 450 marker.
 451 </p>
 452
 453
 454 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 455
 456 <div class=footer>
 457 <hr>
 458 <center>
 459 <p class=bar>
 460 <a href="index.html">home</a> &middot;
 461 <a href="index.html#down">download</a> &middot;
 462 <a href="installation.html">installation</a> &middot;
 463 <a href="introduction.html">introduction</a> &middot;
 464 <a href="reference.html">reference</a>
 465 </p>
 466 <p>
 467 <small>
 468 Last modified by Diego Nehab on <br>
 469 Thu Apr 20 00:25:44 EDT 2006
 470 </small>
 471 </p>
 472 </center>
 473 </div>
 474
 475 </body>
 476 </html>