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