tmail 1.2.1 → 1.2.2

data/CHANGES

@@ -1,4 +1,13 @@
-= TMail 1.2.1 / 2008-01-11
+=== 1.2.2 / 2008-03-07
+
+* Fixed install bug with gem pacakge (1.2.1 was not compiling on gem install)
+* A _LOT_ more documentation...!
+* More documentation - (Mikel)
+* Applied Ruby 1.9 patches to the library - All tests passing now - (Mikel)
+* Closed #17719 - Fixed UNIXMbox code - readonly was not working and raising an exception.  Now works.
+* Closed #18038 - Multiple froms not being parsed correctly, added a test case to cover this and show the correct handling - (Mikel)
+
+=== 1.2.1 / 2008-01-11
 
 * More documentation (Mikel)
 * Added 15 test cases from the Rails ActionMailer to TMail
@@ -9,8 +18,44 @@
 * Closed #16899 - HeaderField.new_from_port and added test cases to cover this code (Maarten O.)
 * Closed #16900 - UNIXMbox.fromaddr missing port param and does not return Envelope Sender (Maarten O.)
 
-= TMail 1.2.0 / 2007-11-29
+=== 1.2.0 / 2007-11-29
+
+* 5 major enhancements:
+  * Extensive documentation work. (mikel)
+  * Renamed scanner_c.c to mailscanner.c. (trans)
+  * Removed base64 c extension. It's speed benefit was negligable (only 0.2 sec over 10000 sizable encode/decode runs) (trans)
+  * Closed 15445 - TMail::Mail#create_forward now returns a new Mail object that has the original mail as an encoded 7 bit multipart attachment.  Also moved create_forward and create_reply from tmail/net into tmail/interface as it makes more sense to have it there. (mikel)
+  * Closed 15643 - TMail::Mail#reply_addresses was returning an empty array if reply_to was set to nil (ie, the header field existed but was empty) instead of returning the from address or default. (mikel)
+  * Closed 16025 - TMail scanner.rb would not parse ATOM chars correctly making it fail tests where the C version passed them.  Fixed this by updating the Scanner.rb version to be in step with the C version (there was an extra @ symbol in the ATOM CHARS definition that was not in the C version.) (mikel)
+  * Fixed scanner.rb so that it would pass the same tests that the C version does - had a sundry @ symbol inside of the ATOM CHARS
+* 3 minor enhancements:
+  * Renamed scanner_c.c to tmailscanner.c (trans)
+  * Changed TMail::Mail#sender to have a default "default" value of nil to be in alignment with all the other interface methods (mikel)
+  * Made base64_decode and base64_encode into ! versions as they are destructive on the mail body (encodes the body to base64 or decodes it), made aliases for base64_decode and base64_encode to point back to the bang versions.  Doing this with a view to change base64_encode to a non destructive version (returns the encoded body) in future versions. (mikel)
+
+=== 1.1.1 / 2007-11-05
+
+* 3 major enhancement:
+  * Created unified package, for installation in any platform.
+  * Added require_arch.rb to facilitate multi-platform support.
+  * If compilation fails, set NORUBYEXT="true" and reinstall.
+* 3 minor enhancement:
+  * Fixed line wrapping of long header fields so that they wrap at the correct whitespace points.
+  * Fixed bug where re-assigning the mail.body to existing mail object that already had a parsed body would not re-parse the body.
+  * Started documenting the source code... lots more to do.
+
+=== 1.1.0 / 2007-10-28
+
+* 1 minor enhancements:
+  * Changed the quoting of paramaters in the header fields to wrap double quotes around fields that are needed to be quoted.
+  * Removed keeping double quotes around a filename that does not need double quotes per RFC 1521
+  * More clean up and getting tests passing.  Now standing at 2 failures out of 3366 assertions.  One is the incorrect handling of "@"@test.com (returns @@test.com) and the other is a japanese encoding issue.
+
+=== 1.0.0 / 2007-10-28
+
+* 1 major enhancement:
+  * TMail is now released as a GEM!
+* 2 minor enhancements:
+  * Fixed bug 15077 - TMail now recognizes attachments as soon as they are added to the body.
+  * Refactored handling of quotations in header fields - now cleaner
 
-* Extensive documentation work. (mikel)
-* Renamed scanner_c.c to mailscanner.c.
-* Removed base64 c extension. It's speed benefit was negligable (only 0.2 sec over 10000 sizable encode/decode runs).

data/MANIFEST

