mail 1.6.0 → 2.0.3

data/lib/mail/encodings/encodings.rb

@@ -1,5 +1,9 @@
 # encoding: utf-8
 module Mail
+  # Raised when attempting to decode an unknown encoding type
+  class UnknownEncodingType < StandardError #:nodoc:
+  end
+
   module Encodings
     
     include Mail::Patterns

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

@@ -0,0 +1,16 @@
+module Mail
+  
+  class AddressContainer < Array
+    
+    def initialize(field, list = [])
+      @field = field
+      super(list)
+    end
+
+    def << (address)
+      @field << address
+    end
+
+  end
+  
+end

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

@@ -10,7 +10,7 @@ module Mail
       
       def parse(val = value)
         unless val.blank?
-          @tree ||= AddressList.new(value)
+          @tree = AddressList.new(val)
         else
           nil
         end
@@ -25,12 +25,26 @@ module Mail
 
       # Returns the address string of all the addresses in the address list
       def addresses
-        tree.addresses.map { |a| a.address }
+        list = tree.addresses.map { |a| a.address }
+        Mail::AddressContainer.new(self, list)
       end
 
       # Returns the formatted string of all the addresses in the address list
       def formatted
-        tree.addresses.map { |a| a.format }
+        list = tree.addresses.map { |a| a.format }
+        Mail::AddressContainer.new(self, list)
+      end
+      
+      # Returns the display name of all the addresses in the address list
+      def display_names
+        list = tree.addresses.map { |a| a.display_name }
+        Mail::AddressContainer.new(self, list)
+      end
+      
+      # Returns the actual address objects in the address list
+      def addrs
+        list = tree.addresses
+        Mail::AddressContainer.new(self, list)
       end
       
       # Returns a hash of group name => address strings for the address list
@@ -55,6 +69,17 @@ module Mail
       def default
         addresses
       end
+
+      def <<(val)
+        case
+        when val.nil?
+          raise ArgumentError, "Need to pass an address to <<"
+        when val.blank?
+          parse(encoded)
+        else
+          parse((formatted + [val]).join(", "))
+        end
+      end
       
       private
       

data/lib/mail/fields/return_path_field.rb

@@ -54,5 +54,9 @@ module Mail
       addresses.first
     end
     
+    def default
+      address
+    end
+    
   end
 end

data/lib/mail/mail.rb

@@ -50,52 +50,70 @@ module Mail
     Mail::Message.new(args, &block)
   end
 
-  # Set the default configuration to send and receive emails.  The defaults
-  # are global, allowing you to just call them once and use them everywhere.
-  # if port values are omitted from the SMTP and POP3 method calls, then it
-  # is assumed to use the default ports of 25 and 110 respectively.
-  # 
-  # You call defaults in a block, then you can set the basic host and port,
-  # by passing arguments, also, if the method you are using required more
-  # information (like pop3), then pass a block to it and call methods like
-  # user, pass, enable_tls etc.
-  # 
-  # The arguments and block are both optional.
+  # Sets the default delivery method and retriever method for all new Mail objects.
+  # The delivery_method and retriever_method default to :smtp and :pop3, with defaults
+  # set.
+  # 
+  # So sending a new email, if you have an SMTP server running on localhost is
+  # as easy as:
+  # 
+  #   Mail.deliver do
+  #     to      'mikel@test.lindsaar.net'
+  #     from    'bob@test.lindsaar.net'
+  #     subject 'hi there!'
+  #     body    'this is a body'
+  #   end
+  # 
+  # If you do not specify anything, you will get the following equivalent code set in
+  # every new mail object:
+  # 
+  #   Mail.defaults do
+  #     delivery_method :smtp, { :address              => "localhost",
+  #                              :port                 => 25,
+  #                              :domain               => 'localhost.localdomain',
+  #                              :user_name            => nil,
+  #                              :password             => nil,
+  #                              :authentication       => nil,
+  #                              :enable_starttls_auto => true  }
+  # 
+  #     retriever_method :pop3, { :address             => "localhost",
+  #                               :port                => 995,
+  #                               :user_name           => nil,
+  #                               :password            => nil,
+  #                               :enable_ssl          => true }
+  #   end
+  # 
+  #   Mail.delivery_method.new  #=> Mail::SMTP instance
+  #   Mail.retriever_method.new #=> Mail::POP3 instance
   #
