- ## broken? means no message can be loaded (e.g. IMAP server is
- ## down), so don't even bother.
- bool_reader :usual, :archived, :dirty, :broken
- attr_reader :cur_offset
- attr_accessor :id
+ ## In particular, Sup doesn't need to move messages, mark them as
+ ## read, delete them, or anything else. (Well, it's nice to be able
+ ## to delete them, but that is optional.)
+ ##
+ ## On the other hand, Sup assumes that you can assign each message a
+ ## unique integer id, such that newer messages have higher ids than
+ ## earlier ones, and that those ids stay constant across sessions
+ ## (in the absence of some other client going in and fucking
+ ## everything up). For example, for mboxes I use the file offset of
+ ## the start of the message. If a source does NOT have that
+ ## capability, e.g. IMAP, then you have to do a little more work to
+ ## simulate it.
+ ##
+ ## To write a new source, subclass this class, and implement:
+ ##
+ ## - start_offset
+ ## - end_offset (exclusive!) (or, #done?)
+ ## - load_header offset
+ ## - load_message offset
+ ## - raw_header offset
+ ## - raw_message offset
+ ## - check (optional)
+ ## - next (or each, if you prefer): should return a message and an
+ ## array of labels.
+ ##
+ ## ... where "offset" really means unique id. (You can tell I
+ ## started with mbox.)
+ ##
+ ## All exceptions relating to accessing the source must be caught
+ ## and rethrown as FatalSourceErrors or OutOfSyncSourceErrors.
+ ## OutOfSyncSourceErrors should be used for problems that a call to
+ ## sup-sync will fix (namely someone's been playing with the source
+ ## from another client); FatalSourceErrors can be used for anything
+ ## else (e.g. the imap server is down or the maildir is missing.)
+ ##
+ ## Finally, be sure the source is thread-safe, since it WILL be
+ ## pummelled from multiple threads at once.
+ ##
+ ## Examples for you to look at: mbox/loader.rb, imap.rb, and
+ ## maildir.rb.