@@ -0,0 +1,188 @@
+Rakefile
+doc
+test
+test/temp_test_one.rb
+test/kcode.rb
+test/test_utils.rb
+test/test_attachments.rb
+test/test_encode.rb
+test/test_mbox.rb
+test/test_helper.rb
+test/test_header.rb
+test/test_base64.rb
+test/test_address.rb
+test/fixtures
+test/fixtures/raw_email8
+test/fixtures/raw_email_simple
+test/fixtures/raw_email13
+test/fixtures/raw_email5
+test/fixtures/mailbox_without_any_from_or_sender
+test/fixtures/raw_email4
+test/fixtures/mailbox
+test/fixtures/raw_email_with_nested_attachment
+test/fixtures/raw_email
+test/fixtures/raw_email_quoted_with_0d0a
+test/fixtures/raw_base64_decoded_string
+test/fixtures/mailbox_without_return_path
+test/fixtures/raw_email3
+test/fixtures/raw_email_reply
+test/fixtures/raw_email_with_bad_date
+test/fixtures/mailbox_without_from
+test/fixtures/raw_email_multiple_from
+test/fixtures/raw_email10
+test/fixtures/raw_email_with_quoted_illegal_boundary
+test/fixtures/raw_base64_email
+test/fixtures/raw_email_with_partially_quoted_subject
+test/fixtures/raw_email9
+test/fixtures/raw_email2
+test/fixtures/raw_email11
+test/fixtures/raw_email_with_multipart_mixed_quoted_boundary
+test/fixtures/raw_email_with_illegal_boundary
+test/fixtures/raw_email6
+test/fixtures/raw_email7
+test/fixtures/raw_base64_encoded_string
+test/fixtures/raw_email12
+test/test_mail.rb
+test/test_scanner.rb
+test/test_port.rb
+test/extctrl.rb
+test/test_quote.rb
+NOTES
+CHANGES
+LICENSE
+README
+ext
+ext/tmailscanner
+ext/tmailscanner/tmail
+ext/tmailscanner/tmail/depend
+ext/tmailscanner/tmail/MANIFEST
+ext/tmailscanner/tmail/extconf.rb
+ext/tmailscanner/tmail/tmailscanner.c
+ext/Makefile
+setup.rb
+meta
+meta/MANIFEST
+meta/project.yaml
+meta/unixname
+meta/VERSION
+site
+site/img
+site/img/tfire.jpg
+site/img/stamp.jpg
+site/img/tmail.png
+site/img/mailman.gif
+site/img/envelope.jpg
+site/img/stamp-sm.jpg
+site/img/stampborder.jpg
+site/quickstart
+site/quickstart/usage.html
+site/quickstart/index.html
+site/quickstart/quickstart.html
+site/js
+site/js/jquery.js
+site/outdated
+site/outdated/DEPENDS
+site/outdated/Incompatibilities
+site/outdated/Incompatibilities.ja
+site/outdated/README.ja
+site/outdated/NEWS
+site/outdated/doc.ja
+site/outdated/doc.ja/config.html
+site/outdated/doc.ja/usage.html
+site/outdated/doc.ja/mailbox.html
+site/outdated/doc.ja/mail.html
+site/outdated/doc.ja/index.html
+site/outdated/doc.ja/basics.html
+site/outdated/doc.ja/tmail.html
+site/outdated/doc.ja/address.html
+site/outdated/doc.ja/details.html
+site/outdated/doc.ja/port.html
+site/outdated/rdd
+site/outdated/rdd/mail.rrd.m
+site/outdated/rdd/port.rrd.m
+site/outdated/rdd/config.rrd.m
+site/outdated/rdd/index.rhtml.m
+site/outdated/rdd/mailbox.rrd.m
+site/outdated/rdd/usage.rd.m
+site/outdated/rdd/basics.rd.m
+site/outdated/rdd/details.rd.m
+site/outdated/rdd/tmail.rrd.m
+site/outdated/rdd/address.rrd.m
+site/outdated/BUGS
+site/index.html
+site/contributing
+site/contributing/index.html
+site/reference
+site/reference/config.html
+site/reference/mailbox.html
+site/reference/mail.html
+site/reference/index.html
+site/reference/tmail.html
+site/reference/address.html
+site/reference/port.html
+site/css
+site/css/layout.css
+site/css/style.css
+site/css/clean.css
+site/download
+site/download/index.html
+site/log
+site/log/changelog.xml
+site/log/Changelog.xsl
+lib
+lib/tmail.rb
+lib/tmail
+lib/tmail/base64.rb
+lib/tmail/loader.rb
+lib/tmail/main.rb
+lib/tmail/scanner.rb
+lib/tmail/require_arch.rb
+lib/tmail/config.rb
+lib/tmail/port.rb
+lib/tmail/encode.rb
+lib/tmail/scanner_r.rb
+lib/tmail/parser.rb
+lib/tmail/version.rb
+lib/tmail/obsolete.rb
+lib/tmail/parser.y
+lib/tmail/quoting.rb
+lib/tmail/mbox.rb
+lib/tmail/Makefile
+lib/tmail/stringio.rb
+lib/tmail/utils.rb
+lib/tmail/interface.rb
+lib/tmail/attachments.rb
+lib/tmail/index.rb
+lib/tmail/mail.rb
+lib/tmail/net.rb
+lib/tmail/address.rb
+lib/tmail/header.rb
+lib/tmail/compat.rb
+lib/tmail/mailbox.rb
+lib/tmail/core_extensions.rb
+sample
+sample/extract-attachements.rb
+sample/parse-test.rb
+sample/bench_base64.rb
+sample/multipart.rb
+sample/parse-bench.rb
+sample/data
+sample/data/test
+sample/data/normal
+sample/data/simple
+sample/data/multipart
+sample/data/sendtest
+sample/from-check.rb
+sample/sendmail.rb
+work
+work/script
+work/script/test
+work/script/rdoc
+work/script/setup
+work/script/make
+log
+log/BugTrackingLog.txt
+log/Changelog.txt
+log/Changelog-0.txt
+log/Todo.txt
+log/Testlog.txt

