--- /dev/null
+=begin rdoc
+
+= Mail class
+
+=end
+#--
+# Copyright (c) 1998-2003 Minero Aoki <aamine@loveruby.net>
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+# Note: Originally licensed under LGPL v2+. Using MIT license for Rails
+# with permission of Minero Aoki.
+#++
+
+
+
+require 'tmail/interface'
+require 'tmail/encode'
+require 'tmail/header'
+require 'tmail/port'
+require 'tmail/config'
+require 'tmail/utils'
+require 'tmail/attachments'
+require 'tmail/quoting'
+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 ) #:nodoc:
+ @port = port || StringPort.new
+ @config = Config.to_config(conf)
+
+ @header = {}
+ @body_port = nil
+ @body_parsed = false
+ @epilogue = ''
+ @parts = []
+
+ @port.ropen {|f|
+ parse_header f
+ parse_body f unless @port.reproducible?
+ }
+ 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
+ "\#<#{self.class} port=#{@port.inspect} bodyport=#{@body_port.inspect}>"
+ end
+
+ #
+ # to_s interfaces
+ #
+
+ public
+
+ include StrategyInterface
+
+ def write_back( eol = "\n", charset = 'e' )
+ parse_body
+ @port.wopen {|stream| encoded eol, charset, stream }
+ end
+
+ def accept( strategy )
+ with_multipart_encoding(strategy) {
+ ordered_each do |name, field|
+ next if field.empty?
+ strategy.header_name canonical(name)
+ field.accept strategy
+ strategy.puts
+ end
+ strategy.puts
+ body_port().ropen {|r|
+ strategy.write r.read
+ }
+ }
+ end
+
+ private
+
+ def canonical( name )
+ name.split(/-/).map {|s| s.capitalize }.join('-')
+ end
+
+ def with_multipart_encoding( strategy )
+ if parts().empty? # DO NOT USE @parts
+ yield
+
+ else
+ bound = ::TMail.new_boundary
+ if @header.key? 'content-type'
+ @header['content-type'].params['boundary'] = bound
+ else
+ store 'Content-Type', %<multipart/mixed; boundary="#{bound}">
+ end
+
+ yield
+
+ parts().each do |tm|
+ strategy.puts
+ strategy.puts '--' + bound
+ tm.accept strategy
+ end
+ strategy.puts
+ strategy.puts '--' + bound + '--'
+ strategy.write epilogue()
+ end
+ end
+
+ ###
+ ### header
+ ###
+
+ public
+
+ ALLOW_MULTIPLE = {
+ 'received' => true,
+ 'resent-date' => true,
+ 'resent-from' => true,
+ 'resent-sender' => true,
+ 'resent-to' => true,
+ 'resent-cc' => true,
+ 'resent-bcc' => true,
+ 'resent-message-id' => true,
+ 'comments' => true,
+ 'keywords' => true
+ }
+ USE_ARRAY = ALLOW_MULTIPLE
+
+ def header
+ @header.dup
+ end
+
+ # Returns a TMail::AddressHeader object of the field you are querying.
+ # Examples:
+ # @mail['from'] #=> #<TMail::AddressHeader "mikel@test.com.au">
+ # @mail['to'] #=> #<TMail::AddressHeader "mikel@test.com.au">
+ #
+ # You can get the string value of this by passing "to_s" to the query:
+ # Example:
+ # @mail['to'].to_s #=> "mikel@test.com.au"
+ def []( key )
+ @header[key.downcase]
+ end
+
+ def sub_header(key, param)
+ (hdr = self[key]) ? hdr[param] : nil
+ end
+
+ alias fetch []
+
+ # Allows you to set or delete TMail header objects at will.
+ # Examples:
+ # @mail = TMail::Mail.new
+ # @mail['to'].to_s # => 'mikel@test.com.au'
+ # @mail['to'] = 'mikel@elsewhere.org'
+ # @mail['to'].to_s # => 'mikel@elsewhere.org'
+ # @mail.encoded # => "To: mikel@elsewhere.org\r\n\r\n"
+ # @mail['to'] = nil
+ # @mail['to'].to_s # => nil
+ # @mail.encoded # => "\r\n"
+ #
+ # Note: setting mail[] = nil actually deletes the header field in question from the object,
+ # it does not just set the value of the hash to nil
+ def []=( key, val )
+ dkey = key.downcase
+
+ if val.nil?
+ @header.delete dkey
+ return nil
+ end
+
+ case val
+ when String
+ header = new_hf(key, val)
+ when HeaderField
+ ;
+ when Array
+ ALLOW_MULTIPLE.include? dkey or
+ raise ArgumentError, "#{key}: Header must not be multiple"
+ @header[dkey] = val
+ return val
+ else
+ header = new_hf(key, val.to_s)
+ end
+ if ALLOW_MULTIPLE.include? dkey
+ (@header[dkey] ||= []).push header
+ else
+ @header[dkey] = header
+ end
+
+ val
+ end
+
+ alias store []=
+
+ # Allows you to loop through each header in the TMail::Mail object in a block
+ # Example:
+ # @mail['to'] = 'mikel@elsewhere.org'
+ # @mail['from'] = 'me@me.com'
+ # @mail.each_header { |k,v| puts "#{k} = #{v}" }
+ # # => from = me@me.com
+ # # => to = mikel@elsewhere.org
+ def each_header
+ @header.each do |key, val|
+ [val].flatten.each {|v| yield key, v }
+ end
+ end
+
+ alias each_pair each_header
+
+ def each_header_name( &block )
+ @header.each_key(&block)
+ end
+
+ alias each_key each_header_name
+
+ def each_field( &block )
+ @header.values.flatten.each(&block)
+ end
+
+ alias each_value each_field
+
+ FIELD_ORDER = %w(
+ return-path received
+ resent-date resent-from resent-sender resent-to
+ resent-cc resent-bcc resent-message-id
+ date from sender reply-to to cc bcc
+ message-id in-reply-to references
+ subject comments keywords
+ mime-version content-type content-transfer-encoding
+ content-disposition content-description
+ )
+
+ def ordered_each
+ list = @header.keys
+ FIELD_ORDER.each do |name|
+ if list.delete(name)
+ [@header[name]].flatten.each {|v| yield name, v }
+ end
+ end
+ list.each do |name|
+ [@header[name]].flatten.each {|v| yield name, v }
+ end
+ end
+
+ def clear
+ @header.clear
+ end
+
+ def delete( key )
+ @header.delete key.downcase
+ end
+
+ def delete_if
+ @header.delete_if do |key,val|
+ if Array === val
+ val.delete_if {|v| yield key, v }
+ val.empty?
+ else
+ yield key, val
+ end
+ end
+ end
+
+ def keys
+ @header.keys
+ end
+
+ def key?( key )
+ @header.key? key.downcase
+ end
+
+ def values_at( *args )
+ args.map {|k| @header[k.downcase] }.flatten
+ end
+
+ alias indexes values_at
+ alias indices values_at
+
+ private
+
+ def parse_header( f )
+ name = field = nil
+ unixfrom = nil
+
+ while line = f.gets
+ case line
+ when /\A[ \t]/ # continue from prev line
+ raise SyntaxError, 'mail is began by space' unless field
+ field << ' ' << line.strip
+
+ when /\A([^\: \t]+):\s*/ # new header line
+ add_hf name, field if field
+ name = $1
+ field = $' #.strip
+
+ when /\A\-*\s*\z/ # end of header
+ add_hf name, field if field
+ name = field = nil
+ break
+
+ when /\AFrom (\S+)/
+ unixfrom = $1
+
+ when /^charset=.*/
+
+ else
+ raise SyntaxError, "wrong mail header: '#{line.inspect}'"
+ end
+ end
+ add_hf name, field if name
+
+ if unixfrom
+ add_hf 'Return-Path', "<#{unixfrom}>" unless @header['return-path']
+ end
+ end
+
+ def add_hf( name, field )
+ key = name.downcase
+ field = new_hf(name, field)
+
+ if ALLOW_MULTIPLE.include? key
+ (@header[key] ||= []).push field
+ else
+ @header[key] = field
+ end
+ end
+
+ def new_hf( name, field )
+ HeaderField.new(name, field, @config)
+ end
+
+ ###
+ ### body
+ ###
+
+ public
+
+ def body_port
+ parse_body
+ @body_port
+ end
+
+ def each( &block )
+ body_port().ropen {|f| f.each(&block) }
+ end
+
+ def quoted_body
+ body_port.ropen {|f| return f.read }
+ end
+
+ def quoted_body= str
+ body_port.wopen { |f| f.write str }
+ str
+ end
+
+ def body=( str )
+ # Sets the body of the email to a new (encoded) string.
+ #
+ # We also reparses the email if the body is ever reassigned, this is a performance hit, however when
+ # you assign the body, you usually want to be able to make sure that you can access the attachments etc.
+ #
+ # Usage:
+ #
+ # mail.body = "Hello, this is\nthe body text"
+ # # => "Hello, this is\nthe body"
+ # mail.body
+ # # => "Hello, this is\nthe body"
+ @body_parsed = false
+ parse_body(StringInput.new(str))
+ parse_body
+ @body_port.wopen {|f| f.write str }
+ str
+ end
+
+ alias preamble quoted_body
+ alias preamble= quoted_body=
+
+ def epilogue
+ parse_body
+ @epilogue.dup
+ end
+
+ def epilogue=( str )
+ parse_body
+ @epilogue = str
+ str
+ end
+
+ def parts
+ parse_body
+ @parts
+ end
+
+ def each_part( &block )
+ parts().each(&block)
+ end
+
+ # Returns true if the content type of this part of the email is
+ # a disposition attachment
+ def disposition_is_attachment?
+ (self['content-disposition'] && self['content-disposition'].disposition == "attachment")
+ end
+
+ # Returns true if this part's content main type is text, else returns false.
+ # By main type is meant "text/plain" is text. "text/html" is text
+ def content_type_is_text?
+ self.header['content-type'] && (self.header['content-type'].main_type != "text")
+ end
+
+ private
+
+ def parse_body( f = nil )
+ return if @body_parsed
+ if f
+ parse_body_0 f
+ else
+ @port.ropen {|f|
+ skip_header f
+ parse_body_0 f
+ }
+ end
+ @body_parsed = true
+ end
+
+ def skip_header( f )
+ while line = f.gets
+ return if /\A[\r\n]*\z/ === line
+ end
+ end
+
+ def parse_body_0( f )
+ if multipart?
+ read_multipart f
+ else
+ @body_port = @config.new_body_port(self)
+ @body_port.wopen {|w|
+ w.write f.read
+ }
+ end
+ end
+
+ def read_multipart( src )
+ bound = @header['content-type'].params['boundary']
+ is_sep = /\A--#{Regexp.quote bound}(?:--)?[ \t]*(?:\n|\r\n|\r)/
+ lastbound = "--#{bound}--"
+
+ ports = [ @config.new_preamble_port(self) ]
+ begin
+ f = ports.last.wopen
+ while line = src.gets
+ if is_sep === line
+ f.close
+ break if line.strip == lastbound
+ ports.push @config.new_part_port(self)
+ f = ports.last.wopen
+ else
+ f << line
+ end
+ end
+ @epilogue = (src.read || '')
+ ensure
+ f.close if f and not f.closed?
+ end
+
+ @body_port = ports.shift
+ @parts = ports.map {|p| self.class.new(p, @config) }
+ end
+
+ end # class Mail
+
+end # module TMail
projects / depot.git / blobdiff