mail 1.3.0 → 1.3.1

data/CHANGELOG.rdoc

@@ -1,3 +1,22 @@
+== Sun Dec 13 01:06:17 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Version 1.3.1
+* Resolved Issue #18 - Wrong instance variable name
+* Resolved Issue #15 - Duplicate block call
+
+== Thu Dec 10 21:25:37 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Resolved Issue #13 - replacing From field results in from field becoming optional field.
+
+== Thu  3 Dec 2009 00:52:12 UTC Mikel Lindsaar <raasdnil@gmail.com>
+
+* Added POP upgrades from Nicolas Fouché
+* Added patch to handle multiple from lines in email from Luke Grimstrup
+
+== Mon Nov 23 23:34:22 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Resolved Issue #12 - Wrong comment in smtp.rb
+
 == Mon Nov 23 22:35:50 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
 
 * Changed the way attachments are added so that it does not break depending on the order

data/README.rdoc

@@ -229,18 +229,52 @@ or
  
  mail.deliver!
 
-=== Getting an email from a pop server:
+=== Getting emails from a pop server:
+
+The most recent email:
 
  require 'mail'
  
  Mail.defaults do
-   pop3 'mail.myhost.com.au', 110
-   user 'mikel'
-   pass 'mypass'
+   pop3 'mail.myhost.com.au', 110 do
+     user 'mikel'
+     pass 'mypass'
+   end
  end
  
- emails = Mail.get_all_mail
- 
+ emails = Mail.last do |email|
+   email.reply!("I'll be back on Monday, please be patient!") # +reply!+ still not implemented ^^
+ end
+
+The 3 oldest emails sorted by date in descendent order:
+
+ require 'mail'
+
+ Mail.defaults do
+   pop3 'mail.myhost.co.jp', 995 do
+     user 'mikel'
+     pass 'mypass'
+     enable_tls
+   end
+ end
+
+ emails = Mail.first(:count => 3, :order => :desc) do |email|
+   email.date
+ end
+
+Or even all emails:
+
+ require 'mail'
+
+ Mail.defaults do
+   pop3 'mail.myhost.com.au' do
+     user 'mikel'
+     pass 'mypass'
+   end
+ end
+
+ emails = Mail.all
+
  emails.length #=> 12
 
 === Reading an Email

data/Rakefile

@@ -12,7 +12,7 @@ require 'bundler'
 
 spec = Gem::Specification.new do |s|
   s.name        = "mail"
-  s.version     = "1.3.0"
+  s.version     = "1.3.1"
   s.author      = "Mike Lindsaar"
   s.email       = "raasdnil@gmail.com"
   s.homepage    = "http://github.com/mikel/mail"

data/lib/mail/body.rb

@@ -54,10 +54,39 @@ module Mail
       if other.class == String
         self.decoded == other
       else
-        self.eql?(other)
+        super
       end
     end
     
+    # Accepts a string and performs a regular expression against the decoded text
+    # 
+    # Examples:
+    # 
+    #   body = Mail::Body.new('The body')
+    #   body =~ /The/ #=> 0
+    #   
+    #   body = Mail::Body.new("VGhlIGJvZHk=\n")
+    #   body.encoding = 'base64'
+    #   body =~ /The/ #=> 0
+    def =~(regexp)
+      self.decoded =~ regexp
+    end
+    
+    # Accepts a string and performs a regular expression against the decoded text
+    # 
+    # Examples:
+    # 
+    #   body = Mail::Body.new('The body')
+    #   body.match(/The/) #=> #<MatchData "The">
+    #   
+    #   body = Mail::Body.new("VGhlIGJvZHk=\n")
+    #   body.encoding = 'base64'
+    #   body.match(/The/) #=> #<MatchData "The">
+    def match(regexp)
+      self.decoded.match(regexp)
+    end
+    
+    
     # Returns the raw source that the body was initialized with, without
     # any tampering
     def raw_source

data/lib/mail/configuration.rb

@@ -67,7 +67,9 @@ module Mail
     #  end
     # 
     #  Mail.defaults do
-    #    pop3 '127.0.0.1', 110
+    #    pop3 '127.0.0.1', 995 do
+    #      enable_tls
+    #    end
     #  end
     def pop3(*args, &block)
       if args.size > 0
@@ -104,9 +106,6 @@ module Mail
           port host_array[1]
         end
       end
-      if block_given?
-        klass.instance.settings(&block)
-      end
       klass.instance.settings(&block)
     end
 

data/lib/mail/field.rb

@@ -149,7 +149,7 @@ module Mail
     def new_field(name, value)
       # Could do this with constantize and make it "as DRY as", but a simple case 
       # statement is, well, simpler... 
-      case name
+      case name.to_s
       when /^to$/i
         ToField.new(name, value)
       when /^cc$/i

data/lib/mail/fields/bcc_field.rb

@@ -21,7 +21,9 @@
 #  mail['bcc'] #=> '#<Mail::Field:0x180e5e8 @field=#<Mail::BccField:0x180e1c4
 #  mail['Bcc'] #=> '#<Mail::Field:0x180e5e8 @field=#<Mail::BccField:0x180e1c4
 # 
