mail 2.2.6.1 → 2.2.7

data/CHANGELOG.rdoc

@@ -1,3 +1,18 @@
+== Thu Oct  7 15:44:31 UTC 2010 Mikel Lindsaar <mikel@rubyx.com>
+
+* Version Bump to 2.2.7
+* Release 2.2.7
+
+== Thu Oct  7 15:42:57 UTC 2010 Mikel Lindsaar <mikel@rubyx.com>
+
+* Added fix for Windows using 'rb' flags, thanks to Luis Lavena and dzhang for pointing it out
+* Fixed up Rakefile to require bundler to run specs and give more appropriate errors messages if this fails
+
+== Tue Sep 28 14:59:03 UTC 2010 Mikel Lindsaar <mikel@rubyx.com>
+
+* Merged POP3 delete support work from Michael Prendergast
+* Merged IMAP support work from Fabian Staubli
+
 == Mon Sep 13 02:31:21 UTC 2010 Mikel Lindsaar <mikel@rubyx.com>
 
 * Replace some missing documentation

data/Rakefile

@@ -1,3 +1,24 @@
+begin
+  require "rubygems"
+  require "bundler"
+rescue LoadError
+  raise "Could not load the bundler gem. Install it with `gem install bundler`."
+end
+
+if Gem::Version.new(Bundler::VERSION) <= Gem::Version.new("1.0.0")
+  raise RuntimeError, "Your bundler version is too old for Mail" +
+   "Run `gem install bundler` to upgrade."
+end
+
+begin
+  # Set up load paths for all bundled gems
+  ENV["BUNDLE_GEMFILE"] = File.expand_path("../Gemfile", __FILE__)
+  Bundler.setup
+rescue Bundler::GemNotFound
+  raise RuntimeError, "Bundler couldn't find some gems." +
+    "Did you run `bundle install`?"
+end
+
 require File.expand_path('../spec/environment', __FILE__)
 
 require 'rake/rdoctask'

data/lib/VERSION

@@ -1,4 +1,4 @@
-patch:6
+patch:7
 major:2
-build:1
+build:
 minor:2

data/lib/mail/configuration.rb

@@ -53,6 +53,8 @@ module Mail
         Mail::POP3
       when :pop3
         Mail::POP3
+      when :imap
+        Mail::IMAP
       else
         method
       end
@@ -64,4 +66,4 @@ module Mail
 
   end
 
-end
+end

data/lib/mail/elements/address.rb

@@ -104,7 +104,7 @@ module Mail
     #  a.local #=> 'mikel'
     def local
       parse unless @parsed
-      "#{obs_domain_list}#{get_local.strip}"
+      "#{obs_domain_list}#{get_local.strip}" if get_local
     end
 
     # Returns the domain part (the right hand side of the @ sign in the email address) of
@@ -297,7 +297,7 @@ module Mail
       when tree.respond_to?(:addr_spec)
         tree.addr_spec.local_part.text_value
       else
-        tree.local_part.text_value
+        tree ? tree.local_part.text_value : nil
       end
     end
     

data/lib/mail/mail.rb

@@ -147,6 +147,12 @@ module Mail
     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)
@@ -167,7 +173,7 @@ module Mail
 
   # Reads in an email message from a path and instantiates it as a new Mail::Message
   def self.read(filename)
-    self.new(File.read(filename))
+    self.new(File.open(filename, 'rb') { |f| f.read })
   end
 
   # Delete all emails from a POP3 server.
@@ -181,6 +187,10 @@ module Mail
     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 = []

data/lib/mail/message.rb

@@ -115,6 +115,8 @@ module Mail
       @delivery_method = Mail.delivery_method.dup
 
       @transport_encoding = Mail::Encodings.get_encoding('7bit')
+      
+      @mark_for_delete = false
 
       if args.flatten.first.respond_to?(:each_pair)
         init_with_hash(args.flatten.first)
@@ -1622,10 +1624,10 @@ module Mail
       add_multipart_mixed_header
       if values.is_a?(String)
         basename = File.basename(values)
-        filedata = File.read(values)
+        filedata = File.open(values, 'rb') { |f| f.read }
       else
         basename = values[:filename]
-        filedata = values[:content] || File.read(values[:filename])
+        filedata = values[:content] || File.open(values[:filename], 'rb') { |f| f.read }
       end
       self.attachments[basename] = filedata
     end
