* guile: update documentation, message module

guile/mu-guile.texi

@@ -196,8 +196,8 @@ 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:
@@ -224,9 +224,12 @@ 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
@@ -360,9 +363,28 @@ 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
 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)))))