From e4d5d6de8aa37963427349d8b471545081b9c56d Mon Sep 17 00:00:00 2001 From: djcb Date: Thu, 5 Jan 2012 00:08:50 +0200 Subject: [PATCH] * mu-guile.texi: start of mu-guile documentation (WIP) --- guile/mu-guile.texi | 225 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 213 insertions(+), 12 deletions(-) diff --git a/guile/mu-guile.texi b/guile/mu-guile.texi index cf5fdad4..b25df590 100644 --- a/guile/mu-guile.texi +++ b/guile/mu-guile.texi @@ -33,8 +33,10 @@ programming language. @menu * Introduction:: -* Installation:: -* First steps:: +* Getting started:: +* Initialization:: +* Messages:: +* Contacts:: Appendices @@ -56,19 +58,19 @@ extension language. @t{mu-guile} connects @t{mu} and @t{guile}, and allows you to easily write programs to do things with your e-mails. -@c @menu -@c * Why another e-mail client?:: -@c * What mu4e does and doesn't do:: -@c @end menu +@node Getting started +@chapter Getting started -@c @node Why another e-mail client? -@c @section Why another e-mail client? +@menu +* Installation:: +* First steps:: +@end menu -@c @node What mu4e does and doesn't do -@c @section What mu4e does and doesn't do +This chapter walks you through the installation and some basic steps to ensure +things work correctly. @node Installation -@chapter Installation +@section Installation @t{mu-guile} is part of @t{mu} - by installing the latter, the former will be installed as well. Note, however, that @t{mu-guile} requires you to have @@ -123,7 +125,7 @@ following to your @file{~/.guile}: After this, you should be ready to go. @node First steps -@chapter First steps +@section First steps Assuming @t{mu-guile} has been installed correctly (@ref{Installation}), and also assuming that you have already indexed your e-mail messages (if @@ -167,6 +169,205 @@ scheme@(guile-user)> (for-each (mu:message-list "hello")) @end verbatim +@node Initialization +@chapter Initialization + +It is of course possible to write separate programs with @t{mu-guile}, but for +now we'll do things @emph{interactively}, i.e., from the Guile-prompt +(``@abbr{REPL}''). + +We start our @t{mu-guile} session by starting @t{guile}: + +@verbatim +$ guile +GNU Guile 2.0.3.82-a2c66 +Copyright (C) 1995-2011 Free Software Foundation, Inc. + +Guile comes with ABSOLUTELY NO WARRANTY; for details type `,show w'. +This program is free software, and you are welcome to redistribute it +under certain conditions; type `,show c' for details. + +Enter `,help' for help. +scheme@(guile-user)> +@end verbatim + +Now, the first thing we need to do is load the @t{mu-guile} modules; +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 +@end itemize + +Let's simply load all of them: + +@verbatim +scheme@(guile-user)> (use-modules (mu) (mu message) (mu contact)) +@end verbatim + +Assuming you have installed everything correctly, the first time you do this, +@t{guile} will probably respond by showing some message about compiling the +modules, and then end with another prompt. + +Before we can do anything with @t{mu guile}, we need to initialize the +system. The reason as to not do this automatically is to enable people to use +non-default places to keep there @t{mu} data files. + +We can initialize the system with: + +@verbatim +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/") +@end verbatim + +If all worked up until here, we're ready to go with @t{mu-guile}. + +@node Messages +@chapter Messages + +In this chapter, we discuss how to find messages, and then how to do various +things with them. + +@menu +* Finding messages:: +* Message functions:: +@end menu + +@node Finding messages +@section Finding messages +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 [])} +@item @code{(mu:for-each-message [])} +@end itemize + +The first function, @code{mu:message-list} returns a list of all messages +matching @t{}; if you leave @t{} out, it +returns @emph{all} messages. + +For example, to get all messages with @emph{coffee} in the subject line, you +could do: + +@verbatim +scheme@(guile-user)> (mu:message-list "subject:coffee") +$1 = (#< 9040640> #< 9040630> + #< 9040570>) +@end verbatim + +So, we get a list with three @t{} objects. We'll discuss them in a +bit more detail in the next section, but let's just use the @code{subject} +function ('method') provided by @t{} objects to retrieve the +subject-field. + +For your convenience, @t{guile} has saved the result in @t{$1}, so to get the +subject of the first message in the list, we can do: + +@verbatim +scheme@(guile-user)> (subject (car $1)) +$2 = "Re: best coffee ever!" +@end verbatim + +The second function we mentioned, @code{mu:for-each-message}, executes some +function for each message matched by the search expression (or @emph{all} +message if the search expression is omitted). + +@verbatim +scheme@(guile-user)> (mu:for-each-message + (lambda(msg) + (display (subject msg)) + (newline)) + "subject:coffee") +Re: best coffee ever! +best coffee ever! +scheme@(guile-user)> +@end verbatim + +Using @code{mu:message-list} and/or +@code{mu:for-each-message}@footnote{Implementation node: +@code{mu:message-list} is implemented in terms of @code{mu:for-each-message}, +not the other way around. Due to the way @t{mu} works, +@code{mu:for-each-message} is rather more efficient than a combination for +@code{for-each} and @code{mu:message-list}} and a couple of @t{} +methods, together with that Guile/Scheme provides should allow for many +interesting programs. + +@node Message functions +@section Message functions + +Now that we've seen how to retrieve lists of message objects +(@code{}), let's see what we can do with such an object. + +@code{} defines the following methods +@footnote{A note on naming: functions we have seen before -- +@code{mu:initialize}, @code{mu:message-list} and @code{mu:for-each-message} +are prefixed with @t{mu:}. This is not the case for the @code{} +methods to be discussed next, such as the methods @code{subject} and +@code{from}. Reason for this is that it is not @emph{needed}, since these +methods only recognized for @code{} objects, and do not affect +anything else, while the @code{mu:}-prefixed are 'globally visible' and thus +we need to be careful about naming conflicts} + that all only take a single +@code{} object as a parameter. We won't go into the exact meanings +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{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{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{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{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. +@end itemize + +With these functions, we can query messages for their properties; for example: + +@verbatim +scheme@(guile-user)> (define msg (car (mu:message-list "snow"))) +scheme@(guile-user)> (subject msg) +$1 = "Re: Running in the snow is beautiful" +scheme@(guile-user)> (flags msg) +$2 = (mu:replied mu:seen) +scheme@(guile-user)> (strftime "%F" (localtime (date msg))) +$3 = "2011-01-15" +@end verbatim + +There are a couple more functions: +@itemize +@item @code{(header "")} returns an arbitrary message +header (or @t{#f} if not found) -- e.g. @code{(header msg "User-Agent")} +@item @code{(contacts contact-type)} which returns a list +of contacts (names/e-mail addresses in the To/From/Cc/Bcc-fields). +@xref{Contacts}. + +@end itemize + + +@node Contacts +@chapter Contacts + + @node GNU Free Documentation License @appendix GNU Free Documentation License