mail 2.6.6 → 2.7.1

data/lib/mail/message.rb

@@ -56,15 +56,23 @@ module Mail
     #
     # ===Making an email via a block
     #
-    #  mail = Mail.new do
-    #       from 'mikel@test.lindsaar.net'
-    #         to 'you@test.lindsaar.net'
-    #    subject 'This is a test email'
-    #       body File.read('body.txt')
+    #  mail = Mail.new do |m|
+    #    m.from 'mikel@test.lindsaar.net'
+    #    m.to 'you@test.lindsaar.net'
+    #    m.subject 'This is a test email'
+    #    m.body File.read('body.txt')
     #  end
     #
     #  mail.to_s #=> "From: mikel@test.lindsaar.net\r\nTo: you@...
     #
+    # If may also pass a block with no arguments, in which case it will
+    # be evaluated in the scope of the new message instance:
+    #
+    #  mail = Mail.new do
+    #    from 'mikel@test.lindsaar.net'
+    #    # …
+    #  end
+    #
     # ===Making an email via passing a string
     #
     #  mail = Mail.new("To: mikel@test.lindsaar.net\r\nSubject: Hello\r\n\r\nHi there!")
@@ -129,8 +137,23 @@ module Mail
         init_with_string(args.flatten[0].to_s)
       end
 
+      # Support both builder styles:
+      #
+      #   Mail.new do
+      #     to 'recipient@example.com'
+      #   end
+      #
+      # and
+      #
+      #   Mail.new do |m|
+      #     m.to 'recipient@example.com'
+      #   end
       if block_given?
-        instance_eval(&block)
+        if block.arity.zero? || (RUBY_VERSION < '1.9' && block.arity < 1)
+          instance_eval(&block)
+        else
+          yield self
+        end
       end
 
       self
@@ -213,7 +236,7 @@ module Mail
     self.default_charset = 'UTF-8'
 
     def register_for_delivery_notification(observer)
-      STDERR.puts("Message#register_for_delivery_notification is deprecated, please call Mail.register_observer instead")
+      warn("Message#register_for_delivery_notification is deprecated, please call Mail.register_observer instead")
       Mail.register_observer(observer)
     end
 
@@ -225,7 +248,7 @@ module Mail
       Mail.inform_interceptors(self)
     end
 
-    # Delivers an mail object.
+    # Delivers a mail object.
     #
     # Examples:
     #
@@ -360,13 +383,8 @@ module Mail
       if self.message_id && other.message_id
         self.encoded == other.encoded
       else
-        self_message_id, other_message_id = self.message_id, other.message_id
-        begin
-          self.message_id, other.message_id = '<temp@test>', '<temp@test>'
-          self.encoded == other.encoded
-        ensure
-          self.message_id, other.message_id = self_message_id, other_message_id
-        end
+        dup.tap { |m| m.message_id = '<temp@test>' }.encoded ==
+          other.dup.tap { |m| m.message_id = '<temp@test>' }.encoded
       end
     end
 
@@ -1193,8 +1211,8 @@ module Mail
     def default( sym, val = nil )
       if val
         header[sym] = val
-      else
-        header[sym].default if header[sym]
+      elsif field = header[sym]
+        field.default
       end
     end
 
@@ -1240,14 +1258,13 @@ module Mail
     def body(value = nil)
       if value
         self.body = value
-#        add_encoding_to_body
       else
         process_body_raw if @body_raw
         @body
       end
     end
 
-    def body_encoding(value)
+    def body_encoding(value = nil)
       if value.nil?
         body.encoding
       else
@@ -1256,7 +1273,7 @@ module Mail
     end
 
     def body_encoding=(value)
-        body.encoding = value
+      body.encoding = value
     end
 
     # Returns the list of addresses this message should be sent to by
@@ -1420,7 +1437,7 @@ module Mail
     end
 
     def has_transfer_encoding? # :nodoc:
-      STDERR.puts(":has_transfer_encoding? is deprecated in Mail 1.4.3.  Please use has_content_transfer_encoding?\n#{caller}")
+      warn(":has_transfer_encoding? is deprecated in Mail 1.4.3.  Please use has_content_transfer_encoding?\n#{caller}")
       has_content_transfer_encoding?
     end
 
