summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorArun Isaac2019-07-26 01:53:22 +0530
committerArun Isaac2019-07-28 12:13:43 +0530
commitac83c2a00c13702bc365cd0f3074239fa63d743f (patch)
treed5055a15da9dba36033bb207a541ee890098f8fe /doc
parent36474696eaa6187e7077f73d02daeb0138e03124 (diff)
downloadguile-email-ac83c2a00c13702bc365cd0f3074239fa63d743f.tar.gz
guile-email-ac83c2a00c13702bc365cd0f3074239fa63d743f.tar.lz
guile-email-ac83c2a00c13702bc365cd0f3074239fa63d743f.zip
email: Support email with mixed encoding of characters.
Prior to this, parse-email would accept email in the form of a string. A string is constrained to use the same encoding for all its characters whereas an email can have characters encoded using different encoding schemes. Therefore, it is more correct that parse-email deals with bytevectors instead of strings. * email/utils.scm (read-bytes-till): New function. * email/email.scm (body->mime-entities, email->headers+body, decode-body): Deal with emails as bytevectors instead of strings. (parse-mime-entity): Rename text argument to bv. (parse-email, parse-email-body): Overload to handle input in the form of a string or bytevector. * doc/guile-email.texi (Parsing e-mail): Document overloading of parse-email and parse-email-body. * tests/email.scm ("handle truncated multipart message gracefully"): Deal in bytevectors instead of strings. ("email with 8 bit encoding and non UTF-8 charset", "multipart email with a 8 bit encoding and non UTF-8 charset part"): New tests. * tests/email-with-8bit-encoding-and-non-utf8-charset, tests/multipart-email-with-a-8bit-encoding-and-non-utf8-charset-part: New files. Reported-by: Jack Hill <jackhill@jackhill.us>
Diffstat (limited to 'doc')
-rw-r--r--doc/guile-email.texi34
1 files changed, 27 insertions, 7 deletions
diff --git a/doc/guile-email.texi b/doc/guile-email.texi
index b606021..70a4e28 100644
--- a/doc/guile-email.texi
+++ b/doc/guile-email.texi
@@ -53,22 +53,42 @@ RF2047 and RFC2049.
@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
+@deftypefn {Scheme Procedure} parse-email (bytevector @var{email})
+@deftypefnx {Scheme Procedure} parse-email (string @var{email})
+Parse bytevector @var{email} and return result as an @code{<email>}
+record.
+
+Parse string @var{email} and return result as an @code{<email>}
+record.
+@end deftypefn
@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
+@deftypefn {Scheme Procedure} parse-email-body (string @var{headers}) (bytevector @var{body})
+@deftypefnx {Scheme Procedure} parse-email-body (string @var{headers}) (string @var{body})
+Parse bytevector @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
+
+Parse string @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 deftypefn
+
+Note that while an email can have characters encoded using different
+schemes, a string is constrained to have all characters encoded using
+the same scheme. Therefore, passing a string to @code{parse-email} or
+@code{parse-email-body} will not always produce correct results. Hence,
+this variant of @code{parse-email} and @code{parse-email-body} will be
+deprecated in the future. This variant is only provided in the interest
+of backward compatibility.
@node Encoding and Decoding
@chapter Encoding and Decoding