3 class SourceError < StandardError; end
6 ## Implementing a new source is typically quite easy, because Sup
7 ## only needs to be able to:
8 ## 1. See how many messages it contains
9 ## 2. Get an arbirtrary message
10 ## 3. (optional) see whether the source has marked it read or not
12 ## In particular, Sup doesn't need to move messages, mark them as
13 ## read, delete them, or anything else. (Well, at some point it will
14 ## need to delete them, but that will be an optional capability.)
16 ## On the other hand, Sup assumes that you can assign each message a
17 ## unique integer id, such that newer messages have higher ids than
18 ## earlier ones, and that those ids stay constant across sessions
19 ## (in the absence of some other client going in and fucking
20 ## everything up). For example, for mboxes I use the file offset of
21 ## the start of the message. If a source does NOT have that
22 ## capability, e.g. IMAP, then you have to do a little more work to
25 ## To write a new source, subclass this class, and implement:
28 ## - end_offset (exclusive!)
29 ## - pct_done (percent of the way cur_offset is to end_offset)
30 ## - load_header offset
31 ## - load_message offset
32 ## - raw_header offset
33 ## - raw_full_message offset
34 ## - next (or each, if you prefer)
36 ## ... where "offset" really means unique id. (You can tell I
37 ## started with mbox.)
39 ## You can throw SourceErrors from any of those, but we don't catch
40 ## anything else, so make sure you catch *all* errors and reraise
41 ## them as SourceErrors, and set broken_msg to something if the
42 ## source needs to be rescanned.
44 ## Also, be sure to make the source thread-safe, since it WILL be
45 ## pummeled from multiple threads at once.
47 ## Two examples for you to look at, though sadly neither of them is
48 ## as simple as I'd like: mbox/loader.rb and imap.rb
52 ## dirty? described whether cur_offset has changed, which means the
53 ## source info needs to be re-saved to sources.yaml.
55 ## broken? means no message can be loaded, e.g. IMAP server is
56 ## down, mbox file is corrupt and needs to be rescanned, etc.
57 bool_reader :usual, :archived, :dirty
58 attr_reader :uri, :cur_offset, :broken_msg
61 def initialize uri, initial_offset=nil, usual=true, archived=false, id=nil
63 @cur_offset = initial_offset
71 def broken?; !@broken_msg.nil?; end
72 def to_s; @uri.to_s; end
73 def seek_to! o; self.cur_offset = o; end
81 def == o; o.to_s == to_s; end
83 return true if broken?
85 (self.cur_offset ||= start_offset) >= end_offset
86 rescue SourceError => e
90 def is_source_for? uri; URI(self.uri) == URI(uri); end
95 self.cur_offset ||= start_offset
96 until done? || broken? # just like life!
98 raise "no message" unless n
101 rescue SourceError => e
102 self.broken_msg = e.message
115 # Redwood::log "#{to_s}: #{m}"
119 Redwood::register_yaml(Source, %w(uri cur_offset usual archived id))