@@ -1468,34 +1485,26 @@ module Mail
       if !body.empty?
         # Only give a warning if this isn't an attachment, has non US-ASCII and the user
         # has not specified an encoding explicitly.
-        if @defaulted_charset && body.raw_source.not_ascii_only? && !self.attachment?
+        if @defaulted_charset && !body.raw_source.ascii_only? && !self.attachment?
           warning = "Non US-ASCII detected and no charset defined.\nDefaulting to UTF-8, set your own if this is incorrect.\n"
-          STDERR.puts(warning)
+          warn(warning)
         end
         header[:content_type].parameters['charset'] = @charset
       end
     end
 
     # Adds a content transfer encoding
-    #
-    # Otherwise raises a warning
     def add_content_transfer_encoding
-      if body.only_us_ascii?
-        header[:content_transfer_encoding] = '7bit'
-      else
-        warning = "Non US-ASCII detected and no content-transfer-encoding defined.\nDefaulting to 8bit, set your own if this is incorrect.\n"
-        STDERR.puts(warning)
-        header[:content_transfer_encoding] = '8bit'
-      end
+      header[:content_transfer_encoding] ||= body.default_encoding
     end
 
     def add_transfer_encoding # :nodoc:
-      STDERR.puts(":add_transfer_encoding is deprecated in Mail 1.4.3.  Please use add_content_transfer_encoding\n#{caller}")
+      warn(":add_transfer_encoding is deprecated in Mail 1.4.3.  Please use add_content_transfer_encoding\n#{caller}")
       add_content_transfer_encoding
     end
 
     def transfer_encoding # :nodoc:
-      STDERR.puts(":transfer_encoding is deprecated in Mail 1.4.3.  Please use content_transfer_encoding\n#{caller}")
+      warn(":transfer_encoding is deprecated in Mail 1.4.3.  Please use content_transfer_encoding\n#{caller}")
       content_transfer_encoding
     end
 
@@ -1505,7 +1514,7 @@ module Mail
     end
 
     def message_content_type
-      STDERR.puts(":message_content_type is deprecated in Mail 1.4.3.  Please use mime_type\n#{caller}")
+      warn(":message_content_type is deprecated in Mail 1.4.3.  Please use mime_type\n#{caller}")
       mime_type
     end
 
@@ -1537,7 +1546,7 @@ module Mail
 
     # Returns the content type parameters
     def mime_parameters
-      STDERR.puts(':mime_parameters is deprecated in Mail 1.4.3, please use :content_type_parameters instead')
+      warn(':mime_parameters is deprecated in Mail 1.4.3, please use :content_type_parameters instead')
       content_type_parameters
     end
 
@@ -1563,7 +1572,14 @@ module Mail
 
     # returns the part in a multipart/report email that has the content-type delivery-status
     def delivery_status_part
-      @delivery_stats_part ||= parts.select { |p| p.delivery_status_report_part? }.first
+      unless defined? @delivery_status_part
+        @delivery_status_part =
+          if delivery_status_report?
+            parts.detect(&:delivery_status_report_part?)
+          end
+      end
+
+      @delivery_status_part
     end
 
     def bounced?
@@ -1778,9 +1794,6 @@ module Mail
       else
         basename = values[:filename]
         filedata = values
-        unless filedata[:content]
-          filedata = values.merge(:content=>File.open(values[:filename], 'rb') { |f| f.read })
-        end
       end
       self.attachments[basename] = filedata
     end
@@ -1798,7 +1811,6 @@ module Mail
     # ready to send
     def ready_to_send!
       identify_and_set_transfer_encoding
-      parts.sort!([ "text/plain", "text/enriched", "text/html", "multipart/alternative" ])
       parts.each do |part|
         part.transport_encoding = transport_encoding
         part.ready_to_send!
@@ -1807,7 +1819,7 @@ module Mail
     end
 
     def encode!
