mirror of https://github.com/djcb/mu.git
* mu-guile.texi: start of mu-guile documentation (WIP)
This commit is contained in:
parent
9d60da9a20
commit
e4d5d6de8a
|
@ -33,8 +33,10 @@ programming language.
|
||||||
|
|
||||||
@menu
|
@menu
|
||||||
* Introduction::
|
* Introduction::
|
||||||
* Installation::
|
* Getting started::
|
||||||
* First steps::
|
* Initialization::
|
||||||
|
* Messages::
|
||||||
|
* Contacts::
|
||||||
|
|
||||||
Appendices
|
Appendices
|
||||||
|
|
||||||
|
@ -56,19 +58,19 @@ extension language.
|
||||||
@t{mu-guile} connects @t{mu} and @t{guile}, and allows you to easily write
|
@t{mu-guile} connects @t{mu} and @t{guile}, and allows you to easily write
|
||||||
programs to do things with your e-mails.
|
programs to do things with your e-mails.
|
||||||
|
|
||||||
@c @menu
|
@node Getting started
|
||||||
@c * Why another e-mail client?::
|
@chapter Getting started
|
||||||
@c * What mu4e does and doesn't do::
|
|
||||||
@c @end menu
|
|
||||||
|
|
||||||
@c @node Why another e-mail client?
|
@menu
|
||||||
@c @section Why another e-mail client?
|
* Installation::
|
||||||
|
* First steps::
|
||||||
|
@end menu
|
||||||
|
|
||||||
@c @node What mu4e does and doesn't do
|
This chapter walks you through the installation and some basic steps to ensure
|
||||||
@c @section What mu4e does and doesn't do
|
things work correctly.
|
||||||
|
|
||||||
@node Installation
|
@node Installation
|
||||||
@chapter Installation
|
@section Installation
|
||||||
|
|
||||||
@t{mu-guile} is part of @t{mu} - by installing the latter, the former will be
|
@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
|
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.
|
After this, you should be ready to go.
|
||||||
|
|
||||||
@node First steps
|
@node First steps
|
||||||
@chapter First steps
|
@section First steps
|
||||||
|
|
||||||
Assuming @t{mu-guile} has been installed correctly (@ref{Installation}), and
|
Assuming @t{mu-guile} has been installed correctly (@ref{Installation}), and
|
||||||
also assuming that you have already indexed your e-mail messages (if
|
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"))
|
(mu:message-list "hello"))
|
||||||
@end verbatim
|
@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 [<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
|
||||||
|
matching @t{<search-expression>}; if you leave @t{<search-expression>} 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 = (#<<mu-message> 9040640> #<<mu-message> 9040630>
|
||||||
|
#<<mu-message> 9040570>)
|
||||||
|
@end verbatim
|
||||||
|
|
||||||
|
So, we get a list with three @t{<mu-message>} 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{<mu-message>} 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{<mu-message>}
|
||||||
|
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{<mu-message>}), let's see what we can do with such an object.
|
||||||
|
|
||||||
|
@code{<mu-message>} 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{<mu-message>}
|
||||||
|
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{<mu-message>} 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{<mu-message>} 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 <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
|
||||||
|
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
|
@node GNU Free Documentation License
|
||||||
@appendix GNU Free Documentation License
|
@appendix GNU Free Documentation License
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue