Class: RMail::Header

Class | RMail::Header
In: | lib/rmail/header.rb
Parent: | Object

# Overview

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.

# Terminology

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.

# 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 add_message_id add_raw address_list_assign address_list_fetch bcc bcc= cc cc= clear clone content_type date date= delete delete_at delete_if dup each each_key each_name each_pair each_value empty? fetch fetch_all field? from from= has_key? include? key? keys length match match? mbox_from mbox_from= media_type member? message_id names new param params recipients replace reply_to reply_to= select set set_boundary size subject subject= subtype to to= to_a to_s to_string

### Included Modules

Enumerable

### Constants

MESSAGE_ID_MAXRAND | = | 0x7fffffff
BASE36 | = | "0123456789abcdefghijklmnopqrstuvwxyz"
PARAM_SCAN_RE | = | %r{ ; | [^;"]*"(?:|.*?(?:[^\\]|\\\\))"\s* # fix fontification " | [^;]+ }x
NAME_VALUE_SCAN_RE | = | %r{ = | [^="]*"(?:.*?(?:[^\\]|\\\\))" # fix fontification "\s* | [^=]+ }x

### Attributes

fields | [RW] |

### Public Class methods

new()

Creates a new empty header object.

### Public Instance methods

==(other)

Returns true if the two objects have the same number of fields, in the same order, with the same values.

[](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.

[]=(name, value)

Append a new field with `name` and `value`. If you want control of where the field is inserted, see add.

Returns `value`.

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.

add_message_id(fqdn = nil)

Sets the value of this object‘s Message-Id: field to a new random value.

If you don‘t supply a `fqdn` (fully qualified domain name) then one will be randomly generated for you. If a valid address exists in the From: field, its domain will be used as a basis.

Part of the randomness in the header is taken from the header itself, so it is best to call this method after adding other fields to the header — especially those that make it unique (Subject:, To:, Cc:, etc).

add_raw(raw)

Add a new field as a raw string together with a parsed name/value. This method is used mainly by the parser and regular programs should stick to add.

address_list_assign(field_name, addresses)

Set a given field to a list of supplied `addresses`.

The `addresses` may be a String, RMail::Address, or Array. If a String, it is parsed for valid email addresses and those found are used. If an RMail::Address, the result of RMail::Address#format is used. If an Array, each element of the array must be either a String or RMail::Address and is treated as above.

This method is used to implement many of the convenience methods such as from=, to=, etc.

address_list_fetch(field_name)

Retrieve a given field‘s value as an RMail::Address::List of RMail::Address objects.

This method is used to implement many of the convenience methods such as from, to, etc.

bcc()

Returns the value of the Bcc: field as an Array of RMail::Address objects.

See address_list_fetch for details on what is returned.

bcc=(addresses)

Sets the Bcc: field to the supplied address or addresses.

See address_list_assign for information on valid values for `addresses`.

cc()

Returns the value of the Cc: field as an Array of RMail::Address objects.

See address_list_fetch for details on what is returned.

cc=(addresses)

Sets the Cc: field to the supplied address or addresses.

See address_list_assign for information on valid values for `addresses`.

clear()

Delete all fields in this object. Returns self.

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.

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.

date()

Return the value of the Date: field, parsed into a Time object. Returns nil if there is no Date: field or the field value could not be parsed.

date=(time)

Deletes any existing Date: fields and appends a new one corresponding to the given Time object.

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.

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.

each( {|name, value| ...}

Executes block once for each field in the header, passing the key and value as parameters.

Returns self.

each_key()

Alias for each_name

each_name() {|i.name| ...}

Executes block once for each field in the header, passing the field‘s name as a parameter.

Returns self

each_pair(

Alias for each

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

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’.

from()

Returns the value of the From: header as an Array of RMail::Address objects.

See address_list_fetch for details on what is returned.

This method does not return a single RMail::Address value because it is legal to have multiple addresses in a From: header.

This method always returns at least the empty list. So if you are always only interested in the first from address (most likely the case), you can safely say:

       header.from.first

from=(addresses)

Sets the From: field to the supplied address or addresses.

See address_list_assign for information on valid values for `addresses`.

Note that the From: header usually contains only one address, but it is legal to have more than one.

has_key?(name)

Alias for field?

include?(name)

Alias for field?

key?(name)

Alias for field?

keys()

Alias for names

length()

Return the number of fields in this object.

match(name, value)

Find all fields that match the given +name and `value`.

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). Use the regexp // if you want to test all field names.

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. Use the regexp // if you want to match all possible field values.

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

Examples:

     received = header.match('Received', //)
     destinations = header.match(/^(to|cc|bcc)$/, //)
     bigfoot_received = header.match('received',
                                     /from.*by.*bigfoot\.com.*LiteMail/im)

See also: match?

match?(name, value)

Determine if there is any fields that match the given `name` and `value`.

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). Use the regexp // if you want to test all field names.

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 should use a multi-line Regexp. Also consider using a case insensitive Regexp. Use the regexp // if you want to match all possible field values.

Returns true if there is a match, false otherwise.

Example:

       if h.match?('x-ml-name', /ruby-dev/im)
         # do something
       end

See also: match

mbox_from()

Gets the "From " line previously set with mbox_from=, or nil.

mbox_from=(value)

Sets the "From " line commonly used in the Unix mbox mailbox format. The `value` supplied should be the entire "From " line.

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 field, 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.

member?(name)

Alias for field?

message_id()

Returns the value of this object‘s Message-Id: field.

names()

Returns an array consisting of the names of every field in this header.

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.

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.

recipients()

Returns an RMail::Address::List array holding all the recipients of this message. This uses the contents of the To, Cc, and Bcc fields. Duplicate addresses are eliminated.

replace(other)

Replaces the contents of this header with that of another header object. Returns self.

reply_to()

Returns the value of the Reply-To: header as an Array of RMail::Address objects.

reply_to=(addresses)

Sets the Reply-To: field to the supplied address or addresses.

See address_list_assign for information on valid values for `addresses`.

select(*names)

Returns an array of pairs [ name, value ] for all fields with one of the names passed.

set(name, value, params = nil)

First delete any fields with `name`, then append a new field with `name`, `value`, and `params` as in add.

set_boundary(boundary)

Set the boundary parameter of this message‘s Content-Type: field.

size()

Alias for length

subject()

Return the subject of this message.

subject=(string)

Set the subject of this message

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 field, 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.

to()

Returns the value of the To: field as an Array of RMail::Address objects.

See address_list_fetch for details on what is returned.

to=(addresses)

Sets the To: field to the supplied address or addresses.

See address_list_assign for information on valid values for `addresses`.

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.

[Validate]