=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'] || ::TMail.new_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