In Files

Parent

Class Index [+]

Quicksearch

Mail::Body

Body

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.

Public Class Methods

new(string = '') click to toggle source
    # 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

Public Instance Methods

<<( val ) click to toggle source
     # File lib/mail/body.rb, line 250
250:     def <<( val )
251:       if @parts
252:         @parts << val
253:       else
254:         @parts = Mail::PartsList.new[val]
255:       end
256:     end
==(other) click to toggle source

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
=~(regexp) click to toggle source

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
boundary() click to toggle source

Returns the boundary used by the body

     # File lib/mail/body.rb, line 237
237:     def boundary
238:       @boundary
239:     end
boundary=( val ) click to toggle source

Allows you to change the boundary of this Body object

     # File lib/mail/body.rb, line 242
242:     def boundary=( val )
243:       @boundary = val
244:     end
charset() click to toggle source
     # File lib/mail/body.rb, line 187
187:     def charset
188:       @charset
189:     end
charset=( val ) click to toggle source
     # File lib/mail/body.rb, line 191
191:     def charset=( val )
192:       @charset = val
193:     end
decoded() click to toggle source
     # File lib/mail/body.rb, line 175
175:     def decoded
176:       if !Encodings.defined?(encoding)
177:         raise UnknownEncodingType, "Don't know how to decode #{encoding}, please call #encoded and decode it yourself."
178:       else
179:         Encodings.get_encoding(encoding).decode(raw_source)
180:       end
181:     end
empty?() click to toggle source
     # File lib/mail/body.rb, line 273
273:     def empty?
274:       !!raw_source.to_s.empty?
275:     end
encoded(transfer_encoding = '8bit') click to toggle source

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:             decoded = dec.decode(raw_source)
166:             if defined?(Encoding) && charset && charset != "US-ASCII"
167:               decoded.encode!(charset)
168:               decoded.force_encoding('BINARY') unless Encoding.find(charset).ascii_compatible?
169:             end
170:             enc.encode(decoded)
171:         end
172:       end
173:     end
encoding(val = nil) click to toggle source
     # File lib/mail/body.rb, line 195
195:     def encoding(val = nil)
196:       if val
197:         self.encoding = val
198:       else
199:         @encoding
200:       end
201:     end
encoding=( val ) click to toggle source
     # File lib/mail/body.rb, line 203
203:     def encoding=( val )
204:       @encoding = if val == "text" || val.blank?
205:           (only_us_ascii? ? '7bit' : '8bit')
206:       else
207:           val
208:       end
209:     end
epilogue() click to toggle source

Returns the epilogue (any text that is after the last MIME boundary)

     # File lib/mail/body.rb, line 222
222:     def epilogue
223:       @epilogue
224:     end
epilogue=( val ) click to toggle source

Sets the epilogue to a string (adds text after the last MIME boundary)

     # File lib/mail/body.rb, line 227
227:     def epilogue=( val )
228:       @epilogue = val
229:     end
get_best_encoding(target) click to toggle source
     # 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
include?(other) click to toggle source

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
match(regexp) click to toggle source

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
multipart?() click to toggle source

Returns true if there are parts defined in the body

     # File lib/mail/body.rb, line 232
232:     def multipart?
233:       true unless parts.empty?
234:     end
only_us_ascii?() click to toggle source
     # File lib/mail/body.rb, line 269
269:     def only_us_ascii?
270:       !(raw_source =~ /[^\x01-\x7f]/)
271:     end
parts() click to toggle source
     # File lib/mail/body.rb, line 246
246:     def parts
247:       @parts
248:     end
preamble() click to toggle source

Returns the preamble (any text that is before the first MIME boundary)

     # File lib/mail/body.rb, line 212
212:     def preamble
213:       @preamble
214:     end
preamble=( val ) click to toggle source

Sets the preamble to a string (adds text before the first MIME boundary)

     # File lib/mail/body.rb, line 217
217:     def preamble=( val )
218:       @preamble = val
219:     end
raw_source() click to toggle source

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
set_sort_order(order) click to toggle source

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
sort_parts!() click to toggle source

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
split!(boundary) click to toggle source
     # File lib/mail/body.rb, line 258
258:     def split!(boundary)
259:       self.boundary = boundary
260:       parts = raw_source.split("--#{boundary}")
261:       # Make the preamble equal to the preamble (if any)
262:       self.preamble = parts[0].to_s.strip
263:       # Make the epilogue equal to the epilogue (if any)
264:       self.epilogue = parts[1].to_s.sub('--', '').strip
265:       parts[1...1].to_a.each { |part| @parts << Mail::Part.new(part) }
266:       self
267:     end
to_s() click to toggle source
     # File lib/mail/body.rb, line 183
183:     def to_s
184:       decoded
185:     end

Private Instance Methods

crlf_boundary() click to toggle source
     # File lib/mail/body.rb, line 279
279:     def crlf_boundary
280:       "\r\n\r\n--#{boundary}\r\n"
281:     end
end_boundary() click to toggle source
     # File lib/mail/body.rb, line 283
283:     def end_boundary
284:       "\r\n\r\n--#{boundary}--\r\n"
285:     end
set_charset() click to toggle source
     # File lib/mail/body.rb, line 287
287:     def set_charset
288:       only_us_ascii? ? @charset = 'US-ASCII' : @charset = nil
289:     end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.