tmail 1.2.1 → 1.2.2

data/lib/tmail/attachments.rb

@@ -1,6 +1,6 @@
 =begin rdoc
 
-= Attachment handling class
+= Attachment handling file
 
 =end
 

data/lib/tmail/base64.rb

@@ -1,9 +1,4 @@
-# = TITLE:
-#
-#   Base64
-#
-# = COPYRIGHT:
-#
+#--
 #   Copyright (c) 1998-2003 Minero Aoki <aamine@loveruby.net>
 #
 #   Permission is hereby granted, free of charge, to any person obtaining
@@ -27,10 +22,9 @@
 #
 #   Note: Originally licensed under LGPL v2+. Using MIT license for Rails
 #   with permission of Minero Aoki.
-
-#
+#++
+#:stopdoc:
 module TMail
-
   module Base64
 
     module_function
@@ -48,5 +42,5 @@ module TMail
     end
 
   end
-
 end
+#:startdoc:

data/lib/tmail/compat.rb

@@ -1,17 +1,18 @@
-unless Enumerable.method_defined?(:map)
-  module Enumerable
+#:stopdoc:
+unless Enumerable.method_defined?(:map) 
+  module Enumerable #:nodoc:
     alias map collect
   end
 end
 
 unless Enumerable.method_defined?(:select)
-  module Enumerable
+  module Enumerable #:nodoc:
     alias select find_all
   end
 end
 
 unless Enumerable.method_defined?(:reject)
-  module Enumerable
+  module Enumerable #:nodoc:
     def reject
       result = []
       each do |i|
@@ -23,7 +24,7 @@ unless Enumerable.method_defined?(:reject)
 end
 
 unless Enumerable.method_defined?(:sort_by)
-  module Enumerable
+  module Enumerable #:nodoc:
     def sort_by
       map {|i| [yield(i), i] }.sort.map {|val, i| i }
     end
@@ -31,9 +32,10 @@ unless Enumerable.method_defined?(:sort_by)
 end
 
 unless File.respond_to?(:read)
-  def File.read(fname)
+  def File.read(fname) #:nodoc:
     File.open(fname) {|f|
       return f.read
     }
   end
 end
+#:startdoc:

data/lib/tmail/config.rb

@@ -1,8 +1,3 @@
-=begin rdoc
-
-= Configuration Class
-
-=end
 #--
 # Copyright (c) 1998-2003 Minero Aoki <aamine@loveruby.net>
 #
@@ -28,7 +23,7 @@
 # Note: Originally licensed under LGPL v2+. Using MIT license for Rails
 # with permission of Minero Aoki.
 #++
-
+#:stopdoc:
 module TMail
 
   class Config
@@ -69,3 +64,4 @@ module TMail
   end
 
 end
+#:startdoc:

data/lib/tmail/core_extensions.rb

@@ -1,14 +1,9 @@
-=begin rdoc
-
-= Ruby on Rails Core Extensions
-
-provides .blank?
-
-=end
-unless Object.respond_to?(:blank?) #:nodoc:
-  # Check first to see if we are in a Rails environment, no need to 
-  # define these methods if we are
+#:stopdoc:
+unless Object.respond_to?(:blank?)
   class Object
+    # Check first to see if we are in a Rails environment, no need to 
+    # define these methods if we are
+
     # An object is blank if it's nil, empty, or a whitespace string.
     # For example, "", "   ", nil, [], and {} are blank.
     #
@@ -27,41 +22,42 @@ unless Object.respond_to?(:blank?) #:nodoc:
     end
   end
 
-  class NilClass #:nodoc:
+  class NilClass
     def blank?
       true
     end
   end
 
-  class FalseClass #:nodoc:
+  class FalseClass
     def blank?
       true
     end
   end
 
-  class TrueClass #:nodoc:
+  class TrueClass
     def blank?
       false
     end
   end
 
-  class Array #:nodoc:
+  class Array
     alias_method :blank?, :empty?
   end
 
-  class Hash #:nodoc:
+  class Hash
     alias_method :blank?, :empty?
   end
 
-  class String #:nodoc:
+  class String
     def blank?
       empty? || strip.empty?
     end
   end
 
-  class Numeric #:nodoc:
+  class Numeric
     def blank?
       false
     end
   end
-end
+end
+#:startdoc:

data/lib/tmail/encode.rb

@@ -1,7 +1,4 @@
-# = TITLE:
-#
-#   Text Encoding class
-#
+#--
 # = COPYRIGHT:
 #
 #   Copyright (c) 1998-2003 Minero Aoki <aamine@loveruby.net>
@@ -27,14 +24,22 @@
 #
 #   Note: Originally licensed under LGPL v2+. Using MIT license for Rails
 #   with permission of Minero Aoki.
-
+#++
+#:stopdoc:
 require 'nkf'
 require 'tmail/base64'
 require 'tmail/stringio'
 require 'tmail/utils'
+#:startdoc:
 
 
 module TMail
+  
+  #:stopdoc:
+  class << self
+    attr_accessor :KCODE
+  end
+  self.KCODE = 'NONE'
 
   module StrategyInterface
 
@@ -52,10 +57,34 @@ module TMail
     end
     module_function :create_dest
 
+    #:startdoc:
+    # Returns the TMail object encoded and ready to be sent via SMTP etc.
+    # You should call this before you are packaging up your  email to
+    # correctly escape all the values that need escaping in the email, line
+    # wrap the email etc.
+    # 
+    # It is also a good idea to call this before you marshal or serialize
+    # a TMail object.
+    # 
+    # For Example:
+    # 
+    #  email = TMail::Load(my_email_file)
+    #  email_to_send = email.encoded
     def encoded( eol = "\r\n", charset = 'j', dest = nil )
       accept_strategy Encoder, eol, charset, dest
     end
 
+    # Returns the TMail object decoded and ready to be used by you, your
+    # program etc.
+    # 
+    # You should call this before you are packaging up your  email to
+    # correctly escape all the values that need escaping in the email, line
+    # wrap the email etc.
+    # 
+    # For Example:
+    # 
+    #  email = TMail::Load(my_email_file)
+    #  email_to_send = email.encoded
     def decoded( eol = "\n", charset = 'e', dest = nil )
       # Turn the E-Mail into a string and return it with all
       # encoded characters decoded.  alias for to_s
@@ -64,7 +93,7 @@ module TMail
 
     alias to_s decoded
 
-    def accept_strategy( klass, eol, charset, dest = nil )
+    def accept_strategy( klass, eol, charset, dest = nil ) #:nodoc:
       dest ||= ''
       accept klass.new( create_dest(dest), charset, eol )
       dest
@@ -72,6 +101,7 @@ module TMail
 
   end
 
+  #:stopdoc:
 
   ###
   ### MIME B encoding decoder
@@ -90,8 +120,8 @@ module TMail
     }
 
     def self.decode( str, encoding = nil )
-      encoding ||= (OUTPUT_ENCODING[$KCODE] || 'j')
-      opt = '-m' + encoding
+      encoding ||= (OUTPUT_ENCODING[TMail.KCODE] || 'j')
+      opt = '-mS' + encoding
       str.gsub(ENCODED_WORDS) {|s| NKF.nkf(opt, s) }
     end
 
@@ -193,7 +223,7 @@ module TMail
 
     def initialize( dest = nil, encoding = nil, eol = "\r\n", limit = nil )
       @f = StrategyInterface.create_dest(dest)
-      @opt = OPTIONS[$KCODE]
+      @opt = OPTIONS[TMail.KCODE]
       @eol = eol
       @folded = false
       @preserve_quotes = true
@@ -368,11 +398,16 @@ module TMail
     end
 
     def concat_A_S( types, strs )
+      if RUBY_VERSION < '1.9'
+        a = ?a; s = ?s
+      else
+        a = 'a'.ord; s = 's'.ord
+      end
       i = 0
       types.each_byte do |t|
         case t
