@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************

The library @file{libmu_scm} provides an interface between Mailutils
and Guile, allowing to access the Mailutils functionality from a
Scheme program. For more information about Guile, refer to
@ref{Top,,Overview,guile,The Guile Reference Manual}. For information
about Scheme programming language, @xref{Top,,,r4rs,Revised(4) Report on
the Algorithmic Language Scheme}.

@menu
Functions Provided by libmu_scm

* Address Functions::
* Mailbox Functions::
* Message Functions::
* MIME Functions::
* Log Functions::

Using libmu_scm

* Direct Linking::
* Dynamic Linking::

@end menu


@node Address Functions
@section Address Functions

@deffn {Scheme Function} mu-address-get-personal ADDRESS NUM
Return personal part of an email address.
@end deffn

@deffn {Scheme Function} mu-address-get-comments ADDRESS NUM
@end deffn

@deffn {Scheme Function} mu-address-get-email ADDRESS NUM
Return email part of an email address.
@end deffn

@deffn {Scheme Function} mu-address-get-domain ADDRESS NUM
Return domain part of an email address
@end deffn

@deffn {Scheme Function} mu-address-get-local ADDRESS NUM
Return local part of an email address.
@end deffn

@deffn {Scheme Function} mu-address-get-count ADDRESS
Return number of parts in email address.
@end deffn

@node Mailbox Functions
@section Mailbox Functions

@deffn {Scheme Function} mu-mailbox-open URL MODE
Opens a mailbox specified by URL.
@end deffn

@deffn {Scheme Function} mu-mailbox-close MBOX
Closes mailbox MBOX
@end deffn

@deffn {Scheme Function} mu-mailbox-get-url MBOX
Returns the URL of the mailbox.
@end deffn

@deffn {Scheme Function} mu-mailbox-get-port MBOX MODE
Returns a port associated with the contents of the MBOX.
MODE is a string defining operation mode of the stream. It may
contain any of the two characters: @samp{r} for reading, @samp{w} for
writing.
@end deffn

@deffn {Scheme Function} mu-mailbox-get-message MBOX MSGNO
Retrieve from MBOX message # MSGNO.
@end deffn

@deffn {Scheme Function} mu-mailbox-messages-count MBOX
Returns number of messages in the mailbox.
@end deffn

@deffn {Scheme Function} mu-mailbox-expunge MBOX
Expunges deleted messages from the mailbox.
@end deffn

@deffn {Scheme Function} mu-mailbox-url MBOX
Returns the URL of the mailbox
@end deffn

@deffn {Scheme Function} mu-mailbox-append-message MBOX MESG
Appends the message to the mailbox
@end deffn

@node Message Functions
@section Message Functions

@deffn {Scheme Function} mu-message-copy MESG
Creates the copy of the given message.
@end deffn

@deffn {Scheme Function} mu-message-set-header MESG HEADER VALUE REPLACE
Sets new VALUE to the header HEADER of the message MESG.
If the HEADER is already present in the message its value
is replaced with the supplied one if the optional REPLACE is
#t. Otherwise new header is created and appended.
@end deffn

@deffn {Scheme Function} mu-message-get-size MESG
Returns the size of the given message.
@end deffn

@deffn {Scheme Function} mu-message-get-lines MESG
Returns number of lines in the given message.
@end deffn

@deffn {Scheme Function} mu-message-get-sender MESG
Returns the sender email address for the message MESG.
@end deffn

@deffn {Scheme Function} mu-message-get-header MESG HEADER
Returns the header value of the HEADER in the MESG.
@end deffn

@deffn {Scheme Function} mu-message-get-header-fields MESG HEADERS
Returns the list of headers in the MESG. If optional HEADERS is
specified it should be a list of header names to restrict return
value to.
@end deffn

@deffn {Scheme Function} mu-message-set-header-fields MESG LIST REPLACE
Set the headers in the message MESG from LIST
LIST is a list of (cons HEADER VALUE)
Optional parameter REPLACE specifies whether the new header
values should replace the headers already present in the
message.
@end deffn

