mail 2.0.5 → 2.1.0

data/CHANGELOG.rdoc

@@ -1,3 +1,15 @@
+== Mon Jan 25 10:36:33 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Now passes a block to the delivery handler, which can just call yield if it want's Mail to just do it's normal delivery method
+* Moved Mail.deliveries into Mail::TestMailer.deliveries. Now only gets mail appended to it if you are sending with the :test delivery_method (only for testing)
+* Version bump to 2.1.0
+
+== Mon Jan 25 01:44:13 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Change :deliver! to deliver a mail object, bypassing the :perform_deliveries and :raise_delivery_errors flags, also does not append the mail object to Mail.deliveries, thus the ! (dangerous).  The intended use for :deliver! is for people wanting to have their own delivery_handler (like ActionMailer uses) to track and handle delivery failures.
+* Added :delivery_handler to Message.  Allows you to pass an object that will be sent :deliver_mail(self) by the Mail::Message instance when it is sent :deliver and bypasses the usual delivery method.
+* Changed :perform_deliveries flag to be more consistent with it's name, mail will not append itself to the Mail.deliveries collection if :perform_deliveries is false
+
 == Sat Jan 23 23:49:50 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
 
 * Version bump to 2.0.5

data/Rakefile

@@ -12,7 +12,7 @@ require 'bundler'
 
 spec = Gem::Specification.new do |s|
   s.name        = "mail"
-  s.version     = "2.0.5"
+  s.version     = "2.1.0"
   s.author      = "Mike Lindsaar"
   s.email       = "raasdnil@gmail.com"
   s.homepage    = "http://github.com/mikel/mail"

data/lib/mail/configuration.rb

@@ -13,9 +13,12 @@ module Mail
   # which can be overwritten on a per mail object basis.
   class Configuration
     include Singleton
-    
-    @delivery_method  = nil
-    @retriever_method = nil
+
+    def initialize
+      @delivery_method  = nil
+      @retriever_method = nil
+      super
+    end
 
     def delivery_method(method = nil, settings = {})
       return @delivery_method if @delivery_method && method.nil?

data/lib/mail/fields/common/common_address.rb

@@ -19,7 +19,7 @@ module Mail
       # Allows you to iterate through each address object in the syntax tree
       def each
         tree.addresses.each do |address|
-          yield
+          yield(address)
         end
       end
 

data/lib/mail/fields/common/common_field.rb

@@ -46,7 +46,11 @@ module Mail
       private
 
       def strip_field(field_name, string)
