Provided by: libmail-box-perl_2.110-1_all 
NAME
Mail::Message::Field - one line of a message header
INHERITANCE
Mail::Message::Field
is a Mail::Reporter
Mail::Message::Field is extended by
Mail::Message::Field::Fast
Mail::Message::Field::Flex
Mail::Message::Field::Full
SYNOPSIS
my $field = Mail::Message::Field->new(From => 'fish@tux.aq');
print $field->name;
print $field->body;
print $field->comment;
print $field->content; # body & comment
$field->print(\*OUT);
print $field->string;
print "$field\n";
print $field->attribute('charset') || 'us-ascii';
DESCRIPTION
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:
my @from = $message->from;
my $sender = $message->sender;
my $subject = $message->subject;
my $msgid = $message->messageId;
my @to = $message->to;
my @cc = $message->cc;
my @bcc = $message->bcc;
my @dest = $message->destinations;
my $other = $message->get('Reply-To');
See documentation in the base class.
OVERLOADED
overload: ""()
(stringification) produces the unfolded body of the field, which may be what you expect. This is
what makes what the field object seems to be a simple string. The string is produced by
unfoldedBody().
example:
print $msg->get('subject'); # via overloading
print $msg->get('subject')->unfoldedBody; # same
my $subject = $msg->get('subject') || 'your mail';
print "Re: $subject\n";
overload: 0+()
(numification) When the field is numeric, the value will be returned. The result is produced by
toInt(). If the value is not correct, a 0 is produced, to simplify calculations.
overload: <=>()
(numeric comparison) Compare the integer field contents with something else.
example:
if($msg->get('Content-Length') > 10000) ...
if($msg->size > 10000) ... ; # same, but better
overload: bool()
Always true, to make it possible to say "if($field)".
overload: cmp()
(string comparison) Compare the unfolded body of a field with an other field or a string, using the
buildin "cmp".
METHODS
See documentation in the base class.
Constructors
See documentation in the base class.
$obj->clone()
Create a copy of this field object.
Mail::Message::Field->new(DATA)
See Mail::Message::Field::Fast::new(), Mail::Message::Field::Flex::new(), and
Mail::Message::Field::Full::new(). By default, a "Fast" field is produced.
-Option--Defined in --Default
log Mail::Reporter 'WARNINGS'
trace Mail::Reporter 'WARNINGS'
log => LEVEL
trace => LEVEL
The field
$obj->isStructured()
Mail::Message::Field->isStructured()
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.
example:
my $field = Mail::Message::Field->new(From => 'me');
if($field->isStructured)
Mail::Message::Field->isStructured('From');
$obj->length()
Returns the total length of the field in characters, which includes the field's name, body and
folding characters.
$obj->nrLines()
Returns the number of lines needed to display this header-line.
$obj->print([FILEHANDLE])
Print the whole header-line to the specified file-handle. One line may result in more than one
printed line, because of the folding of long lines. The FILEHANDLE defaults to the selected handle.
$obj->size()
Returns the number of bytes needed to display this header-line, Same as length().
$obj->string([WRAP])
Returns the field as string. By default, this returns the same as folded(). However, the optional
WRAP will cause to re-fold to take place (without changing the folding stored inside the field).
$obj->toDisclose()
Returns whether this field can be disclosed to other people, for instance when sending the message to
an other party. Returns a "true" or "false" condition. See also
Mail::Message::Head::Complete::printUndisclosed().
Access to the name
$obj->Name()
Returns the name of this field in original casing. See name() as well.
$obj->name()
Returns the name of this field, with all characters lower-cased for ease of comparison. See Name()
as well.
$obj->wellformedName([STRING])
(Instance method class method) As instance method, the current field's name is correctly formatted
and returned. When a STRING is used, that one is formatted.
example:
print Mail::Message::Field->Name('content-type')
# --> Content-Type
my $field = $head->get('date');
print $field->Name;
# --> Date
Access to the body
$obj->body()
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().
$obj->folded()
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...
example:
my @lines = $field->folded;
print $field->folded;
print scalar $field->folded; # faster
$obj->foldedBody([BODY])
Returns the body as a set of lines. In scalar context, this will be one line containing newlines. Be
warned about the newlines when you do pattern-matching on the result of thie method.
The optional BODY argument changes the field's body. The folding of the argument must be correct.
$obj->stripCFWS([STRING])
Mail::Message::Field->stripCFWS([STRING])
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.
$obj->unfoldedBody([BODY, [WRAP]])
Returns the body as one single line, where all folding information (if available) is removed. This
line will also NOT end on a new-line.
The optional BODY argument changes the field's body. The right folding is performed before
assignment. The WRAP may be specified to enforce a folding size.
example:
my $body = $field->unfoldedBody;
print "$field"; # via overloading
Access to the content
$obj->addresses()
Returns a list of Mail::Address objects, which represent the e-mail addresses found in this header
line.
example:
my @addr = $message->head->get('to')->addresses;
my @addr = $message->to;
$obj->attribute(NAME [, VALUE])
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.
example:
my $field = Mail::Message::Field->new(
'Content-Type: text/plain; charset="us-ascii"');
print $field->attribute('charset');
# --> us-ascii
print $field->attribute('bitmap') || 'no'
# --> no
$field->atrribute(filename => '/tmp/xyz');
$field->print;
# --> Content-Type: text/plain; charset="us-ascii";
# filename="/tmp/xyz"
# Automatically folded, and no doubles created.
$obj->attributes()
Returns a list of key-value pairs, where the values are not yet decoded.
example:
my %attributes = $head->get('Content-Disposition')->attributes;
$obj->comment([STRING])
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.
$obj->study()
Study the header field in detail: turn on the full parsing and detailed understanding of the content
of the fields. Mail::Message::Field::Fast and Mail::Message::Field::Fast objects will be transformed
into any Mail::Message::Field::Full object.
example:
my $subject = $msg->head->get('subject')->study;
my $subject = $msg->head->study('subject'); # same
my $subject = $msg->study('subject'); # same
$obj->toDate([TIME])
Mail::Message::Field->toDate([TIME])
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.
example:
my $now = time;
Mail::Message::Field->toDate($now);
Mail::Message::Field->toDate(time);
Mail::Message::Field->toDate(localtime);
Mail::Message::Field->toDate; # same
# returns someting like:
# Wed, 28 Aug 2002 10:40:25 +0200
$obj->toInt()
Returns the value which is related to this field as integer. A check is performed whether this is
right.
Other methods
$obj->dateToTimestamp(STRING)
Mail::Message::Field->dateToTimestamp(STRING)
Convert a STRING which represents and RFC compliant time string into a timestamp like is produced by
the "time" function.
Internals
$obj->consume(LINE | (NAME,BODY|OBJECTS))
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".
$obj->defaultWrapLength([LENGTH])
Any field from any header for any message will have this default wrapping. This is maintained in one
global variable. Without a specified LENGTH, the current value is returned. The default is 78.
$obj->fold(NAME, BODY, [MAXCHARS])
Mail::Message::Field->fold(NAME, BODY, [MAXCHARS])
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.
$obj->setWrapLength([LENGTH])
Force the wrapping of this field to the specified LENGTH characters. The wrapping is performed with
fold() and the results stored within the field object.
example: refolding the field
$field->setWrapLength(99);
$obj->stringifyData(STRING|ARRAY|OBJECTS)
This method implements the translation of user supplied objects into ascii fields. The process is
explained in "Specifying field data".
$obj->unfold(STRING)
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.
Error handling
See documentation in the base class.
$obj->AUTOLOAD()
See "Error handling" in Mail::Reporter
$obj->addReport(OBJECT)
See "Error handling" in Mail::Reporter
$obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
Mail::Message::Field->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
See "Error handling" in Mail::Reporter
$obj->errors()
See "Error handling" in Mail::Reporter
$obj->log([LEVEL [,STRINGS]])
Mail::Message::Field->log([LEVEL [,STRINGS]])
See "Error handling" in Mail::Reporter
$obj->logPriority(LEVEL)
Mail::Message::Field->logPriority(LEVEL)
See "Error handling" in Mail::Reporter
$obj->logSettings()
See "Error handling" in Mail::Reporter
$obj->notImplemented()
See "Error handling" in Mail::Reporter
$obj->report([LEVEL])
See "Error handling" in Mail::Reporter
$obj->reportAll([LEVEL])
See "Error handling" in Mail::Reporter
$obj->trace([LEVEL])
See "Error handling" in Mail::Reporter
$obj->warnings()
See "Error handling" in Mail::Reporter
Cleanup
See documentation in the base class.
$obj->DESTROY()
See "Cleanup" in Mail::Reporter
DETAILS
Field syntax
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.
Folding fields
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.
Structured fields
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().
Comments in fields
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.
Getting a field
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.
Using get() field
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.
Using study() field
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.
The Mail::Message::study() method will only return the last field with that name as object.
Mail::Message::Head::study() and Mail::Message::Field::study() return all fields when used in list
context.
Using resent groups
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.
The field's data
There are many ways to get the fields info as object, and there are also many ways to process this data
within the field.
Access to the field
• string()
Returns the text of the body exactly as will be printed to file when print() is called, so name, main
body, and attributes.
• foldedBody()
Returns the text of the body, like string(), but without the name of the field.
• unfoldedBody()
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.
• stripCFWS()
Returns the text of structured fields, where new-lines and comments are removed from the string.
This is a good start for parsing the field, for instance to find e-mail addresses in them.
• Mail::Message::Field::Full::decodedBody()
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.
Using simplified field access
Some fields are accessed that often that there are support methods to provide simplified access. All
these methods are called upon a message directly.
Specifying field data
Field data can be anything, strongly dependent on the type of field at hand. If you decide to contruct
the fields very carefully via some Mail::Message::Field::Full extension (like via
Mail::Message::Field::Addresses objects), then you will have protection build-in. However, you can
bluntly create any Mail::Message::Field object based on some data.
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.
• a Mail::Address object
The most used Perl object to parse and produce address lines. This object does not understand
character set encodings in phrases.
• a Mail::Identity object
As part of the User::Identity distribution, this object has full understanding of the meaning of one
e-mail address, related to a person. All features defined by rfc2822 are implemented.
• a User::Identity object
A person is specified, which may have more than one Mail::Identity's defined. Some methods, like
Mail::Message::reply() and Mail::Message::forward() try to select the right e-mail address smart (see
their method descriptions), but in other cases the first e-mail address found is used.
• a User::Identity::Collection::Emails object
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.
Field class implementation
For performance reasons only, there are three types of fields: the fast, the flexible, and the full
understander:
• Mail::Message::Field::Fast
"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.
• Mail::Message::Field::Flex
The flexible implementation uses a hash to store the data. The new() and "init" methods are split,
so this object is extensible.
• Mail::Message::Field::Full
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.
DIAGNOSTICS
Warning: Field content is not numerical: $content
The numeric value of a field is requested (for instance the "Lines" or "Content-Length" fields should
be numerical), however the data contains weird characters.
Warning: Illegal character in field name $name
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.
Error: Package $package does not implement $method.
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.
SEE ALSO
This module is part of Mail-Box distribution version 2.110, built on January 05, 2014. Website:
http://perl.overmeer.net/mailbox/
LICENSE
Copyrights 2001-2014 by [Mark Overmeer]. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl
itself. See http://www.perl.com/perl/misc/Artistic.html
perl v5.18.1 2014-01-05 Mail::Message::Field(3pm)