data/NOTES

@@ -1,4 +1,4 @@
-[ANN] TMail 1.2.1 - 11 Jan 2008
+[ANN] TMail 1.2.2 - 11 Jan 2008
 
 TMail is The Mail Handling Library for Ruby!
 

data/README

@@ -2,7 +2,7 @@
 
     http://tmail.rubyforge.org/
 
-    Mikel Lindsaar   senior developer
+    Mikel Lindsaar   maintainer
     Trans            assitant developer
     Minero Aoki      original developer   
 
@@ -14,11 +14,13 @@ TMail is used by the Ruby on Rails web framework as the Email abstraction layer
 
 The goal of the TMail handling library is to be able to parse and handle raw Email sources and produce RFC compliant Emails as a result.  If you find something that TMail does that violates an RFC, we want to know and we'll get it fixed fast.
 
-== FEATURES/PROBLEMS:
+== DOCUMENTATION:
+
+The place you will want to look first is the TMail::Mail class.  This has the vast majority of methods you will be using to talk to your TMail object.
 
-TMail is about 95% or so RFC compliant on the handling of emails.
+== FEATURES/PROBLEMS:
 
-There is a few edge case problems (such as if the person has an unquoted @ symbol in the To: field) that are not handled yet.  But we are working on these.
+TMail is fairly RFC compliant on the handling of emails.
 
 There are also some problems in the header handling, but for 99.9% of email, you will be fine.  Usually, the problems revolve around parsing incomming emails and making sense of them.
 
@@ -123,6 +125,10 @@ If you now puts the email again, it will not be included:
 
 You can just call to_s on any email to have it serialized out as a single string with the right number of line breaks and encodings.
 