-        string.to_s.gsub(/#{field_name}:\s+/i, '')
+        if string.is_a?(Array)
+          string.join(', ')
+        else
+          string.to_s.gsub(/#{field_name}:\s+/i, '')
+        end
       end
 
     end

data/lib/mail/mail.rb

@@ -169,25 +169,6 @@ module Mail
   def Mail.read(filename)
     Mail.new(File.read(filename))
   end
-
-  # Provides a store of all the emails sent
-  def Mail.deliveries
-    @@deliveries ||= []
-  end
-
-  # Allows you to over write the default deliveries store from an array to some
-  # other object.  If you just want to clear the store, call Mail.deliveries.clear.
-  # 
-  # If you place another object here, please make sure it responds to:
-  # 
-  # * << (message)
-  # * clear
-  # * length
-  # * size
-  # * and other common Array methods
-  def Mail.deliveries=(val)
-    @@deliveries = val
-  end
   
   protected
   

data/lib/mail/message.rb

@@ -102,9 +102,12 @@ module Mail
 
       @perform_deliveries = true
       @raise_delivery_errors = true
+
+      @delivery_handler = nil
+      
       @delivery_method = Mail.delivery_method.dup
       @delivery_notification_observers = []
-      
+
       if args.flatten.first.respond_to?(:each_pair)
         init_with_hash(args.flatten.first)
       else
@@ -118,7 +121,76 @@ module Mail
       self
     end
 
+    # If you assign a delivery handler, mail will call :deliver_mail on the
+    # object you assign to delivery_handler, it will pass itself as the 
+    # single argument.
+    # 
+    # If you define a delivery_handler, then you are responsible for the
+    # following actions in the delivery cycle:
+    # 
+    # * Appending the mail object to Mail.deliveries as you see fit.
+    # * Checking the mail.perform_deliveries flag to decide if you should
+    #   actually call :deliver! the mail object or not.
+    # * Checking the mail.raise_delivery_errors flag to decide if you
+    #   should raise delivery errors if they occur.
+    # * Actually calling :deliver! (with the bang) on the mail object to
+    #   get it to deliver itself.
+    # 
+    # A simplest implementation of a delivery_handler would be
+    # 
+    #   class MyObject
+    #
+    #     def initialize
+    #       @mail = Mail.new('To: mikel@test.lindsaar.net')
+    #       @mail.delivery_handler = self
+    #     end
+    # 
+    #     attr_accessor :mail
+    # 
+    #     def deliver_mail(mail)
+    #       yield
+    #     end
+    #   end
+    # 
+    # Then doing:
+    # 
+    #   obj = MyObject.new
+    #   obj.mail.deliver
+    # 
+    # Would cause Mail to call obj.deliver_mail passing itself as a parameter,
+    # which then can just yield and let Mail do it's own private do_delivery
+    # method.
+    attr_accessor :delivery_handler
+
+    # If set to false, mail will go through the motions of doing a delivery,
+    # but not actually call the delivery method or append the mail object to
+    # the Mail.deliveries collection.  Useful for testing.
+    #
+    #   Mail.deliveries.size #=> 0
+    #   mail.delivery_method :smtp
+    #   mail.perform_deliveries = false
+    #   mail.deliver                        # Mail::SMTP not called here
+    #   Mail.deliveries.size #=> 0
+    # 
+    # If you want to test and query the Mail.deliveries collection to see what
+    # mail you sent, you should set perform_deliveries to true and use
+    # the :test mail delivery_method:
+    # 
+    #   Mail.deliveries.size #=> 0
+    #   mail.delivery_method :test
+    #   mail.perform_deliveries = true
+    #   mail.deliver
+    #   Mail.deliveries.size #=> 1
+    # 
+    # This setting is ignored by mail (though still available as a flag) if you
+    # define a delivery_handler
     attr_accessor :perform_deliveries
+
+    # If set to false, mail will silently catch and ignore any exceptions
+    # raised through attempting to deliver an email.
+    # 
+    # This setting is ignored by mail (though still available as a flag) if you
+    # define a delivery_handler
     attr_accessor :raise_delivery_errors
 
     def register_for_delivery_notification(observer)
@@ -138,22 +210,29 @@ module Mail
     # Examples:
     # 
     #  mail = Mail.read('file.eml')
-    #  mail.deliver!
+    #  mail.deliver
     def deliver
-      if perform_deliveries
-        begin
-          delivery_method.deliver!(self)
-          Mail.deliveries << self
-        rescue Exception => e # Net::SMTP errors or sendmail pipe errors
-          raise e if raise_delivery_errors
-        end
+      if delivery_handler
+        delivery_handler.deliver_mail(self) { do_delivery }
+      else
+        do_delivery
+        inform_observers
       end
+      self
+    end
+
+    # This method bypasses checking perform_deliveries and raise_delivery_errors, 
+    # so use with caution.
+    # 
+    # It still however fires callbacks to the observers if they are defined.
+    # 
+    # Returns self
+    def deliver!
+      delivery_method.deliver!(self)
       inform_observers
       self
     end
     
-    alias :deliver! :deliver
-    
     def delivery_method(method = nil, settings = {})
       unless method
         @delivery_method
@@ -1571,7 +1650,7 @@ module Mail
       find_attachment
     end
     
-    private
+  private
 
     #  2.1. General Description
     #   A message consists of header fields (collectively called "the header
@@ -1679,5 +1758,15 @@ module Mail
       filename
     end
 
+    def do_delivery
+      begin
+        if perform_deliveries
+          delivery_method.deliver!(self)
+        end
+      rescue Exception => e # Net::SMTP errors or sendmail pipe errors
+        raise e if raise_delivery_errors
+      end
+    end
+    
   end
 end

data/lib/mail/network/delivery_methods/test_mailer.rb

@@ -6,6 +6,26 @@ module Mail
   # if you want to make a custom mailer for Mail
   class TestMailer
 
+    # Provides a store of all the emails sent with the TestMailer so you can check them.
+    def TestMailer.deliveries
+      @@deliveries ||= []
+    end
+
+    # Allows you to over write the default deliveries store from an array to some
+    # other object.  If you just want to clear the store, 
+    # call TestMailer.deliveries.clear.
+    # 
+    # If you place another object here, please make sure it responds to:
+    # 
+    # * << (message)
+    # * clear
+    # * length
+    # * size
+    # * and other common Array methods
+    def TestMailer.deliveries=(val)
+      @@deliveries = val
+    end
+
     def initialize(values)
       @settings = {}
     end
@@ -13,6 +33,7 @@ module Mail
     attr_accessor :settings
 
     def deliver!(mail)
+      Mail::TestMailer.deliveries << mail
     end
     
   end

data/lib/mail/version.rb

@@ -2,8 +2,8 @@
 module Mail
   module VERSION
     MAJOR = 2
-    MINOR = 0
-    TINY  = 5
+    MINOR = 1
+    TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mail
 version: !ruby/object:Gem::Version 
-  version: 2.0.5
+  version: 2.1.0
 platform: ruby
 authors: 
 - Mike Lindsaar
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-24 00:00:00 +11:00
+date: 2010-01-25 00:00:00 +11:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency