diff options
| -rw-r--r-- | doc/guile-email.texi | 262 |
1 files changed, 262 insertions, 0 deletions
diff --git a/doc/guile-email.texi b/doc/guile-email.texi index 16f9f72..d4c3504 100644 --- a/doc/guile-email.texi +++ b/doc/guile-email.texi @@ -94,6 +94,268 @@ 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 Data Types +@chapter Data Types + +guile-email provides data types for representing emails and MIME +entities. + +@section email data type + +@deftp {Data Type} <email> headers body +This is the data type representing emails. +@end deftp + +@deffn {Scheme Procedure} email? object +@deffnx {Scheme Procedure} email-headers email +@deffnx {Scheme Procedure} email-body email +Predicate and field accessors for the @code{<email>} data type. +@end deffn + +@deffn {Scheme Procedure} make-email headers body +Construct an @code{<email>} object. @var{headers} is an association +list of email headers. @var{body} is either a string or a list of +@code{<mime-entity>} objects. +@end deffn + +@section mime-entity data type + +@deftp {Data Type} <mime-entity> headers body +This is the data type representing MIME entities. +@end deftp + +@deffn {Scheme Procedure} mime-entity? object +@deffnx {Scheme Procedure} mime-entity-headers mime-entity +@deffnx {Scheme Procedure} mime-entity-body mime-entity +Predicate and field accessors for the @code{<mime-entity>} data type. +@end deffn + +@deffn {Scheme Procedure} make-mime-entity headers body +Construct a mime-entity object. @var{headers} is an association list of +MIME entity headers. @var{body} is either a string or a list of +@code{<mime-entity>} objects. +@end deffn + +@section email headers + +The following descriptions of email headers are only a summary. Please +see the relevant RFCs for more details. + +@subsection email header types + +@deftp {Email Header Type} AssociationList +An association list of key-value pairs (@pxref{Association Lists,,, +guile}). Keys are the name of the email header, downcased and converted +to symbols. Values are specific to the header and explained below. +@end deftp + +@deftp {Email Header Type} Date +An SRFI-19 date. @xref{SRFI-19 Date,,, guile}. +@end deftp + +@deftp {Email Header Type} Address +An association list of atmost two keys - 'name' and 'address'. The +values corresponding to these keys are explained below. + +@table @code +@item name +Display name of the email address. When the email address +does not specifiy a display name, this key will be absent. +@item address +Actual email address. +@end table +@end deftp + +@deftp {Email Header Type} AddressList +A list of addresses, each of type 'Address'. +@end deftp + +@deftp {Email Header Type} MessageID +A string containing an email message ID with the surrounding angle +brackets (@samp{<} and @samp{>}) removed. Email message IDs uniquely +identify the email. +@end deftp + +@deftp {Email Header Type} MessageIDList +A list of message IDs, each of type @code{MessageID}. +@end deftp + +@subsection email headers + +@deftypevr {Email Header} Date date +The date the email was sent on, as specified in the @dfn{Date} header. +@end deftypevr + +@deftypevr {Email Header} AddressList from +The list of authors of the email, as specified in the @dfn{From} header. +@end deftypevr + +@deftypevr {Email Header} Address sender +The sender of the email, as specified in the @dfn{Sender} header. +@end deftypevr + +@deftypevr {Email Header} AddressList reply-to +The list of addresses the author of the email suggests replies be sent +to, as specified in the @dfn{Reply-To} header. +@end deftypevr + +@deftypevr {Email Header} AddressList to +The list of primary recipients of the email, as specified in the +@dfn{To} header. +@end deftypevr + +@deftypevr {Email Header} AddressList cc +The list of other recipients of the email at whom the content of the +email may not be directed, as specified in the @dfn{Cc} header. +@end deftypevr + +@deftypevr {Email Header} AddressList bcc +THe list of recipients whose address is not to be revealed to other +recipients of the email, as specified in the @dfn{Bcc} header. +@end deftypevr + +@deftypevr {Email Header} MessageID message-id +The message ID of the email, as specified in the @dfn{Message-ID} +header. +@end deftypevr + +@deftypevr {Email Header} MessageIDList in-reply-to +The list of message IDs of emails to which this email is a reply, as +specified in the @dfn{In-Reply-To} header. +@end deftypevr + +@deftypevr {Email Header} MessageIDList references +The list of message IDs specified in the @dfn{References} header. +@end deftypevr + +@deftypevr {Email Header} String subject +A string identifying the topic of the email, as specified in the +@dfn{Subject} header. +@end deftypevr + +@deftypevr {Email Header} String comments +A string containing additional comments on the body of the email, as +specified in the @dfn{Comments} header. +@end deftypevr + +@deftypevr {Email Header} StringList keywords +A list of strings each an important word or phrase, as specified in the +@dfn{Keywords} header. +@end deftypevr + +@deftypevr {Email Header} Date resent-date +The date at which the resent message was dispatched by the resender, as +specified in the @dfn{Resent-Date} header. +@end deftypevr + +@deftypevr {Email Header} AddressList resent-from +The list of addresses specified in the @dfn{Resent-From} header. +@end deftypevr + +@deftypevr {Email Header} Address resent-sender +The address specified in the @dfn{Resent-Sender} header. +@end deftypevr + +@deftypevr {Email Header} AddressList resent-to +The list of addresses specified in the @dfn{Resent-To} header. +@end deftypevr + +@deftypevr {Email Header} AddressList resent-cc +The list of addresses specified in the @dfn{Resent-Cc} header. +@end deftypevr + +@deftypevr {Email Header} AddressList resent-bcc +The list of addresses specified in the @dfn{Resent-Bcc} header. +@end deftypevr + +@deftypevr {Email Header} MessageID resent-message-id +The message ID specified in the @dfn{Resent-Message-ID} header. +@end deftypevr + +@c TODO: Document trace fields + +@deftypevr {Email Header} String mime-version +The MIME version specified in the @dfn{MIME-Version} header. +@end deftypevr + +@deftypevr {Email Header} AssociationList content-type +The MIME type of the body, as specified in the @dfn{Content-Type} +header, as an association list. The following keys always exist in the +association list. Any additional parameters will also be listed as +key-value pairs. Keys are names of the parameters, downcased and +converted to symbols. + +@table @code +@item type +The primary type +@item subtype +The secondary type +@item charset +The charset +@end table +@end deftypevr + +If no Content-Type header is present, a type of @code{text}, a subtype +of @code{plain} and a charset of ``utf-8'' is assumed as the default. +That is, the following: + +@example +((type . text) + (subtype . plain) + (charset . "utf-8")) +@end example + +@deftypevr {Email Header} AssociationList content-disposition +The content disposition type, as specified in the +@dfn{Content-Disposition} header, as an association list. The following +keys always exist in the association list. + +@table @code +@item type +@table @code +@item inline +@item attachment +@end table +@end table + +Other optional keys include + +@table @code +@item filename +@item creation-date +@item modification-date +@item read-date +@item size +@end table + +Any additional parameters will also be listed as key-value pairs. +Keys are names of the parameters, downcased and converted to +symbols. +@end deftypevr + +@deftypevr {Email Header} Symbol content-transfer-encoding +The encoding of the body of the email as specified in the +@dfn{Content-Transfer-Encoding} header. This can be one of the +following symbols. + +@table @code +@item 7bit +The message is 7-bit encoded. This is the default if no +Content-Transfer-Encoding header is present. +@item 8bit +The message is 8-bit encoded. +@item quoted-printable +The message is encoded using Quoted-Printable encoding. +@item base64 +The message is encoded using Base64 encoding. +@end table + +Note that guile-email automatically decodes the email. The user need +not read the @code{content-transfer-encoding} and invoke the appropriate +decoding procedure. The @code{content-transfer-encoding} header is only +provided for the sake of completion. +@end deftypevr + @node Encoding and Decoding @chapter Encoding and Decoding |