Mail::Message::Head::FieldGroup(3pm)

1Mail::Message::Head::FiUesledrGrCoounpt(r3i)buted Perl DMoaciulm:e:nMteastsiaogne::Head::FieldGroup(3)
2
3
4

NAME

6       Mail::Message::Head::FieldGroup - a sub set of fields in a header
7

INHERITANCE

9        Mail::Message::Head::FieldGroup
10          is a Mail::Reporter
11
12        Mail::Message::Head::FieldGroup is extended by
13          Mail::Message::Head::ListGroup
14          Mail::Message::Head::ResentGroup
15          Mail::Message::Head::SpamGroup
16

SYNOPSIS

18       Never instantiated directly.
19

DESCRIPTION

21       Some fields have a combined meaning: a set of fields which represent
22       one intermediate step during the transport of the message (a resent
23       group, implemented in Mail::Message::Head::ResentGroup), fields added
24       by mailing list software (implemented in
25       Mail::Message::Head::ListGroup), or fields added by Spam detection
26       related software (implemented by Mail::Message::Head::SpamGroup).  Each
27       set of fields can be extracted or added as group with objects which are
28       based on the implementation in this class.
29

METHODS

31   Constructors
32       $obj->clone
33           Make a copy of this object.  The collected fieldnames are copied
34           and the list type information.  No deep copy is made for the
35           header: this is only copied as reference.
36
37       $obj->from(HEAD|MESSAGE)
38           Create a group of fields based on the specified MESSAGE or message
39           HEAD.  This may return one or more of the objects, which depends on
40           the type of group.  Mailing list fields are all stored in one
41           object, where resent and spam groups can appear more than once.
42
43       $obj->implementedTypes
44           Mail::Message::Head::FieldGroup->implementedTypes
45
46           Returns a list of strings containing all possible return values for
47           type().
48
49       Mail::Message::Head::FieldGroup->new(FIELDS, OPTIONS)
50           Construct an object which maintains one set of header FIELDS.  The
51           FIELDS may be specified as "Mail::Message::Field" objects or as
52           key-value pairs.  The OPTIONS and FIELDS (as key-value pair) can be
53           mixed: they are distinguished by their name, where the fields
54           always start with a capital.  The field objects must aways lead the
55           OPTIONS.
56
57            -Option  --Defined in     --Default
58             head                       undef
59             log       Mail::Reporter   'WARNINGS'
60             software                   undef
61             trace     Mail::Reporter   'WARNINGS'
62             type                       undef
63             version                    undef
64
65           head => HEAD
66             The header HEAD object is used to store the grouped fields in.
67             If no header is specified, a Mail::Message::Head::Partial is
68             created for you.  If you wish to scan the existing fields in a
69             header, then use the from() method.
70
71           log => LEVEL
72           software => STRING
73             Name of the software which produced the fields.
74
75           trace => LEVEL
76           type => STRING
77             Group name for the fields.  Often the same, or close to the same
78             STRING, as the "software" option contains.
79
80           version => STRING
81             Version number for the software which produced the fields.
82
83   The header
84       $obj->add((FIELD, VALUE) | OBJECT)
85           Add a field to the header, using the field group.  When the field
86           group is already attached to a real message header, it will appear
87           in that one as well as being registed in this set.  If no header is
88           defined, the field only appears internally.
89
90           example: adding a field to a detached list group
91
92            my $this = Mail::Message::Head::ListGroup->new(...);
93            $this->add('List-Id' => 'mailbox');
94            $msg->addListGroup($this);
95            $msg->send;
96
97           example: adding a field to an attached list group
98
99            my $lg = Mail::Message::Head::ListGroup->from($msg);
100            $lg->add('List-Id' => 'mailbox');
101
102       $obj->addFields([FIELDNAMES])
103           Add some FIELDNAMES to the set.
104
105       $obj->attach(HEAD)
106           Add a group of fields to a message HEAD.  The fields will be
107           cloned(!)  into the header, so that the field group object can be
108           used again.
109
110           example: attaching a list group to a message
111
112            my $lg = Mail::Message::Head::ListGroup->new(...);
113            $lg->attach($msg->head);
114            $msg->head->addListGroup($lg);   # same
115
116            $msg->head->addSpamGroup($sg);   # also implemented with attach
117
118       $obj->delete
119           Remove all the header lines which are combined in this fields
120           group, from the header.
121
122       $obj->fieldNames
123           Return the names of the fields which are used in this group.
124
125       $obj->fields
126           Return the fields which are defined for this group.
127
128       $obj->head
129           Returns the header object, which includes these fields.
130
131   Access to the header
132       $obj->software
133           Returns the name of the software as is defined in the headers.  The
134           may be slightly different from the return value of type(), but
135           usually not too different.
136
137       $obj->type
138           Returns an abstract name for the field group; which software is
139           controling it.  "undef" is returned in case the type is not known.
140           Valid names are group type dependent: see the applicable manual
141           pages.  A list of all types can be retreived with
142           implementedTypes().
143
144       $obj->version
145           Returns the version number of the software used to produce the
146           fields.  Some kinds of software do leave such a trace, other cases
147           will return "undef"
148
149   Internals
150       $obj->collectFields([NAME])
151           Scan the header for fields which are usually contained in field
152           group with the specified NAME.  For mailinglist groups, you can not
153           specify a NAME: only one set of headers will be found (all headers
154           are considered to be produced by exactly one package of mailinglist
155           software).
156
157           This method is automatically called when a field group is
158           constructed via from() on an existing header or message.
159
160           Returned are the names of the list header fields found, in scalar
161           context the amount of fields.  An empty list/zero indicates that
162           there was no group to be found.
163
164           Please warn the author of MailBox if you see that to few or too
165           many fields are included.
166
167       $obj->detected(TYPE, SOFTWARE, VERSION)
168           Sets the values for the field group type, software, and version,
169           prossibly to "undef".
170
171   Error handling
172       $obj->AUTOLOAD
173           See "Error handling" in Mail::Reporter
174
175       $obj->addReport(OBJECT)
176           See "Error handling" in Mail::Reporter
177
178       $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
179           Mail::Message::Head::FieldGroup->defaultTrace([LEVEL]|[LOGLEVEL,
180           TRACELEVEL]|[LEVEL, CALLBACK])
181
182           See "Error handling" in Mail::Reporter
183
184       $obj->details
185           Produce information about the detected/created field group, which
186           may be helpful during debugging.  A nicely formatted string is
187           returned.
188
189       $obj->errors
190           See "Error handling" in Mail::Reporter
191
192       $obj->log([LEVEL [,STRINGS]])
193           Mail::Message::Head::FieldGroup->log([LEVEL [,STRINGS]])
194
195           See "Error handling" in Mail::Reporter
196
197       $obj->logPriority(LEVEL)
198           Mail::Message::Head::FieldGroup->logPriority(LEVEL)
199
200           See "Error handling" in Mail::Reporter
201
202       $obj->logSettings
203           See "Error handling" in Mail::Reporter
204
205       $obj->notImplemented
206           See "Error handling" in Mail::Reporter
207
208       $obj->print([FILEHANDLE])
209           Print the group to the specified FILEHANDLE or GLOB.  This is
210           probably only useful for debugging purposed.  The output defaults
211           to the selected file handle.
212
213       $obj->report([LEVEL])
214           See "Error handling" in Mail::Reporter
215
216       $obj->reportAll([LEVEL])
217           See "Error handling" in Mail::Reporter
218
219       $obj->trace([LEVEL])
220           See "Error handling" in Mail::Reporter
221
222       $obj->warnings
223           See "Error handling" in Mail::Reporter
224
225   Cleanup
226       $obj->DESTROY
227           See "Cleanup" in Mail::Reporter
228
229       $obj->inGlobalDestruction
230           See "Cleanup" in Mail::Reporter
231

DIAGNOSTICS

233       Error: Package $package does not implement $method.
234           Fatal error: the specific package (or one of its superclasses) does
235           not implement this method where it should. This message means that
236           some other related classes do implement this method however the
237           class at hand does not.  Probably you should investigate this and
238           probably inform the author of the package.
239

LICENSE

245       Copyrights 2001-2011 by Mark Overmeer. For other contributors see
246       ChangeLog.
247
248       This program is free software; you can redistribute it and/or modify it
249       under the same terms as Perl itself.  See
250       http://www.perl.com/perl/misc/Artistic.html
251
252
253
254perl v5.12.3                      2011-01-26Mail::Message::Head::FieldGroup(3)