1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
\input texinfo
@setfilename guile-email.info
@settitle guile-email
@copying
Copyright @copyright{} 2019 Arun Isaac@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end copying
@ifnottex
@node Top
@top guile-email
@end ifnottex
@menu
* Introduction:: What is guile-email?
* Parsing e-mail:: Parsing e-mail
* Encoding and Decoding:: Encoding and decoding Base64, Quoted-Printable
and Q-encoding
* Contributing:: Contributing
Indices
* Procedure Index::
* Type Index::
@end menu
@node Introduction
@chapter Introduction
guile-email is a collection of email utilities implemented in pure
guile. It supports parsing MIME (Multipurpose Internet Mail Extensions)
compliant email messages as specified in RFC5322, RFC2045, RFC2046,
RF2047 and RFC2049.
@section Features
@itemize
@item Parse @uref{https://tools.ietf.org/html/rfc5322,,RFC5322} compliant email messages (currently does not support @uref{https://tools.ietf.org/html/rfc5322#section-4,,obsolete syntax})
@item Parse MIME compliant email messages as specified in @uref{https://tools.ietf.org/html/rfc2045,,RFC2045}, @uref{https://tools.ietf.org/html/rfc2046,,RFC2046}, @uref{https://tools.ietf.org/html/rfc2047,,RFC2047} and @uref{https://tools.ietf.org/html/rfc2049,,RFC2049}
@item Parse non-standard @uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Mail-Headers.html, Emacs message mode parens style addresses}
@item Encode and decode Quoted-Printable encoding, Base64 encoding and Q-encoding
@item Read emails from the @uref{https://en.wikipedia.org/wiki/Mbox, mbox format}
@end itemize
@node Parsing e-mail
@chapter Parsing e-mail
@deffn {Scheme Procedure} parse-email email
Parse string @var{email} and return result as an <email> record.
@end deffn
@deffn {Scheme Procedure} parse-email-headers headers
Parse string @var{headers} as email headers and return an association
list of header keys and values.
@end deffn
@deffn {Scheme Procedure} parse-email-body headers body
Parse @var{body} as email body where @var{headers} is an association
list of header keys and values as returned by
@code{parse-email-headers}. Return a list of <mime-entity> records if
the body is a multipart message. Else, return a single <mime-entity>
record.
@end deffn
@node Encoding and Decoding
@chapter Encoding and Decoding
guile-email supports encoding and decoding using Base64 encoding,
Quoted-Printable encoding and Q-encoding. Note that guile-email
automatically invokes the necessary decoding procedures while parsing
email. The following procedures are only provided in case you need to
use them in a context not automatically handled by guile-email.
Character encoding schemes such as UTF-8 encode characters as bytes.
Encoding schemes such as Quoted-Printable encoding, Base64 encoding and
Q-encoding re-encode these bytes as 7-bit text suitable for transmission
over a medium such as email that is not 8-bit clean. Therefore, the
input to the following encoding procedures and the output from the
following decoding procedures is a bytevector. Encoding characters to
bytes or decoding bytes to characters is not within the scope of these
procedures. @xref{Representing Strings as Bytes,,, guile} for more
information on how to do this.
@section Base64 encoding
@example
(use-modules (email base64))
@end example
@deffn {Scheme Procedure} base64-encode bv
Encode bytevector @var{bv} using Base64 encoding and return the encoded
string.
@end deffn
@deffn {Scheme Procedure} base64-decode str
Decode Base64 encoded string @var{str} and return the decoded
bytevector.
@end deffn
@section Quoted-Printable encoding
@example
(use-modules (email quoted-printable))
@end example
The Quoted-Printable encoding and decoding procedures in this section
are typed functions in that they behave differently based on the types
of their arguments.
@deftypefn {Scheme Procedure} {} quoted-printable-encode (bytevector @var{bv})
@deftypefnx {Scheme Procedure} {} quoted-printable-encode (port @var{in})
@deftypefnx {Scheme Procedure} {} quoted-printable-encode (port @var{in}) (port @var{out})
Encode bytevector @var{bv} using Quoted-Printable encoding and return
the encoded string.
Read bytes from the bytevector input port @var{in} and return the
Quoted-Printable encoded string.
Read bytes from the bytevector input port @var{in} and write the
Quoted-Printable encoded string to output port @var{out}.
@end deftypefn
@deftypefn {Scheme Procedure} {} quoted-printable-decode (string @var{str})
@deftypefnx {Scheme Procedure} {} quoted-printable-decode (port @var{in})
@deftypefnx {Scheme Procedure} {} quoted-printable-decode (port @var{in}) (port @var{out})
Decode Quoted-Printable encoded string @var{str} and return the decoded
bytevector.
Read Quoted-Printable encoded characters from input port @var{in} and
return the decoded bytevector.
Read Quoted-Printable encoded characters from port @var{in} and write
the decoded bytevector to bytevector output port @var{out}.
@end deftypefn
@section Q-encoding
@example
(use-modules (email quoted-printable))
@end example
@deffn {Scheme Procedure} q-encoding-encode bv
Encode bytevector @var{bv} using Q-encoding and return the encoded
string.
@end deffn
@deffn {Scheme Procedure} q-encoding-decode str
Decode Q-encoding encoded string @var{str} and return the decoded
bytevector.
@end deffn
@node Contributing
@chapter Contributing
Feedback, suggestions, feature requests, bug reports and patches are all
welcome. Please write to the mailing list at
@email{guile-email@@systemreboot.net}.
@node Procedure Index
@chapter Procedure Index
@printindex fn
@node Type Index
@chapter Type Index
@printindex tp
@bye
|