@@ -1720,7 +1722,36 @@ module Mail
     def find_first_mime_type(mt)
       all_parts.detect { |p| p.mime_type == mt }
     end
-
+  
+    # Skips the deletion of this message. All other messages
+    # flagged for delete still will be deleted at session close (i.e. when
+    # #find exits). Only has an effect if you're using #find_and_delete
+    # or #find with :delete_after_find set to true.
+    def skip_deletion
+      @mark_for_delete = false
+    end
+    
+    # Sets whether this message should be deleted at session close (i.e. 
+    # after #find). Message will only be deleted if messages are retrieved
+    # using the #find_and_delete method, or by calling #find with 
+    # :delete_after_find set to true.    
+    def mark_for_delete=(value = true)
+      @mark_for_delete = value
+    end
+    
+    # Returns whether message will be marked for deletion.
+    # If so, the message will be deleted at session close (i.e. after #find 
+    # exits), but only if also using the #find_and_delete method, or by 
+    # calling #find with :delete_after_find set to true.
+    #
+    # Side-note: Just to be clear, this method will return true even if
+    # the message hasn't yet been marked for delete on the mail server. 
+    # However, if this method returns true, it *will be* marked on the
+    # server after each block yields back to #find or #find_and_delete. 
+    def is_marked_for_delete?
+      return @mark_for_delete
+    end
+    
   private
 
     #  2.1. General Description

data/lib/mail/network/retriever_methods/imap.rb

@@ -1,5 +1,39 @@
+# encoding: utf-8
+
 module Mail
+  # The IMAP retriever allows to get the last, first or all emails from a POP3 server.
+  # Each email retrieved (RFC2822) is given as an instance of +Message+.
+  #
+  # While being retrieved, emails can be yielded if a block is given.
+  #
+  # === Example of retrieving Emails from GMail:
+  #
+  #   Mail.defaults do
+  #     retriever_method :imap, { :address             => "imap.googlemail.com",
+  #                               :port                => 993,
+  #                               :user_name           => '<username>',
+  #                               :password            => '<password>',
+  #                               :enable_ssl          => true }
+  #   end
+  #
+  #   Mail.all    #=> Returns an array of all emails
+  #   Mail.first  #=> Returns the first unread email
+  #   Mail.last   #=> Returns the first unread email
+  #
+  # You can also pass options into Mail.find to locate an email in your imap mailbox
+  # with the following options:
+  #
+  #   mailbox: name of the mailbox used for email retrieval. The default is 'INBOX'.
+  #   what:    last or first emails. The default is :first.
+  #   order:   order of emails returned. Possible values are :asc or :desc. Default value is :asc.
+  #   count:   number of emails to retrieve. The default value is 10. A value of 1 returns an
+  #            instance of Message, not an array of Message instances.
+  #
+  #   Mail.find(:what => :first, :count => 10, :order => :asc)
+  #   #=> Returns the first 10 emails in ascending order
+  #
   class IMAP
+    require 'net/imap'
     
     def initialize(values)
       self.settings = { :address              => "localhost",
@@ -9,10 +43,144 @@ module Mail
                         :authentication       => nil,
                         :enable_ssl           => false }.merge!(values)
     end
-    
-    def IMAP.get_messages(&block)
-      # To be implemented
+
+    attr_accessor :settings
+
+    # Get the oldest received email(s)
+    #
+    # Possible options:
+    #   mailbox: mailbox to retrieve the oldest received email(s) from. The default is 'INBOX'.
+    #   count:   number of emails to retrieve. The default value is 1.
+    #   order:   order of emails returned. Possible values are :asc or :desc. Default value is :asc.
+    #   keys:    keywords for the imap SEARCH command. Can be either a string holding the entire 
+    #            search string or a single-dimension array of search keywords and arguments.
+    #
+    def first(options={}, &block)
+      options ||= {}
+      options[:what] = :first
+      options[:count] ||= 1
+      find(options, &block)
+    end
+
+    # Get the most recent received email(s)
+    #
+    # Possible options:
+    #   mailbox: mailbox to retrieve the most recent received email(s) from. The default is 'INBOX'.
+    #   count:   number of emails to retrieve. The default value is 1.
+    #   order:   order of emails returned. Possible values are :asc or :desc. Default value is :asc.
+    #   keys:    keywords for the imap SEARCH command. Can be either a string holding the entire 
+    #            search string or a single-dimension array of search keywords and arguments.
+    #
+    def last(options={}, &block)
+      options ||= {}
+      options[:what] = :last
+      options[:count] ||= 1
+      find(options, &block)
+    end
+
+    # Get all emails.
+    #
+    # Possible options:
+    #   mailbox: mailbox to retrieve all email(s) from. The default is 'INBOX'.
+    #   count:   number of emails to retrieve. The default value is 1.
+    #   order:   order of emails returned. Possible values are :asc or :desc. Default value is :asc.
+    #   keys:    keywords for the imap SEARCH command. Can be either a string holding the entire 
+    #            search string or a single-dimension array of search keywords and arguments.
+    #
+    def all(options={}, &block)
+      options ||= {}
+      options[:count] = :all
+      options[:keys]  = 'ALL'
+      find(options, &block)
     end
     
