Cl-Pop Ver 0.2.0
Introduction
Cl-pop is designed to be an opensource portable common lisp
pop-client based for RFC 1939. It has two interface levels. The first
is a higher level interface useful for common functions needed to
process the email messages. The second is an interface to the standard
pop function calls as defined by RFC 1939.
Version 0.2.0 broke the dependency on cl-smtp and switched to usocket for establishing
the socket connections to the pop server. Note this change also effected the internal pop-connection class structure.
Dependencies
Cl-pop uses the following packages which are available from Clike.net
- USOCKET - used to establish the socket connection for the different lisp environments
- Split-Sequence - used by usocket
- CL-PPCRE - for parsing the return strings from the pop server
Installation
A asdf system definition is provided to install the package
Supported Lisp Compilers
Cl-pop should work in every lisp environment that Usocket supports although it has only been testing in Lispworks, Allegro and SBCL.
- Allegro Common Lisp
- ArmedBear (post feb 11th, 2006 versions)
- Clisp
- CMUCL
- ECL
- Lispworks
- OpenMCL
- SBCL
- Scieneer Common Lisp
If you wish to port cl-pop to another platform, it should be as simple
as defining the functions make-smtp-socket and socket-stream to be
compatible with your chosen platform, (see existing examples in the
CL-SMTP system) as the core to cl-pop is written in ANSI compatible
Common Lisp and the package CL-PPCRE supports many more plateforms.
Documentation
Mailbox Functions
open-pop-connection &key host (port 110) username password ==> Pop Connection Instance
Establishes a
connection to a pop server using the connection parameters. Returns an
instance of the class pop-connection which will be used by the later
functions to communicate with the server.
close-pop-connection pop-connection-instance
Closes the connection with the pop server and closes the lisp socket
with-pop-connection (conn-var &rest args) &body body
Establishes an open connection
to the server, args should be the same as open-pop-connection. On
exiting the connection will be closed
message-count pop-connection-instance ==> integer
Number of messages currently in the pop mailbox.
save-message pop-connection-instance message-num local-pathname
Saves email message with cooresponding message number to the file designated by pathname. The message includes the headers
message-headers pop-connection-instance message-num ==> assoc-list
Returns an assoc list of the
email headers, if duplicate or multiline headers are present, they will
be appended togther to form one associated pair
retrieve-pop-message pop-connection-instance message-num &key (max-size) ==> plist
Returns an assoc list of the
email headers, if duplicate or multiline headers are present, they will
be appended togther to form one associated pair
delete-pop-message pop-connection-instance message-num
Marked given message number for deletion. Deletion does not happen until the connection is closed.
Standard Pop Functions
The following are the basic pop
functions as described by the RFC. The functions take the form
send-pop-<rfc function name>. Typically one will use the above
functions instead, but these would be helpful if one wishes to write
their own higher level routines.
send-pop-stat pop-connecion-instance => list of integers
Returns a list of
integers. The first integer is the number of messages in the mailbox,
the second is the combined size of the messages.
send-pop-list pop-connection-instance &optional message-num => List of lists
Returns a list of list of
integers where each list contains the message number and the size of
that message.It the message number is provided only the information on
the message is returned otherwise all messages are returned.
send-pop-dele pop-connection-instance message-num => boolean
Marks the message with the provided message number for deletion. Deletion does not occur until the QUIT command is issued.
send-pop-rset pop-connection-instance => boolean
Unmarks all previous message that were marked for deletion
send-pop-uidl pop-connection-instance &optional message-num => list of lists
Returns a list of lists giving
the message number and the pop servers unique id for that message. If a
message number is provided only the listing for that message is
returned.
send-pop-noop pop-connection-instance => boolean
No operation command. Useful for testing in the connection is still alive.
send-pop-top pop-connection-instance message-num line-count => List of strings
Returns the message header and the first X number of lines of the message for the given message number.
send-pop-retr pop-connection-instance message-num => list of strings
Returns a list of strings, where each string represents one line in the message.
send-pop-quit pop-connection-instance => boolean
Issues the pop quit command, which
closes the connection to the pop server. At this point all messages
marked for deletion will be deleted.
Future Enhancement Items / Limitations
- A full conditional system for signally non-terminal errors, currently these are simply written to standard-output
- A reconnect feature to re-establish contact if the socket was unexpectedly closed.
- Message parsing routines to surgically read different sections of a multi-part message.
Contributors
Brian Sorg, brian.sorg@liberatinginsight.com
Bug Reports
Report problems to Brian Sorg, brian.sorg@liberatinginsight.com