summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorArun Isaac2019-06-25 14:05:45 +0530
committerArun Isaac2019-06-25 14:05:45 +0530
commit60f333d4a61f70151cc56f76eba42388f54ebb56 (patch)
tree42847bc00cec71560ed1ffb4595451aabe048715 /doc
parent8268c96427ff7fd218eb20cf739b394fe58dd5f9 (diff)
downloadguile-email-60f333d4a61f70151cc56f76eba42388f54ebb56.tar.gz
guile-email-60f333d4a61f70151cc56f76eba42388f54ebb56.tar.lz
guile-email-60f333d4a61f70151cc56f76eba42388f54ebb56.zip
doc: Document encoding and decoding procedures.
* doc/guile-email.texi (Encoding and Decoding): New chapter.
Diffstat (limited to 'doc')
-rw-r--r--doc/guile-email.texi77
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