/ 
Mail-Box-2.023
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Message::Field

NAME

Mail::Message::Field - one line of a message header

CLASS INHERITANCE

Mail::Message::Field is a Mail::Reporter

Mail::Message::Field is extended by Mail::Message::Field::Fast Mail::Message::Field::Flex

SYNOPSIS

my $field = Mail::Message::Field->new(From => 'me@example.com');
print $field->name;
print $field->body;
print $field->comment;
print $field->content;  # body & comment
$field->print(\*OUT);
print $field->toString;
print "$field\n";
print $field->attribute('charset') || 'us-ascii';

DESCRIPTION

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 $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');

Header Fields

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.

A head line is composed of two parts separated by a color (:). Before the colon is called the name of the field, and the right part the body. In some lines, the body contains a semicolon (;) which indicates the start of something refered to as comment. This comment is often used to contain attributes: key-value pairs of information, which is of course much more important than simply accompanying text.

folding

Many implementations of mail transfer agents (MTAs) have problems with lines longer than 998 characters. Many implementations of mail user agents (MUAs) can not handle lines longer than 78 characters well. MTAs are programs which implement the SMTP protocol, like the sendmail command or a web-browser which sends e-mail. MUAs are programs which people use to read their e-mail, like mutt, elm, pine, or also a web-browser.

To avoid the problems with long lines, head lines are often folded into lines of 78 characters maximum. Longer lines are wrapped, in RFC-terms folded. On some places in the body of a field, a line-feed is inserted. The remaining part of the body is on the next line, which MUST be preceeded by at least one white-space (tab or blank)

Some fields are called structured: their structure is well-defined by the RFC. In these fields, their is more flexibility where folding may take place. Other fields only permit folding on white-spaces.

consideration

Mail::Message::Field is the only object in the Mail::Box suite which is 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.

For the same reason, the are two types of fields: the flexible and the fast:

  • Mail::Message::Field::Flex

    The flexible implementation uses a has to store the data. The new() and init are split, so this object is extensible.

  • Mail::Message::Field::Fast

    The fast implementation uses an array to store the same data. That will be faster. Furthermore, it is less extensible because the object creation and initiation is merged into one method.

As user of the object, there is not visible difference.

METHODS

Initiation

consume LINE | (NAME,BODY|OBJECTS)

(Class method) 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 be an application program.

new DATA

See Mail::Message::Field::Fast::new() or Mail::Message::Field::Flex::new(). By default, a Fast field is produced.

OPTION               DEFAULT
log                  'WARNINGS'
trace                'WARNINGS'
log => LEVEL

See Mail::Reporter::new(log)

trace => LEVEL

See Mail::Reporter::new(trace)

The Field

clone

Create a copy of this field object.

isStructured

(object method or class method)

Examples:

my $field = Mail::Message::Field->new(From => 'me');
if($field->isStructured)

Mail::Message::Field->isStructured('From');
length

Returns the total length of the field in characters, which includes the field's name, body and folding characters.

Access to the Field

Name

Returns the name of this field in original casing. See name() as well.

addresses

Returns a list of Mail::Address objects, which represent the e-mail addresses found in this header line.

Examples:

my @addr = $message->head->get('to')->addresses;
my @addr = $message->to;
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.

Examples:

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'); # sets field
body

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 aby case, the string is unfolded.

Whether the field is structured is defined by isStructured(). This method may be what you want, but usually, the folded_body() and unfolded_body() are what you are looking for.

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 attributes() on them.

dateToTimestamp STRING

(Class method) Convert a STRING which represents and RFC compliant time string into a timestamp like is produced by the time function.

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 folded_body() to get the same information without the field's name.

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

Examples:

my @lines = $field->folded;
print $field->folded;
print scalar $field->folded; # faster
folded_body [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.

name

Returns the name of this field, with all characters lower-cased for ease of comparison. See Name() as well.

nrLines

Returns the number of lines needed to display this header-line.

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.

size

Returns the number of bytes needed to display this header-line.

stripCFWS STRING

(Class method) Remove the comments and folding white spaces from the string.

toDate [TIME]

(Class method) Convert a timestamp into a MIME-acceptable date format. This differs from the default output of localtime in scalar context. Without argument, the localtime is used to get the current time. Be sure to have your timezone set right, especially when this script runs automatically.

Examples:

my $now = localtime;
Mail::Message::Field->toDate($now);

Mail::Message::Field->toDate(scalar localtime);
Mail::Message::Field->toDate;  # same
# returns someting like:  Wed, 28 Aug 2002 10:40:25 +0200
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::printUndisclosed()

toInt

Returns the value which is related to this field as integer. A check is performed whether this is right.

toString [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).

unfolded_body [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.

Examples:

my $body = $field->unfolded_body;
print "$field";   # via overloading
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.

Examples:

print Mail::Message::Field->Name('content-type') # Content-Type

my $field = $head->get('date');
print $field->Name;                              # Date

Reading and Writing [internals]

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.

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.

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.

Even without LENGTH this method is useful: the default wrap length will be enforced (re-folding will take place).

Examples:

$field->setWrapLength(99);
$field->setWrapLength;
unfold STRING

The reverse of fold(): all lines which form the body of a field are joined into one by removing all line terminators (even the last). The blank at the beginning of the first line is removed as well.

Logging and Tracing

defaultTrace [LEVEL, [LEVEL]

See Mail::Reporter::defaultTrace()

errors

See Mail::Reporter::errors()

log [LEVEL [,STRINGS]]

See Mail::Reporter::log()

report [LEVEL]

See Mail::Reporter::report()

reportAll [LEVEL]

See Mail::Reporter::reportAll()

trace [LEVEL]

See Mail::Reporter::trace()

warnings

See Mail::Reporter::warnings()

Other Methods

AUTOLOAD

See Mail::Reporter::AUTOLOAD()

DESTROY

See Mail::Reporter::DESTROY()

inGlobalDestruction

See Mail::Reporter::inGlobalDestruction()

logPriority LEVEL

See Mail::Reporter::logPriority()

logSettings

See Mail::Reporter::logSettings()

notImplemented

See Mail::Reporter::notImplemented()

SEE ALSO

A good start to read is Mail::Box-Overview. More documentation and a mailinglist are available from the project's website at http://perl.overmeer.net/mailbox/.

AUTHOR

Mark Overmeer (mark@overmeer.net) with the help of many.

VERSION

This code is beta, version 2.023.

Copyright (c) 2001-2002 Mark Overmeer. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.