Class Mail::Header
In: /home/matt/rubymail/mail/header.rb
/home/matt/rubymail/mail/heaer.rb
Parent: Object

Overview

The Mail::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 class.

Terminology

header:The entire header. Each Mail::Header object holds one 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.

Conventions

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
==    []    []=    add    clear    clone    delete    delete_at    delete_if    dup    each    each_name    each_value    empty?    fetch    fetch_all    field?    length    match    match?    mbox_from=    names    new    replace    select    shift    to_a    to_s    to_string    unshift   
Attributes
fields  [RW] 
mbox_from  [R]  Gets the "From " line previously set with mbox_from=, or nil.
Included modules
Enumerable Enumerable
Public Class methods
new()
Creates a new empty header object.
Public Instance methods
[](name_or_index)
Return the value of the first matching header of a given field name, or nil if none found. If passed a Fixnum, returns the header indexed by the number.
dup()
Creates a shallow copy of this header object. A new Mail::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, so in place modifications of the strings will affect both objects.
clone()
Creates a deep 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. 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 name. If there is no such field, 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.
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.
shift()
Removes the first field from the header and returns it as a [ name, value ] array.
unshift()
Removes the last field from the header and returns it as a
name, value
array.
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)
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.

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, regexp)
Match regexp against all field values with a field name of name. If name is nil, all fields are tested. If name is a Regexp, the field names are matched against the regexp. Returns true if there is a match, false otherwise.

Returns a new Mail::Header holding all matching headers.

See also: #match?

match?(name, value)
Match regexp against all field values with a field name of name. If name is nil, all fields are tested. If name is a Regexp, the field names are matched against the regexp. Returns true if there is a match, false otherwise.

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.