+    # Find emails in a POP3 mailbox. Without any options, the 10 last received emails are returned.
+    #
+    # Possible options:
+    #   mailbox: mailbox to search the email(s) in. The default is 'INBOX'.
+    #   what:    last or first emails. The default is :first.
+    #   order:   order of emails returned. Possible values are :asc or :desc. Default value is :asc.
+    #   count:   number of emails to retrieve. The default value is 10. A value of 1 returns an
+    #            instance of Message, not an array of Message instances.
+    #
+    def find(options={}, &block)
+      options = validate_options(options)
+
+      start do |imap|
+        imap.select(options[:mailbox])
+
+        message_ids = imap.uid_search(options[:keys])
+        message_ids.reverse! if options[:what].to_sym == :last
+        message_ids = message_ids.first(options[:count]) if options[:count].is_a?(Integer)
+        message_ids.reverse! if (options[:what].to_sym == :last && options[:order].to_sym == :asc) ||
+                                (options[:what].to_sym != :last && options[:order].to_sym == :desc)
+
+        if block_given?
+          message_ids.each do |message_id|
+            fetchdata = imap.uid_fetch(message_id, ['RFC822'])[0]
+
+            yield Mail.new(fetchdata.attr['RFC822'])
+          end
+        else
+          emails = []
+          message_ids.each do |message_id|
+            fetchdata = imap.uid_fetch(message_id, ['RFC822'])[0]
+
+            emails << Mail.new(fetchdata.attr['RFC822'])
+          end
+          emails.size == 1 && options[:count] == 1 ? emails.first : emails
+        end
+      end
+    end
+
+    # Delete all emails from a IMAP mailbox
+    def delete_all(mailbox='INBOX')
+      mailbox ||= 'INBOX'
+
+      start do |imap|
+        imap.select(mailbox)
+        imap.uid_search(['ALL']).each do |message_id|
+          imap.uid_store(message_id, "+FLAGS", [Net::IMAP::DELETED])
+        end
+        imap.expunge
+      end
+    end
+
+    # Returns the connection object of the retrievable (IMAP or POP3)
+    def connection(&block)
+      raise ArgumentError.new('Mail::Retrievable#connection takes a block') unless block_given?
+
+      start do |imap|
+        yield imap
+      end
+    end
+
+    private
+
+      # Set default options
+      def validate_options(options)
+        options ||= {}
+        options[:mailbox] ||= 'INBOX'
+        options[:count]   ||= 10
+        options[:order]   ||= :asc
+        options[:what]    ||= :first
+        options[:keys]    ||= 'ALL'
+        options
+      end
+
+      # Start an IMAP session and ensures that it will be closed in any case.
+      def start(config=Mail::Configuration.instance, &block)
+        raise ArgumentError.new("Mail::Retrievable#imap_start takes a block") unless block_given?
+
+        imap = Net::IMAP.new(settings[:address], settings[:port], settings[:enable_ssl], nil, false)
+        imap.login(settings[:user_name], settings[:password])
+
+        yield imap
+      ensure
+        if defined?(imap) && imap && !imap.disconnected?
+          imap.disconnect
+        end
+      end
+
   end
-end
+end

data/lib/mail/network/retriever_methods/pop3.rb

@@ -89,12 +89,15 @@ module Mail
     #   order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
     #   count: number of emails to retrieve. The default value is 10. A value of 1 returns an
     #          instance of Message, not an array of Message instances.
+    #   delete_after_find: flag for whether to delete each retreived email after find. Default
+    #           is false. Use #find_and_delete if you would like this to default to true.
     #
     def find(options = {}, &block)
       options = validate_options(options)
       
       start do |pop3|
         mails = pop3.mails