+== CONTRIBUTING:
+
+You can visit the {Contributing to TMail}[link:http://tmail.rubyforge.org/contributing/] to find out how to contribute to TMail, developers are welcome and wanted!
+
 == REQUIREMENTS:
 
 * C compiler if you want the Ruby extension for Scanner

data/Rakefile

@@ -1,11 +1,2 @@
-require 'rubygems'
-require 'rake'
-require 'rake/testtask'
+require File.join(File.dirname(__FILE__), "setup.rb")
 
-# Run the unit tests
-Rake::TestTask.new { |t|
-  t.libs << "test"
-  t.pattern = 'test/test_*.rb'
-  t.verbose = true
-  t.warning = false
-}

data/lib/tmail.rb

@@ -2,3 +2,4 @@ require 'tmail/version'
 require 'tmail/mail'
 require 'tmail/mailbox'
 require 'tmail/core_extensions'
+require 'tmail/net'

data/lib/tmail/Makefile

@@ -1,4 +1,3 @@
-#
 # lib/tmail/Makefile
 #
 

data/lib/tmail/address.rb

@@ -3,7 +3,6 @@
 = Address handling class
 
 =end
-#
 #--
 # Copyright (c) 1998-2003 Minero Aoki <aamine@loveruby.net>
 #
@@ -36,18 +35,105 @@ require 'tmail/parser'
 
 module TMail
 
+  # = Class Address
+  # 
+  # Provides a complete handling library for email addresses. Can parse a string of an
+  # address directly or take in preformatted addresses themseleves.  Allows you to add
+  # and remove phrases from the front of the address and provides a compare function for
+  # email addresses.
+  # 
+  # == Parsing and Handling a Valid Address:
+  # 
+  # Just pass the email address in as a string to Address.parse:
+  # 
+  #  email = TMail::Address.parse('Mikel Lindsaar <mikel@lindsaar.net>)
+  #  #=> #<TMail::Address mikel@lindsaar.net>
+  #  email.address
+  #  #=> "mikel@lindsaar.net"
+  #  email.local
+  #  #=> "mikel"
+  #  email.domain
+  #  #=> "lindsaar.net"
+  #  email.name             # Aliased as phrase as well
+  #  #=> "Mikel Lindsaar"
+  # 
+  # == Detecting an Invalid Address
+  # 
+  # If you want to check the syntactical validity of an email address, just pass it to
+  # Address.parse and catch any SyntaxError:
+  # 
+  #  begin
+  #    TMail::Mail.parse("mikel   2@@@@@ me .com")
+  #  rescue TMail::SyntaxError
+  #    puts("Invalid Email Address Detected")
+  #  else
+  #    puts("Address is valid")
+  #  end
+  #  #=> "Invalid Email Address Detected"
   class Address
 
-    include TextUtils
-
+    include TextUtils #:nodoc:
+    
+    # Sometimes you need to parse an address, TMail can do it for you and provide you with
+    # a fairly robust method of detecting a valid address.
+    # 
+    # Takes in a string, returns a TMail::Address object.
+    # 
+    # Raises a TMail::SyntaxError on invalid email format
     def Address.parse( str )
-      Parser.parse :ADDRESS, str
+      Parser.parse :ADDRESS, special_quote_address(str)
+    end
+    
+    def Address.special_quote_address(str) #:nodoc:
+      # Takes a string which is an address and adds quotation marks to special
+      # edge case methods that the RACC parser can not handle.
+      #
+      # Right now just handles two edge cases:
+      #
+      # Full stop as the last character of the display name:
+      #   Mikel L. <mikel@me.com>
+      # Returns:
+      #   "Mikel L." <mikel@me.com>
+      #
+      # Unquoted @ symbol in the display name:
+      #   mikel@me.com <mikel@me.com>
+      # Returns:
+      #   "mikel@me.com" <mikel@me.com>
+      #
+      # Any other address not matching these patterns just gets returned as is. 
+      case
+      # This handles the missing "" in an older version of Apple Mail.app
+      # around the display name when the display name contains a '@'
+      # like 'mikel@me.com <mikel@me.com>'
+      # Just quotes it to: '"mikel@me.com" <mikel@me.com>'
+      when str =~ /\A([^"].+@.+[^"])\s(<.*?>)\Z/
+        return "\"#{$1}\" #{$2}"
+      # This handles cases where 'Mikel A. <mikel@me.com>' which is a trailing
+      # full stop before the address section.  Just quotes it to
+      # '"Mikel A. <mikel@me.com>"
+      when str =~ /\A(.*?\.)\s(<.*?>)\Z/
+        return "\"#{$1}\" #{$2}"
+      else
+        str
+      end
     end
 
-    def address_group?
+    def address_group? #:nodoc:
       false
     end
 
+    # Address.new(local, domain)
+    # 
+    # Accepts:
+    # 
+    # * local - Left of the at symbol
+    # 
+    # * domain - Array of the domain split at the periods.
+    # 
+    # For example:
+    # 
+    #  Address.new("mikel", ["lindsaar", "net"])
+    #  #=> "#<TMail::Address mikel@lindsaar.net>"
     def initialize( local, domain )
       if domain
         domain.each do |s|
@@ -58,8 +144,8 @@ module TMail
       # This is to catch an unquoted "@" symbol in the local part of the
       # address.  Handles addresses like <"@"@me.com> and makes sure they
       # stay like <"@"@me.com> (previously were becomming <@@me.com>)
-      if local.to_s == '@' || local.to_s =~ /\A[^"].*?@.*?[^"]\Z/ 
-        @local = "\"#{local.to_s}\""
+      if local && (local.join == '@' || local.join =~ /\A[^"].*?@.*?[^"]\Z/)
+        @local = "\"#{local.join}\""
       else
         @local = local
       end
@@ -69,33 +155,97 @@ module TMail
       @routes = []
     end
 
-    attr_reader :name
+    # Provides the name or 'phrase' of the email address.
+    # 
+    # For Example:
+    # 
+    #  email = TMail::Address.parse("Mikel Lindsaar <mikel@lindsaar.net>")
+    #  email.name
+    #  #=> "Mikel Lindsaar"
+    def name
+      @name
+    end
 
+    # Setter method for the name or phrase of the email
+    # 
+    # For Example:
+    # 
+    #  email = TMail::Address.parse("mikel@lindsaar.net")
+    #  email.name
+    #  #=> nil
+    #  email.name = "Mikel Lindsaar"
+    #  email.to_s
+    #  #=> "Mikel Lindsaar <mikel@me.com>"
     def name=( str )
       @name = str
       @name = nil if str and str.empty?
     end
 
+    #:stopdoc:
     alias phrase  name
     alias phrase= name=
-
-    attr_reader :routes
-
-    def inspect
+    #:startdoc:
+    
+    # This is still here from RFC 822, and is now obsolete per RFC2822 Section 4.
+    # 
+    # "When interpreting addresses, the route portion SHOULD be ignored."
+    # 
+    # It is still here, so you can access it.
+    # 
+    # Routes return the route portion at the front of the email address, if any.
+    # 
+    # For Example:
+    #  email = TMail::Address.parse( "<@sa,@another:Mikel@me.com>")
+    #  => #<TMail::Address Mikel@me.com>
+    #  email.to_s
+    #  => "<@sa,@another:Mikel@me.com>"
+    #  email.routes
+    #  => ["sa", "another"]
+    def routes
+      @routes
+    end
+    
+    def inspect #:nodoc:
       "#<#{self.class} #{address()}>"
     end
 
+    # Returns the local part of the email address
+    # 
+    # For Example:
+    # 
+    #  email = TMail::Address.parse("mikel@lindsaar.net")
+    #  email.local
+    #  #=> "mikel"
     def local
       return nil unless @local
       return '""' if @local.size == 1 and @local[0].empty?
-      @local.map {|i| quote_atom(i) }.join('.')
+      # Check to see if it is an array before trying to map it
+      if @local.respond_to?(:map)
+        @local.map {|i| quote_atom(i) }.join('.')
+      else
+        quote_atom(@local)
+      end
     end
 
+    # Returns the domain part of the email address
+    # 
+    # For Example:
+    # 
+    #  email = TMail::Address.parse("mikel@lindsaar.net")
+    #  email.local
+    #  #=> "lindsaar.net"
     def domain
       return nil unless @domain
       join_domain(@domain)
     end
 
+    # Returns the full specific address itself
+    # 
+    # For Example:
+    # 
+    #  email = TMail::Address.parse("mikel@lindsaar.net")
+    #  email.address
+    #  #=> "mikel@lindsaar.net"
     def spec
       s = self.local
       d = self.domain
@@ -106,18 +256,41 @@ module TMail
       end
     end
 
-    alias address  spec
-
+    alias address spec
+
+    # Provides == function to the email.  Only checks the actual address
+    # and ignores the name/phrase component
+    # 
+    # For Example
+    # 
+    #  addr1 = TMail::Address.parse("My Address <mikel@lindsaar.net>")
+    #  #=> "#<TMail::Address mikel@lindsaar.net>"
+    #  addr2 = TMail::Address.parse("Another <mikel@lindsaar.net>")
+    #  #=> "#<TMail::Address mikel@lindsaar.net>"
+    #  addr1 == addr2
+    #  #=> true
     def ==( other )
       other.respond_to? :spec and self.spec == other.spec
     end
 
     alias eql? ==
 
+    # Provides a unique hash value for this record against the local and domain
+    # parts, ignores the name/phrase value
+    # 
+    #  email = TMail::Address.parse("mikel@lindsaar.net")
+    #  email.hash
+    #  #=> 18767598
     def hash
       @local.hash ^ @domain.hash
     end
 
+    # Duplicates a TMail::Address object returning the duplicate
+    # 
+    #  addr1 = TMail::Address.parse("mikel@lindsaar.net")
+    #  addr2 = addr1.dup
+    #  addr1.id == addr2.id
+    #  #=> false
     def dup
       obj = self.class.new(@local.dup, @domain.dup)
       obj.name = @name.dup if @name
@@ -125,9 +298,9 @@ module TMail
       obj
     end
 
-    include StrategyInterface
+    include StrategyInterface #:nodoc:
 
-    def accept( strategy, dummy1 = nil, dummy2 = nil )
+    def accept( strategy, dummy1 = nil, dummy2 = nil ) #:nodoc:
       unless @local
         strategy.meta '<>'   # empty return-path
         return