Object
The body is where the text of the email is stored. Mail treats the body as a single object. The body itself has no information about boundaries used in the MIME standard, it just looks at it’s content as either a single block of text, or (if it is a multipart message) as an array of blocks o text.
A body has to be told to split itself up into a multipart message by calling # with the correct boundary. This is because the body object has no way of knowing what the correct boundary is for itself (there could be many boundaries in a body in the case of a nested MIME text).
Once split is called, Mail::Body will slice itself up on this boundary, assigning anything that appears before the first part to the preamble, and anything that appears after the closing boundary to the epilogue, then each part gets initialized into a Mail::Part object.
The boundary that is used to split up the Body is also stored in the Body object for use on encoding itself back out to a string. You can overwrite this if it needs to be changed.
On encoding, the body will return the preamble, then each part joined by the boundary, followed by a closing boundary string and then the epilogue.
# File lib/mail/body.rb, line 29 29: def initialize(string = '') 30: @boundary = nil 31: @preamble = nil 32: @epilogue = nil 33: @charset = nil 34: @part_sort_order = [ "text/plain", "text/enriched", "text/html" ] 35: @parts = Mail::PartsList.new 36: if string.blank? 37: @raw_source = '' 38: else 39: # Do join first incase we have been given an Array in Ruby 1.9 40: if string.respond_to?(:join) 41: @raw_source = string.join('') 42: elsif string.respond_to?(:to_s) 43: @raw_source = string.to_s 44: else 45: raise "You can only assign a string or an object that responds_to? :join or :to_s to a body." 46: end 47: end 48: @encoding = (only_us_ascii? ? '7bit' : '8bit') 49: set_charset 50: end
# File lib/mail/body.rb, line 244 244: def <<( val ) 245: if @parts 246: @parts << val 247: else 248: @parts = Mail::PartsList.new[val] 249: end 250: end
Matches this body with another body. Also matches the decoded value of this body with a string.
Examples:
body = Mail::Body.new('The body') body == body #=> true body = Mail::Body.new('The body') body == 'The body' #=> true body = Mail::Body.new("VGhlIGJvZHk=\n") body.encoding = 'base64' body == "The body" #=> true
# File lib/mail/body.rb, line 66 66: def ==(other) 67: if other.class == String 68: self.decoded == other 69: else 70: super 71: end 72: end
Accepts a string and performs a regular expression against the decoded text
Examples:
body = Mail::Body.new('The body') body =~ /The/ #=> 0 body = Mail::Body.new("VGhlIGJvZHk=\n") body.encoding = 'base64' body =~ /The/ #=> 0
# File lib/mail/body.rb, line 84 84: def =~(regexp) 85: self.decoded =~ regexp 86: end
Returns the boundary used by the body
# File lib/mail/body.rb, line 231 231: def boundary 232: @boundary 233: end
Allows you to change the boundary of this Body object
# File lib/mail/body.rb, line 236 236: def boundary=( val ) 237: @boundary = val 238: end
# File lib/mail/body.rb, line 182 182: def charset 183: @charset 184: end
# File lib/mail/body.rb, line 186 186: def charset=( val ) 187: @charset = val 188: end
# File lib/mail/body.rb, line 170 170: def decoded 171: if !Encodings.defined?(encoding) 172: raise UnknownEncodingType, "Don't know how to decode #{encoding}, please call #encoded and decode it yourself." 173: else 174: Encodings.get_encoding(encoding).decode(raw_source) 175: end 176: end
# File lib/mail/body.rb, line 268 268: def empty? 269: !!raw_source.to_s.empty? 270: end
Returns a body encoded using transfer_encoding. Multipart always uses an identiy encoding (i.e. no encoding). Calling this directly is not a good idea, but supported for compatibility TODO: Validate that preamble and epilogue are valid for requested encoding
# File lib/mail/body.rb, line 150 150: def encoded(transfer_encoding = '8bit') 151: if multipart? 152: self.sort_parts! 153: encoded_parts = parts.map { |p| p.encoded } 154: ([preamble] + encoded_parts).join(crlf_boundary) + end_boundary + epilogue.to_s 155: else 156: be = get_best_encoding(transfer_encoding) 157: dec = Mail::Encodings::get_encoding(encoding) 158: enc = Mail::Encodings::get_encoding(be) 159: if transfer_encoding == encoding and dec.nil? 160: # Cannot decode, so skip normalization 161: raw_source 162: else 163: # Decode then encode to normalize and allow transforming 164: # from base64 to Q-P and vice versa 165: enc.encode(dec.decode(raw_source)) 166: end 167: end 168: end
# File lib/mail/body.rb, line 190 190: def encoding(val = nil) 191: if val 192: self.encoding = val 193: else 194: @encoding 195: end 196: end
# File lib/mail/body.rb, line 198 198: def encoding=( val ) 199: if val == "text" || val.blank? then 200: val = "8bit" 201: end 202: @encoding = (val == "text") ? "8bit" : val 203: end
Returns the epilogue (any text that is after the last MIME boundary)
# File lib/mail/body.rb, line 216 216: def epilogue 217: @epilogue 218: end
Sets the epilogue to a string (adds text after the last MIME boundary)
# File lib/mail/body.rb, line 221 221: def epilogue=( val ) 222: @epilogue = val 223: end
# File lib/mail/body.rb, line 141 141: def get_best_encoding(target) 142: target_encoding = Mail::Encodings.get_encoding(target) 143: target_encoding.get_best_compatible(encoding, raw_source) 144: end
Accepts anything that responds to # and checks if it’s a substring of the decoded text
Examples:
body = Mail::Body.new('The body') body.include?('The') #=> true body = Mail::Body.new("VGhlIGJvZHk=\n") body.encoding = 'base64' body.include?('The') #=> true
# File lib/mail/body.rb, line 112 112: def include?(other) 113: self.decoded.include?(other.to_s) 114: end
Accepts a string and performs a regular expression against the decoded text
Examples:
body = Mail::Body.new('The body') body.match(/The/) #=> #<MatchData "The"> body = Mail::Body.new("VGhlIGJvZHk=\n") body.encoding = 'base64' body.match(/The/) #=> #<MatchData "The">
# File lib/mail/body.rb, line 98 98: def match(regexp) 99: self.decoded.match(regexp) 100: end
Returns true if there are parts defined in the body
# File lib/mail/body.rb, line 226 226: def multipart? 227: true unless parts.empty? 228: end
# File lib/mail/body.rb, line 263 263: def only_us_ascii? 264: raw_source.each_byte {|b| return false if (b == 0 || b > 127)} 265: true 266: end
# File lib/mail/body.rb, line 240 240: def parts 241: @parts 242: end
Returns the preamble (any text that is before the first MIME boundary)
# File lib/mail/body.rb, line 206 206: def preamble 207: @preamble 208: end
Sets the preamble to a string (adds text before the first MIME boundary)
# File lib/mail/body.rb, line 211 211: def preamble=( val ) 212: @preamble = val 213: end
Returns the raw source that the body was initialized with, without any tampering
# File lib/mail/body.rb, line 137 137: def raw_source 138: @raw_source 139: end
Allows you to set the sort order of the parts, overriding the default sort order. Defaults to ‘text/plain’, then ‘text/enriched’, then ‘text/html’ with any other content type coming after.
# File lib/mail/body.rb, line 119 119: def set_sort_order(order) 120: @part_sort_order = order 121: end
Allows you to sort the parts according to the default sort order, or the sort order you set with :set_sort_order.
sort_parts! is also called from :encode, so there is no need for you to call this explicitly
# File lib/mail/body.rb, line 127 127: def sort_parts! 128: @parts.each do |p| 129: p.body.set_sort_order(@part_sort_order) 130: @parts.sort!(@part_sort_order) 131: p.body.sort_parts! 132: end 133: end
# File lib/mail/body.rb, line 252 252: def split!(boundary) 253: self.boundary = boundary 254: parts = raw_source.split("--#{boundary}") 255: # Make the preamble equal to the preamble (if any) 256: self.preamble = parts[0].to_s.strip 257: # Make the epilogue equal to the epilogue (if any) 258: self.epilogue = parts[1].to_s.sub('--', '').strip 259: parts[1...1].to_a.each { |part| @parts << Mail::Part.new(part) } 260: self 261: end
# File lib/mail/body.rb, line 274 274: def crlf_boundary 275: "\r\n\r\n--#{boundary}\r\n" 276: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.