Added to the repository

1 files changed, 275 insertions, 0 deletions

diff --git a/doc/texinfo/libmu_scm.texi b/doc/texinfo/libmu_scm.texi
new file mode 100644
index 000000000..5512fbf69
--- /dev/null
+++ b/doc/texinfo/libmu_scm.texi
@@ -0,0 +1,275 @@
+@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 Function mu-address-get-personal ADDRESS NUM
+Return personal part of an email address.
+@end deffn
+
+@deffn Function mu-address-get-comments ADDRESS NUM
+@end deffn
+
+@deffn Function mu-address-get-email ADDRESS NUM
+Return email part of an email address.
+@end deffn
+
+@deffn Function mu-address-get-domain ADDRESS NUM
+Return domain part of an email address
+@end deffn
+
+@deffn Function mu-address-get-local ADDRESS NUM
+Return local part of an email address.
+@end deffn
+
+@deffn Function mu-address-get-count ADDRESS
+Return number of parts in email address.
+@end deffn
+
+@node Mailbox Functions
+@section Mailbox Functions
+
+@deffn Function mu-mailbox-open URL MODE
+Opens a mailbox specified by URL.
+@end deffn
+
+@deffn Function mu-mailbox-close MBOX
+Closes mailbox MBOX
+@end deffn
+
+@deffn Function mu-mailbox-get-url MBOX
+Returns the URL of the mailbox.
+@end deffn
+
+@deffn 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 Function mu-mailbox-get-message MBOX MSGNO
+Retrieve from MBOX message # MSGNO.
+@end deffn
+
+@deffn Function mu-mailbox-messages-count MBOX
+Returns number of messages in the mailbox.
+@end deffn
+
+@deffn Function mu-mailbox-expunge MBOX
+Expunges deleted messages from the mailbox.
+@end deffn
+
+@deffn Function mu-mailbox-url MBOX
+Returns the URL of the mailbox
+@end deffn
+
+@deffn Function mu-mailbox-append-message MBOX MESG
+Appends the message to the mailbox
+@end deffn
+
+@node Message Functions
+@section Message Functions
+
+@deffn Function mu-message-copy MESG
+Creates the copy of the given message.
+@end deffn
+
+@deffn 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 Function mu-message-get-size MESG
+Returns the size of the given message.
+@end deffn
+
+@deffn Function mu-message-get-lines MESG
+Returns number of lines in the given message.
+@end deffn
+
+@deffn Function mu-message-get-sender MESG
+Returns the sender email address for the message MESG.
+@end deffn
+
+@deffn Function mu-message-get-header MESG HEADER
+Returns the header value of the HEADER in the MESG.
+@end deffn
+
+@deffn 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 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 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 Function mu-message-get-flag MESG FLAG
+Return value of the attribute FLAG.
+@end deffn
+
+@deffn 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 Function mu-message-get-user-flag MESG FLAG
+Returns value of the user attribute FLAG.
+@end deffn
+
+@deffn 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 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 Function mu-message-get-body MESG
+Returns the message body for the message MESG.
+@end deffn
+
+@deffn 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 Function mu-mime-create FLAGS MESG
+Creates a new MIME object.
+@end deffn
+
+@deffn Function mu-mime-multipart? MIME
+Returns #t if MIME is a multipart object.
+@end deffn
+
+@deffn Function mu-mime-get-num-parts MIME
+Returns number of parts in a MIME object.
+@end deffn
+
+@deffn Function mu-mime-get-part MIME PART
+Returns part number PART from a MIME object.
+@end deffn
+
+@deffn Function mu-mime-add-part MIME MESG
+Adds MESG to the MIME object.
+@end deffn
+
+@deffn Function mu-mime-get-message MIME
+Converts MIME object to a message.
+@end deffn
+
+@node Log Functions
+@section Log Functions
+
+@deffn Function mu-openlog IDENT OPTION FACILITY
+Opens a connection to the system logger for Guile program.
+@end deffn
+
+@deffn Function mu-logger PRIO TEXT
+Generates a log message to be distributed via syslogd.
+@end deffn
+
+@deffn 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}.
+
+
+