made pct_done optional

[sup] / lib / sup / source.rb

diff --git a/lib/sup/source.rb b/lib/sup/source.rb
index 0e0337ac62b4f2166122e8cd178daf24659fafcb..d3f96e179126a2a1e6f988bee5492e0b1e0dfe63 100644 (file)
--- a/lib/sup/source.rb
+++ b/lib/sup/source.rb
@@ -3,26 +3,56 @@ module Redwood
 class SourceError < StandardError; end
 
 class Source
-  ## dirty? described whether cur_offset has changed, which means the
-  ## source needs to be re-saved to disk.
+  ## Implementing a new source is typically quite easy, because Sup
+  ## only needs to be able to:
+  ##  1. See how many messages it contains
+  ##  2. Get an arbirtrary message
+  ##  3. (optional) see whether the source has marked it read or not
   ##
-  ## broken? means no message can be loaded, e.g. IMAP server is
-  ## down, mbox file is corrupt and needs to be rescanned.
-
-  ## When writing a new source, you should implement:
+  ## In particular, Sup doesn't need to move messages, mark them as
+  ## read, delete them, or anything else. (Well, at some point it will
+  ## need to delete them, but that will be an optional capability.)
+  ##
+  ## 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!)
+  ## - load_header offset
+  ## - load_message offset
+  ## - raw_header offset
+  ## - raw_full_message offset
+  ## - next (or each, if you prefer)
+  ##
+  ## ... where "offset" really means unique id. (You can tell I
+  ## started with mbox.)
   ##
-  ## start_offset
-  ## end_offset
-  ## load_header(offset)
-  ## load_message(offset)
-  ## raw_header(offset)
-  ## raw_full_message(offset)
-  ## next (or each, if you prefer)
+  ## You can throw SourceErrors from any of those, but we don't catch
+  ## anything else, so make sure you catch *all* errors and reraise
+  ## them as SourceErrors, and set broken_msg to something if the
+  ## source needs to be rescanned.
+  ##
+  ## Also, be sure to make the source thread-safe, since it WILL be
+  ## pummeled from multiple threads at once.
+  ##
+  ## Two examples for you to look at, though sadly neither of them is
+  ## as simple as I'd like: mbox/loader.rb and imap.rb
+
 
-  ## you can throw SourceErrors from any of those, but we don't catch
-  ## anything else, so make sure you catch all non-fatal errors and
-  ## reraise them as source errors.
 
+  ## dirty? described whether cur_offset has changed, which means the
+  ## source info needs to be re-saved to sources.yaml.
+  ##
+  ## broken? means no message can be loaded, e.g. IMAP server is
+  ## down, mbox file is corrupt and needs to be rescanned, etc.
   bool_reader :usual, :archived, :dirty
   attr_reader :uri, :cur_offset, :broken_msg
   attr_accessor :id
@@ -38,7 +68,7 @@ class Source
   end
 
   def broken?; !@broken_msg.nil?; end
-  def to_s; @uri; end
+  def to_s; @uri.to_s; end
   def seek_to! o; self.cur_offset = o; end
   def reset!
     return if broken?
@@ -56,7 +86,7 @@ class Source
       true
     end
   end
-  def is_source_for? s; to_s == s; end
+  def is_source_for? uri; URI(self.uri) == URI(uri); end
 
   def each
     return if broken?