kelredd-mailer 0.1.2 → 0.1.3

data/README.rdoc

@@ -78,25 +78,20 @@ This is just a little gem to let you configure and send email using TMail over N
     
     # open the mailbox, getting a Net:POP3 object
     mailbox.open do |box|
-    
       # box is a Net::POP3 obj
       box.each_mail do |mail|
         puts mail.header
       end
-      
     end
     
     # check any email in mailbox, getting a collection of Net::POPMail objects
     mailbox.check do |email|
-    
       # email is a collection of Net::POPMail objects
       puts email.length
-      
     end
     
     # download said email to files
     mailbox.check do |email|
-    
       # nothing special here, just using Net::POP3 patterns for handling mail
       pop.mails.each_with_index do |mail, index|
         File.open( "inbox/#{index}", 'w+' ) do |file|
@@ -104,12 +99,71 @@ This is just a little gem to let you configure and send email using TMail over N
         end
         mail.delete
       end
-      
     end
 
     # empty the mailbox
     mailbox.empty!
     
+=== File cacheing your mail
+
+Mailer provides a file cache object to abstract caching your mail to the file system.  You configure it much like you would a mailbox and call 'get_new_mail!' to download and cache new mail to the file system.  The file cache will attempt to delete any mail it downloads from the server.
+
+    # build and configure your file cache
+    test_at_example = Mailer::FileCache.new(~/.mailer/test_at_example, {
+      :server => "pop.server",      # set to whatever needed
+      :port => 995,                 # set to whatever needed
+      :email => "test@example.com", # the inbox to check
+      :password => "secret"         # the email account pop password
+    })
+    
+    
+    # download new mail
+    test_at_example.get_new_mail!
+    
+    
+    # do stuff with the files in the cache via opened File objects
+    # => the cache mixes in Enumerable, returning open File streams
+    test_at_example.each do |file|
+      # some code to read or do stuff with the opened File object
+    end
+    
+    headers = test_at_example.collect do |file|
+      # some code to parse out and return the header info to a string
+    end
+    
+    # or even better, build TMail::Mail objects from the mail files
+    tmails = test_at_example.collect do |file|
+      TMail::Mail.parse(file.read)
+    end
+    
+    
+    # if you prefer, just get the collection of file paths, to use as you see fit
+    # => 'entries' is just an array of paths to the files in the cache
+    entry_file_paths = test_at_example.entries
+    tmails = test_at_example.entries.collect do |path|
+      TMail::Mail.load(path)
+    end
+    
+    
+    # work through the cache one at a time using the cache keys
+    test_at_example.keys.each do |key|
+      test_at_example.read(key) do |file|
+        # do something with the open file stream
+      end
+      test_at_example.delete(key)
+    end
+    
+    
+    # test if the cache has any entries
+    test_at_example.empty?    # => false
+    
+    # delete entries one at a time
+    test_at_example.delete(path_or_key)
+    
+    # clear out the entire cache in one fell swoop
+    test_at_example.clear!
+    test_at_example.empty?    # => true
+    
 == Testing
 
 Mailer has some helpers and Shoulda macros to ease testing that emails were delivered with the correct parameters, fields, and content.

data/Rakefile

@@ -19,9 +19,7 @@ spec = Gem::Specification.new do |s|
   
   s.add_dependency('log4r')
   s.add_dependency('tmail', '>= 1.2.3.0')
-
-  # to run the test suite, you will need this as well
-  #s.add_dependency('kelredd-useful', '>= 0.2.0')  # gem install kelredd-useful --source http://gemcutter.org
+  s.add_dependency('kelredd-useful', '~> 0.2.0')
 end
 
 Rake::GemPackageTask.new(spec) do |pkg|

data/lib/mailer.rb

@@ -6,8 +6,12 @@ require 'log4r'
 require 'mailer/exceptions'
 require 'mailer/config'
 require 'mailer/deliveries'
-require 'mailer/tls'
+
 require 'mailer/mailbox'
+require 'mailer/file_cache'
+
+# move SMTP code into abstracted SMTP class that is proxied by the Mailer module
+require 'mailer/ssl/tls'
 
 module Mailer
   

data/lib/mailer/file_cache.rb

