email: Add accessors for common header fields.

* email/email.scm (sanitize-field): New function.
(email-from, email-to, email-cc, email-bcc, email-subject, email-date,
email-message-id, email-content-type): New public functions.
* doc/guile-email.texi (Data Types): Document them.

2 files changed, 71 insertions, 1 deletions

diff --git a/doc/guile-email.texi b/doc/guile-email.texi
index 72d8ee3..b359af4 100644
--- a/doc/guile-email.texi
+++ b/doc/guile-email.texi
@@ -3,7 +3,7 @@
 @settitle guile-email
 
 @copying
-Copyright @copyright{} 2019, 2021 Arun Isaac@*
+Copyright @copyright{} 2019, 2021, 2025 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
@@ -114,6 +114,18 @@ This is the data type representing emails.
 Predicate and field accessors for the @code{<email>} data type.
 @end deffn
 
+@deffn {Scheme Procedure} email-from email
+@deffnx {Scheme Procedure} email-to email
+@deffnx {Scheme Procedure} email-cc email
+@deffnx {Scheme Procedure} email-bcc email
+@deffnx {Scheme Procedure} email-subject email
+@deffnx {Scheme Procedure} email-date email
+@deffnx {Scheme Procedure} email-message-id email
+@deffnx {Scheme Procedure} email-content-type email
+Accessors for specific headers in @var{email}. Prefer these to
+@code{email-headers} when possible.
+@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
diff --git a/email/email.scm b/email/email.scm
index 22d9739..5e1ef9d 100644
--- a/email/email.scm
+++ b/email/email.scm
@@ -43,6 +43,14 @@
             email?
             email-headers
             email-body
+            email-from
+            email-to
+            email-cc
+            email-bcc
+            email-subject
+            email-date
+            email-message-id
+            email-content-type
             <mime-entity>
             make-mime-entity
             mime-entity?
@@ -71,6 +79,56 @@
   (headers mime-entity-headers)
   (body mime-entity-body))
 
+(define (sanitize-field email field)
+  "Sanitize @var{field} value in @var{email} and return a new sanitized
+value."
+  (let ((field-value (assq-ref (email-headers email)
+                               field)))
+    (if (string? field-value)
+        ;; Invalid fields show up as strings in the parse tree.
+        ;; Discard them and return an empty list.
+        (list)
+        field-value)))
+
+(define (email-from email)
+  "Return list of From addresses in @var{email}."
+  (or (sanitize-field email 'from)
+      (list)))
+
+(define (email-to email)
+  "Return list of To addresses in @var{email}."
+  (or (sanitize-field email 'to)
+      (list)))
+
+(define (email-cc email)
+  "Return list of Cc addresses in @var{email}."
+  (or (sanitize-field email 'cc)
+      (list)))
+
+(define (email-bcc email)
+  "Return list of Bcc addresses in @var{email}."
+  (or (sanitize-field email 'bcc)
+      (list)))
+
+(define (email-subject email)
+  "Return Subject of @var{email}."
+  (assq-ref (email-headers email)
+            'subject))
+
+(define (email-date email)
+  "Return Date of @var{email}."
+  (sanitize-field email 'date))
+
+(define (email-message-id email)
+  "Return Message-ID of @var{email}."
+  (assq-ref (email-headers email)
+            'message-id))
+
+(define (email-content-type email)
+  "Return Content-Type of @var{email}."
+  (assq-ref (email-headers email)
+            'content-type))
+
 (define string->lcase-symbol
   (compose string->symbol string-downcase))