Class RMail::Header |
|
The RMail::Header class supports the creation and manipulation of RFC2822 mail headers.
A mail header is a little bit like a Hash. The fields are keyed by a string field name. It is also a little bit like an Array, since the fields are in a specific order. This class provides many of the methods of both the Hash and Array class. It also includes the Enumerable module.
header: | The entire header. Each RMail::Header object is one mail header. |
field: | An element of the header. Fields have a name and a value. For example, the field "Subject: Hi Mom!" has a name of "Subject" and a value of "Hi Mom!" |
name: | A name of a field. For example: "Subject" or "From". |
value: | The value of a field. |
The header's fields are stored in a particular order. Methods such as each process the headers in this order.
When field names or values are added to the object they are frozen. This helps prevent accidental modification to what is stored in the object.
Methods |
Attributes |
:fields | [RW] |
Included modules |
Public Class methods |
new() |
Creates a new empty header object.
Public Instance methods |
[](name_or_index) |
Return the value of the first matching field of a field name, or nil if none found. If passed a Fixnum, returns the header indexed by the number.
dup() |
Creates a copy of this header object. A new RMail::Header is created and the instance data is copied over. However, the new object will still reference the same strings held in the original object. Since these strings are frozen, this usually won't matter.
clone() |
Creates a complete copy of this header object, including any singleton methods and strings. The returned object will be a complete and unrelated duplicate of the original.
clear() |
Delete all fields in this object. Returns self.
replace(other) |
Replaces the contents of this header with that of another header object. Returns self.
length() |
Return the number of fields in this object.
fetch(name, *rest) {|name| ...} |
Return the value of the first matching field of a given name. If there is no such field, the value returned by the supplied block is returned. If no block is passed, the value of default_value is returned. If no default_value is specified, an IndexError exception is raised.
fetch_all(name, *rest) {|name| ...} |
Returns the values of every field named name. If there are no such fields, the value returned by the block is returned. If no block is passed, the value of default_value is returned. If no default_value is specified, an IndexError exception is raised.
field?(name) |
Returns true if the message has a field named 'name'.
delete(name) |
Deletes all fields with name. Returns self.
delete_at(index) |
Deletes the field at the specified index and returns its value.
delete_if() {|name, value| ...} |
Deletes the field if the passed block returns true. Returns self.
each() {|name, value| ...} |
Executes block once for each field in the header, passing the key and value as parameters.
Returns self.
each_name() {|i.name| ...} |
Executes block once for each field in the header, passing the field's name as a parameter.
Returns self
each_value() {|i.value| ...} |
Executes block once for each field in the header, passing the field's value as a parameter.
Returns self
empty?() |
Returns true if the header contains no fields
select(*names) |
Returns an array of pairs [ name, value ] for all fields with one of the names passed.
names() |
Returns an array consisting of the names of every field in this header.
add(name, value, index = nil, params = nil) |
Add a new field with name and value. When index is nil (the default if not specified) the line is appended to the header, otherwise it is inserted at the specified index. E.g. an index of 0 will prepend the header line.
You can pass additional parameters for the header as a hash table params. Every key of the hash will be the name of the parameter, and every key's value the parameter value.
E.g.
header.add('Content-Type', 'multipart/mixed', nil, 'boundary' => 'the boundary')
will add this header
Content-Type: multipart/mixed; boundary="the boundary"
Always returns self.
[]=(name, value) |
Append a new field with name and value. If you want control of where the field is inserted, see add.
Returns value.
==(other) |
Returns true if the two objects have the same number of fields, in the same order, with the same values.
to_a() |
Returns a new array holding one [ name, value ] array per field in the header.
to_s() |
Converts the header to a string, including any mbox from line. Equivalent to header.to_string(true).
to_string(mbox_from = false) |
Converts the header to a string. If mbox_from is true, then the mbox from line is also included.
match?(name, value) |
Determine if there is any fields that match the given name and value.
If name is nil, all fields are tested. If name is a String, all fields of that name are tested. If name is a Regexp the field names are matched against the regexp (the field names are converted to lower case first).
If value is nil, all values are matched. If value is a String, it is converted to a case insensitive Regexp that matches the string. Otherwise, it must be a Regexp. Note that the field value may be folded across many lines, so you may need to use a multi-line Regexp. Also consider using a case insensitive Regexp.
Returns true if there is a match, false otherwise.
Example:
if h.match?('x-ml-name', /ruby-dev/) # do something end
See also: match
match(name, value) |
Find all fields that match the given +name and value.
If name is nil, all fields are tested. If name is a String, all fields of that name are tested. If name is a Regexp, the field names are matched against the regexp (the field names are converted to lower case first).
If value is nil, all values are matched. If value is a String, it is converted to a case insensitive Regexp that matches the string. Otherwise, it must be a Regexp. Note that the field value may be folded across many lines, so you may need to use a multi-line Regexp. Also consider using a case insensitive Regexp.
Returns a new RMail::Header holding all matching headers.
Examples:
received = header.match('Received', nil) destinations = header.match(/^(to|cc|bcc)$/, nil) bigfoot_received = header.match('received', /from.*by.*bigfoot\.com.*LiteMail/im)
See also: match?
mbox_from=(value) |
Sets the "From " line commonly used in the Unix mbox mailbox format. The value supplied should be the entire "From " line.
mbox_from() |
Gets the "From " line previously set with mbox_from=, or nil.
content_type(default = nil) {|| ...} |
This returns the full content type of this message converted to lower case.
If there is no content type header, returns the passed block is executed and its return value is returned. If no block is passed, the value of the default argument is returned.
media_type(default = nil) {|| ...} |
This returns the main media type for this message converted to lower case. This is the first portion of the content type. E.g. a content type of text/plain has a media type of text.
If there is no content type header, returns the passed block is executed and its return value is returned. If no block is passed, the value of the default argument is returned.
subtype(default = nil) {|| ...} |
This returns the media subtype for this message, converted to lower case. This is the second portion of the content type. E.g. a content type of text/plain has a media subtype of plain.
If there is no content type header, returns the passed block is executed and its return value is returned. If no block is passed, the value of the default argument is returned.
params(field_name, default = nil) {|field_name| ...} |
This returns a hash of parameters. Each key in the hash is the name of the parameter in lower case and each value in the hash is the unquoted parameter value. If a parameter has no value, its value in the hash will be true.
If the field or parameter does not exist or it is malformed in a way that makes it impossible to parse, then the passed block is executed and its return value is returned. If no block is passed, the value of the default argument is returned.
param(field_name, param_name, default = nil) {|field_name, param_name| ...} |
This returns the parameter value for the given parameter in the given field. The value returned is unquoted.
If the field or parameter does not exist or it is malformed in a way that makes it impossible to parse, then the passed block is executed and its return value is returned. If no block is passed, the value of the default argument is returned.
set_boundary(boundary) |
Set the boundary parameter of this message's Content-Type: header.