Mail::Message::Field - one line of a message header Mail::Message::Field is a Mail::Reporter 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'; 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');

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: The flexible implementation uses a has to store the data. The "new" and "init" are split, so this object is extendible. The fast implementation uses an array to store the same data. That will be faster. Furthermore, it is less extendible because the object creation and initiation is merged into one method. As user of the object, there is not visible difference. The general methods for "Mail::Message::Field" objects: addresses new ... attribute NAME [, VALUE] print [FILEHANDLE] body toDate TIME comment [STRING] toInt content toString folded [ARRAY-OF-LINES] wellformedName ... name The extra methods for extension writers: clone nrLines isStructured setWrapLength CHARS newNoCheck NAME, BODY, COMM... size Create a new header-object. Specify the whole header-LINE at once, and it will be split-up for you. I case you already have the parts of the header-line, you may specify them. In structured fields (a list of pre-defined fields are considered to have a well-described format, checked with the "isStructured" method) everything behind a semi-color is officially a COMMENT. The comment is often (ab)used to supply extra information about the body information. When the field you specify is structured, and you do not specify a comment yourself, it will be stripped from the LINE or BODY for you. To keep the communication overlead low (there are too many of these field-objects to be created), the OPTIONS may be specified as last argument to "new", but as reference to an array. There are no options defined yet, but they may appear in the future. In case you specify a single OBJECT, or a reference to an array of OBJECTS, these objects are processed to become suitable to fill a field. When you specify one or more "Mail::Address" objects, these are tranformed into a string using their "format" method. You may also add one "Mail::Message::Field", which body is taken. For other objects, stringification is tried. In case of an array, the elements are joined with a comma. Examples: my @options = (log => 'NOTICE', trace => 'NONE'); my $mime = Mail::Message::Field->new( 'Content-Type: text/plain; charset=US-ASCII', \@options); my $mime = Mail::Message::Field->new( 'Content-Type' => 'text/plain; charset=US-ASCII'); my $mime = Mail::Message::Field->new( 'Content-Type' => 'text/plain', 'charset=US-ASCII'); my $mime = Mail::Message::Field->new( To => Mail::Address->new('my name', 'me@example.com'); my $mime = Mail::Message::Field->new( Cc => [ Mail::Address->new('your name', 'you@example.com') , Mail::Address->new('his name', 'he@example.com') ]); But, more often, you would call my $head = Mail::Message::Head->new; $head->add('Content-Type' => 'text/plain; charset=US-ASCII'); which implicitly calls this constructor (when needed). You can specify the same things for "add" as this "new" accepts. Returns the name of this field, with all characters lower-cased for ease of comparison. (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 Returns the body of the field, unmodified but stripped from comment and CR LF characters (as far as were present at creation). Returns the comment (part after a semi-colon) in the header-line, optionally after setting it to a new value first. Returns the body and comment part of the field, separated by a semi-colon. Returns the folded version of the 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 a blank. 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. For instance 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 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. Returns the whole header-line. Example: my @lines = $field->toString; print $field->toString; print "$field"; Returns the value which is related to this field as integer. A check is performed whether this is right. (Class method) Convert a timestamp into a MIME-acceptable date format. Example: Mail::Message::Field->toDate(localtime); 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; Create a copy of this field object. (object method or class method) Examples: my $field = Mail::Message::Field->new(From => 'me'); if($field->isStructured) Mail::Message::Field->isStructured('From'); Returns the number of lines needed to display this header-line. Returns the number of bytes needed to display this header-line. Make the header fold before the specified number of CHARS on a line. This will be ignored for un-structured headers. (Class method) Do not use this yourself. This created an object without checking, which is ok when the parser is doing that already. However, if you add unchecked fields you may get into big trouble! Mail::Box-Overview For support and additional documentation, see http://perl.overmeer.net/mailbox/ Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This code is beta, version 2.018. 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.