+        pop3.reset # Clears all "deleted" marks. This prevents non-explicit/accidental deletions due to server settings.
         mails.sort! { |m1, m2| m2.number <=> m1.number } if options[:what] == :last
         mails = mails.first(options[:count]) if options[:count].is_a? Integer
         
@@ -105,12 +108,16 @@ module Mail
         
         if block_given?
           mails.each do |mail|
-            yield Mail.new(mail.pop)
+            new_message = Mail.new(mail.pop)
+            new_message.marked_for_delete = true if options[:delete_after_find]
+            yield new_message
+            mail.delete if options[:delete_after_find] && new_message.is_marked_for_delete? # Delete if still marked for delete
           end
         else
           emails = []
           mails.each do |mail|
             emails << Mail.new(mail.pop)
+            mail.delete if options[:delete_after_find]
           end
           emails.size == 1 && options[:count] == 1 ? emails.first : emails
         end
@@ -118,6 +125,23 @@ module Mail
       end
     end
     
+    # Find emails in a POP3 mailbox, and then deletes them. Without any options, the 
+    # five last received emails are returned.
+    #
+    # Possible options:
+    #   what:  last or first emails. The default is :first.
+    #   order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
+    #   count: number of emails to retrieve. The default value is 10. A value of 1 returns an
+    #          instance of Message, not an array of Message instances.
+    #   delete_after_find: flag for whether to delete each retreived email after find. Default
+    #           is true. Call #find if you would like this to default to false.
+    #
+    def find_and_delete(options = {}, &block)
+      options ||= {}
+      options[:delete_after_find] ||= true
+      find(options, &block)      
+    end 
+    
     # Delete all emails from a POP3 server   
     def delete_all
       start do |pop3|
@@ -127,6 +151,15 @@ module Mail
         end
       end
     end
+
+    # Returns the connection object of the retrievable (IMAP or POP3)
+    def connection(&block)
+      raise ArgumentError.new('Mail::Retrievable#connection takes a block') unless block_given?
+
+      start do |pop3|
+        yield pop3
+      end
+    end
     
   private
   
@@ -136,10 +169,13 @@ module Mail
       options[:count] ||= 10
       options[:order] ||= :asc
       options[:what]  ||= :first
+      options[:delete_after_find] ||= false
       options
     end
   
-    # Start a POP3 session and ensures that it will be closed in any case.
+    # Start a POP3 session and ensure that it will be closed in any case. Any messages
+    # marked for deletion via #find_and_delete or with the :delete_after_find option
+    # will be deleted when the session is closed.
     def start(config = Configuration.instance, &block)
       raise ArgumentError.new("Mail::Retrievable#pop3_start takes a block") unless block_given?
     
@@ -150,10 +186,9 @@ module Mail
       yield pop3
     ensure
       if defined?(pop3) && pop3 && pop3.started?
-        pop3.reset # This clears all "deleted" marks from messages.
         pop3.finish
       end
     end
-  
+
   end
-end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: mail
 version: !ruby/object:Gem::Version 
-  hash: 101
+  hash: 9
   prerelease: false
   segments: 
   - 2
   - 2
-  - 6
-  - 1
-  version: 2.2.6.1
+  - 7
+  version: 2.2.7
 platform: ruby
 authors: 
 - Mikel Lindsaar
@@ -16,11 +15,13 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-13 00:00:00 +10:00
+date: 2010-10-08 00:00:00 +11:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  version_requirements: &id001 !ruby/object:Gem::Requirement 
+  name: activesupport
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -31,12 +32,12 @@ dependencies:
         - 3
         - 6
         version: 2.3.6
-  requirement: *id001
   type: :runtime
-  name: activesupport
-  prerelease: false
+  version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  version_requirements: &id002 !ruby/object:Gem::Requirement 
+  name: mime-types
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -45,12 +46,12 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  requirement: *id002
   type: :runtime
-  name: mime-types
-  prerelease: false
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  version_requirements: &id003 !ruby/object:Gem::Requirement 
+  name: treetop
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -61,10 +62,8 @@ dependencies:
         - 4
         - 5
         version: 1.4.5
-  requirement: *id003
   type: :runtime
-  name: treetop
-  prerelease: false
+  version_requirements: *id003
 description: A really Ruby Mail handler.
 email: raasdnil@gmail.com
 executables: []