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
30       Extends "DESCRIPTION" in Mail::Reporter.
31

METHODS

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

DIAGNOSTICS

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

LICENSE

249       Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other
250       contributors see ChangeLog.
251
252       This program is free software; you can redistribute it and/or modify it
253       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
254
255
256
257perl v5.36.0                      2023-01-20Mail::Message::Head::FieldGroup(3)