Merge branch 'master' into tmm1

CHANGELOG.rdoc

@@ -1,3 +1,20 @@
+== Mon Jan 25 11:36:13 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Added ability for address fields to init on an array instead of just a string.
+* Version bump to 2.1.1
+
+== 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

README.rdoc

@@ -219,11 +219,9 @@ what you are doing.
 
 === Sending an email:
 
- require 'mail'
-
- Mail.defaults do
-   smtp '127.0.0.1', 25
- end
+Mail defaults to sending via SMTP to local host port 25.  If you have a 
+sendmail or postfix daemon running on on this port, sending email is as
+easy as:
 
  Mail.deliver do
        from 'me@test.lindsaar.net'
@@ -235,10 +233,6 @@ what you are doing.
 
 or
 
- Mail.defaults do
-   smtp '127.0.0.1' # Port 25 defult
- end
-
  mail = Mail.new do
        from 'me@test.lindsaar.net'
          to 'you@test.lindsaar.net'
@@ -249,6 +243,22 @@ or
 
  mail.deliver!
 
+Sending via sendmail can be done like so:
+
+  mail = Mail.new do
+        from 'me@test.lindsaar.net'
+          to 'you@test.lindsaar.net'
+     subject 'Here is the image you wanted'
+        body File.read('body.txt')
+    add_file {:filename => 'somefile.png', :content => File.read('/somefile.png')}
+  end
+
+  mail.delivery_method :sendmail
+
+  mail.deliver
+
+mail.deliver!
+
 
 === Getting emails from a pop server:
 
@@ -344,10 +354,6 @@ simple as possible.... (asking a lot from a mail library)
 
  require 'mail'
 
- Mail.defaults do
-   smtp '127.0.0.1' # Port 25 defult
- end
-
  mail = Mail.deliver do
    to 'nicolas@test.lindsaar.net.au'
    from 'Mikel Lindsaar <mikel@test.lindsaar.net.au>'

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.1"
   s.author      = "Mike Lindsaar"
   s.email       = "raasdnil@gmail.com"
   s.homepage    = "http://github.com/mikel/mail"

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?

lib/mail/fields/common/common_field.rb

@@ -46,7 +46,11 @@ def responsible_for?( val )
       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

lib/mail/mail.rb

@@ -169,25 +169,6 @@ def Mail.all(*args, &block)
   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
 

lib/mail/message.rb

@@ -102,9 +102,12 @@ def initialize(*args, &block)
 
       @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 @@ def initialize(*args, &block)
       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 @@ def inform_observers
     # 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 @@ def filename
       find_attachment
     end
 
-    private
+  private
 
     #  2.1. General Description
     #   A message consists of header fields (collectively called "the header
@@ -1679,5 +1758,15 @@ def find_attachment
       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

lib/mail/network/delivery_methods/test_mailer.rb

@@ -6,13 +6,34 @@ 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
 
     attr_accessor :settings
 
     def deliver!(mail)
+      Mail::TestMailer.deliveries << mail
     end
 
   end

lib/mail/version.rb

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

spec/mail/field_spec.rb

@@ -10,6 +10,11 @@
       Mail::Field.new('To: Mikel').field.class.should == Mail::ToField
     end
 
+    it "should allow you to init on an array" do
+      field = Mail::Field.new("To", ['test1@lindsaar.net', 'Mikel <test2@lindsaar.net>'])
+      field.addresses.should == ["test1@lindsaar.net", "test2@lindsaar.net"]
+    end
+
     it "should allow us to pass an empty value" do
       doing {Mail::Field.new('To')}.should_not raise_error
       Mail::Field.new('To').field.class.should == Mail::ToField

spec/mail/fields/common/common_address_spec.rb

@@ -60,7 +60,7 @@
       field.value = 'mikel@test.lindsaar.net'
       field.addresses.should == ['mikel@test.lindsaar.net']
     end
-    
+
     it "should encode to an empty string if it has no addresses or groups" do
       field = Mail::ToField.new("To", "")
       field.encoded.should == ''