-      STDERR.puts("Deprecated in 1.1.0 in favour of :ready_to_send! as it is less confusing with encoding and decoding.")
+      warn("Deprecated in 1.1.0 in favour of :ready_to_send! as it is less confusing with encoding and decoding.")
       ready_to_send!
     end
 
@@ -1823,16 +1835,13 @@ module Mail
     end
 
     def without_attachments!
-      return self unless has_attachments?
-
-      parts.delete_if { |p| p.attachment? }
-      body_raw = if parts.empty?
-                   ''
-                 else
-                   body.encoded
-                 end
+      if has_attachments?
+        parts.delete_if { |p| p.attachment? }
 
-      @body = Mail::Body.new(body_raw)
+        reencoded = parts.empty? ? '' : body.encoded(content_transfer_encoding)
+        @body = nil # So the new parts won't be added to the existing body
+        self.body = reencoded
+      end
 
       self
     end
@@ -1975,7 +1984,7 @@ module Mail
 
   private
 
-    HEADER_SEPARATOR = /#{CRLF}#{CRLF}|#{CRLF}#{WSP}*#{CRLF}(?!#{WSP})/m
+    HEADER_SEPARATOR = /#{Constants::CRLF}#{Constants::CRLF}/
 
     #  2.1. General Description
     #   A message consists of header fields (collectively called "the header
@@ -1984,9 +1993,6 @@ module Mail
     #   this standard. The body is simply a sequence of characters that
     #   follows the header and is separated from the header by an empty line
     #   (i.e., a line with nothing preceding the CRLF).
-    #
-    # Additionally, I allow for the case where someone might have put whitespace
-    # on the "gap line"
     def parse_message
       header_part, body_part = raw_source.lstrip.split(HEADER_SEPARATOR, 2)
       self.header = header_part
@@ -1994,8 +2000,7 @@ module Mail
     end
 
     def raw_source=(value)
-      value = value.dup.force_encoding(Encoding::BINARY) if RUBY_VERSION >= "1.9.1"
-      @raw_source = ::Mail::Utilities.to_crlf(value)
+      @raw_source = value
     end
 
     # see comments to body=. We take data and process it lazily
@@ -2007,11 +2012,9 @@ module Mail
         @body_raw = nil
         add_encoding_to_body
       when @body && @body.multipart?
-        @body << Mail::Part.new(value)
-        add_encoding_to_body
+        self.text_part = value
       else
         @body_raw = value
-#        process_body_raw
       end
     end
 
@@ -2026,7 +2029,7 @@ module Mail
 
     def set_envelope_header
       raw_string = raw_source.to_s
