\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

@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

@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.

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

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