mail-portertech 2.6.2.edge

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

@@ -0,0 +1,63 @@
+# encoding: utf-8
+
+module Mail
+
+  class Retriever
+
+    # Get the oldest received email(s)
+    #
+    # Possible options:
+    #   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.
+    #
+    def first(options = {}, &block)
+      options ||= {}
+      options[:what] = :first
+      options[:count] ||= 1
+      find(options, &block)
+    end
+    
+    # Get the most recent received email(s)
+    #
+    # Possible options:
+    #   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.
+    #
+    def last(options = {}, &block)
+      options ||= {}
+      options[:what] = :last
+      options[:count] ||= 1
+      find(options, &block)
+    end
+    
+    # Get all emails.
+    #
+    # Possible options:
+    #   order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
+    #
+    def all(options = {}, &block)
+      options ||= {}
+      options[:count] = :all
+      find(options, &block)
+    end
+
+    # Find emails in the 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 
+
+  end
+
+end

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

@@ -0,0 +1,173 @@
+# encoding: utf-8
+
+module Mail
+  # The IMAP retriever allows to get the last, first or all emails from a IMAP 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 last 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.
+  #   keys:    are passed as criteria to the SEARCH command.  They can either be a string holding the entire search string, 
+  #            or a single-dimension array of search keywords and arguments.  Refer to  [IMAP] section 6.4.4 for a full list
+  #            The default is 'ALL'
+  #
+  #   Mail.find(:what => :first, :count => 10, :order => :asc, :keys=>'ALL')
+  #   #=> Returns the first 10 emails in ascending order
+  #
+  class IMAP < Retriever
+    require 'net/imap' unless defined?(Net::IMAP)
+    
+    def initialize(values)
+      self.settings = { :address              => "localhost",
+                        :port                 => 143,
+                        :user_name            => nil,
+                        :password             => nil,
+                        :authentication       => nil,
+                        :enable_ssl           => false }.merge!(values)
+    end
+
+    attr_accessor :settings
+
+    # Find emails in a IMAP 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.
+    #   read_only: will ensure that no writes are made to the inbox during the session.  Specifically, if this is
+    #              set to true, the code will use the EXAMINE command to retrieve the mail.  If set to false, which
+    #              is the default, a SELECT command will be used to retrieve the mail
+    #              This is helpful when you don't want your messages to be set to read automatically. Default is false.
+    #   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.
+    #   keys:   are passed as criteria to the SEARCH command.  They can either be a string holding the entire search string, 
+    #           or a single-dimension array of search keywords and arguments.  Refer to  [IMAP] section 6.4.4 for a full list
+    #           The default is 'ALL'
+    #
+    def find(options={}, &block)
+      options = validate_options(options)
+
+      start do |imap|
+        options[:read_only] ? imap.examine(options[:mailbox]) : imap.select(options[:mailbox])
+
+        uids = imap.uid_search(options[:keys])
+        uids.reverse! if options[:what].to_sym == :last
+        uids = uids.first(options[:count]) if options[:count].is_a?(Integer)
+        uids.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?
+          uids.each do |uid|
+            uid = options[:uid].to_i unless options[:uid].nil?
+            fetchdata = imap.uid_fetch(uid, ['RFC822'])[0]
+            new_message = Mail.new(fetchdata.attr['RFC822'])
+            new_message.mark_for_delete = true if options[:delete_after_find]
+            if block.arity == 3
+              yield new_message, imap, uid
+            else
+              yield new_message
+            end
+            imap.uid_store(uid, "+FLAGS", [Net::IMAP::DELETED]) if options[:delete_after_find] && new_message.is_marked_for_delete?
+            break unless options[:uid].nil?
+          end
+          imap.expunge if options[:delete_after_find]
+        else
+          emails = []
+          uids.each do |uid|
+            uid = options[:uid].to_i unless options[:uid].nil?
+            fetchdata = imap.uid_fetch(uid, ['RFC822'])[0]
+            emails << Mail.new(fetchdata.attr['RFC822'])
+            imap.uid_store(uid, "+FLAGS", [Net::IMAP::DELETED]) if options[:delete_after_find]
+            break unless options[:uid].nil?
+          end
+          imap.expunge if options[:delete_after_find]
+          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'
+      mailbox = Net::IMAP.encode_utf7(mailbox)
+
+      start do |imap|
+        imap.uid_search(['ALL']).each do |uid|
+          imap.uid_store(uid, "+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[:uid]     ||= nil
+        options[:delete_after_find] ||= false
+        options[:mailbox] = Net::IMAP.encode_utf7(options[:mailbox])
+        options[:read_only] ||= false
+
+        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)
+        if settings[:authentication].nil?
+          imap.login(settings[:user_name], settings[:password])
+        else
+          # Note that Net::IMAP#authenticate('LOGIN', ...) is not equal with Net::IMAP#login(...)!
+          # (see also http://www.ensta.fr/~diam/ruby/online/ruby-doc-stdlib/libdoc/net/imap/rdoc/classes/Net/IMAP.html#M000718)
+          imap.authenticate(settings[:authentication], settings[:user_name], settings[:password])
+        end
+
+        yield imap
+      ensure
+        if defined?(imap) && imap && !imap.disconnected?
+          imap.disconnect
+        end
+      end
+
+  end
+end

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

