Mail::Message::Field - one line of a message header
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
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';
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');
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.
$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
$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().
$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
$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
$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.
$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.
$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.
$obj->AUTOLOAD
See Mail::Reporter/"Error handling"
$obj->addReport(OBJECT)
See Mail::Reporter/"Error handling"
$obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
Mail::Message::Field->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
See Mail::Reporter/"Error handling"
$obj->errors
See Mail::Reporter/"Error handling"
$obj->log([LEVEL [,STRINGS]])
Mail::Message::Field->log([LEVEL [,STRINGS]])
See Mail::Reporter/"Error handling"
$obj->logPriority(LEVEL)
Mail::Message::Field->logPriority(LEVEL)
See Mail::Reporter/"Error handling"
$obj->logSettings
See Mail::Reporter/"Error handling"
$obj->notImplemented
See Mail::Reporter/"Error handling"
$obj->report([LEVEL])
See Mail::Reporter/"Error handling"
$obj->reportAll([LEVEL])
See Mail::Reporter/"Error handling"
$obj->trace([LEVEL])
See Mail::Reporter/"Error handling"
$obj->warnings
See Mail::Reporter/"Error handling"
$obj->DESTROY
$obj->inGlobalDestruction
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 preceeded by
blanks, but followed by one blank). Each attribute is preceeded by
a separate semi-colon (";"). Names of fields are case-insensitive and
cannot contain blanks.
example: of fields
Correct fields:
Field: hi! Content-Type: text/html; charset=latin1
Incorrect fields, but accepted:
Field : wrong, blank before colon Field: # wrong, empty Field:not nice, blank preferred after colon One Two: wrong, blank in name
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.
example: of field folding
Subject: this is a short line, and not folded Subject: this subject field is much longer, and therefore folded into multiple lines, although one more than needed.
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.
example: of field comments
To: mailbox (Mail::Box mailinglist) <mailbox@overmeer.net> Date: Thu, 13 Sep 2001 09:40:48 +0200 (CEST) Subject: goodbye (was: hi!)
On the first line, the text "Mail::Box mailinglist" is used as comment. Be warned that rfc2822 explicitly states that comments in e-mail address specifications should not be considered to contain any usable information.
On the second line, the timezone is specified as comment. The Date
field format has no way to indicate the timezone of the sender, but only
contains the timezone difference to UTC, however one could decide to add
this as comment. Application must ignore this data because the Date
field is structured.
The last field is unstructured. The text between parantheses is an integral part of the subject line.
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.
example: of using get()
print $msg->get('subject') || 'no subject';
print $msg->head->get('subject') || 'no subject';
my @to = $msg->head->get('to');
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.
example: of using study()
print $msg->study('subject') || 'no subject';
my @rec = $msg->head->study('Received');
my $from = $msg->head->get('From')->study;
my $from = $msg->head->study('From'); # same
my @addr = $from->addresses;
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.
example: of using resent groups
my $rgs = $msg->head->resentGroups; $rgs[0]->delete if @rgs; $msg->head->removeResentGroups;
There are many ways to get the fields info as object, and there are also many ways to process this data within the field.
Some fields are accessed that often that there are support methods to provide simplified access. All these methods are called upon a message directly.
example: of simplified field access
print $message->subject;
print $message->get('subject') || ''; # same
my @from = $message->from; # returns addresses
$message->reply->send if $message->sender;
The sender method will return the address specified in the Sender
field, or the first named in the From field. It will return undef
in case no address is known.
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:
"\n") it will be folded according to the standard rules.
example: specifying simple field data
my $f = Mail::Message::Field->new(Subject => 'hi!'); my $b = Mail::Message->build(Subject => 'monkey');
example: s specifying e-mail addresses for a field
use Mail::Address;
my $fish = Mail::Address->new('Mail::Box', 'fish@tux.aq');
print $fish->format; # ==> Mail::Box <fish@tux.aq>
my $exa = Mail::Address->new(undef, 'me@example.com');
print $exa->format; # ==> me@example.com
my $b = $msg->build(To => "you@example.com");
my $b = $msg->build(To => $fish);
my $b = $msg->build(To => [ $fish, $exa ]);
my @all = ($fish, "you@example.com", $exa);
my $b = $msg->build(To => \@all);
my $b = $msg->build(To => [ "xyz", @all ]);
example: specifying identities for a field
use User::Identity;
my $patrik = User::Identity->new
( name => 'patrik'
, full_name => "Patrik Fältström" # from rfc
, charset => "ISO-8859-1"
);
$patrik->add
( email => "him@home.net"
);
my $b = $msg->build(To => $patrik);
$b->get('To')->print;
# ==> =?ISO-8859-1?Q?Patrik_F=E4ltstr=F6m?=
# <him@home.net>
For performance reasons only, there are three types of fields: the fast, the flexible, and the full understander:
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.
init methods are split, so this object is extensible.
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.
This module is part of Mail-Box distribution version 2.082, built on April 28, 2008. Website: http://perl.overmeer.net/mailbox/
Copyrights 2001-2008 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