Class: RMail::Message

Inherits:
Object
  • Object
show all
Defined in:
lib/rmail/message.rb

Overview

The RMail::Message is an object representation of a standard Internet email message, including MIME multipart messages.

An RMail::Message object represents a message header (held in the contained RMail::Header object) and a message body. The message body may either be a single String for single part messages or an Array of RMail::Message objects for MIME multipart messages.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Message

Create a new, empty, RMail::Message.


44
45
46
47
48
49
50
 
# File 'lib/rmail/message.rb', line 44

def initialize
  @header = RMail::Header.new
  @body = nil
  @epilogue = nil
  @preamble = nil
  @delimiters = nil
end

Instance Attribute Details

#epilogue ⇒ Object

Access the epilogue string for this message. The epilogue string is relevant only for multipart messages. It is the text that occurs after all parts of the message and is generally nil.


134
135
136
 
# File 'lib/rmail/message.rb', line 134

def epilogue
  @epilogue
end

#preamble ⇒ Object

Access the preamble string for this message. The preamble string is relevant only for multipart messages. It is the text that occurs just before the first part of the message, and is generally nil or simple English text describing the nature of the message.


141
142
143
 
# File 'lib/rmail/message.rb', line 141

def preamble
  @preamble
end

Instance Method Details

#==(other) ⇒ Object

Test if this message is structured exactly the same as the other message. This is useful mainly for testing.


54
55
56
57
58
59
 
# File 'lib/rmail/message.rb', line 54

def ==(other)
  @preamble == other.preamble &&
    @epilogue == other.epilogue &&
    @header == other.header &&
    @body == other.body
end

#add_part(part) ⇒ Object

Add a part to the message. After this message is called, the #multipart? method will return true and the #body method will #return an array of parts.


92
93
94
95
96
97
98
99
100
 
# File 'lib/rmail/message.rb', line 92

def add_part(part)
  if @body.nil?
	@body = [part]
  elsif @body.is_a?(Array)
    @body.push(part)
  else
	@body = [@body, part]
  end
end

#body ⇒ Object

Returns the body of the message as a String or Array.

If #multipart? returns true, it will be an array of RMail::Message objects. Otherwise it will be a String.

See also #header.


67
68
69
 
# File 'lib/rmail/message.rb', line 67

def body
  return @body
end

#body=(s) ⇒ Object

Sets the body of the message to the given value. It should either be a String or an Array of RMail:Message objects.


73
74
75
 
# File 'lib/rmail/message.rb', line 73

def body=(s)
  @body = s
end

#decode ⇒ Object

Decode the body of this message.

If the body of this message is encoded with quoted-printable or base64, this function will decode the data into its original form and return it as a String. If the body is not encoded, it is returned unaltered.

This only works when the message is not a multipart. The Content-Transfer-Encoding: header field is consulted to determine the encoding of the body part.

Raises:

  • (TypeError) 

112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/rmail/message.rb', line 112

def decode
  raise TypeError, "Can not decode a multipart message." if multipart?
  case header.fetch('content-transfer-encoding', '7bit').strip.downcase
  when 'quoted-printable'
    Utils.quoted_printable_decode(@body)
  when 'base64'
    Utils.base64_decode(@body)
  else
    @body
  end
end

#each ⇒ Object

Call the supplied block for each line of the message. Each line will contain a trailing newline (\n).


162
163
164
165
166
167
168
 
# File 'lib/rmail/message.rb', line 162

def each()
  # FIXME: this is incredibly inefficient!  The only users of this
  # is RMail::Deliver -- get them to use a RMail::Serialize object.
  to_s.each("\n") { |line|
    yield line
  }
end

#each_part ⇒ Object

Return each part of this message

FIXME: not tested

Raises:

  • (TypeError) 

153
154
155
156
157
158
 
# File 'lib/rmail/message.rb', line 153

def each_part
  raise TypeError, "not a multipart message" unless multipart?
  @body.each do |part|
    yield part
  end
end

#get_delimiters ⇒ Object

This is used by the serializing functions to retrieve the MIME multipart delimiter strings found while parsing the message. These delimiters are then used when serializing the message again.

Normal uses of RMail::Message will never use this method, and so it is left undocumented.


191
192
193
194
195
196
197
198
199
 
# File 'lib/rmail/message.rb', line 191

def get_delimiters          # :nodoc:
  unless multipart? and @delimiters and @delimiters_boundary and
      @delimiters.length == @body.length + 1 and
      header.param('content-type', 'boundary') == @delimiters_boundary
    @delimiters = nil
    @delimiters_boundary = nil
  end
  [ @delimiters, @delimiters_boundary ]
end

#header ⇒ Object

Returns the RMail::Header object.

See also #body.


80
81
82
 
# File 'lib/rmail/message.rb', line 80

def header()
  return @header
end

#multipart? ⇒ Boolean

Return true if the message consists of multiple parts.

Returns:

  • (Boolean) 

85
86
87
 
# File 'lib/rmail/message.rb', line 85

def multipart?
  @body.is_a?(Array)
end

#part(i) ⇒ Object

Get the indicated part from a multipart message.

Raises:

  • (TypeError) 

125
126
127
128
129
 
# File 'lib/rmail/message.rb', line 125

def part(i)
  raise TypeError,
    "Can not get part on a single part message." unless multipart?
  @body[i]
end

#set_delimiters(delimiters, boundary) ⇒ Object

This is used by the RMail::Parser to set the MIME multipart delimiter strings found in the message. These delimiters are then used when serializing the message again.

Normal uses of RMail::Message will never use this method, and so it is left undocumented.

Raises:

  • (TypeError) 

176
177
178
179
180
181
182
 
# File 'lib/rmail/message.rb', line 176

def set_delimiters(delimiters, boundary) # :nodoc:
  raise TypeError, "not a multipart message" unless multipart?
  raise ArgumentError, "delimiter array wrong size" unless
    delimiters.length == @body.length + 1
  @delimiters = delimiters.to_ary
  @delimiters_boundary = boundary.to_str
end

#to_s ⇒ Object

Returns the entire message in a single string. This uses the RMail::Serialize class.


145
146
147
148
 
# File 'lib/rmail/message.rb', line 145

def to_s()
  require 'rmail/serialize'
  RMail::Serialize.new('').serialize(self)
end