NAME

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

CLASS HIERARCHY

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

SYNOPSIS

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

DESCRIPTION

The object stores one header-line, and facilitates access routines to that line.

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. The new constructor even does not call a separate init, so please contact the author of Mail::Box if you want to create extensions to this object.

METHOD INDEX

The general methods for Mail::Message::Field objects:

      attribute NAME [, VALUE]             nrLines
      body                                 print [FILEHANDLE]
      clone                                setWrapLength CHARS
      comment                              size
      isStructured                         toDate TIME
      name                                 toInt
      new ...                              toString

METHODS

new LINE [,ARRAY-OF-OPTIONS]

new NAME, BODY [,COMMENT [, OPTIONS]]

new NAME, OBJECT|ARRAY-OF-OBJECTS [,COMMENT [, OPTIONS]]

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

clone

Create a copy of this field object.

name

Returns the name of this field, with all characters lower-cased for ease of comparison.

body

Returns the body of the field, unmodified but stripped from comment and CR LF characters (as far as were present at creation).

comment

Returns the comment (part after a semi-colon) in the header-line.

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

toString

Returns the whole header-line.

Example:

    my @lines = $field->toString;
    print $field->toString;
    print "$field";

toInt

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

isStructured

(object method or class method)

Examples:

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

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

nrLines

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

size

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

setWrapLength CHARS

Make the header fold before the specified number of CHARS on a line. This will be ignored for un-structured headers.

toDate TIME

(Class method) Convert a timestamp into a MIME-acceptable date format.

Example:

 Mail::Message::Field->toDate(localtime);

SEE ALSO

Mail::Box-Overview

AUTHOR

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.

VERSION

This code is beta, version 2.00_18.

Copyright (c) 2001 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.