source.rb in sup-0.1

- old
+ new

@@ -3,19 +3,19 @@
 class SourceError < StandardError; end
 class OutOfSyncSourceError < SourceError; end
 class FatalSourceError < SourceError; end
 
 class Source
-  ## Implementing a new source is typically quite easy, because Sup
-  ## only needs to be able to:
+  ## Implementing a new source should be easy, because Sup only needs
+  ## to be able to:
   ##  1. See how many messages it contains
-  ##  2. Get an arbirtrary message
+  ##  2. Get an arbitrary 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, at some point it will
-  ## need to delete them, but that will be an optional capability.)
+  ## 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
@@ -31,11 +31,12 @@
   ## - load_header offset
   ## - load_message offset
   ## - raw_header offset
   ## - raw_full_message offset
   ## - check
-  ## - next (or each, if you prefer)
+  ## - 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
@@ -44,11 +45,11 @@
   ## 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
-  ## pummeled from multiple threads at once.
+  ## pummelled from multiple threads at once.
   ##
   ## Examples for you to look at: mbox/loader.rb, imap.rb, and
   ## maildir.rb.
 
   ## let's begin!
@@ -58,18 +59,22 @@
   bool_reader :usual, :archived, :dirty
   attr_reader :uri, :cur_offset
   attr_accessor :id
 
   def initialize uri, initial_offset=nil, usual=true, archived=false, id=nil
+    raise ArgumentError, "id must be an integer: #{id.inspect}" unless id.is_a? Fixnum if id
+
     @uri = uri
     @cur_offset = initial_offset
     @usual = usual
     @archived = archived
     @id = id
     @dirty = false
   end
 
+  def file_path; nil end
+
   def to_s; @uri.to_s; end
   def seek_to! o; self.cur_offset = o; end
   def reset!; seek_to! start_offset; end
   def == o; o.uri == uri; end
   def done?; (self.cur_offset ||= start_offset) >= end_offset; end
@@ -94,9 +99,7 @@
   def cur_offset= o
     @cur_offset = o
     @dirty = true
   end
 end
-
-Redwood::register_yaml(Source, %w(uri cur_offset usual archived id))
 
 end