diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guile-email.texi | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/doc/guile-email.texi b/doc/guile-email.texi index 9fed64e..900d070 100644 --- a/doc/guile-email.texi +++ b/doc/guile-email.texi @@ -21,6 +21,8 @@ Documentation License''. @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 @@ -66,6 +68,81 @@ 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. + +@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 + +@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 + +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 + +@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 @end deffn @node Contributing |