-  #  Mail.defaults do
-  #    smtp 'smtp.myhost.fr', 587
-  #    pop3 'pop.myhost.fr' do
-  #      user 'bernardo'
-  #      pass 'mypass'
-  #      enable_tls
-  #    end
-  #  end
+  # Each mail object inherits the default set in Mail.delivery_method, however, on
+  # a per email basis, you can override the method:
+  #
+  #   mail.delivery_method :sendmail
   # 
-  # You will also want to specify a delivery and retriever type, the defaults
-  # are SMTP and POP3.  You set the types by passing a symbol:
+  # Or you can override the method and pass in settings:
   # 
-  #  Mail.defaults do
-  #    retriever_method :pop3
-  #    delivery_method :smtp
-  #  end
+  #   mail.delivery_method :sendmail, { :address => 'some.host' }
   # 
-  # The only implemented methods at the moment are :pop3, :smtp and :test
+  # You can also just modify the settings:
   # 
-  # You can also specify your own delivery class which must respond to :deliver!
-  # or a retriever class which must respond to :get_messages
+  #   mail.delivery_settings = { :address => 'some.host' }
   # 
-  #  Mail.defaults do
-  #    retriever_method MyOwnRetriever.new
-  #  end
-  # 
-  # Once you have set defaults, you can call Mail.deliver to send an email
-  # through the Mail.deliver method.
+  # The passed in hash is just merged against the defaults with +merge!+ and the result
+  # assigned the mail object.  So the above example will change only the :address value
+  # of the global smtp_settings to be 'some.host', keeping all other values
   def Mail.defaults(&block)
-    if block_given?
-      Mail::Configuration.instance.defaults(&block)
-    else
-      Mail::Configuration.instance
-    end
+    Mail::Configuration.instance.instance_eval(&block)
+  end
+  
+  # Returns the delivery method selected, defaults to an instance of Mail::SMTP
+  def Mail.delivery_method
+    Mail::Configuration.instance.delivery_method
+  end
+
+  # Returns the retriever method selected, defaults to an instance of Mail::POP3
+  def Mail.retriever_method
+    Mail::Configuration.instance.retriever_method
   end
 
   # Send an email using the default configuration.  You do need to set a default
@@ -119,41 +137,35 @@ module Mail
   # And your email object will be created and sent.
   def Mail.deliver(*args, &block)
     mail = Mail.new(args, &block)
-    Deliverable.perform_delivery!(mail)
+    delivery_method.deliver!(mail)
     mail
   end
 
+  # Find emails in a POP3 server.
+  # See Mail::POP3 for a complete documentation.
+  def Mail.find(*args, &block)
+    retriever_method.find(*args, &block)
+  end
+
   # Receive the first email(s) from a Pop3 server.
   # See Mail::POP3 for a complete documentation.
   def Mail.first(*args, &block)
-    Retrievable.first(*args, &block)
+    retriever_method.first(*args, &block)
   end
 
   # Receive the first email(s) from a Pop3 server.
   # See Mail::POP3 for a complete documentation.
   def Mail.last(*args, &block)
-    Retrievable.last(*args, &block)
+    retriever_method.last(*args, &block)
   end
 
-  # Receive all emails from a Pop3 server.
+  # Receive all emails from a POP3 server.
   # See Mail::POP3 for a complete documentation.
   def Mail.all(*args, &block)
-    Retrievable.all(*args, &block)
-  end
-
-  # Receive all emails from a Pop3 server.
-  # DEPRECATED: please use Mail.all instead.
-  def Mail.get_all_mail(*args, &block)
-    warn "Mail.get_all_mail is deprecated. Please use Mail.all instead."
-    all(*args, &block)
-  end
-
-  # Find emails in a Pop3 server.
-  # See Mail::POP3 for a complete documentation.
-  def Mail.find(*args, &block)
-    Retrievable.find(*args, &block)
+    retriever_method.all(*args, &block)
   end
 
+  # Reads in an email message from a path and instantiates it as a new Mail::Message
   def Mail.read(filename)
     Mail.new(File.read(filename))
   end

data/lib/mail/message.rb

@@ -100,6 +100,8 @@ module Mail
       @text_part = nil
       @html_part = nil
       
+      @delivery_method = Mail.delivery_method.clone
+      
       if args.flatten.first.respond_to?(:each_pair)
         init_with_hash(args.flatten.first)
       else
@@ -119,8 +121,18 @@ module Mail
     # 
     #  mail = Mail.read('file.eml')
     #  mail.deliver!