-      if match_data = raw_source.to_s.match(/\AFrom\s(#{TEXT}+)#{CRLF}/m)
+      if match_data = raw_string.match(/\AFrom\s(#{TEXT}+)#{Constants::CRLF}/m)
         set_envelope(match_data[1])
         self.raw_source = raw_string.sub(match_data[0], "")
       end
@@ -2036,6 +2039,13 @@ module Mail
       body.split!(boundary)
     end
 
+    def allowed_encodings
+      case mime_type
+      when 'message/rfc822'
+        [Encodings::SevenBit, Encodings::EightBit, Encodings::Binary]
+      end
+    end
+
     def add_encoding_to_body
       if has_content_transfer_encoding?
         @body.encoding = content_transfer_encoding
@@ -2043,11 +2053,11 @@ module Mail
     end
 
     def identify_and_set_transfer_encoding
-        if body && body.multipart?
-            self.content_transfer_encoding = @transport_encoding
-        else
-            self.content_transfer_encoding = body.get_best_encoding(@transport_encoding)
-        end
+      if body && body.multipart?
+        self.content_transfer_encoding = @transport_encoding
+      else
+        self.content_transfer_encoding = body.negotiate_best_encoding(@transport_encoding, allowed_encodings).to_s
+      end
     end
 
     def add_required_fields
@@ -2130,10 +2140,10 @@ module Mail
       content_disp_name = header[:content_disposition].filename rescue nil
       content_loc_name  = header[:content_location].location rescue nil
       case
-      when content_type && content_type_name
-        filename = content_type_name
       when content_disposition && content_disp_name
         filename = content_disp_name
+      when content_type && content_type_name
+        filename = content_type_name
       when content_location && content_loc_name
         filename = content_loc_name
       else

data/lib/mail/multibyte/chars.rb

@@ -1,5 +1,6 @@
 # encoding: utf-8
 # frozen_string_literal: true
+require 'mail/multibyte/unicode'
 
 module Mail #:nodoc:
   module Multibyte #:nodoc:
@@ -40,7 +41,7 @@ module Mail #:nodoc:
       if RUBY_VERSION >= "1.9"
         # Creates a new Chars instance by wrapping _string_.
         def initialize(string)
-          @wrapped_string = string
+          @wrapped_string = string.dup
           @wrapped_string.force_encoding(Encoding::UTF_8) unless @wrapped_string.frozen?
         end
       else
@@ -103,7 +104,7 @@ module Mail #:nodoc:
         # Returns a new Chars object containing the _other_ object concatenated to the string.
         #
         # Example:
-        #   ('Café'.mb_chars + ' périferôl').to_s # => "Café périferôl"
+        #   (Mail::Multibyte.mb_chars('Café') + ' périferôl').to_s # => "Café périferôl"
         def +(other)
           chars(@wrapped_string + other)
         end
@@ -111,7 +112,7 @@ module Mail #:nodoc:
         # Like <tt>String#=~</tt> only it returns the character offset (in codepoints) instead of the byte offset.
         #
         # Example:
-        #   'Café périferôl'.mb_chars =~ /ô/ # => 12
+        #   Mail::Multibyte.mb_chars('Café périferôl') =~ /ô/ # => 12
         def =~(other)
           translate_offset(@wrapped_string =~ other)
         end
@@ -119,7 +120,7 @@ module Mail #:nodoc:
         # Inserts the passed string at specified codepoint offsets.
         #
         # Example:
-        #   'Café'.mb_chars.insert(4, ' périferôl').to_s # => "Café périferôl"
+        #   Mail::Multibyte.mb_chars('Café').insert(4, ' périferôl').to_s # => "Café périferôl"
         def insert(offset, fragment)
           unpacked = Unicode.u_unpack(@wrapped_string)
           unless offset > unpacked.length
@@ -135,7 +136,7 @@ module Mail #:nodoc:
         # Returns +true+ if contained string contains _other_. Returns +false+ otherwise.
         #
         # Example:
-        #   'Café'.mb_chars.include?('é') # => true
+        #   Mail::Multibyte.mb_chars('Café').include?('é') # => true
         def include?(other)
           # We have to redefine this method because Enumerable defines it.
           @wrapped_string.include?(other)
@@ -144,8 +145,8 @@ module Mail #:nodoc:
         # Returns the position _needle_ in the string, counting in codepoints. Returns +nil+ if _needle_ isn't found.
         #
         # Example:
-        #   'Café périferôl'.mb_chars.index('ô')   # => 12
-        #   'Café périferôl'.mb_chars.index(/\w/u) # => 0
+        #   Mail::Multibyte.mb_chars('Café périferôl').index('ô')   # => 12
+        #   Mail::Multibyte.mb_chars('Café périferôl').index(/\w/u) # => 0
         def index(needle, offset=0)
           wrapped_offset = first(offset).wrapped_string.length
           index = @wrapped_string.index(needle, wrapped_offset)
@@ -157,8 +158,8 @@ module Mail #:nodoc:
         # string. Returns +nil+ if _needle_ isn't found.
         #
         # Example:
-        #   'Café périferôl'.mb_chars.rindex('é')   # => 6
-        #   'Café périferôl'.mb_chars.rindex(/\w/u) # => 13
+        #   Mail::Multibyte.mb_chars('Café périferôl').rindex('é')   # => 6
+        #   Mail::Multibyte.mb_chars('Café périferôl').rindex(/\w/u) # => 13
         def rindex(needle, offset=nil)
           offset ||= length
           wrapped_offset = first(offset).wrapped_string.length
@@ -190,7 +191,7 @@ module Mail #:nodoc:
         # Returns the codepoint of the first character in the string.
         #
         # Example:
-        #   'こんにちは'.mb_chars.ord # => 12371
+        #   Mail::Multibyte.mb_chars('こんにちは').ord # => 12371
         def ord
           Unicode.u_unpack(@wrapped_string)[0]
         end
@@ -199,10 +200,10 @@ module Mail #:nodoc:
         #
         # Example:
         #
-        #   "¾ cup".mb_chars.rjust(8).to_s
+        #   Mail::Multibyte.mb_chars("¾ cup").rjust(8).to_s
         #   # => "   ¾ cup"
         #
-        #   "¾ cup".mb_chars.rjust(8, " ").to_s # Use non-breaking whitespace
+        #   Mail::Multibyte.mb_chars("¾ cup").rjust(8, " ").to_s # Use non-breaking whitespace
         #   # => "   ¾ cup"
         def rjust(integer, padstr=' ')
           justify(integer, :right, padstr)
@@ -212,10 +213,10 @@ module Mail #:nodoc:
         #
         # Example:
         #
-        #   "¾ cup".mb_chars.rjust(8).to_s
+        #   Mail::Multibyte.mb_chars("¾ cup").rjust(8).to_s
         #   # => "¾ cup   "
         #
-        #   "¾ cup".mb_chars.rjust(8, " ").to_s # Use non-breaking whitespace
+        #   Mail::Multibyte.mb_chars("¾ cup").rjust(8, " ").to_s # Use non-breaking whitespace
         #   # => "¾ cup   "
         def ljust(integer, padstr=' ')
           justify(integer, :left, padstr)
@@ -225,10 +226,10 @@ module Mail #:nodoc:
         #
         # Example:
         #
-        #   "¾ cup".mb_chars.center(8).to_s
+        #   Mail::Multibyte.mb_chars("¾ cup").center(8).to_s
         #   # => " ¾ cup  "
         #
-        #   "¾ cup".mb_chars.center(8, " ").to_s # Use non-breaking whitespace
+        #   Mail::Multibyte.mb_chars("¾ cup").center(8, " ").to_s # Use non-breaking whitespace
         #   # => " ¾ cup  "
         def center(integer, padstr=' ')
           justify(integer, :center, padstr)
@@ -244,7 +245,7 @@ module Mail #:nodoc:
       # instances instead of String. This makes chaining methods easier.
       #
       # Example:
-      #   'Café périferôl'.mb_chars.split(/é/).map { |part| part.upcase.to_s } # => ["CAF", " P", "RIFERÔL"]
+      #   Mail::Multibyte.mb_chars('Café périferôl').split(/é/).map { |part| part.upcase.to_s } # => ["CAF", " P", "RIFERÔL"]
       def split(*args)
         @wrapped_string.split(*args).map { |i| i.mb_chars }
       end
@@ -292,7 +293,7 @@ module Mail #:nodoc:
       # Reverses all characters in the string.
       #
       # Example:
-      #   'Café'.mb_chars.reverse.to_s # => 'éfaC'
+      #   Mail::Multibyte.mb_chars('Café').reverse.to_s # => 'éfaC'
       def reverse
         chars(Unicode.g_unpack(@wrapped_string).reverse.flatten.pack('U*'))
       end
@@ -301,7 +302,7 @@ module Mail #:nodoc:
       # character.
       #
       # Example:
-      #   'こんにちは'.mb_chars.slice(2..3).to_s # => "にち"
+      #   Mail::Multibyte.mb_chars('こんにちは').slice(2..3).to_s # => "にち"
       def slice(*args)
         if args.size > 2
           raise ArgumentError, "wrong number of arguments (#{args.size} for 1)" # Do as if we were native
@@ -338,7 +339,7 @@ module Mail #:nodoc:
       # Convert characters in the string to uppercase.
       #
       # Example:
-      #   'Laurent, où sont les tests ?'.mb_chars.upcase.to_s # => "LAURENT, OÙ SONT LES TESTS ?"
+      #   Mail::Multibyte.mb_chars('Laurent, où sont les tests ?').upcase.to_s # => "LAURENT, OÙ SONT LES TESTS ?"
       def upcase
         chars(Unicode.apply_mapping(@wrapped_string, :uppercase_mapping))
       end
@@ -346,7 +347,7 @@ module Mail #:nodoc:
       # Convert characters in the string to lowercase.
       #
       # Example:
-      #   'VĚDA A VÝZKUM'.mb_chars.downcase.to_s # => "věda a výzkum"
+      #   Mail::Multibyte.mb_chars('VĚDA A VÝZKUM').downcase.to_s # => "věda a výzkum"
       def downcase
         chars(Unicode.apply_mapping(@wrapped_string, :lowercase_mapping))
       end
@@ -354,7 +355,7 @@ module Mail #:nodoc:
       # Converts the first character to uppercase and the remainder to lowercase.
       #
       # Example:
-      #  'über'.mb_chars.capitalize.to_s # => "Über"
+      #  Mail::Multibyte.mb_chars('über').capitalize.to_s # => "Über"
       def capitalize
         (slice(0) || chars('')).upcase + (slice(1..-1) || chars('')).downcase
       end
@@ -362,8 +363,8 @@ module Mail #:nodoc:
       # Capitalizes the first letter of every word, when possible.
       #
       # Example:
-      #   "ÉL QUE SE ENTERÓ".mb_chars.titleize    # => "Él Que Se Enteró"
-      #   "日本語".mb_chars.titleize                 # => "日本語"
+      #   Mail::Multibyte.mb_chars("ÉL QUE SE ENTERÓ").titleize    # => "Él Que Se Enteró"
+      #   Mail::Multibyte.mb_chars("日本語").titleize                 # => "日本語"
       def titleize
         chars(downcase.to_s.gsub(/\b('?\S)/u) { Unicode.apply_mapping $1, :uppercase_mapping })
       end
@@ -383,7 +384,7 @@ module Mail #:nodoc:
       #
       # Example:
       #   'é'.length                         # => 2
-      #   'é'.mb_chars.decompose.to_s.length # => 3
+      #   Mail::Multibyte.mb_chars('é').decompose.to_s.length # => 3
       def decompose
         chars(Unicode.decompose_codepoints(:canonical, Unicode.u_unpack(@wrapped_string)).pack('U*'))
       end
@@ -392,7 +393,7 @@ module Mail #:nodoc:
       #
       # Example:
       #   'é'.length                       # => 3
-      #   'é'.mb_chars.compose.to_s.length # => 2
+      #   Mail::Multibyte.mb_chars('é').compose.to_s.length # => 2
       def compose
         chars(Unicode.compose_codepoints(Unicode.u_unpack(@wrapped_string)).pack('U*'))
       end
@@ -400,8 +401,8 @@ module Mail #:nodoc:
       # Returns the number of grapheme clusters in the string.
       #
       # Example:
-      #   'क्षि'.mb_chars.length   # => 4
-      #   'क्षि'.mb_chars.g_length # => 3
+      #   Mail::Multibyte.mb_chars('क्षि').length   # => 4
+      #   Mail::Multibyte.mb_chars('क्षि').g_length # => 3
       def g_length
         Unicode.g_unpack(@wrapped_string).length
       end

data/lib/mail/multibyte/unicode.rb

@@ -302,16 +302,16 @@ module Mail
         # See http://www.unicode.org/reports/tr15, Table 1
         codepoints = u_unpack(string)
         case form
-          when :d
-            reorder_characters(decompose_codepoints(:canonical, codepoints))
-          when :c
-            compose_codepoints(reorder_characters(decompose_codepoints(:canonical, codepoints)))
-          when :kd
-            reorder_characters(decompose_codepoints(:compatability, codepoints))
-          when :kc
-            compose_codepoints(reorder_characters(decompose_codepoints(:compatability, codepoints)))
-          else
-            raise ArgumentError, "#{form} is not a valid normalization variant", caller
+        when :d
+          reorder_characters(decompose_codepoints(:canonical, codepoints))
+        when :c
+          compose_codepoints(reorder_characters(decompose_codepoints(:canonical, codepoints)))
+        when :kd
+          reorder_characters(decompose_codepoints(:compatability, codepoints))
+        when :kc
+          compose_codepoints(reorder_characters(decompose_codepoints(:compatability, codepoints)))
+        else
+          raise ArgumentError, "#{form} is not a valid normalization variant", caller
         end.pack('U*')
       end
 

data/lib/mail/multibyte.rb

@@ -1,24 +1,73 @@
 # encoding: utf-8
 # frozen_string_literal: true
+require 'mail/multibyte/chars'
+
 module Mail #:nodoc:
   module Multibyte
-    require 'mail/multibyte/exceptions'
-    require 'mail/multibyte/chars'
-    require 'mail/multibyte/unicode'
+    # Raised when a problem with the encoding was found.
+    class EncodingError < StandardError; end
 
-    # The proxy class returned when calling mb_chars. You can use this accessor to configure your own proxy
-    # class so you can support other encodings. See the Mail::Multibyte::Chars implementation for
-    # an example how to do this.
-    #
-    # Example:
-    #   Mail::Multibyte.proxy_class = CharsForUTF32
-    def self.proxy_class=(klass)
-      @proxy_class = klass
+    class << self
+      # The proxy class returned when calling mb_chars. You can use this accessor to configure your own proxy
+      # class so you can support other encodings. See the Mail::Multibyte::Chars implementation for
+      # an example how to do this.
+      #
+      # Example:
+      #   Mail::Multibyte.proxy_class = CharsForUTF32
+      attr_accessor :proxy_class
     end
 
-    # Returns the current proxy class
-    def self.proxy_class
-      @proxy_class ||= Mail::Multibyte::Chars
+    self.proxy_class = Mail::Multibyte::Chars
+
+    if RUBY_VERSION >= "1.9"
+      # == Multibyte proxy
+      #
+      # +mb_chars+ is a multibyte safe proxy for string methods.
+      #
+      # In Ruby 1.8 and older it creates and returns an instance of the Mail::Multibyte::Chars class which
+      # encapsulates the original string. A Unicode safe version of all the String methods are defined on this proxy
+      # class. If the proxy class doesn't respond to a certain method, it's forwarded to the encapsuled string.
+      #
+      #   name = 'Claus Müller'
+      #   name.reverse # => "rell??M sualC"
+      #   name.length  # => 13
+      #
+      #   name.mb_chars.reverse.to_s # => "rellüM sualC"
+      #   name.mb_chars.length       # => 12
+      #
+      # In Ruby 1.9 and newer +mb_chars+ returns +self+ because String is (mostly) encoding aware. This means that
+      # it becomes easy to run one version of your code on multiple Ruby versions.
+      #
+      # == Method chaining
+      #
+      # All the methods on the Chars proxy which normally return a string will return a Chars object. This allows
+      # method chaining on the result of any of these methods.
+      #
+      #   name.mb_chars.reverse.length # => 12
+      #
+      # == Interoperability and configuration
+      #
+      # The Chars object tries to be as interchangeable with String objects as possible: sorting and comparing between
+      # String and Char work like expected. The bang! methods change the internal string representation in the Chars
+      # object. Interoperability problems can be resolved easily with a +to_s+ call.
+      #
+      # For more information about the methods defined on the Chars proxy see Mail::Multibyte::Chars. For
+      # information about how to change the default Multibyte behaviour see Mail::Multibyte.
+      def self.mb_chars(str)
+        if proxy_class.consumes?(str)
+          proxy_class.new(str)
+        else
+          str
+        end
+      end
+    else
+      def self.mb_chars(str)
+        if proxy_class.wants?(str)
+          proxy_class.new(str)
+        else
+          str
+        end
+      end
     end
 
     # Regular expressions that describe valid byte sequences for a character
@@ -40,4 +89,4 @@ module Mail #:nodoc:
   end
 end
 
-require 'mail/multibyte/utils'
+require 'mail/multibyte/utils'