dball-mail 2.2.9.1

data/lib/mail/header.rb

@@ -0,0 +1,264 @@
+# encoding: utf-8
+module Mail
+  
+  # Provides access to a header object.
+  # 
+  # ===Per RFC2822
+  # 
+  #  2.2. Header Fields
+  # 
+  #   Header fields are lines composed of a field name, followed by a colon
+  #   (":"), followed by a field body, and terminated by CRLF.  A field
+  #   name MUST be composed of printable US-ASCII characters (i.e.,
+  #   characters that have values between 33 and 126, inclusive), except
+  #   colon.  A field body may be composed of any US-ASCII characters,
+  #   except for CR and LF.  However, a field body may contain CRLF when
+  #   used in header "folding" and  "unfolding" as described in section
+  #   2.2.3.  All field bodies MUST conform to the syntax described in
+  #   sections 3 and 4 of this standard.
+  class Header
+    include Patterns
+    include Utilities
+    include Enumerable
+    
+    # Creates a new header object.
+    # 
+    # Accepts raw text or nothing.  If given raw text will attempt to parse
+    # it and split it into the various fields, instantiating each field as
+    # it goes.
+    # 
+    # If it finds a field that should be a structured field (such as content
+    # type), but it fails to parse it, it will simply make it an unstructured
+    # field and leave it alone.  This will mean that the data is preserved but
+    # no automatic processing of that field will happen.  If you find one of
+    # these cases, please make a patch and send it in, or at the least, send
+    # me the example so we can fix it.
+    def initialize(header_text = nil, charset = nil)
+      @errors = []
+      @charset = charset
+      self.raw_source = header_text.to_crlf
+      split_header if header_text
+    end
+    
+    # The preserved raw source of the header as you passed it in, untouched
+    # for your Regexing glory.
+    def raw_source
+      @raw_source
+    end
+    
+    # Returns an array of all the fields in the header in order that they
+    # were read in.
+    def fields
+      @fields ||= FieldList.new
+    end
+    
+    #  3.6. Field definitions
+    #  
+    #   It is important to note that the header fields are not guaranteed to
+    #   be in a particular order.  They may appear in any order, and they
+    #   have been known to be reordered occasionally when transported over
+    #   the Internet.  However, for the purposes of this standard, header
+    #   fields SHOULD NOT be reordered when a message is transported or
+    #   transformed.  More importantly, the trace header fields and resent
+    #   header fields MUST NOT be reordered, and SHOULD be kept in blocks
+    #   prepended to the message.  See sections 3.6.6 and 3.6.7 for more
+    #   information.
+    # 
+    # Populates the fields container with Field objects in the order it
+    # receives them in.
+    #
+    # Acceps an array of field string values, for example:
+    # 
+    #  h = Header.new
+    #  h.fields = ['From: mikel@me.com', 'To: bob@you.com']
+    def fields=(unfolded_fields)
+      @fields = Mail::FieldList.new
+      unfolded_fields.each do |field|
+
+        field = Field.new(field, nil, charset)
+        field.errors.each { |error| self.errors << error }
+        selected = select_field_for(field.name)
+
+        if selected.any? && limited_field?(field.name)
+          selected.first.update(field.name, field.value)
+        else
+          @fields << field
+        end
+      end
+
+    end
+    
+    def errors
+      @errors
+    end
+    
+    #  3.6. Field definitions
+    #  
+    #   The following table indicates limits on the number of times each
+    #   field may occur in a message header as well as any special
+    #   limitations on the use of those fields.  An asterisk next to a value
+    #   in the minimum or maximum column indicates that a special restriction
+    #   appears in the Notes column.
+    #
+    #   <snip table from 3.6>
+    #
+    # As per RFC, many fields can appear more than once, we will return a string
+    # of the value if there is only one header, or if there is more than one 
+    # matching header, will return an array of values in order that they appear
+    # in the header ordered from top to bottom.
+    # 
+    # Example:
+    # 
+    #  h = Header.new
+    #  h.fields = ['To: mikel@me.com', 'X-Mail-SPAM: 15', 'X-Mail-SPAM: 20']
+    #  h['To']          #=> 'mikel@me.com'
+    #  h['X-Mail-SPAM'] #=> ['15', '20']
+    def [](name)
+      name = dasherize(name).downcase
+      selected = select_field_for(name)
+      case
+      when selected.length > 1
+        selected.map { |f| f }
+      when !selected.blank?
+        selected.first
+      else
+        nil
+      end
+    end
+    
+    # Sets the FIRST matching field in the header to passed value, or deletes
+    # the FIRST field matched from the header if passed nil
+    # 
+    # Example:
+    # 
+    #  h = Header.new
+    #  h.fields = ['To: mikel@me.com', 'X-Mail-SPAM: 15', 'X-Mail-SPAM: 20']
+    #  h['To'] = 'bob@you.com'
+    #  h['To']    #=> 'bob@you.com'
+    #  h['X-Mail-SPAM'] = '10000'
+    #  h['X-Mail-SPAM'] # => ['15', '20', '10000']
+    #  h['X-Mail-SPAM'] = nil
+    #  h['X-Mail-SPAM'] # => nil
+    def []=(name, value)
+      name = dasherize(name)
+      fn = name.downcase
+      selected = select_field_for(fn)
+      
+      case
+      # User wants to delete the field
+      when !selected.blank? && value == nil
+        fields.delete_if { |f| selected.include?(f) }
+        
+      # User wants to change the field
+      when !selected.blank? && limited_field?(fn)
+        selected.first.update(fn, value)
+        
+      # User wants to create the field
+      else
+        # Need to insert in correct order for trace fields
+        self.fields << Field.new(name.to_s, value, charset)
+      end
+    end
+    
+    def charset
+      params = self[:content_type].parameters rescue nil
+      if params
+        params[:charset]
+      else
+        @charset
+      end
+    end
+    
+    def charset=(val)
+      params = self[:content_type].parameters rescue nil
+      if params
+        params[:charset] = val
+      end
+      @charset = val
+    end
+    
+    LIMITED_FIELDS   = %w[ date from sender reply-to to cc bcc 
+                           message-id in-reply-to references subject
+                           return-path content-type mime-version
+                           content-transfer-encoding content-description 
+                           content-id content-disposition content-location]
+
+    def encoded
+      buffer = ''
+      fields.each do |field|
+        buffer << field.encoded
+      end
+      buffer
+    end
+
+    def to_s
+      encoded
+    end
+    
+    def decoded
+      raise NoMethodError, 'Can not decode an entire header as there could be character set conflicts, try calling #decoded on the various fields.'
+    end
+
+    def field_summary
+      fields.map { |f| "<#{f.name}: #{f.value}>" }.join(", ")
+    end
+
+    # Returns true if the header has a Message-ID defined (empty or not)
+    def has_message_id?
+      !fields.select { |f| f.responsible_for?('Message-ID') }.empty?
+    end
+
+    # Returns true if the header has a Content-ID defined (empty or not)
+    def has_content_id?
+      !fields.select { |f| f.responsible_for?('Content-ID') }.empty?
+    end
+
+    # Returns true if the header has a Date defined (empty or not)
+    def has_date?
+      !fields.select { |f| f.responsible_for?('Date') }.empty?
+    end
+
+    # Returns true if the header has a MIME version defined (empty or not)
+    def has_mime_version?
+      !fields.select { |f| f.responsible_for?('Mime-Version') }.empty?
+    end
+
+    private
+    
+    def raw_source=(val)
+      @raw_source = val
+    end
+    
+    # 2.2.3. Long Header Fields
+    # 
+    #  The process of moving from this folded multiple-line representation
+    #  of a header field to its single line representation is called
+    #  "unfolding". Unfolding is accomplished by simply removing any CRLF
+    #  that is immediately followed by WSP.  Each header field should be
+    #  treated in its unfolded form for further syntactic and semantic
+    #  evaluation.
+    def unfold(string)
+      string.gsub(/#{CRLF}#{WSP}+/, ' ').gsub(/#{WSP}+/, ' ')
+    end
+    
+    # Returns the header with all the folds removed
+    def unfolded_header
+      @unfolded_header ||= unfold(raw_source)
+    end
+    
+    # Splits an unfolded and line break cleaned header into individual field
+    # strings.
+    def split_header
+      self.fields = unfolded_header.split(CRLF)
+    end
+    
+    def select_field_for(name)
+      fields.select { |f| f.responsible_for?(name.to_s) }
+    end
+    
+    def limited_field?(name)
+      LIMITED_FIELDS.include?(name.to_s.downcase)
+    end
+    
+  end
+end

data/lib/mail/mail.rb

@@ -0,0 +1,255 @@
+# encoding: utf-8
+module Mail
+
+  # Allows you to create a new Mail::Message object.
+  # 
+  # You can make an email via passing a string or passing a block.
+  # 
+  # For example, the following two examples will create the same email
+  # message:
+  # 
+  # Creating via a string:
+  # 
+  #  string = 'To: mikel@test.lindsaar.net\r\n'
+  #  string << 'From: bob@test.lindsaar.net\r\n\r\n'
+  #  string << 'Subject: This is an email\r\n'
+  #  string << '\r\n'
+  #  string << 'This is the body'
+  #  Mail.new(string)
+  # 
+  # Or creating via a block:
+  # 
+  #  message = Mail.new do
+  #    to 'mikel@test.lindsaar.net'
+  #    from 'bob@test.lindsaar.net'
+  #    subject 'This is an email'
+  #    body 'This is the body'
+  #  end
+  # 
+  # Or creating via a hash (or hash like object):
+  # 
+  #  message = Mail.new({:to => 'mikel@test.lindsaar.net',
+  #                      'from' => 'bob@test.lindsaar.net',
+  #                       :subject 'This is an email',
+  #                       :body 'This is the body' })
+  # 
+  # Note, the hash keys can be strings or symbols, the passed in object
+  # does not need to be a hash, it just needs to respond to :each_pair
+  # and yield each key value pair.
+  # 
+  # As a side note, you can also create a new email through creating
+  # a Mail::Message object directly and then passing in values via string,
+  # symbol or direct method calls.  See Mail::Message for more information.
+  # 
+  #  mail = Mail.new
+  #  mail.to = 'mikel@test.lindsaar.net'
+  #  mail[:from] = 'bob@test.lindsaar.net'
+  #  mail['subject'] = 'This is an email'
+  #  mail.body = 'This is the body'
+  def self.new(*args, &block)
+    Message.new(args, &block)
+  end
+
+  # 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
+  #
+  # 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
+  # 
+  # Or you can override the method and pass in settings:
+  # 
+  #   mail.delivery_method :sendmail, { :address => 'some.host' }
+  # 
+  # You can also just modify the settings:
+  # 
+  #   mail.delivery_settings = { :address => 'some.host' }
+  # 
+  # 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 self.defaults(&block)
+    Configuration.instance.instance_eval(&block)
+  end
+
+  # Returns the delivery method selected, defaults to an instance of Mail::SMTP
+  def self.delivery_method
+    Configuration.instance.delivery_method
+  end
+
+  # Returns the retriever method selected, defaults to an instance of Mail::POP3
+  def self.retriever_method
+    Configuration.instance.retriever_method
+  end
+
+  # Send an email using the default configuration.  You do need to set a default
+  # configuration first before you use self.deliver, if you don't, an appropriate
+  # error will be raised telling you to.
+  # 
+  # If you do not specify a delivery type, SMTP will be used.
+  # 
+  #  Mail.deliver do
+  #   to 'mikel@test.lindsaar.net'
+  #   from 'ada@test.lindsaar.net'
+  #   subject 'This is a test email'
+  #   body 'Not much to say here'
+  #  end
+  # 
+  # You can also do:
+  # 
+  #  mail = Mail.read('email.eml')
+  #  mail.deliver!
+  # 
+  # And your email object will be created and sent.
+  def self.deliver(*args, &block)
+    mail = self.new(args, &block)
+    mail.deliver
+    mail
+  end
+
+  # Find emails in a POP3 server.
+  # See Mail::POP3 for a complete documentation.
+  def self.find(*args, &block)
+    retriever_method.find(*args, &block)
+  end
+
+  # Finds and then deletes retrieved emails from a POP3 server.
+  # See Mail::POP3 for a complete documentation.
+  def self.find_and_delete(*args, &block)
+    retriever_method.find_and_delete(*args, &block)
+  end
+
+  # Receive the first email(s) from a Pop3 server.
+  # See Mail::POP3 for a complete documentation.
+  def self.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 self.last(*args, &block)
+    retriever_method.last(*args, &block)
+  end
+
+  # Receive all emails from a POP3 server.
+  # See Mail::POP3 for a complete documentation.
+  def self.all(*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 self.read(filename)
+    self.new(File.open(filename, 'rb') { |f| f.read })
+  end
+
+  # Delete all emails from a POP3 server.
+  # See Mail::POP3 for a complete documentation.
+  def self.delete_all(*args, &block)
+    retriever_method.delete_all(*args, &block)
+  end
+
+  # Instantiates a new Mail::Message using a string
+  def Mail.read_from_string(mail_as_string)
+    Mail.new(mail_as_string)
+  end
+
+  def Mail.connection(&block)
+    retriever_method.connection(&block)
+  end
+
+  # Initialize the observers and interceptors arrays
+  @@delivery_notification_observers = []
+  @@delivery_interceptors = []
+
+  # You can register an object to be informed of every email that is sent through
+  # this method.
+  # 
+  # Your object needs to respond to a single method #delivered_email(mail)
+  # which receives the email that is sent.
+  def self.register_observer(observer)
+    unless @@delivery_notification_observers.include?(observer)
+      @@delivery_notification_observers << observer
+    end
+  end
+
+  # You can register an object to be given every mail object that will be sent,
+  # before it is sent.  So if you want to add special headers or modify any
+  # email that gets sent through the Mail library, you can do so.
+  # 
+  # Your object needs to respond to a single method #delivering_email(mail)
+  # which receives the email that is about to be sent.  Make your modifications
+  # directly to this object.
+  def self.register_interceptor(interceptor)
+    unless @@delivery_interceptors.include?(interceptor)
+      @@delivery_interceptors << interceptor
+    end
+  end
+
+  def self.inform_observers(mail)
+    @@delivery_notification_observers.each do |observer|
+      observer.delivered_email(mail)
+    end
+  end
+
+  def self.inform_interceptors(mail)
+    @@delivery_interceptors.each do |interceptor|
+      interceptor.delivering_email(mail)
+    end
+  end
+
+  protected
+
+  def self.random_tag
+    t = Time.now
+    sprintf('%x%x_%x%x%d%x',
+            t.to_i, t.tv_usec,
+            $$, Thread.current.object_id.abs, self.uniq, rand(255))
+  end
+
+  private
+
+  def self.something_random
+    (Thread.current.object_id * rand(255) / Time.now.to_f).to_s.slice(-3..-1).to_i
+  end
+
+  def self.uniq
+    @@uniq += 1
+  end
+
+  @@uniq = self.something_random
+
+end