NAME

Mail::Field - Base class for manipulation of mail header fields

SYNOPSIS

    use Mail::Field;
    
    $field = Mail::Field->new('Subject', 'some subject text');
    print $field->tag,": ",$field->stringify,"\n";

    $field = Mail::Field->subject('some subject text');

DESCRIPTION

Mail::Field is a base class for packages that create and manipulate fields from Email (and MIME) headers. Each different field will have its own sub-class, defining its own interface.

This document describes the minimum interface that each sub-class should provide, and also guidlines on how the field specific interface should be defined.

CONSTRUCTOR

Mail::Field, and it's sub-classes define several methods which return new objects. These can all be termed to be constructors.

new ( TAG [, STRING | OPTIONS ] ): The new constructor will create an object in the class which defines the field specified by the tag argument.; After creation of the object :-; If the tag argument is followed by a single string then the parse method will be called with this string.; If the tag argument is followed by more than one arguments then the create method will be called with these arguments.
extract ( TAG, HEAD [, INDEX ] ): This constuctor takes as arguments the tag name, a Mail::Head object and optionally an index.; If the index argument is given then extract will retrieve the given tag from the Mail::Head object and create a new Mail::Field based object. undef will be returned in the field does not exist.; If the index argument is not given the the result depends on the context in which extract is called. If called in a scalar context the result will be as if extract was called with an index value of zero. If called in an array context then all tags will be retrieved and a list of Mail::Field objects will be returned.
combine ( FIELD_LIST ): This constructor takes as arguments a list of Mail::Field objects, which should all be of the same sub-class, and creates a new object in that same class.; This constructor is nor defined in Mail::Field as there is no generic way to combine the various field types. Each sub-class should define its own combine constructor, if combining is possible/allowed.

METHODS

parse
set
tag
stringify

SUB-CLASS PACKAGE NAMES

All sub-classes should be called Mail::Field::name where name is derived from the tag using these rules.

Consider a tag as being made up of elements separated by '-'
Convert all characters to lowercase except the first in each element, which should be uppercase.
name is then created from these elements by using the first N characters from each element.
N is calculated by using the formula :-
```
    int((7 + #elements) / #elements)
```
name is then limited to a maximum of 8 characters, keeping the first 8 characters

For an example of this take a look at the definition of the _header_pkg_name subroutine in Mail::Field

AUTHOR

Graham Barr.

Maintained by Mark Overmeer <mailtools@overmeer.net>

CREDITS

Eryq <eryq@rhine.gsfc.nasa.gov> - for all the help in defining this package so that Mail::* and MIME::* can be integrated together.

COPYRIGHT