-#  mail.bcc.to_s  #=> 'Mikel Lindsaar <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
+#  mail.bcc.to_s      #=> ''      # Bcc field does not get output into an email
+#  mail.bcc.encoded   #=> ''      # Bcc field does not get output into an email
+#  mail.bcc.decoded   #=> 'Mikel Lindsaar <mikel@test.lindsaar.net>, ada@test.lindsaar.net'
 #  mail.bcc.addresses #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']
 #  mail.bcc.formatted #=> ['Mikel Lindsaar <mikel@test.lindsaar.net>', 'ada@test.lindsaar.net']
 # 

data/lib/mail/mail.rb

@@ -123,16 +123,35 @@ module Mail
     mail
   end
 
-  # Returns all the messages on the server using the retriever method set up
-  # in Mail.defaults
-  def Mail.get_all_mail(&block)
-    if block_given?
-      Retrievable.get_messages.each do |message|
-        yield message
-      end
-    else
-      Retrievable.get_messages
-    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)
+  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)
+  end
+
+  # 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)
   end
 
   def Mail.read(filename)

data/lib/mail/message.rb

@@ -808,7 +808,7 @@ module Mail
     end
     
     def set_envelope_header
-      if match_data = raw_source.to_s.match(/From\s(#{TEXT}+)#{CRLF}(.*)/m)
+      if match_data = raw_source.to_s.match(/^From\s(#{TEXT}+)#{CRLF}(.*)/m)
         set_envelope(match_data[1])
         self.raw_source = match_data[2]
       end
@@ -920,10 +920,5 @@ module Mail
       filename
     end
 
-    # Only POP3 is supported for now
-    def Message.get_all_mail(&block)
-      self.pop3_get_all_mail(&block)
-    end
-
   end
 end

data/lib/mail/network/delivery_methods/smtp.rb

@@ -32,7 +32,7 @@ module Mail
     # The helo domain used at the begining of an SMTP conversation,
     # default is 'localhost.localdomain'
     def helo(value = nil)
-      value ? @help = value : @helo ||= 'localhost.localdomain'
+      value ? @helo = value : @helo ||= 'localhost.localdomain'
     end
     
     # Turn on TLS
@@ -40,7 +40,7 @@ module Mail
       @tls = true
     end
     
-    # Turn on TLS
+    # Turn off TLS
     def disable_tls
       @tls = false
     end

data/lib/mail/network/retrievable.rb

@@ -8,10 +8,12 @@
 module Mail
   module Retrievable
 
-    def self.get_messages
-      Mail.defaults.retriever_method.get_messages
+    module_function
+
+    def method_missing(name, *args, &block)
+      Mail.defaults.retriever_method.__send__(name, *args, &block)
     end
-  
+
   end
-  
+
 end

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

@@ -1,3 +1,12 @@
+# encoding: utf-8
+
+# 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.
+#
+# This module uses the defaults set in Configuration to retrieve POP3 settings.
+# 
 module Mail
   class POP3
     include Singleton
@@ -46,40 +55,107 @@ module Mail
       @tls || false
     end
     
-    # Get all emails via POP3.
-    # TODO :limit option
-    # TODO :order option
-    def POP3.get_messages(&block)
-      config = Mail.defaults
-      if config.pop3.host.blank? || config.pop3.port.blank?
-        raise ArgumentError.new('Please call +Mail.defaults+ to set the POP3 configuration')
-      end
+    # 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 POP3.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 POP3.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 POP3.all(options = {}, &block)
+      options ||= {}
+      options[:count] = :all
+      find(options, &block)
+    end
+    
+    # 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.
+    #
+    def POP3.find(options = {}, &block)
+      validate_configuration
+      options = validate_options(options)
       
       start do |pop3|
+        mails = pop3.mails
+        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?
-          pop3.each_mail do |pop_mail|
-            yield Mail.new(pop_mail.pop)
+          mails.each do |mail|
+            yield Mail.new(mail.pop)
           end
         else
           emails = []
-          pop3.each_mail do |pop_mail|
-            emails << Mail.new(pop_mail.pop)
+          mails.each do |mail|
+            emails << Mail.new(mail.pop)
           end
-          emails
+          emails.size == 1 && options[:count] == 1 ? emails.first : emails
         end
+        
       end
-      
     end
     
-    private
+  private
     
+    # Ensure that the POP3 configuration is set
+    def POP3.validate_configuration
+      config = Mail::Configuration.instance
+      if config.pop3.host.blank? || config.pop3.port.blank?
+        raise ArgumentError.new('Please call +Mail.defaults+ to set the POP3 configuration')
+      end
+    end
+  
+    # Set default options
+    def POP3.validate_options(options)
+      options ||= {}
+      options[:count] ||= 10
+      options[:order] ||= :asc
+      options[:what] ||= :first
+      options
+    end
+  
+    # Start a POP3 session and ensures that it will be closed in any case.
     def POP3.start(config = Mail::Configuration.instance, &block)
       raise ArgumentError.new("Mail::Retrievable#pop3_start takes a block") unless block_given?
-      
+    
       pop3 = Net::POP3.new(config.pop3.host, config.pop3.port, isapop = false)
       pop3.enable_ssl(verify = OpenSSL::SSL::VERIFY_NONE) if config.pop3.tls?
       pop3.start(config.pop3.user, config.pop3.pass)
-      
+    
       yield pop3
     ensure
       if defined?(pop3) && pop3 && pop3.started?

data/lib/mail/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mail
 version: !ruby/object:Gem::Version 
-  version: 1.3.0
+  version: 1.3.1
 platform: ruby
 authors: 
 - Mike Lindsaar
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-24 00:00:00 +11:00
+date: 2009-12-13 00:00:00 +11:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency