tmail 1.2.1 → 1.2.2

data/lib/tmail/mailbox.rb

@@ -150,9 +150,78 @@ module TMail
 
   class UNIXMbox
   
+    class << self
+      alias newobj new
+    end
+
+    # Creates a new mailbox object that you can iterate through to collect the
+    # emails from with "each_port".  
+    # 
+    # You need to pass it a filename of a unix mailbox format file, the format of this
+    # file can be researched at this page at {wikipedia}[link:http://en.wikipedia.org/wiki/Mbox]
+    # 
+    # ==== Parameters
+    # 
+    # +filename+: The filename of the mailbox you want to open
+    # 
+    # +tmpdir+: Can be set to override TMail using the system environment's temp dir. TMail will first
+    # use the temp dir specified by you (if any) or then the temp dir specified in the Environment's TEMP
+    # value then the value in the Environment's TMP value or failing all of the above, '/tmp'
+    # 
+    # +readonly+: If set to false, each email you take from the mail box will be removed from the mailbox.
+    # default is *false* - ie, it *WILL* truncate your mailbox file to ZERO once it has read the emails out.
+    # 
+    # ==== Options:
+    # 
+    # None
+    # 
+    # ==== Examples:
+    # 
+    #  # First show using readonly true:
+    # 
+    #  require 'ftools'
+    #  File.size("../test/fixtures/mailbox")
+    #  #=> 20426
+    #
+    #  mailbox = TMail::UNIXMbox.new("../test/fixtures/mailbox", nil, true) 
+    #  #=> #<TMail::UNIXMbox:0x14a2aa8 @readonly=true.....>
+    #
+    #  mailbox.each_port do |port| 
+    #    mail = TMail::Mail.new(port)
+    #    puts mail.subject
+    #  end
+    #  #Testing mailbox 1
+    #  #Testing mailbox 2
+    #  #Testing mailbox 3
+    #  #Testing mailbox 4
+    #  require 'ftools'
+    #  File.size?("../test/fixtures/mailbox")
+    #  #=> 20426
+    # 
+    #  # Now show with readonly set to the default false
+    # 
+    #  mailbox = TMail::UNIXMbox.new("../test/fixtures/mailbox") 
+    #  #=> #<TMail::UNIXMbox:0x14a2aa8 @readonly=false.....>
+    #
+    #  mailbox.each_port do |port| 
+    #    mail = TMail::Mail.new(port)
+    #    puts mail.subject
+    #  end
+    #  #Testing mailbox 1
+    #  #Testing mailbox 2
+    #  #Testing mailbox 3
+    #  #Testing mailbox 4
+    # 
+    #  File.size?("../test/fixtures/mailbox")
+    #  #=> nil
+    def UNIXMbox.new( filename, tmpdir = nil, readonly = false )
+      tmpdir = ENV['TEMP'] || ENV['TMP'] || '/tmp'
+      newobj(filename, "#{tmpdir}/ruby_tmail_#{$$}_#{rand()}", readonly, false)
+    end
+
     def UNIXMbox.lock( fname )
       begin
-        f = File.open(fname)
+        f = File.open(fname, 'r+')
         f.flock File::LOCK_EX
         yield f
       ensure
@@ -161,15 +230,6 @@ module TMail
       end
     end
 
-    class << self
-      alias newobj new
-    end
-
-    def UNIXMbox.new( fname, tmpdir = nil, readonly = false )
-      tmpdir = ENV['TEMP'] || ENV['TMP'] || '/tmp'
-      newobj(fname, "#{tmpdir}/ruby_tmail_#{$$}_#{rand()}", readonly, false)
-    end
-
     def UNIXMbox.static_new( fname, dir, readonly = false )
       newobj(fname, dir, readonly, true)
     end

data/lib/tmail/main.rb

@@ -1,4 +1,6 @@
+#:stopdoc:
 require 'tmail/version'
 require 'tmail/mail'
 require 'tmail/mailbox'
 require 'tmail/core_extensions'
+#:startdoc:

data/lib/tmail/mbox.rb

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

data/lib/tmail/net.rb

@@ -1,8 +1,3 @@
-=begin rdoc
-
-= Net provides SMTP wrapping
-
-=end
 #--
 # Copyright (c) 1998-2003 Minero Aoki <aamine@loveruby.net>
 #
@@ -29,13 +24,14 @@
 # with permission of Minero Aoki.
 #++
 
+#:stopdoc:
 require 'nkf'
-
+#:startdoc:
 
 module TMail
 
   class Mail
-
+    
     def send_to( smtp )
       do_send_to(smtp) do
         ready_to_send
@@ -131,7 +127,7 @@ module TMail
   
   end
 
-
+  #:stopdoc:
   class DeleteFields
 
     NOSEND_FIELDS = %w(
@@ -155,8 +151,9 @@ module TMail
     end
   
   end
+  #:startdoc:
 
-
+  #:stopdoc:
   class AddMessageId
 
     def initialize( fqdn = nil )
@@ -170,8 +167,9 @@ module TMail
     end
   
   end
+  #:startdoc:
 
-
+  #:stopdoc:
   class AddDate
 
     def exec( mail )
@@ -179,8 +177,9 @@ module TMail
     end
   
   end
+  #:startdoc:
 
-
+  #:stopdoc:
   class MimeEncodeAuto
 
     def initialize( s = nil, m = nil )
@@ -198,8 +197,9 @@ module TMail
     end
   
   end
-
+  #:startdoc:
   
+  #:stopdoc:
   class MimeEncodeSingle
 
     def exec( mail )
@@ -225,8 +225,9 @@ module TMail
     end
   
   end
-
-
+  #:startdoc:
+  
+  #:stopdoc:
   class MimeEncodeMulti
 
     def exec( mail, top = true )
@@ -243,5 +244,5 @@ module TMail
     end
 
   end
-
+  #:startdoc:
 end   # module TMail

data/lib/tmail/obsolete.rb

@@ -2,6 +2,9 @@
 
 = Obsolete methods that are depriciated
 
+If you really want to see them, go to lib/tmail/obsolete.rb and view to your
+heart's content.
+
 =end
 #--
 # Copyright (c) 1998-2003 Minero Aoki <aamine@loveruby.net>
@@ -28,10 +31,9 @@
 # Note: Originally licensed under LGPL v2+. Using MIT license for Rails
 # with permission of Minero Aoki.
 #++
+#:stopdoc:
+module TMail #:nodoc:
 
-module TMail
-
-  # mail.rb
   class Mail
     alias include? key?
     alias has_key? key?
@@ -51,8 +53,6 @@ module TMail
     alias has_value? value?
   end
 
-
-  # facade.rb
   class Mail
     def from_addr( default = nil )
       addr, = from_addrs(nil)
@@ -83,13 +83,11 @@ module TMail
     alias each_dest each_destination
   end
 
-
-  # address.rb
   class Address
     alias route routes
     alias addr spec
 
-    def spec=( str )
+    def spec=( str ) 
       @local, @domain = str.split(/@/,2).map {|s| s.split(/\./) }
     end
 
@@ -97,8 +95,6 @@ module TMail
     alias address= spec=
   end
 
-
-  # mbox.rb
   class MhMailbox
     alias new_mail new_port
     alias each_mail each_port
@@ -115,8 +111,6 @@ module TMail
     alias each_newmail each_new_port
   end
 
-
-  # utils.rb
   extend TextUtils
 
   class << self
@@ -135,3 +129,4 @@ module TMail
   end
 
 end   # module TMail
+#:startdoc:

data/lib/tmail/parser.rb

@@ -1,3 +1,4 @@
+#:stopdoc:
 # DO NOT MODIFY!!!!
 # This file is automatically generated by racc 1.4.5
 # from racc grammer file "parser.y".

data/lib/tmail/require_arch.rb

@@ -1,3 +1,4 @@
+#:stopdoc:
 require 'rbconfig'
 
 # Attempts to require anative extension.
@@ -54,3 +55,4 @@ end
 #     end
 #   end
 # end
+#:startdoc:

data/lib/tmail/scanner.rb

@@ -28,7 +28,7 @@
 # Note: Originally licensed under LGPL v2+. Using MIT license for Rails
 # with permission of Minero Aoki.
 #++
-
+#:stopdoc:
 #require 'tmail/require_arch'
 require 'tmail/utils'
 require 'tmail/config'
@@ -46,3 +46,4 @@ module TMail
     Scanner = TMailScanner
   end
 end
+#:stopdoc:

data/lib/tmail/scanner_r.rb

@@ -26,7 +26,7 @@
 # Note: Originally licensed under LGPL v2+. Using MIT license for Rails
 # with permission of Minero Aoki.
 #++
-
+#:stopdoc:
 require 'tmail/config'
 
 module TMail
@@ -105,7 +105,7 @@ module TMail
       @received  = (scantype == :RECEIVED)
       @is_mime_header = MIME_HEADERS[scantype]
 
-      atom, token, @quoted_re, @domlit_re, @comment_re = PATTERN_TABLE[$KCODE]
+      atom, token, @quoted_re, @domlit_re, @comment_re = PATTERN_TABLE[TMail.KCODE]
       @word_re = (MIME_HEADERS[scantype] ? token : atom)
     end
 
@@ -145,34 +145,34 @@ module TMail
 
         if s = readstr(@word_re)
           if @is_mime_header
-            yield :TOKEN, s
+            yield [:TOKEN, s]
           else
             # atom
             if /\A\d+\z/ === s
-              yield :DIGIT, s
+              yield [:DIGIT, s]
             elsif @received
-              yield RECV_TOKEN[s.downcase] || :ATOM, s
+              yield [RECV_TOKEN[s.downcase] || :ATOM, s]
             else
-              yield :ATOM, s
+              yield [:ATOM, s]
             end
           end
 
         elsif skip(/\A"/)
-          yield :QUOTED, scan_quoted_word()
+          yield [:QUOTED, scan_quoted_word()]
 
         elsif skip(/\A\[/)
-          yield :DOMLIT, scan_domain_literal()
+          yield [:DOMLIT, scan_domain_literal()]
 
         elsif skip(/\A\(/)
           @comments.push scan_comment()
 
         else
           c = readchar()
-          yield c, c
+          yield [c, c]
         end
       end
 
-      yield false, '$'
+      yield [false, '$']
     end
 
     def scan_quoted_word
@@ -259,3 +259,4 @@ module TMail
   end
 
 end   # module TMail
+#:startdoc:

data/lib/tmail/utils.rb

@@ -1,8 +1,3 @@
-=begin rdoc
-
-= General Purpose TMail Utilities
-
-=end
 #--
 # Copyright (c) 1998-2003 Minero Aoki <aamine@loveruby.net>
 #
@@ -29,21 +24,73 @@
 # with permission of Minero Aoki.
 #++
 
+# = TMail - The EMail Swiss Army Knife for Ruby
+# 
+# The TMail library provides you with a very complete way to handle and manipulate EMails
+# from within your Ruby programs.
+# 
+# Used as the backbone for email handling by the Ruby on Rails and Nitro web frameworks as
+# well as a bunch of other Ruby apps including the Ruby-Talk mailing list to newsgroup email
+# gateway, it is a proven and reliable email handler that won't let you down.
+# 
+# Originally created by Minero Aoki, TMail has been recently picked up by Mikel Lindsaar and
+# is being actively maintained.  Numerous backlogged bug fixes have been applied as well as
+# Ruby 1.9 compatibility and a swath of documentation to boot.
+# 
+# TMail allows you to treat an email totally as an object and allow you to get on with your
+# own programming without having to worry about crafting the perfect email address validation
+# parser, or assembling an email from all it's component parts.
+# 
+# TMail handles the most complex part of the email - the header.  It generates and parses
+# headers and provides you with instant access to their innards through simple and logically
+# named accessor and setter methods.
+# 
+# TMail also provides a wrapper to Net/SMTP as well as Unix Mailbox handling methods to
+# directly read emails from your unix mailbox, parse them and use them.
+# 
+# Following is the comprehensive list of methods to access TMail::Mail objects.  You can also
+# check out TMail::Mail, TMail::Address and TMail::Headers for other lists.
 module TMail
 
+  # Provides an exception to throw on errors in Syntax within TMail's parsers
   class SyntaxError < StandardError; end
 
-
+  # Provides a new email boundary to separate parts of the email.  This is a random
+  # string based off the current time, so should be fairly unique.
+  # 
+  # For Example:
+  # 
+  #  TMail.new_boundary
+  #  #=> "mimepart_47bf656968207_25a8fbb80114"
+  #  TMail.new_boundary
+  #  #=> "mimepart_47bf66051de4_25a8fbb80240"
   def TMail.new_boundary
     'mimepart_' + random_tag
   end
 
+  # Provides a new email message ID.  You can use this to generate unique email message
+  # id's for your email so you can track them.
+  # 
+  # Optionally takes a fully qualified domain name (default to the current hostname 
+  # returned by Socket.gethostname) that will be appended to the message ID.
+  # 
+  # For Example:
+  # 
+  #  email.message_id = TMail.new_message_id
+  #  #=> "<47bf66845380e_25a8fbb80332@baci.local.tmail>"
+  #  email.to_s
+  #  #=> "Message-Id: <47bf668b633f1_25a8fbb80475@baci.local.tmail>\n\n"
+  #  email.message_id = TMail.new_message_id("lindsaar.net")
+  #  #=> "<47bf668b633f1_25a8fbb80475@lindsaar.net.tmail>"
+  #  email.to_s
+  #  #=> "Message-Id: <47bf668b633f1_25a8fbb80475@lindsaar.net.tmail>\n\n"
   def TMail.new_message_id( fqdn = nil )
     fqdn ||= ::Socket.gethostname
     "<#{random_tag()}@#{fqdn}.tmail>"
   end
 
-  def TMail.random_tag
+  #:stopdoc:
+  def TMail.random_tag #:nodoc:
     @uniq += 1
     t = Time.now
     sprintf('%x%x_%x%x%d%x',
@@ -54,8 +101,13 @@ module TMail
 
   @uniq = 0
 
+  #:startdoc:
+  
+  # Text Utils provides a namespace to define TOKENs, ATOMs, PHRASEs and CONTROL characters that
+  # are OK per RFC 2822.
+  # 
+  # It also provides methods you can call to determine if a string is safe
   module TextUtils
-    # Defines characters per RFC that are OK for TOKENs, ATOMs, PHRASEs and CONTROL characters.
 
     aspecial     = '()<>[]:;.\\,"'
     tspecial     = '()<>[];:\\,"/?='
@@ -67,37 +119,37 @@ module TMail
     TOKEN_UNSAFE  = /[#{Regexp.quote tspecial}#{control}#{lwsp}]/n
     CONTROL_CHAR  = /[#{control}]/n
 
+    # Returns true if the string supplied is free from characters not allowed as an ATOM
     def atom_safe?( str )
-      # Returns true if the string supplied is free from characters not allowed as an ATOM
       not ATOM_UNSAFE === str
     end
 
+    # If the string supplied has ATOM unsafe characters in it, will return the string quoted 
+    # in double quotes, otherwise returns the string unmodified
     def quote_atom( str )
-      # If the string supplied has ATOM unsafe characters in it, will return the string quoted 
-      # in double quotes, otherwise returns the string unmodified
       (ATOM_UNSAFE === str) ? dquote(str) : str
     end
 
+    # If the string supplied has PHRASE unsafe characters in it, will return the string quoted 
+    # in double quotes, otherwise returns the string unmodified
     def quote_phrase( str )
-      # If the string supplied has PHRASE unsafe characters in it, will return the string quoted 
-      # in double quotes, otherwise returns the string unmodified
       (PHRASE_UNSAFE === str) ? dquote(str) : str
     end
 
+    # Returns true if the string supplied is free from characters not allowed as a TOKEN
     def token_safe?( str )
-      # Returns true if the string supplied is free from characters not allowed as a TOKEN
       not TOKEN_UNSAFE === str
     end
 
+    # If the string supplied has TOKEN unsafe characters in it, will return the string quoted 
+    # in double quotes, otherwise returns the string unmodified
     def quote_token( str )
-      # If the string supplied has TOKEN unsafe characters in it, will return the string quoted 
-      # in double quotes, otherwise returns the string unmodified
       (TOKEN_UNSAFE === str) ? dquote(str) : str
     end
 
-    def dquote( str )
-      # Wraps supplied string in double quotes unless it is already wrapped
-      # Returns double quoted string
+    # Wraps supplied string in double quotes unless it is already wrapped
+    # Returns double quoted string
+    def dquote( str ) #:nodoc:
       unless str =~ /^".*?"$/
         '"' + str.gsub(/["\\]/n) {|s| '\\' + s } + '"'
       else
@@ -106,12 +158,14 @@ module TMail
     end
     private :dquote
 
+    # Unwraps supplied string from inside double quotes
+    # Returns unquoted string
     def unquote( str )
-      # Unwraps supplied string from inside double quotes
-      # Returns unquoted string
       str =~ /^"(.*?)"$/ ? $1 : str
     end
     
+    # Provides a method to join a domain name by it's parts and also makes it
+    # ATOM safe by quoting it as needed
     def join_domain( arr )
       arr.map {|i|
           if /\A\[.*\]\z/ === i
@@ -122,7 +176,7 @@ module TMail
       }.join('.')
     end
 
-
+    #:stopdoc:
     ZONESTR_TABLE = {
       'jst' =>   9 * 60,
       'eet' =>   2 * 60,
@@ -168,9 +222,10 @@ module TMail
       'y'   =>  12 * 60,
       'z'   =>   0 * 60
     }
+    #:startdoc:
 
+    # Takes a time zone string from an EMail and converts it to Unix Time (seconds)
     def timezone_string_to_unixtime( str )
-      # Takes a time zone string from an EMail and converts it to Unix Time (seconds)
       if m = /([\+\-])(\d\d?)(\d\d)/.match(str)
         sec = (m[2].to_i * 60 + m[3].to_i) * 60
         m[1] == '-' ? -sec : sec
@@ -181,7 +236,7 @@ module TMail
       end
     end
 
-
+    #:stopdoc:
     WDAY = %w( Sun Mon Tue Wed Thu Fri Sat TMailBUG )
     MONTH = %w( TMailBUG Jan Feb Mar Apr May Jun
                          Jul Aug Sep Oct Nov Dec TMailBUG )
@@ -201,7 +256,7 @@ module TMail
 
 
     MESSAGE_ID = /<[^\@>]+\@[^>\@]+>/
-
+    
     def message_id?( str )
       MESSAGE_ID === str
     end
@@ -239,7 +294,7 @@ module TMail
     }
 
     def to_kcode( str )
-      flag = NKF_FLAGS[$KCODE] or return str
+      flag = NKF_FLAGS[TMail.KCODE] or return str
       NKF.nkf(flag, str)
     end
 
@@ -274,6 +329,8 @@ module TMail
         end
       end
     end
+    #:startdoc:
+
 
   end