-    def deliver!
-      Deliverable.perform_delivery!(self)
+    def deliver
+      @delivery_method.deliver!(self)
+    end
+    
+    alias :deliver! :deliver
+    
+    def delivery_method(method = nil, settings = {})
+      unless method
+        @delivery_method
+      else
+        @delivery_method = Mail::Configuration.instance.lookup_delivery_method(method).new(settings)
+      end
     end
     
     # Provides the operator needed for sort et al.
@@ -271,6 +283,15 @@ module Mail
     # 
     #  mail.bcc 'Mikel <mikel@test.lindsaar.net>'
     #  mail.bcc #=> ['mikel@test.lindsaar.net']
+    # 
+    # Additionally, you can append new addresses to the returned Array like
+    # object.
+    # 
+    # Example:
+    # 
+    #  mail.bcc 'Mikel <mikel@test.lindsaar.net>'
+    #  mail.bcc << 'ada@test.lindsaar.net'
+    #  mail.bcc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']
     def bcc( val = nil )
       default :bcc, val
     end
@@ -303,6 +324,15 @@ module Mail
     # 
     #  mail.cc 'Mikel <mikel@test.lindsaar.net>'
     #  mail.cc #=> ['mikel@test.lindsaar.net']
+    # 
+    # Additionally, you can append new addresses to the returned Array like
+    # object.
+    # 
+    # Example:
+    # 
+    #  mail.cc 'Mikel <mikel@test.lindsaar.net>'
+    #  mail.cc << 'ada@test.lindsaar.net'
+    #  mail.cc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']
     def cc( val = nil )
       default :cc, val
     end
@@ -399,6 +429,15 @@ module Mail
     # 
     #  mail.from 'Mikel <mikel@test.lindsaar.net>'
     #  mail.from #=> ['mikel@test.lindsaar.net']
+    # 
+    # Additionally, you can append new addresses to the returned Array like
+    # object.
+    # 
+    # Example:
+    # 
+    #  mail.from 'Mikel <mikel@test.lindsaar.net>'
+    #  mail.from << 'ada@test.lindsaar.net'
+    #  mail.from #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']
     def from( val = nil )
       default :from, val
     end
@@ -520,6 +559,15 @@ module Mail
     # 
     #  mail.reply_to 'Mikel <mikel@test.lindsaar.net>'
     #  mail.reply_to #=> ['mikel@test.lindsaar.net']
+    # 
+    # Additionally, you can append new addresses to the returned Array like
+    # object.
+    # 
+    # Example:
+    # 
+    #  mail.reply_to 'Mikel <mikel@test.lindsaar.net>'
+    #  mail.reply_to << 'ada@test.lindsaar.net'
+    #  mail.reply_to #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']
     def reply_to( val = nil )
       default :reply_to, val
     end
@@ -552,6 +600,15 @@ module Mail
     # 
     #  mail.resent_bcc 'Mikel <mikel@test.lindsaar.net>'
     #  mail.resent_bcc #=> ['mikel@test.lindsaar.net']
+    # 
+    # Additionally, you can append new addresses to the returned Array like
+    # object.
+    # 
+    # Example:
+    # 
+    #  mail.resent_bcc 'Mikel <mikel@test.lindsaar.net>'
+    #  mail.resent_bcc << 'ada@test.lindsaar.net'
+    #  mail.resent_bcc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']
     def resent_bcc( val = nil )
       default :resent_bcc, val
     end
@@ -584,6 +641,15 @@ module Mail
     # 
     #  mail.resent_cc 'Mikel <mikel@test.lindsaar.net>'
     #  mail.resent_cc #=> ['mikel@test.lindsaar.net']
+    # 
+    # Additionally, you can append new addresses to the returned Array like
+    # object.
+    # 
+    # Example:
+    # 
+    #  mail.resent_cc 'Mikel <mikel@test.lindsaar.net>'
+    #  mail.resent_cc << 'ada@test.lindsaar.net'
+    #  mail.resent_cc #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']
     def resent_cc( val = nil )
       default :resent_cc, val
     end
@@ -624,6 +690,15 @@ module Mail
     # 
     #  mail.resent_from ['Mikel <mikel@test.lindsaar.net>']
     #  mail.resent_from #=> 'mikel@test.lindsaar.net'
+    # 
+    # Additionally, you can append new addresses to the returned Array like
+    # object.
+    # 
+    # Example:
+    # 
+    #  mail.resent_from 'Mikel <mikel@test.lindsaar.net>'
+    #  mail.resent_from << 'ada@test.lindsaar.net'
+    #  mail.resent_from #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']
     def resent_from( val = nil )
       default :resent_from, val
     end