-        when ?a then add_text strs[i]
-        when ?s then add_lwsp strs[i]
+        when a then add_text strs[i]
+        when s then add_lwsp strs[i]
         else
           raise "TMail FATAL: unknown flag: #{t.chr}"
         end
@@ -520,5 +555,5 @@ module TMail
     end
 
   end
-
+  #:startdoc:
 end    # module TMail

data/lib/tmail/header.rb

@@ -1,11 +1,3 @@
-=begin rdoc
-
-= Header handling class
-
-=end
-# RFC #822 ftp://ftp.isi.edu/in-notes/rfc822.txt
-# 
-#
 #--
 # Copyright (c) 1998-2003 Minero Aoki <aamine@loveruby.net>
 #
@@ -38,9 +30,10 @@ require 'tmail/parser'
 require 'tmail/config'
 require 'tmail/utils'
 
-
+#:startdoc:
 module TMail
 
+  # Provides methods to handle and manipulate headers in the email
   class HeaderField
 
     include TextUtils
@@ -214,7 +207,11 @@ module TMail
 
     def comments
       ensure_parsed
-      @comments
+      if @comments[0]
+        [Decoder.decode(@comments[0])]
+      else
+        @comments
+      end
     end
 
     private

data/lib/tmail/index.rb

@@ -1,3 +1,4 @@
+#:stopdoc:
 # This is here for Rolls. 
 # Rolls uses this instead of lib/tmail.rb.
 
@@ -5,4 +6,4 @@ require 'tmail/version'
 require 'tmail/mail'
 require 'tmail/mailbox'
 require 'tmail/core_extensions'
-
+#:startdoc:

data/lib/tmail/interface.rb

@@ -966,31 +966,33 @@ module TMail
       end
     end
 
-    # Destructively convert the Mail object's body into a Base64 encoded email
+    # Convert the Mail object's body into a Base64 encoded email
     # returning the modified Mail object
     def base64_encode!
       store 'Content-Transfer-Encoding', 'Base64'
-      self.body = Base64.folding_encode(self.body)
+      self.body = base64_encode
     end
 
-    # ==Depreciation warning
-    # base64_encode will return the body encoded, not modify the message body in 
-    # future versions of TMail
-    alias :base64_encode :base64_encode!
+    # Return the result of encoding the TMail::Mail object body
+    # without altering the current body
+    def base64_encode
+      Base64.folding_encode(self.body)
+    end
 
-    # Destructively convert the Mail object's body into a Base64 decoded email
+    # Convert the Mail object's body into a Base64 decoded email
     # returning the modified Mail object
     def base64_decode!
       if /base64/i === self.transfer_encoding('')
         store 'Content-Transfer-Encoding', '8bit'
-        self.body = Base64.decode(self.body, @config.strict_base64decode?)
+        self.body = base64_decode
       end
     end
 
-    # ==Depreciation warning
-    # base64_decode will return the body decoded, not modify the message body in 
-    # future versions of TMail
-    alias :base64_decode :base64_decode!
+    # Returns the result of decoding the TMail::Mail object body
+    # without altering the current body
+    def base64_decode
+      Base64.decode(self.body, @config.strict_base64decode?)
+    end
 
     # Returns an array of each destination in the email message including to: cc: or bcc:
     # 

data/lib/tmail/loader.rb

@@ -1 +1,3 @@
+#:stopdoc:
 require 'tmail/mailbox'
+#:startdoc:

data/lib/tmail/mail.rb

@@ -28,22 +28,7 @@
 # Note: Originally licensed under LGPL v2+. Using MIT license for Rails
 # with permission of Minero Aoki.
 #++
-# == TMail::Mail
-# === Class Methods
-#  
-# 
-# 
-# 
-# 
-# 
-# 
-# 
-# 
-# 
-# 
-# 
-# 
-# 
+
  
 
 require 'tmail/interface'
@@ -58,23 +43,89 @@ require 'socket'
 
 module TMail
 
