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
  1. USOCKET - used to establish the socket connection for the different lisp environments 
    1. Split-Sequence - used by usocket
  2. 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.
  1. Allegro Common Lisp
  2. ArmedBear (post feb 11th, 2006 versions)
  3. Clisp
  4. CMUCL
  5. ECL
  6. Lispworks
  7. OpenMCL
  8. SBCL
  9. 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
  1. A full conditional system for signally non-terminal errors, currently these are simply written to standard-output
  2. A reconnect feature to re-establish contact if the socket was unexpectedly closed. 
  3. 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