* guile: update documentation, message module

guile/mu-guile.texi

@@ -196,14 +196,14 @@ currently, there are three available:
 
 @itemize
 @item @code{mu} - initialization, functions to get messages, contacts
-@item @code{mu message} - functions to deal with a single message
-@item @code{mu contact} - functions to deal with a single contact
+@item @code{mu message} - functions to deal with messages
+@item @code{mu contact} - functions to deal with contacts
 @end itemize
 
 Let's simply load all of them:
 
 @verbatim
-scheme@(guile-user)> (use-modules (mu) (mu message) (mu contact)) 
+scheme@(guile-user)> (use-modules (mu) (mu message) (mu contact))
 @end verbatim
 
 Assuming you have installed everything correctly, the first time you do this,
@@ -217,16 +217,19 @@ non-default places to keep there @t{mu} data files.
 We can initialize the system with:
 
 @verbatim
-scheme@(guile-user)> (mu:initialize)    
+scheme@(guile-user)> (mu:initialize)
 @end verbatim
 
 Which will use the default location of @file{~/.mu}. Or, instead, if you keep
 your @t{mu} data in a non-standard place:
 
 @verbatim
-scheme@(guile-user)> (mu:initialize "/path/to/my/mu/") 
+scheme@(guile-user)> (mu:initialize #t "/path/to/my/mu/")
 @end verbatim
 
+Note, the second parameter, @t{#t} is for future use; simply set it to @t{#t}
+for now.
+
 If all worked up until here, we're ready to go with @t{mu-guile}.
 
 @node Messages
@@ -246,8 +249,8 @@ Now we are ready to retrieve some messages from the system. There are two
 principle functions to do this:
 
 @itemize
-@item @code{(mu:message-list [<search-expression>])}  
-@item @code{(mu:for-each-message <function> [<search-expression>])}  
+@item @code{(mu:message-list [<search-expression>])}
+@item @code{(mu:for-each-message <function> [<search-expression>])}
 @end itemize
 
 The first function, @code{mu:message-list} returns a list of all messages
@@ -321,24 +324,24 @@ for all of these functions here - for the details about various flags /
 properties, please refer to the @t{mu-find} man-page.
 
 @itemize
-@item @code{bcc}: the @t{Bcc} field of the message, or @t{#f} if there is none      
+@item @code{bcc}: the @t{Bcc} field of the message, or @t{#f} if there is none
 @item @code{body-html}: : the html body of the message, or @t{#f} if there is none
-@item @code{body-txt}: the plain-text body of the message, or @t{#f} if there is none 
-@item @code{cc}: the @t{Bcc} field of the message, or @t{#f} if there is none         
-@item @code{date}: the @t{Date} field of the message, or 0 if there is none       
-@item @code{flags}: list of message-flags for this message      
+@item @code{body-txt}: the plain-text body of the message, or @t{#f} if there is none
+@item @code{cc}: the @t{Bcc} field of the message, or @t{#f} if there is none
+@item @code{date}: the @t{Date} field of the message, or 0 if there is none
+@item @code{flags}: list of message-flags for this message
 @item @code{from}: the @t{From} field of the message, or @t{#f} if there is none
-@item @code{maildir}: the maildir this message lives in, or @t{#f} if there is none    
+@item @code{maildir}: the maildir this message lives in, or @t{#f} if there is none
 @item @code{message-id}: the @t{Message-Id} field of the message, or @t{#f} if there is none
-@item @code{path}: the file system path for this message      
+@item @code{path}: the file system path for this message
 @item @code{priority}: the priority of this message (either @t{mu:low}, @t{mu:normal}
 or @t{mu:high}
 @item @code{references}: the list of messages (message-ids) this message
 refers to in the @t{References:} header
-@item @code{size}: size of the message in bytes        
-@item @code{subject}: the @t{Subject} field of the message, or @t{#f} if there is none.   
-@item @code{tags}: list of tags for this message          
-@item @code{to}: the sender of the message, or @t{#f} if there is none.         
+@item @code{size}: size of the message in bytes
+@item @code{subject}: the @t{Subject} field of the message, or @t{#f} if there is none.
+@item @code{tags}: list of tags for this message
+@item @code{to}: the sender of the message, or @t{#f} if there is none.
 @end itemize
 
 With these functions, we can query messages for their properties; for example:
@@ -357,12 +360,31 @@ There are a couple more functions:
 @itemize
 @item @code{(header <mu-message> "<header-name>")} returns an arbitrary message
 header (or @t{#f} if not found) -- e.g. @code{(header msg "User-Agent")}
-@item @code{(contacts <mu-message> contact-type)} which returns a list  
+@item @code{(contacts <mu-message> contact-type)} which returns a list
 of contacts (names/e-mail addresses in the To/From/Cc/Bcc-fields).
 @xref{Contacts}.
-
 @end itemize
 
+Now, let's write a little example -- let's find out what is the @emph{longest
+subject} of any of your e-mail messages; you can put in a separate file, make
+it executable, and run it like any program.
+
+@verbatim
+#!/bin/sh
+exec guile -e main -s $0 $@
+!#
+(use-modules (mu) (mu message))
+
+(let* ((longest-subj ""))
+  (mu:initialize)
+  (mu:for-each-message
+    (lambda(msg)
+      (let ((subj (subject msg)))
+	(if (and subj (> (string-length subj) (string-length longest-subj)))
+	  (set! longest-subj subj))))
+    query)
+  (format #t "Longest subject: ~a" longest-subj))
+@end verbatim
 
 @node Contacts
 @chapter Contacts
@@ -372,6 +394,4 @@ of contacts (names/e-mail addresses in the To/From/Cc/Bcc-fields).
 @appendix GNU Free Documentation License
 
 @include fdl.texi
-
-
 @bye

guile/mu/message.scm

@@ -22,6 +22,7 @@
 	    <mu-message>
 	    mu:for-each-message
 	    mu:for-each-contact
+	    mu:message-list
 	    ;; internal
 	    mu:for-each-msg-internal
 	    mu:get-contacts
@@ -102,35 +103,3 @@ EXPR. If EXPR is not provided, return a list of /all/ messages in the store."
       (lambda (m)
 	(set! lst (append! lst (list m)))) expr)
     lst))
-
-(define* (mu:tabulate-messages func #:optional (expr #t))
-  "Execute FUNC for each message matching EXPR, and return an alist
-with maps each result of FUNC to its frequency. FUNC is a function
-takes a <mu-message> instance as its argument. For example, to
-tabulate messages by weekday, one could use:
-   (mu:tabulate-messages (lambda(msg) (tm:wday (localtime (date msg)))))."
-  (let ((table '()))
-    (mu:for-each-message
-      (lambda(msg)
-	(let* ((val (func msg))
-		(old-freq (or (assoc-ref table val) 0)))
-	  (set! table (assoc-set! table val (1+ old-freq)))))
-      expr)
-    table))
-
-
-(define* (mu:average-messages func #:optional (expr #t))
-  "Execute FUNC for each message matching EXPR, and return the average
-value of the results of FUNC.  FUNC is a function that takes a
-<mu-message> instance as its argument, and returns some number. For
-example, to get the average message size of messages related to
-icecream:  (mu:average (lambda(msg) (size msg)) \"icecream\" ."
-(let ((count 0) (sum 0))
-  (mu:for-each-message
-    (lambda (msg)
-      (set! count (+1 count))
-      (set! sum (+ sum (func msg))))
-    expr)
-  (if (= count 0)
-    0
-    (exact->inexact (/ sum count)))))