@@ -0,0 +1,137 @@
+require 'useful/ruby_extensions/object'
+require 'mailer/exceptions'
+require 'mailer/mailbox'
+
+module Mailer
+  
+  class FileCache
+    
+    include ::Enumerable
+    
+    attr_reader :home, :name, :mailbox
+    
+    def initialize(home, mailbox_configs={})
+      @home = returning File.expand_path(home) do |path|
+        FileUtils.mkdir_p(path)
+        @name = File.basename(path)
+        @mailbox = Mailer::Mailbox.new(mailbox_configs)
+      end
+    end
+    
+    def get_new_mail!
+      returning([]) do |file_paths|
+        @mailbox.check do |email|
+          email.each do |mail|
+            file_paths << self.write(mail)
+            mail.delete
+          end
+        end
+      end
+    end
+    
+    def read(key)
+      returning self.key_path(key) do |path|
+        if File.exists?(path)
+          File.open(path, 'r') do |file|
+            yield(file) if block_given?
+          end
+        else
+          raise ArgumentError, "the file '#{path}' does not exists"
+        end
+      end
+    end
+     
+    # => write(mail_obj)
+    # => write(custom_key, mail_obj)
+    def write(*args)
+      key, mail = get_key_and_mail(args)
+      returning self.key_path(key) do |path|
+        File.open(path, 'w+') do |file|
+          file.write mail.pop
+        end
+        @entries = nil
+      end
+    end
+    alias_method '<<', 'write'
+    
+    def delete(key)
+      returning self.key_path(key) do |path|
+        FileUtils.rm_rf(path)
+        @entries = nil
+      end
+    end
+    
+    # empties the cache of all entries
+    def clear!
+      returning true do
+        self.keys.each do |key|
+          self.delete(key)
+        end
+        @entries = nil
+      end
+    end
+    
+    def entries
+      @entries ||= Dir[cache_entries_path]
+    end
+    
+    def keys
+      self.entries.collect{|file| File.basename(file)}
+    end
+    
+    def length
+      self.entries.length
+    end
+    alias_method 'size', 'length'
+    
+    def empty?
+      self.entries.empty?
+    end
+    
+    def each
+      self.keys.each do |key|
+        self.read(key) do |file|
+          yield(file) if block_given?
+        end
+      end
+    end
+    
+    protected
+    
+    def key_path(key)
+      File.join([@home, key.to_s])
+    end
+    
+    private
+
+    def cache_entries_path
+      File.join(@home, '*')
+    end
+    
+    def get_key_and_mail(args)
+      returning [] do |key_and_mail|
+        case args.length
+        when 1
+          mail = args.first
+        when 2
+          key = args.first
+          mail = args.last
+        else
+          raise ArgumentError, "invalid write arguements '#{args.inspect}'"
+        end
+        unless mail.kind_of?(::Net::POPMail)
+          raise ArgumentError, "trying to write '#{mail.class.to_s}' object to the cache.  You can only write 'Net::POPMail' objects"
+        end
+        if key.blank?
+          unless mail.respond_to?(:unique_id) && !mail.unique_id.blank?
+            raise ArgumentError, "this mail has an invalid unique_id"
+          end
+          key = mail.unique_id
+        end
+        key_and_mail << key
+        key_and_mail << mail
+      end
+    end
+   
+  end
+end

data/lib/mailer/mailbox.rb

@@ -1,5 +1,5 @@
 require 'mailer/exceptions'
-require 'mailer/pop_ssl'
+require 'mailer/ssl/pop'
 
 module Mailer
   

data/lib/mailer/shoulda_macros/test_unit.rb

@@ -79,7 +79,7 @@ module Mailer::ShouldaMacros::TestUnit
     
   def should_not_pass_the_config_check
     should "not pass the config check: #{subject.inspect}" do
-      assert_raises(Mailer::ConfigError) do
+      assert_raise(Mailer::ConfigError) do
         Mailer.config.check
       end
     end

data/lib/mailer/version.rb

@@ -3,7 +3,7 @@ module Mailer
     
     MAJOR = 0
     MINOR = 1
-    TINY  = 2
+    TINY  = 3
     
     def self.to_s # :nodoc:
       [MAJOR, MINOR, TINY].join('.')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: kelredd-mailer
 version: !ruby/object:Gem::Version 
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors: 
 - Kelly Redding
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-17 00:00:00 -08:00
+date: 2009-11-18 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -32,6 +32,16 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 1.2.3.0
     version: 
+- !ruby/object:Gem::Dependency 
+  name: kelredd-useful
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.2.0
+    version: 
 description: 
 email: kelly@kelredd.com
 executables: []
@@ -46,11 +56,12 @@ files:
 - lib/mailer/config.rb
 - lib/mailer/deliveries.rb
 - lib/mailer/exceptions.rb
+- lib/mailer/file_cache.rb
 - lib/mailer/mailbox.rb
-- lib/mailer/pop_ssl.rb
 - lib/mailer/shoulda_macros/test_unit.rb
+- lib/mailer/ssl/pop.rb
+- lib/mailer/ssl/tls.rb
 - lib/mailer/test_helpers.rb
-- lib/mailer/tls.rb
 - lib/mailer/version.rb
 - lib/mailer.rb
 has_rdoc: true