@deffn {Scheme Function} mu-message-delete MESG FLAG
Mark given message as deleted. Optional FLAG allows to toggle deleted mark
The message is deleted if it is #t and undeleted if it is #f
@end deffn

@deffn {Scheme Function} mu-message-get-flag MESG FLAG
Return value of the attribute FLAG.
@end deffn

@deffn {Scheme Function} mu-message-set-flag MESG FLAG VALUE
Set the given attribute of the message. If optional VALUE is #f, the
attribute is unset.
@end deffn

@deffn {Scheme Function} mu-message-get-user-flag MESG FLAG
Returns value of the user attribute FLAG.
@end deffn

@deffn {Scheme Function} mu-message-set-user-flag MESG FLAG VALUE
Set the given user attribute of the message. If optional VALUE is
#f, the attribute is unset.
@end deffn

@deffn {Scheme Function} mu-message-get-port MESG MODE FULL
Returns a port associated with the given MESG. MODE is a string
defining operation mode of the stream. It may contain any of the
two characters: @samp{r} for reading, @samp{w} for writing.
If optional FULL argument specified, it should be a boolean value.
If it is #t then the returned port will allow access to any
part of the message (including headers). If it is #f then the port
accesses only the message body (the default).
@end deffn

@deffn {Scheme Function} mu-message-get-body MESG
Returns the message body for the message MESG.
@end deffn

@deffn {Scheme Function} mu-message-send MESG MAILER
Sends the message MESG. Optional MAILER overrides default
mailer settings in mu-mailer.
@end deffn

@node MIME Functions
@section MIME Functions

@deffn {Scheme Function} mu-mime-create FLAGS MESG
Creates a new MIME object.
@end deffn

@deffn {Scheme Function} mu-mime-multipart? MIME
Returns #t if MIME is a multipart object.
@end deffn

@deffn {Scheme Function} mu-mime-get-num-parts MIME
Returns number of parts in a MIME object.
@end deffn

@deffn {Scheme Function} mu-mime-get-part MIME PART
Returns part number PART from a MIME object.
@end deffn

@deffn {Scheme Function} mu-mime-add-part MIME MESG
Adds MESG to the MIME object.
@end deffn

@deffn {Scheme Function} mu-mime-get-message MIME
Converts MIME object to a message.
@end deffn

@node Log Functions
@section Log Functions

@deffn {Scheme Function} mu-openlog IDENT OPTION FACILITY
Opens a connection to the system logger for Guile program.
@end deffn

@deffn {Scheme Function} mu-logger PRIO TEXT
Generates a log message to be distributed via syslogd.
@end deffn

@deffn {Scheme Function} mu-closelog
Closes the channel to the system logger open by mu-openlog.
@end deffn

@node Direct Linking
@section Direct Linking

If you plan to link your program directly to @file{libguile}, it will
probably make sense to link @file{libmu_scm} directly as well. The
arguments to the program loader may be obtained by running

@example
mailutils-config --link guile
@end example
@noindent

@xref{mailutils-config}, for more information about this utility.

Here is a sample Makefile fragment:

@example
MU_LDFLAGS=`mailutils-config --link guile`
MU_INCLUDES=`mailutils-config --include`

myprog: myprog.c
        $(CC) -omyprog $(CFLAGS) $(MU_INCLUDES) myprog.c $(MU_LDFLAGS)
@end example        

@node Dynamic Linking
@section Dynamic Linking

Dynamic linking is the preferred method of using @file{libmu_scm}. It
uses Guile ``use-modules'' mechanism. An interface module
@file{mailutils.scm} is provided in order to facilitate using this
method. This module is installed in the package data directory (by
default it is @var{prefix}/share/mailutils). A sample use of
this module is:

@example
(set! %load-path (list "/usr/local/share/mailutils"))
(use-modules (mailutils))

# Now you may use mailutils functions:

(let ((mb (mu-mailbox-open "/var/spool/mail/gray" "r")))
...
@end example

@emph{Note}, that you should explicitly modify the @code{%load-path}
before calling @code{use-modules}, otherwise Guile will not be able to
find @file{mailutils.scm}.