This implementation follows the guidelines of rfc2822 as close as possible, and may there produce a different output than implementations based on the obsolete rfc822. However, the old output will still be accepted.

These objects each store one header line, and facilitates access routines to the information hidden in it. Also, you may want to have a look at the added methods of a message:

Some fields are described in the RFCs as being structured: having a well described syntax. These fields have common ideas about comments and the like, what they do not share with unstructured fields, like the Subject field.

This method may be what you want, but usually, the foldedBody() and unfoldedBody() are what you are looking for. This method is cultural heritage, and should be avoided.

Returns the body of the field. When this field is structured, it will be stripped from everything what is behind the first semi-color (;). In any case, the string is unfolded. Whether the field is structured is defined by isStructured().

Returns the folded version of the whole header. When the header is shorter than the wrap length, a list of one line is returned. Otherwise more lines will be returned, all but the first starting with at least one blank. See also foldedBody() to get the same information without the field's name.

In scalar context, the lines are delived into one string, which is a little faster because that's the way they are stored internally...

Remove the comments and folding white spaces from the STRING. Without string and only as instance method, the unfoldedBody() is being stripped and returned.

WARNING: This operation is only allowed for structured header fields (which are defined by the various RFCs as being so. You don't want parts within braces which are in the Subject header line to be removed, to give an example.

Get the value of an attribute, optionally after setting it to a new value. Attributes are part of some header lines, and hide themselves in the comment field. If the attribute does not exist, then undef is returned. The attribute is still encoded.

Returns the unfolded comment (part after a semi-colon) in a structureed header-line. optionally after setting it to a new STRING first. When undef is specified as STRING, the comment is removed. Whether the field is structured is defined by isStructured().

The comment part of a header field often contains attributes. Often it is preferred to use attribute() on them.

Convert a timestamp into an rfc2822 compliant date format. This differs from the default output of localtime in scalar context. Without argument, the localtime is used to get the current time. $time can be specified as one numeric (like the result of time()) and as list (like produced by c<localtime()> in list context).

Be sure to have your timezone set right, especially when this script runs automatically.

Accepts a whole field $line, or a pair with the field's $name and $body. In the latter case, the $body data may be specified as array of $objects which are stringified. Returned is a nicely formatted pair of two strings: the field's name and a folded body.

This method is called by new(), and usually not by an application program. The details about converting the $objects to a field content are explained in "Specifying field data".

Make the header field with $name fold into multiple lines. Wrapping is performed by inserting newlines before a blanks in the $body, such that no line exceeds the $maxchars and each line is as long as possible.

The RFC requests for folding on nice spots, but this request is mainly ignored because it would make folding too slow.

The reverse action of fold(): all lines which form the body of a field are joined into one by removing all line terminators (even the last). Possible leading blanks on the first line are removed as well.

Fields are stored in the header of a message, which are represented by Mail::Message::Head objects. A field is a combination of a name, body, and attributes. Especially the term "body" is cause for confusion: sometimes the attributes are considered to be part of the body.

The name of the field is followed by a colon (":", not preceded by blanks, but followed by one blank). Each attribute is preceded by a separate semi-colon (";"). Names of fields are case-insensitive and cannot contain blanks.

Fields which are long can be folded to span more than one line. The real limit for lines in messages is only at 998 characters, however such long lines are not easy to read without support of an application. Therefore rfc2822 (which defines the message syntax) specifies explicitly that field lines can be re-formatted into multiple sorter lines without change of meaning, by adding new-line characters to any field before any blank or tab.

Usually, the lines are reformatted to create lines which are 78 characters maximum. Some applications try harder to fold on nice spots, like before attributes. Especially the Received field is often manually folded into some nice layout. In most cases however, it is preferred to produce lines which are as long as possible but max 78.

BE WARNED that all fields can be subjected to folding, and that you usually want the unfolded value.

The rfc2822 describes a large number of header fields explicitly. These fields have a defined meaning. For some of the fields, like the Subject field, the meaning is straight forward the contents itself. These fields are the Unstructured Fields.

Other fields have a well defined internal syntax because their content is needed by e-mail applications. For instance, the To field contains addresses which must be understood by all applications in the same way. These are the Structured Fields, see isStructured().

Stuctured fields can contain comments, which are pieces of text enclosed in parenthesis. These comments can be placed close to anywhere in the line and must be ignored be the application. Not all applications are capable of handling comments correctly in all circumstances.

As many programs as there are handling e-mail, as many variations on accessing the header information are requested. Be careful which way you access the data: read the variations described here and decide which solution suites your needs best.

The get() interface is copied from other Perl modules which can handle e-mail messages. Many applications which simply replace Mail::Internet objects by Mail::Message objects will work without modification.

There is more than one get method. The exact results depend on which get you use. When Mail::Message::get() is called, you will get the unfolded, stripped from comments, stripped from attributes contents of the field as string. Character-set encodings will still be in the string. If the same fieldname appears more than once in the header, only the last value is returned.

When Mail::Message::Head::get() is called in scalar context, the last field with the specified name is returned as field object. This object strinigfies into the unfolded contents of the field, including attributes and comments. In list context, all appearances of the field in the header are returned as objects.

BE WARNED that some lines seem unique, but are not according to the official rfc. For instance, To fields can appear more than once. If your program calls get('to') in scalar context, some information is lost.

As the name study already implies, this way of accessing the fields is much more thorough but also slower. The study of a field is like a get, but provides easy access to the content of the field and handles character-set decoding correctly.

Some fields belong together in a group of fields. For instance, a set of lines is used to define one step in the mail transport process. Each step adds a Received line, and optionally some Resent-* lines and Return-Path. These groups of lines shall stay together and in order when the message header is processed.

The Mail::Message::Head::ResentGroup object simplifies the access to these related fields. These resent groups can be deleted as a whole, or correctly constructed.

Returns the text of the body, like foldedBody(), but then with all new-lines removed. This is the normal way to get the content of unstructured fields. Character-set encodings will still be in place. Fields are stringified into their unfolded representation.

Studied fields can produce the unfolded text decoded into utf8 strings. This is an expensive process, but the only correct way to get the field's data. More useful for people who are not living in ASCII space.

Studied fields

Studied fields have powerful methods to provide ways to access and produce the contents of (structured) fields exactly as the involved rfcs prescribe.

When you create a field, you may specify a string, object, or an array of strings and objects. On the moment, objects are only used to help the construction on e-mail addresses, however you may add some of your own.

The following rules (implemented in stringifyData()) are obeyed given the argument is:

a string

The string must be following the (complicated) rules of the rfc2822, and is made field content as specified. When the string is not terminated by a new-line ("\n") it will be folded according to the standard rules.

All Mail::Identity objects in the collection will be included in the field as a group carying the name of the collection.

any other object

For all other objects, the stringification overload is used to produce the field content.

an ARRAY

You may also specify an array with a mixture of any of the above. The elements will be joined as comma-separated list. If you do not want comma's inbetween, you will have to process the array yourself.

Fast objects are not derived from a Mail::Reporter. The consideration is that fields are so often created, and such a small objects at the same time, that setting-up a logging for each of the objects is relatively expensive and not really useful. The fast field implementation uses an array to store the data: that will be faster than using a hash. Fast fields are not easily inheritable, because the object creation and initiation is merged into one method.

With a full implementation of all applicable RFCs (about 5), the best understanding of the fields is reached. However, this comes with a serious memory and performance penalty. These objects are created from fast or flex header fields when study() is called.

A new field is being created which does contain characters not permitted by the RFCs. Using this field in messages may break other e-mail clients or transfer agents, and therefore mutulate or extinguish your message.

Fatal error: the specific package (or one of its superclasses) does not implement this method where it should. This message means that some other related classes do implement this method however the class at hand does not. Probably you should investigate this and probably inform the author of the package.