@@ -649,7 +724,8 @@ module Mail
     end
     
     # Returns the Resent-Sender value of the mail object, as a single string of an address
-    # spec.  A sender per RFC 2822 must be a single address
+    # spec.  A sender per RFC 2822 must be a single address, so you can not append to
+    # this address.
     #
     # Example:
     # 
@@ -692,6 +768,15 @@ module Mail
     # 
     #  mail.resent_to 'Mikel <mikel@test.lindsaar.net>'
     #  mail.resent_to #=> ['mikel@test.lindsaar.net']
+    # 
+    # Additionally, you can append new addresses to the returned Array like
+    # object.
+    # 
+    # Example:
+    # 
+    #  mail.resent_to 'Mikel <mikel@test.lindsaar.net>'
+    #  mail.resent_to << 'ada@test.lindsaar.net'
+    #  mail.resent_to #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']
     def resent_to( val = nil )
       default :resent_to, val
     end
@@ -719,7 +804,7 @@ module Mail
     end
     
     # Returns the Sender value of the mail object, as a single string of an address
-    # spec.  A sender per RFC 2822 must be a single address
+    # spec.  A sender per RFC 2822 must be a single address.
     #
     # Example:
     # 
@@ -791,6 +876,15 @@ module Mail
     # 
     #  mail.to 'Mikel <mikel@test.lindsaar.net>'
     #  mail.to #=> ['mikel@test.lindsaar.net']
+    # 
+    # Additionally, you can append new addresses to the returned Array like
+    # object.
+    # 
+    # Example:
+    # 
+    #  mail.to 'Mikel <mikel@test.lindsaar.net>'
+    #  mail.to << 'ada@test.lindsaar.net'
+    #  mail.to #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']
     def to( val = nil )
       default :to, val
     end
@@ -1211,20 +1305,47 @@ module Mail
       content_type_parameters ? content_type_parameters['boundary'] : nil
     end
     
-    # Returns an array of parts in the message
+    # Returns a parts list object of all the parts in the message
     def parts
       body.parts
     end
     
-    # Returns an array of attachments in the email recursively
+    # Returns an AttachmentsList object, which holds all of the attachments in
+    # the receiver object (either the entier email or a part within) and all
+    # of it's descendants.
+    # 
+    # It also allows you to add attachments to the mail object directly, like so:
+    # 
+    #  mail.attachments['filename.jpg'] = File.read('/path/to/filename.jpg')
+    # 
+    # If you do this, then Mail will take the file name and work out the mime type
+    # set the Content-Type, Content-Disposition, Content-Transfer-Encoding and 
+    # base64 encode the contents of the attachment all for you.
+    # 
+    # You can also specify overrides if you want by passing a hash instead of a string:
+    # 
+    #  mail.attachments['filename.jpg'] = {:mime_type => 'application/x-gzip',
+    #                                      :content => File.read('/path/to/filename.jpg')}
+    # 
+    # If you want to use a different encoding than Base64, you can pass an encoding in,
+    # but then it is up to you to pass in the content pre-encoded, and don't expect
+    # Mail to know how to decode this data:
+    # 
+    #  file_content = SpecialEncode(File.read('/path/to/filename.jpg'))
+    #  mail.attachments['filename.jpg'] = {:mime_type => 'application/x-gzip',
+    #                                      :encoding => 'SpecialEncoding',
+    #                                      :content => file_content }
+    # 
+    # You can also search for specific attachments:
+    # 
+    #  # By Filename
+    #  mail.attachments['filename.jpg']   #=> Mail::Part object or nil
+    #  
+    #  # or by index
+    #  mail.attachments[0]                #=> Mail::Part (first attachment)
+    #  
     def attachments
-      body.parts.map do |p| 
-        if p.parts.empty?
-          p.attachment if p.attachment?
-        else
-          p.attachments
-        end
-      end.compact.flatten
+      parts.attachments
     end
 
     def has_attachments?
@@ -1310,20 +1431,16 @@ module Mail
     # Adds a file to the message.  You have two options with this method, you can
     # just pass in the absolute path to the file you want and Mail will read the file,
     # get the filename from the path you pass in and guess the mime type, or you
-    # can pass in the filename as a string, and pass in the file data as a blob.
+    # can pass in the filename as a string, and pass in the file content as a blob.
     # 
     # Example:
     # 
     #  m = Mail.new
     #  m.add_file('/path/to/filename.png')
     # 
-    # or
-    # 
     #  m = Mail.new