+  # == Mail Class
+  # 
+  # Accessing a TMail object done via the TMail::Mail class.  As email can be fairly complex
+  # creatures, you will find a large amount of accessor and setter methods in this class!
+  # 
+  # Most of the below methods handle the header, in fact, what TMail does best is handle the
+  # header of the email object.  There are only a few methods that deal directly with the body
+  # of the email, such as base64_encode and base64_decode.
+  # 
+  # === Using TMail inside your code
+  # 
+  # The usual way is to install the gem (see the {README}[link:/README] on how to do this) and
+  # then put at the top of your class:
+  # 
+  #  require 'tmail'
+  # 
+  # You can then create a new TMail object in your code with:
+  # 
+  #  @email = TMail::Mail.new
+  # 
+  # Or if you have an email as a string, you can initialize a new TMail::Mail object and get it
+  # to parse that string for you like so:
+  # 
+  #  @email = TMail::Mail.parse(email_text)
+  # 
+  # You can also read a single email off the disk, for example:
+  # 
+  #  @email = TMail::Mail.load('filename.txt')
+  # 
+  # Also, you can read a mailbox (usual unix mbox format) and end up with an array of TMail
+  # objects by doing something like this:
+  # 
+  #  # Note, we pass true as the last variable to open the mailbox read only
+  #  mailbox = TMail::UNIXMbox.new("mailbox", nil, true)
+  #  @emails = []
+  #  mailbox.each_port { |m| @emails << TMail::Mail.new(m) }
+  #
   class Mail
 
     class << self
+      
+      # Opens an email that has been saved out as a file by itself.
+      # 
+      # This function will read a file non-destructively and then parse
+      # the contents and return a TMail::Mail object.
+      # 
+      # Does not handle multiple email mailboxes (like a unix mbox) for that
+      # use the TMail::UNIXMbox class.
+      # 
+      # Example:
+      #  mail = TMail::Mail.load('filename')
+      # 
       def load( fname )
         new(FilePort.new(fname))
       end
 
       alias load_from load
       alias loadfrom load
-
+      
+      # Parses an email from the supplied string and returns a TMail::Mail
+      # object.
+      # 
+      # Example:
+      #  require 'rubygems'; require 'tmail'
+      #  email_string =<<HEREDOC
+      #  To: mikel@lindsaar.net
+      #  From: mikel@me.com
+      #  Subject: This is a short Email
+      #  
+      #  Hello there Mikel!
+      #  
+      #  HEREDOC
+      #  mail = TMail::Mail.parse(email_string)
+      #  #=> #<TMail::Mail port=#<TMail::StringPort:id=0xa30ac0> bodyport=nil>
+      #  mail.body
+      #  #=> "Hello there Mikel!\n\n"
       def parse( str )
         new(StringPort.new(str))
       end
 
     end
 
-    def initialize( port = nil, conf = DEFAULT_CONFIG )
+    def initialize( port = nil, conf = DEFAULT_CONFIG ) #:nodoc:
       @port = port || StringPort.new
       @config = Config.to_config(conf)
 
@@ -90,6 +141,12 @@ module TMail
       }
     end
 
+    # Provides access to the port this email is using to hold it's data
+    # 
+    # Example:
+    #  mail = TMail::Mail.parse(email_string)
+    #  mail.port
+    #  #=> #<TMail::StringPort:id=0xa2c952>
     attr_reader :port
 
     def inspect
@@ -395,10 +452,12 @@ module TMail
     end
 
     def quoted_body
-      parse_body
-      @body_port.ropen {|f|
-          return f.read
-      }
+      body_port.ropen {|f| return f.read }
+    end
+
+    def quoted_body= str
+      body_port.wopen { |f| f.write str }
+      str
     end
 
     def body=( str )
@@ -420,8 +479,8 @@ module TMail
       str
     end
 
-    alias preamble  body
-    alias preamble= body=
+    alias preamble  quoted_body
+    alias preamble= quoted_body=
 
     def epilogue
       parse_body