1Mail::Field(3)        User Contributed Perl Documentation       Mail::Field(3)
2
3
4

NAME

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

SYNOPSIS

9           use Mail::Field;
10
11           $field = Mail::Field->new('Subject', 'some subject text');
12           print $field->tag,": ",$field->stringify,"\n";
13
14           $field = Mail::Field->subject('some subject text');
15

DESCRIPTION

17       "Mail::Field" is a base class for packages that create and manipulate
18       fields from Email (and MIME) headers. Each different field will have
19       its own sub-class, defining its own interface.
20
21       This document describes the minimum interface that each sub-class
22       should provide, and also guidlines on how the field specific interface
23       should be defined.
24

CONSTRUCTOR

26       Mail::Field, and it's sub-classes define several methods which return
27       new objects. These can all be termed to be constructors.
28
29       new ( TAG [, STRING ⎪ OPTIONS ] )
30           The new constructor will create an object in the class which
31           defines the field specified by the tag argument.
32
33           After creation of the object :-
34
35           If the tag argument is followed by a single string then the "parse"
36           method will be called with this string.
37
38           If the tag argument is followed by more than one arguments then the
39           "create" method will be called with these arguments.
40
41       extract ( TAG, HEAD [, INDEX ] )
42           This constuctor takes as arguments the tag name, a "Mail::Head"
43           object and optionally an index.
44
45           If the index argument is given then "extract" will retrieve the
46           given tag from the "Mail::Head" object and create a new
47           "Mail::Field" based object.  undef will be returned in the field
48           does not exist.
49
50           If the index argument is not given the the result depends on the
51           context in which "extract" is called. If called in a scalar context
52           the result will be as if "extract" was called with an index value
53           of zero. If called in an array context then all tags will be
54           retrieved and a list of "Mail::Field" objects will be returned.
55
56       combine ( FIELD_LIST )
57           This constructor takes as arguments a list of "Mail::Field"
58           objects, which should all be of the same sub-class, and creates a
59           new object in that same class.
60
61           This constructor is nor defined in "Mail::Field" as there is no
62           generic way to combine the various field types. Each sub-class
63           should define its own combine constructor, if combining is possi‐
64           ble/allowed.
65

METHODS

67       parse
68       set
69       tag
70       stringify
71

SUB-CLASS PACKAGE NAMES

73       All sub-classes should be called Mail::Field::name where name is
74       derived from the tag using these rules.
75
76       ·   Consider a tag as being made up of elements separated by '-'
77
78       ·   Convert all characters to lowercase except the first in each ele‐
79           ment, which should be uppercase.
80
81       ·   name is then created from these elements by using the first N char‐
82           acters from each element.
83
84       ·   N is calculated by using the formula :-
85
86               int((7 + #elements) / #elements)
87
88       ·   name is then limited to a maximum of 8 characters, keeping the
89           first 8 characters
90
91       For an example of this take a look at the definition of the
92       "_header_pkg_name" subroutine in "Mail::Field"
93

AUTHOR

95       Graham Barr.
96
97       Maintained by Mark Overmeer <mailtools@overmeer.net>
98

SEE ALSO

100       MIME::*s
101

CREDITS

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

107       Copyright (c) 2002-2003 Mark Overmeer, 1995-2001 Graham Barr. All
108       rights reserved. This program is free software; you can redistribute it
109       and/or modify it under the same terms as Perl itself.
110
111
112
113perl v5.8.8                       2007-05-11                    Mail::Field(3)
Impressum