-    #  m.add_file(:filename => 'filename.png', :data => File.read('/path/to/filename.png'))
-    # 
-    # The above two alternatives will produce the same email message.
-    # 
+    #  m.add_file(:filename => 'filename.png', :content => File.read('/path/to/file.jpg'))
+    #
     # Note also that if you add a file to an existing message, Mail will convert that message
     # to a MIME multipart email, moving whatever plain text body you had into it's own text
     # plain part.
@@ -1338,14 +1455,19 @@ module Mail
     #  m.multipart? #=> true
     #  m.parts.first.content_type.content_type #=> 'text/plain'
     #  m.parts.last.content_type.content_type #=> 'image/png'
-    def add_file(options)
+    # 
+    # See also #attachments
+    def add_file(values)
       convert_to_multipart unless self.multipart? || self.body.decoded.blank?
       add_multipart_mixed_header
-      if options.is_a?(Hash)
-        self.body << Mail::Part.new(options)
+      if values.is_a?(String)
+        basename = File.basename(values)
+        filedata = File.read(values)
       else
-        self.body << Mail::Part.new(:filename => options)
+        basename = values[:filename]
+        filedata = values[:content] || File.read(values[:filename])
       end
+      self.attachments[basename] = filedata
     end
 
     def convert_to_multipart
@@ -1384,7 +1506,27 @@ module Mail
     end
 
     def decoded
-      raise NoMethodError, 'Can not decode an entire message, try calling #decoded on the various fields and body or parts if it is a multipart message.'
+      if self.attachment?
+        decode_body
+      else
+        raise NoMethodError, 'Can not decode an entire message, try calling #decoded on the various fields and body or parts if it is a multipart message.'
+      end
+    end
+
+    def read
+      if self.attachment?
+        decode_body
+      else
+        raise NoMethodError, 'Can not call read on a part unless it is an attachment.'
+      end
+    end
+
+    def decode_body
+      if Mail::Encodings.defined?(content_transfer_encoding)
+        Mail::Encodings.get_encoding(content_transfer_encoding).decode(body.encoded)
+      else
+        raise UnknownEncodingType, "Don't know how to decode #{content_transfer_encoding}, please call #encoded and decode it yourself."
+      end
     end
     
     # Returns true if this part is an attachment
@@ -1399,11 +1541,7 @@ module Mail
     
     # Returns the filename of the attachment
     def filename
-      if attachment?
-        attachment.filename
-      else
-        nil
-      end
+      find_attachment
     end
     
     private
@@ -1446,6 +1584,7 @@ module Mail
     end
     
     def add_required_fields
+      add_multipart_mixed_header    unless parts.empty?
       @body = Mail::Body.new('')    if body.nil?
       add_message_id                unless (has_message_id? || self.class == Mail::Part)
       add_date                      unless has_date?
@@ -1481,16 +1620,6 @@ module Mail
       @header = Mail::Header.new
       @body = Mail::Body.new
 
-      # Strip out the attachment headers and make an attachment
-      if passed_in_options.has_key?(:filename)
-        add_attachment(passed_in_options)
-        passed_in_options.delete(:content_disposition)
-        passed_in_options.delete(:content_type)
-        passed_in_options.delete(:mime_type)
-        passed_in_options.delete(:filename)
-        passed_in_options.delete(:data)
-      end
-      
       passed_in_options.each_pair do |k,v|
         k = underscoreize(k).to_sym if k.class == String
         if k == :headers
@@ -1501,29 +1630,11 @@ module Mail
       end
     end
     
-    def add_attachment(options_hash)
-      @attachment = Mail::Attachment.new(options_hash)
-      mime_type = options_hash[:content_type] || attachment.mime_type
-      self.content_type = "#{mime_type}; filename=\"#{attachment.filename}\""
-      self.content_transfer_encoding = "Base64"
-
-      disposition = options_hash[:content_disposition] || "attachment"
-      self.content_disposition = "#{disposition}; filename=\"#{attachment.filename}\""
-      add_boundary
-      self.body = attachment.encoded
-    end
-    
     def init_with_string(string)
       self.raw_source = string
       set_envelope_header
       parse_message
       separate_parts if multipart?
-      if filename = attachment?
-        encoding = header[:content_transfer_encoding].encoding if content_transfer_encoding
-        @attachment = Mail::Attachment.new(:filename => filename,
-                                           :data => body.encoded,
-                                           :encoding => encoding)
-      end
     end
     
     # Returns the filename of the attachment (if it exists) or returns nil