=head1 NAME
Mail::Message::Field - one line of a message header
=head1 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
=head1 SYNOPSIS
my
$field
= Mail::Message::Field->new(
From
=>
'fish@tux.aq'
);
print
$field
->name;
print
$field
->body;
print
$field
->comment;
print
$field
->content;
$field
->
print
(\
*OUT
);
print
$field
->string;
print
"$field\n"
;
print
$field
->attribute(
'charset'
) ||
'us-ascii'
;
=head1 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'
);
=head1 OVERLOADED
overload: B<
""
>
=over 4
(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 L<unfoldedBody()|Mail::Message::Field/
"Access to the body"
>.
example:
print
$msg
->get(
'subject'
);
print
$msg
->get(
'subject'
)->unfoldedBody;
my
$subject
=
$msg
->get(
'subject'
) ||
'your mail'
;
print
"Re: $subject\n"
;
=back
overload: B<+0>
=over 4
(numification) When the field is numeric, the value will be returned.
The result is produced by L<toInt()|Mail::Message::Field/
"Access to the content"
>. If the value is not correct,
a C<0> is produced, to simplify calculations.
=back
overload: B<<=>>
=over 4
(numeric comparison) Compare the integer field contents
with
something
else
.
example:
if
(
$msg
->get(
'Content-Length'
) > 10000) ...
if
(
$msg
->size > 10000) ... ;
=back
overload: B<bool>
=over 4
Always true, to make it possible to
say
C<
if
(
$field
)>.
=back
overload: B<cmp>
=over 4
(string comparison) Compare the unfolded body of a field
with
an other
field or a string, using the buildin C<cmp>.
=back
=head1 METHODS
=head2 Constructors
$obj
-E<gt>B<clone>
=over 4
Create a copy of this field object.
=back
Mail::Message::Field-E<gt>B<new>(DATA)
=over 4
See L<Mail::Message::Field::Fast::new()|Mail::Message::Field::Fast/
"METHODS"
>,
L<Mail::Message::Field::Flex::new()|Mail::Message::Field::Flex/
"METHODS"
>,
and L<Mail::Message::Field::Full::new()|Mail::Message::Field::Full/
"METHODS"
>.
By
default
, a C<Fast> field is produced.
Option--Defined in --Default
log
Mail::Reporter
'WARNINGS'
trace Mail::Reporter
'WARNINGS'
.
log
=> LEVEL
.
trace
=> LEVEL
=back
=head2 The field
$obj
-E<gt>B<isStructured>
Mail::Message::Field-E<gt>B<isStructured>
=over 4
Some fields are described in the RFCs as being I<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 C<Subject> field.
example:
my
$field
= Mail::Message::Field->new(
From
=>
'me'
);
if
(
$field
->isStructured)
Mail::Message::Field->isStructured(
'From'
);
=back
$obj
-E<gt>B<
length
>
=over 4
Returns the total
length
of the field in characters, which includes the
field's name, body and folding characters.
=back
$obj
-E<gt>B<nrLines>
=over 4
Returns the number of lines needed to display this header-line.
=back
$obj
-E<gt>B<
print
>([FILEHANDLE])
=over 4
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.
=back
$obj
-E<gt>B<size>
=over 4
Returns the number of bytes needed to display this header-line, Same
as L<
length
()|Mail::Message::Field/
"The field"
>.
=back
$obj
-E<gt>B<string>([WRAP])
=over 4
Returns the field as string. By
default
, this returns the same as
L<folded()|Mail::Message::Field/
"Access to the body"
>. However, the optional WRAP will cause to re-fold to take
place (without changing the folding stored inside the field).
=back
$obj
-E<gt>B<toDisclose>
=over 4
Returns whether this field can be disclosed to other people,
for
instance
when
sending the message to an other party. Returns a C<true> or C<false>
condition.
See also L<Mail::Message::Head::Complete::printUndisclosed()|Mail::Message::Head::Complete/
"Access to the header"
>.
=back
=head2 Access to the name
$obj
-E<gt>B<Name>
=over 4
Returns the name of this field in original casing. See L<name()|Mail::Message::Field/
"Access to the name"
> as well.
=back
$obj
-E<gt>B<name>
=over 4
Returns the name of this field,
with
all characters lower-cased
for
ease of comparison. See L<Name()|Mail::Message::Field/
"Access to the name"
> as well.
=back
$obj
-E<gt>B<wellformedName>([STRING])
=over 4
(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'
)
my
$field
=
$head
->get(
'date'
);
print
$field
->Name;
=back
=head2 Access to the body
$obj
-E<gt>B<body>
=over 4
This method may be what you want, but usually, the L<foldedBody()|Mail::Message::Field/
"Access to the body"
> and
L<unfoldedBody()|Mail::Message::Field/
"Access to the body"
> 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 B<stripped> from everything what is behind the first semi-color (C<;>).
In any case, the string is unfolded.
Whether the field is structured is
defined
by L<isStructured()|Mail::Message::Field/
"The field"
>.
=back
$obj
-E<gt>B<folded>
=over 4
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 L<foldedBody()|Mail::Message::Field/
"Access to the body"
> 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;
=back
$obj
-E<gt>B<foldedBody>([BODY])
=over 4
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.
=back
$obj
-E<gt>B<stripCFWS>([STRING])
Mail::Message::Field-E<gt>B<stripCFWS>([STRING])
=over 4
Remove the I<comments> and I<folding white spaces> from the STRING. Without
string and only as instance method, the L<unfoldedBody()|Mail::Message::Field/
"Access to the body"
> 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.
=back
$obj
-E<gt>B<unfoldedBody>([BODY, [WRAP]])
=over 4
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"
;
=back
=head2 Access to the content
$obj
-E<gt>B<addresses>
=over 4
Returns a list of L<Mail::Address|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;
=back
$obj
-E<gt>B<attribute>(NAME [, VALUE])
=over 4
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 C<
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'
);
print
$field
->attribute(
'bitmap'
) ||
'no'
$field
->atrribute(
filename
=>
'/tmp/xyz'
);
$field
->
print
;
=back
$obj
-E<gt>B<attributes>
=over 4
Returns a list of key-value pairs, where the
values
are not yet decoded.
example:
my
%attributes
=
$head
->get(
'Content-Disposition'
)->attributes;
=back
$obj
-E<gt>B<comment>([STRING])
=over 4
Returns the unfolded comment (part
after
a semi-colon) in a structureed
header-line. optionally
after
setting it to a new STRING first.
When C<
undef
> is specified as STRING, the comment is removed.
Whether the field is structured is
defined
by L<isStructured()|Mail::Message::Field/
"The field"
>.
The I<comment> part of a header field often contains C<attributes>. Often
it is preferred to
use
L<attribute()|Mail::Message::Field/
"Access to the content"
> on them.
=back
$obj
-E<gt>B<
study
>
=over 4
Study the header field in detail: turn on the full parsing and detailed
understanding of the content of the fields. L<Mail::Message::Field::Fast|Mail::Message::Field::Fast>
and L<Mail::Message::Field::Fast|Mail::Message::Field::Fast> objects will be transformed into any
L<Mail::Message::Field::Full|Mail::Message::Field::Full> object.
example:
my
$subject
=
$msg
->head->get(
'subject'
)->
study
;
my
$subject
=
$msg
->head->
study
(
'subject'
);
my
$subject
=
$msg
->
study
(
'subject'
);
=back
$obj
-E<gt>B<toDate>([TIME])
Mail::Message::Field-E<gt>B<toDate>([TIME])
=over 4
Convert a timestamp into an rfc2822 compliant date
format
. This differs
from the
default
output of C<
localtime
> in
scalar
context. Without
argument, the C<
localtime
> is used to get the current
time
. TIME can
be specified as one numeric (like the result of C<
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;
=back
$obj
-E<gt>B<toInt>
=over 4
Returns the value which is related to this field as integer. A check is
performed whether this is right.
=back
=head2 Other methods
$obj
-E<gt>B<dateToTimestamp>(STRING)
Mail::Message::Field-E<gt>B<dateToTimestamp>(STRING)
=over 4
Convert a STRING which represents and RFC compliant
time
string into
a timestamp like is produced by the C<
time
> function.
=back
=head2 Internals
$obj
-E<gt>B<consume>(LINE | (NAME,BODY|OBJECTS))
=over 4
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 L<new()|Mail::Message::Field/
"Constructors"
>, and usually not by an application
program. The details about converting the OBJECTS to a field content
are explained in L</Specifying field data>.
=back
$obj
-E<gt>B<defaultWrapLength>([LENGTH])
=over 4
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.
=back
$obj
-E<gt>B<fold>(NAME, BODY, [MAXCHARS])
Mail::Message::Field-E<gt>B<fold>(NAME, BODY, [MAXCHARS])
=over 4
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.
=back
$obj
-E<gt>B<setWrapLength>([LENGTH])
=over 4
Force the wrapping of this field to the specified LENGTH characters. The
wrapping is performed
with
L<fold()|Mail::Message::Field/
"Internals"
> and the results stored within
the field object.
example: refolding the field
$field
->setWrapLength(99);
=back
$obj
-E<gt>B<stringifyData>(STRING|ARRAY|OBJECTS)
=over 4
This method implements the translation of user supplied objects into
ascii fields. The process is explained in L</Specifying field data>.
=back
$obj
-E<gt>B<unfold>(STRING)
=over 4
The
reverse
action of L<fold()|Mail::Message::Field/
"Internals"
>: 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.
=back
=head2 Error handling
$obj
-E<gt>B<AUTOLOAD>
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<addReport>(OBJECT)
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<defaultTrace>([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
Mail::Message::Field-E<gt>B<defaultTrace>([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<errors>
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<
log
>([LEVEL [,STRINGS]])
Mail::Message::Field-E<gt>B<
log
>([LEVEL [,STRINGS]])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<logPriority>(LEVEL)
Mail::Message::Field-E<gt>B<logPriority>(LEVEL)
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<logSettings>
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<notImplemented>
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<report>([LEVEL])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<reportAll>([LEVEL])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<trace>([LEVEL])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<warnings>
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
=head2 Cleanup
$obj
-E<gt>B<DESTROY>
=over 4
See L<Mail::Reporter/
"Cleanup"
>
=back
$obj
-E<gt>B<inGlobalDestruction>
=over 4
See L<Mail::Reporter/
"Cleanup"
>
=back
=head1 DETAILS
=head2 Field syntax
Fields are stored in the header of a message, which are represented by
L<Mail::Message::Head|Mail::Message::Head> objects. A field is a combination of a I<name>,
I<body>, and I<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 (
"C<:>"
, not preceeded by
blanks, but followed by one blank). Each attribute is preceeded by
a separate semi-colon (
"C<;>"
). 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:
Field:not nice, blank preferred
after
colon
One Two: wrong, blank in name
=head3 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 C<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.
=head3 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 C<Subject>
field, the meaning is straight forward the contents itself. These fields
are the I<Unstructured Fields>.
Other fields have a well
defined
internal syntax because their content is
needed by e-mail applications. For instance, the C<To> field contains
addresses which must be understood by all applications in the same way.
These are the I<Structured Fields>, see L<isStructured()|Mail::Message::Field/
"The field"
>.
=head3 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.
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 C<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 C<Date>
field is structured.
The
last
field is unstructured. The text between parantheses is an
integral part of the subject line.
=head2 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.
=head3 Using get() field
The C<get()> interface is copied from other Perl modules which can
handle e-mail messages. Many applications which simply replace
L<Mail::Internet|Mail::Internet> objects by L<Mail::Message|Mail::Message> objects will work
without modification.
There is more than one get method. The exact results depend on which
get you
use
. When L<Mail::Message::get()|Mail::Message/
"The header"
> is called, you will get the
unfolded, stripped from comments, stripped from attributes contents of
the field as B<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 L<Mail::Message::Head::get()|Mail::Message::Head/
"Access to the header"
> is called in
scalar
context, the
last
field
with
the specified name is returned as field B<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, C<To> fields can appear more than once.
If your program calls C<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'
);
=head3 Using
study
() field
As the name C<
study
> already implies, this way of accessing the fields is
much more thorough but also slower. The C<
study
> of a field is like a
C<get>, but provides easy access to the content of the field and handles
character-set decoding correctly.
The L<Mail::Message::
study
()|Mail::Message/
"The header"
> method will only
return
the
last
field
with
that name as object. L<Mail::Message::Head::
study
()|Mail::Message::Head/
"Access to the header"
> and
L<Mail::Message::Field::
study
()|Mail::Message::Field/
"Access to the content"
>
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'
);
my
@addr
=
$from
->addresses;
=head3 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 C<Received> line, and optionally some C<Resent-*> lines and
C<Return-Path>. These groups of lines shall stay together and in order
when
the message header is processed.
The C<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;
=head2 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.
=head3 Access to the field
=over 4
=item * L<string()|Mail::Message::Field/
"The field"
>
Returns the text of the body exactly as will be printed to file
when
L<
print
()|Mail::Message::Field/
"The field"
> is called, so name, main body, and attributes.
=item * L<foldedBody()|Mail::Message::Field/
"Access to the body"
>
Returns the text of the body, like L<string()|Mail::Message::Field/
"The field"
>, but without the name of
the field.
=item * L<unfoldedBody()|Mail::Message::Field/
"Access to the body"
>
Returns the text of the body, like L<foldedBody()|Mail::Message::Field/
"Access to the body"
>, 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.
=item * L<stripCFWS()|Mail::Message::Field/
"Access to the body"
>
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.
=item * L<Mail::Message::Field::Full::decodedBody()|Mail::Message::Field::Full/
"Access to the body"
>
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.
=item * 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.
=back
=head3 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.
example: of simplified field access
print
$message
->subject;
print
$message
->get(
'subject'
) ||
''
;
my
@from
=
$message
->from;
$message
->reply->
send
if
$message
->sender;
The C<sender> method will
return
the address specified in the C<Sender>
field, or the first named in the C<From> field. It will
return
C<
undef
>
in case
no
address is known.
=head3 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 L<Mail::Message::Field::Full|Mail::Message::Field::Full> extension (like via
L<Mail::Message::Field::Addresses|Mail::Message::Field::Addresses> objects), then you will have protection
build-in. However, you can bluntly create any L<Mail::Message::Field|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 L<stringifyData()|Mail::Message::Field/
"Internals"
>) are obeyed
given
the argument is:
=over 4
=item * 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 (C<
"\n"
>) it will be folded according to the standard rules.
=item * a L<Mail::Address|Mail::Address> object
The most used Perl object to parse and produce address lines. This object
does not understand character set encodings in phrases.
=item * a L<Mail::Identity|Mail::Identity> object
As part of the L<User::Identity|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.
=item * a L<User::Identity|User::Identity> object
A person is specified, which may have more than one L<Mail::Identity|Mail::Identity>'s
defined
. Some methods, like L<Mail::Message::reply()|Mail::Message::Construct::Reply/
"Constructing a message"
> and
L<Mail::Message::forward()|Mail::Message::Construct::Forward/
"Constructing a message"
>
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.
=item * a L<User::Identity::Collection::Emails|User::Identity::Collection::Emails> object
All L<Mail::Identity|Mail::Identity> objects in the collection will be included in
the field as a group carying the name of the collection.
=item * any other object
For all other objects, the stringification overload is used to produce
the field content.
=item * 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.
=back
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
my
$fish
= Mail::Address->new(
'Mail::Box'
,
'fish@tux.aq'
);
print
$fish
->
format
;
my
$exa
= Mail::Address->new(
undef
,
'me@example.com'
);
print
$exa
->
format
;
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
my
$patrik
= User::Identity->new
(
name
=>
'patrik'
,
full_name
=>
"Patrik Fältström"
,
charset
=>
"ISO-8859-1"
);
$patrik
->add
(
email
=>
"him@home.net"
);
my
$b
=
$msg
->build(
To
=>
$patrik
);
$b
->get(
'To'
)->
print
;
=head2 Field class implementation
For performance reasons only, there are three types of fields: the
fast, the flexible, and the full understander:
=over 4
=item * L<Mail::Message::Field::Fast|Mail::Message::Field::Fast>
C<Fast> objects are not derived from a C<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.
=item * L<Mail::Message::Field::Flex|Mail::Message::Field::Flex>
The flexible implementation uses a hash to store the data. The L<new()|Mail::Message::Field/
"Constructors"
>
and C<init> methods are
split
, so this object is extensible.
=item * L<Mail::Message::Field::Full|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
L<
study
()|Mail::Message::Field/
"Access to the content"
> is called.
=back
=head1 DIAGNOSTICS
Warning: Field content is not numerical:
$content
=over 4
The numeric value of a field is requested (
for
instance the C<Lines> or
C<Content-Length> fields should be numerical), however the data contains
weird characters.
=back
Warning: Illegal character in field name
$name
=over 4
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.
=back
Error: Package
$package
does not implement
$method
.
=over 4
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
.
=back
=head1 SEE ALSO
This module is part of Mail-Box distribution version 2.081,
=head1 LICENSE
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.