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 METHODS in Mail::Reporter

Constructors

$obj->clone

Create a copy of this field object.

$class->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
$class->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] )
$class->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] )
$class->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.

» 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.

Other methods

$obj->dateToTimestamp( STRING )
$class->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.

» 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.

$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] )
$class->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

$obj->AUTOLOAD
See AUTOLOAD in Mail::Reporter.
$obj->addReport( OBJECT )
See addReport in Mail::Reporter.
$obj->defaultTrace( [LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK] )
$class->defaultTrace( [LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK] )
See defaultTrace in Mail::Reporter.
$obj->errors
See errors in Mail::Reporter.
$obj->log( [LEVEL [,STRINGS]] )
$class->log( [LEVEL [,STRINGS]] )
See log in Mail::Reporter.
$obj->logPriority( LEVEL )
$class->logPriority( LEVEL )
See logPriority in Mail::Reporter.
$obj->logSettings
See logSettings in Mail::Reporter.
$obj->notImplemented
See notImplemented in Mail::Reporter.
$obj->report( [LEVEL] )
See report in Mail::Reporter.
$obj->reportAll( [LEVEL] )
See reportAll in Mail::Reporter.
$obj->trace( [LEVEL] )
See trace in Mail::Reporter.
$obj->warnings
See warnings in Mail::Reporter.

Cleanup

$obj->DESTROY
See DESTROY in Mail::Reporter.