@@ -0,0 +1,140 @@
+# encoding: utf-8
+
+module Mail
+  # The Pop3 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 :pop3, { :address             => "pop.gmail.com",
+  #                               :port                => 995,
+  #                               :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 last unread email
+  # 
+  # You can also pass options into Mail.find to locate an email in your pop mailbox
+  # with the following 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.
+  # 
+  #   Mail.find(:what => :first, :count => 10, :order => :asc)
+  #   #=> Returns the first 10 emails in ascending order
+  # 
+  class POP3 < Retriever
+    require 'net/pop' unless defined?(Net::POP)
+
+    def initialize(values)
+      self.settings = { :address              => "localhost",
+                        :port                 => 110,
+                        :user_name            => nil,
+                        :password             => nil,
+                        :authentication       => nil,
+                        :enable_ssl           => false }.merge!(values)
+    end
+    
+    attr_accessor :settings
+    
+    # Find emails in a POP3 mailbox. Without any options, the 5 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 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
+        
+        if options[:what].to_sym == :last && options[:order].to_sym == :desc ||
+           options[:what].to_sym == :first && options[:order].to_sym == :asc ||
+          mails.reverse!
+        end
+        
+        if block_given?
+          mails.each do |mail|
+            new_message = Mail.new(mail.pop)
+            new_message.mark_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
+        
+      end
+    end
+    
+    # Delete all emails from a POP3 server   
+    def delete_all
+      start do |pop3|
+        unless pop3.mails.empty?
+          pop3.delete_all
+          pop3.finish
+        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
+  
+    # Set default options
+    def validate_options(options)
+      options ||= {}
+      options[:count] ||= 10
+      options[:order] ||= :asc
+      options[:what]  ||= :first
+      options[:delete_after_find] ||= false
+      options
+    end
+  
+    # 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?
+    
+      pop3 = Net::POP3.new(settings[:address], settings[:port], false)
+      pop3.enable_ssl(OpenSSL::SSL::VERIFY_NONE) if settings[:enable_ssl]
+      pop3.start(settings[:user_name], settings[:password])
+    
+      yield pop3
+    ensure
+      if defined?(pop3) && pop3 && pop3.started?
+        pop3.finish
+      end
+    end
+
+  end
+end

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

@@ -0,0 +1,43 @@
+# encoding: utf-8
+
+module Mail
+
+  class TestRetriever < Retriever
+
+    def self.emails
+      @@emails
+    end
+
+    def self.emails=(val)
+      @@emails = val
+    end
+
+    def initialize(values)
+      @@emails = []
+    end
+
+    def find(options = {}, &block)
+      options[:count] ||= :all
+      options[:order] ||= :asc
+      options[:what] ||= :first
+      emails_index = (0...@@emails.size).to_a
+      emails_index.reverse! if options[:what] == :last
+      emails_index = case count = options[:count]
+        when :all then emails_index
+        when Fixnum then emails_index[0, count]
+        else
+          raise 'Invalid count option value: ' + count.inspect
+      end
+      if options[:what] == :last && options[:order] == :asc || options[:what] == :first && options[:order] == :desc
+        emails_index.reverse!
+      end
+      emails_index.each { |idx| @@emails[idx].mark_for_delete = true } if options[:delete_after_find]
+      emails = emails_index.map { |idx| @@emails[idx] }
+      emails.each { |email| yield email } if block_given?
+      @@emails.reject!(&:is_marked_for_delete?) if options[:delete_after_find]
+      emails.size == 1 && options[:count] == 1 ? emails.first : emails
+    end
+
+  end
+
+end

data/lib/mail/parsers.rb

@@ -0,0 +1,26 @@
+module Mail
+  module Parsers
+
+    # Low-level ragel based parsers
+    require 'mail/parsers/ragel'
+
+    AddressListStruct = Struct.new(:addresses, :group_names, :error)
+    AddressStruct = Struct.new(:raw, :domain, :comments, :local,
+                             :obs_domain_list, :display_name, :group, :error)
+    ContentDispositionStruct = Struct.new(:disposition_type, :parameters, :error)
+    ContentLocationStruct = Struct.new(:location, :error)
+    ContentTransferEncodingStruct = Struct.new(:encoding, :error)
+    ContentTypeStruct = Struct.new(:main_type, :sub_type, :parameters, :error)
+    DateTimeStruct = Struct.new(:date_string, :time_string, :error)
+    EnvelopeFromStruct = Struct.new(:address, :ctime_date, :error)
+    MessageIdsStruct = Struct.new(:message_ids, :error)
+    MimeVersionStruct = Struct.new(:major, :minor, :error)
+    PhraseListsStruct = Struct.new(:phrases, :error)
+    ReceivedStruct = Struct.new(:date, :time, :info, :error)
+
+    require 'mail/parsers/ragel/parser_info'
+    Ragel::FIELD_PARSERS.each do |field_parser|
+      require "mail/parsers/#{field_parser}_parser"
+    end
+  end
+end