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 Mail::Message::Head::List‐
25       Group), or fields added by Spam detection related software (implemented
26       by Mail::Message::Head::SpamGroup).  Each set of fields can be
27       extracted or added as group with objects which are based on the imple‐
28       mentation in this class.
29

METHODS

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

DIAGNOSTICS

277       Error: Package $package does not implement $method.
278
279       Fatal error: the specific package (or one of its superclasses) does not
280       implement this method where it should. This message means that some
281       other related classes do implement this method however the class at
282       hand does not.  Probably you should investigate this and probably
283       inform the author of the package.
284

LICENSE

290       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
291       ChangeLog.
292
293       This program is free software; you can redistribute it and/or modify it
294       under the same terms as Perl itself.  See
295       http://www.perl.com/perl/misc/Artistic.html
296
297
298
299perl v5.8.8                       2007-03-25Mail::Message::Head::FieldGroup(3)