scm: return empty lists instead of #f for some methods

Some methods that returned lists would return ~#f~ when there were no
results (e.g., to, from, cc, bcc, references, labels); however, it's
nicer to return an empty list instead, which what we now do. Technically a
breaking change, but justified while we are still 'experimental'.

3 files changed, 61 insertions, 34 deletions

diff --git a/scm/mu-scm-test.scm b/scm/mu-scm-test.scm
index b9af156..3c9b72f 100644
--- a/scm/mu-scm-test.scm
+++ b/scm/mu-scm-test.scm
@@ -40,6 +40,11 @@
     (let ((recip (car (to msg))))
       (test-equal "Bilbo Baggins" (assoc-ref recip 'name))
       (test-equal "bilbo@anotherexample.com" (assoc-ref recip 'email)))
+
+    ;; cc, bc
+    (test-equal '() (cc msg))
+    (test-equal '() (bcc msg))
+
     ;; no date
     (test-assert (not (date msg)))
     ;; flags
@@ -90,7 +95,7 @@
     (test-equal "gcc include search order" (subject msg))
     (test-equal "klub" (header msg "precedence"))
     (test-equal "gcc-help.gcc.gnu.org" (mailing-list msg))
-    (test-equal #f (references msg))
+    (test-equal '() (references msg))
     (test-equal "3BE9E6535E3029448670913581E7A1A20D852173@emss35m06.us.lmco.com" (message-id msg))
     (test-equal "3BE9E6535E3029448670913581E7A1A20D852173@emss35m06.us.lmco.com" (thread-id msg))
 
@@ -98,10 +103,14 @@
     (test-equal "gcc include search order" (assoc-ref alist 'subject))
     (test-equal 'normal (assoc-ref alist 'priority))
     (test-equal '((email . "anon@example.com") (name . "Mickey Mouse"))
-      (car  (assoc-ref alist 'from))))
+      (car  (assoc-ref alist 'from)))
 
-  (test-end "test-message-more"))
+    ;; cc, bc, labels
+    (test-equal '() (cc msg))
+    (test-equal '() (bcc msg))
+    (test-equal '() (labels msg)))
 
+  (test-end "test-message-more"))
 
 (define (test-message-parts)
   (test-begin "test-message-parts")
diff --git a/scm/mu-scm.scm b/scm/mu-scm.scm
index a15ae90..d09e218 100644
--- a/scm/mu-scm.scm
+++ b/scm/mu-scm.scm
@@ -348,16 +348,16 @@ Return #f otherwise."
   (assoc-ref (message->alist message) 'size))
 
 (define-method (references (message <message>))
-  "Get the list of reference of MESSAGE or #f if not available.
+  "Get the list of reference of MESSAGE
  with the oldest first and the direct parent as the last one. Note, any
 reference (message-id) will appear at most once, duplicates and
 fake-message-id (see impls) are filtered out. If there are no references, return
 #f."
-  (assoc-ref (message->alist message) 'references))
+  (or (assoc-ref (message->alist message) 'references) '()))
 
 (define-method (labels (message <message>))
-  "Get the list of labels for MESSAGE or #f if not available."
-  (assoc-ref (message->alist message) 'labels))
+  "Get the list of labels for MESSAGE."
+  (or (assoc-ref (message->alist message) 'labels) '()))
 
 (define-method (thread-id (message <message>))
   "Get the oldest (first) reference for MESSAGE, or message-id if there are none.
@@ -376,14 +376,11 @@ This is method is useful to determine the thread a message is in."
 
 (define-method (flags (message <message>))
   "Get the size of the MESSAGE in bytes or #f if not available."
-  (assoc-ref (message->alist message) 'flags))
+  (or (assoc-ref (message->alist message) 'flags) '()))
 
 (define-method (flag? (message <message>) flag)
   "Does MESSAGE have some FLAG?"
-  (let ((flgs (flags message)))
-    (if flgs
-	(if (member flag flgs) #t #f)
-	#f)))
+  (if (member flag (flags message)) #t #f))
 
 (define-method (draft? (message <message>))
   "Is MESSAGE a draft message?"
@@ -442,22 +439,21 @@ This is method is useful to determine the thread a message is in."
   (flag? message 'calendar))
 
 (define-method (from (message <message>))
-  "Get the sender (the From: field) for MESSAGE or #f if not found."
-  (assoc-ref (message->alist message) 'from))
+  "Get the list  of sender (the From: field) for MESSAGE."
+  (or (assoc-ref (message->alist message) 'from) '()))
 
 (define-method (to (message <message>))
-  "Get the (intended) recipient for MESSAGE (the To: field) or #f if not found."
-  (assoc-ref (message->alist message) 'to))
+  "Get the list of (intended) recipients for MESSAGE (the To: field)."
+  (or (assoc-ref (message->alist message) 'to) '()))
 
 (define-method (cc (message <message>))
-  "Get the (intended) carbon-copy recipient for MESSAGE (the Cc: field) or #f if
-not found."
-  (assoc-ref (message->alist message) 'cc))
+  "Get the list of (intended) carbon-copy recipient for MESSAGE (the Cc: field)."
+  (or (assoc-ref (message->alist message) 'cc) '()))
 
 (define-method (bcc (message <message>))
-  "Get the (intended) blind carbon-copy recipient for MESSAGE (the Bcc: field) or
-#f if not found."
-  (assoc-ref (message->alist message) 'bcc))
+  "Get the list of (intended) blind carbon-copy recipient for MESSAGE (the Bcc:
+field)."
+  (or (assoc-ref (message->alist message) 'bcc) '()))
 
 (define* (body message #:key (html? #f))
   "Get the MESSAGE body or #f if not found
diff --git a/scm/mu-scm.texi b/scm/mu-scm.texi
index bafd32e..a6dcbfd 100644
--- a/scm/mu-scm.texi
+++ b/scm/mu-scm.texi
@@ -455,7 +455,7 @@ Example usage:
 @deffn {Scheme Procedure} mcount
 @end deffn
 
-Returns the number of messages in the store.
+Return the number of messages in the store.
 
 Example usage:
 @lisp
@@ -475,9 +475,35 @@ Example:
      (root-maildir . "/home/user/Maildir") (schema-version . 500))
 @end lisp
 
+More fields may be added.
+
+@deffn {Scheme Procedure} root-maildir
+@end deffn
+
+Get the root maildir directory, that is, the root of under the directory under
+which all messages reside.
+
+This is equivalent to @code{(assoc-ref (store->alist) 'root-maildir)}.
+
+@deffn {Scheme Procedure} personal-addresses
+@end deffn
+
+Get the list of personal-addresses as defined in the @code{mu} database, which
+may be empty.
+
+This is equivalent to @code{(assoc-ref (store->alist) 'personal-addresses)}. Any
+element in this list is either a plain e-mail address, or a PCRE-compatible
+regular expression when the first and last characters are @t{/} (forward-slash);
+see @t{pcre(3)} for further details.
+
+@deffn {Scheme Procedure} labels
+@end deffn
+Get the list of all labels present in the store, which may be empty. Not to be
+confused with @code{labels} procedure for a @code{message} object.
+
 @deffn {Scheme Procedure} labels
 @end deffn
-Get the list of all labels present in the store, or @code{#f} if there are none.
+Get the list of all labels present in the store, which may empty.
 Not to be confused with @code{labels} procedure for a @code{message} object.
 
 @node Message
@@ -682,23 +708,19 @@ Each contact is an alist with at least an @code{email} and optionally a
 
 @deffn {Scheme Procedure} from message
 @end deffn
-Get the list of message senders (usually only one). Returns either a list
-of contacts or @t{#f}.
+Get the list of message senders (usually a single one).
 
 @deffn {Scheme Procedure} to message
 @end deffn
-Get the message's intended @t{To:} recipients. Returns either
-a list of contacts or @t{#f} if not found.
+Get the message's intended @t{To:} recipients list.
 
 @deffn {Scheme Procedure} cc message
 @end deffn
-Get the message's intended carbon-copy @t{Cc:} recipients. Returns either a list
-of contacts or @t{#f} if not found.
+Get the message's intended carbon-copy @t{Cc:} recipients list.
 
 @deffn {Scheme Procedure} bcc message
 @end deffn
-Get the message's intended blind carbon-copy @t{Bcc:} recipients. Returns either
-a list of contacts or @t{#f} if not found.
+Get the message's intended blind carbon-copy @t{Bcc:} recipients list.
 
 @subsection Flags
 
@@ -824,8 +846,8 @@ For example:
 
 @deffn {Scheme Procedure} labels message
 @end deffn
-Get the list of labels for this message, or @code{#f} if there are none.
-Not to be confused with the @code{labels} procedure for a Store.
+Get the list of labels for this message. Not to be confused with the
+@code{labels} procedure for a store.
 
 For example:
 @lisp