source.rb in sup-0.0.7

- old
+ new

@@ -8,40 +8,48 @@
   ##  1. See how many messages it contains
   ##  2. Get an arbirtrary message
   ##  3. (optional) see whether the source has marked it read or not
   ##
   ## In particular, Sup doesn't need to move messages, mark them as
-  ## read, delete them, or anything else. (Well, maybe delete at some
-  ## point.)
+  ## 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 should implement:
+  ## To write a new source, subclass this class, and implement:
   ##
   ## - start_offset
-  ## - end_offset
+  ## - end_offset (exclusive!)
   ## - load_header offset
   ## - load_message offset
   ## - raw_header offset
-  ## - raw_full_message offset-
+  ## - raw_full_message offset
   ## - next (or each, if you prefer)
   ##
+  ## ... where "offset" really means unique id. (You can tell I
+  ## started with mbox.)
+  ##
   ## 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
 
+
+
   ## 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.
@@ -76,10 +84,10 @@
       (self.cur_offset ||= start_offset) >= end_offset
     rescue SourceError => e
       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?
     begin
       self.cur_offset ||= start_offset