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

1Mail::Message::Head::PaUrsteiralC(o3n)tributed Perl DocuMmaeinlt:a:tMieosnsage::Head::Partial(3)
2
3
4

NAME

6       Mail::Message::Head::Partial - subset of header information of a
7       message
8

INHERITANCE

10        Mail::Message::Head::Partial
11          is a Mail::Message::Head::Complete
12          is a Mail::Message::Head
13          is a Mail::Reporter
14

SYNOPSIS

16        my $partial = $head->strip;
17        $partial->isa('Mail::Message::Head')  # true
18        $partial->isDelayed                      # false
19        $partial->isPartial                      # true
20
21        $partial->removeFields( qr/^X-/ );
22        $partial->removeFieldsExcept( qw/To From/ );
23        $partial->removeResentGroups;
24        $partial->removeListGroup;
25        $partial->removeSpamGroups;
26

DESCRIPTION

28       Header information consumes a considerable amount of memory.  Most of
29       this information is only useful during a short period of time in your
30       program, or sometimes it is not used at all.  You then can decide to
31       remove most of the header information.  However, be warned that it will
32       be lost permanently: the header (and therefore the message) gets
33       mutulated!
34
35       Extends "DESCRIPTION" in Mail::Message::Head::Complete.
36

OVERLOADED

38       Extends "OVERLOADED" in Mail::Message::Head::Complete.
39
40       overload: ""
41           Inherited, see "OVERLOADED" in Mail::Message::Head
42
43       overload: bool
44           Inherited, see "OVERLOADED" in Mail::Message::Head
45

METHODS

47       Extends "METHODS" in Mail::Message::Head::Complete.
48
49   Constructors
50       Extends "Constructors" in Mail::Message::Head::Complete.
51
52       Mail::Message::Head::Partial->build( [PAIR|$field], ... )
53           Inherited, see "Constructors" in Mail::Message::Head::Complete
54
55       $obj->clone( [@names|ARRAY|Regexps] )
56           Inherited, see "Constructors" in Mail::Message::Head::Complete
57
58       Mail::Message::Head::Partial->new(%options)
59           Inherited, see "Constructors" in Mail::Message::Head
60
61   The header
62       Extends "The header" in Mail::Message::Head::Complete.
63
64       $obj->isDelayed()
65           Inherited, see "The header" in Mail::Message::Head
66
67       $obj->isEmpty()
68           Inherited, see "The header" in Mail::Message::Head
69
70       $obj->isModified()
71           Inherited, see "The header" in Mail::Message::Head
72
73       $obj->knownNames()
74           Inherited, see "The header" in Mail::Message::Head
75
76       $obj->message( [$message] )
77           Inherited, see "The header" in Mail::Message::Head
78
79       $obj->modified( [BOOLEAN] )
80           Inherited, see "The header" in Mail::Message::Head
81
82       $obj->nrLines()
83           Inherited, see "The header" in Mail::Message::Head::Complete
84
85       $obj->orderedFields()
86           Inherited, see "The header" in Mail::Message::Head
87
88       $obj->size()
89           Inherited, see "The header" in Mail::Message::Head::Complete
90
91       $obj->wrap($integer)
92           Inherited, see "The header" in Mail::Message::Head::Complete
93
94   Access to the header
95       Extends "Access to the header" in Mail::Message::Head::Complete.
96
97       $obj->add( $field | $line | <$name, $body, [$attrs]> )
98           Inherited, see "Access to the header" in
99           Mail::Message::Head::Complete
100
101       $obj->addListGroup($object)
102           Inherited, see "Access to the header" in
103           Mail::Message::Head::Complete
104
105       $obj->addResentGroup($resent_group|$data)
106           Inherited, see "Access to the header" in
107           Mail::Message::Head::Complete
108
109       $obj->addSpamGroup($object)
110           Inherited, see "Access to the header" in
111           Mail::Message::Head::Complete
112
113       $obj->cleanupOrderedFields()
114           The header maintains a list of fields which are ordered in sequence
115           of definition.  It is required to maintain the header order to keep
116           the related fields of resent groups together.  The fields are also
117           included in a hash, sorted on their name for fast access.
118
119           The references to field objects in the hash are real, those in the
120           ordered list are weak.  So when field objects are removed from the
121           hash, their references in the ordered list are automagically
122           undef'd.
123
124           When many fields are removed, for instance with removeFields() or
125           removeFieldsExcept(), then it is useful to remove the list of
126           undefs from the ordered list as well.  In those cases, this method
127           is called automatically, however you may have your own reasons to
128           call this method.
129
130       $obj->count($name)
131           Inherited, see "Access to the header" in
132           Mail::Message::Head::Complete
133
134       $obj->delete($name)
135           Inherited, see "Access to the header" in
136           Mail::Message::Head::Complete
137
138       $obj->get( $name, [$index] )
139           Inherited, see "Access to the header" in Mail::Message::Head
140
141       $obj->grepNames( [@names|ARRAY|Regexps] )
142           Inherited, see "Access to the header" in
143           Mail::Message::Head::Complete
144
145       $obj->listGroup()
146           Inherited, see "Access to the header" in
147           Mail::Message::Head::Complete
148
149       $obj->names()
150           Inherited, see "Access to the header" in
151           Mail::Message::Head::Complete
152
153       $obj->print( [$fh] )
154           Inherited, see "Access to the header" in
155           Mail::Message::Head::Complete
156
157       $obj->printSelected($fh, <STRING|Regexp>, ...)
158           Inherited, see "Access to the header" in
159           Mail::Message::Head::Complete
160
161       $obj->printUndisclosed( [$fh] )
162           Inherited, see "Access to the header" in
163           Mail::Message::Head::Complete
164
165       $obj->removeContentInfo()
166           Inherited, see "Access to the header" in
167           Mail::Message::Head::Complete
168
169       $obj->removeField($field)
170           Inherited, see "Access to the header" in
171           Mail::Message::Head::Complete
172
173       $obj->removeFields( <STRING|Regexp>, ... )
174           Remove the fields from the header which are exactly named 'STRING'
175           (case insensitive) or match the regular expresssion.  Do not forget
176           to add the 'i' modifier to the regexp, because fields are case
177           insensitive.
178
179           See also removeField() which is used to remove one field object
180           from the header.  The reverse specification can be made with
181           removeFieldsExcept().
182
183           example:
184
185            $head->removeFields('bcc', 'received');
186            $head->removeFields( qr/^content-/i );
187
188       $obj->removeFieldsExcept(STRING|Regexp, ...)
189           Remove all fields from the header which are not equivalent to one
190           of the specified STRINGs (case-insensitive) and which are not
191           matching one of the REGular EXPressions.  Do not forget to add the
192           'i' modifier to the Regexp, because fields are case insensitive.
193
194           See also removeField() which is used to remove one field object
195           from the header.  The reverse specification can be made with
196           removeFields().
197
198           example:
199
200            $head->removeFieldsExcept('subject', qr/^content-/i );
201            $head->removeFieldsExcept( qw/subject to from sender cc/ );
202
203       $obj->removeListGroup()
204           Removes all header lines which are used to administer mailing
205           lists.  Which fields that are is explained in
206           Mail::Message::Head::ListGroup.  Returned is the number of removed
207           lines.
208
209       $obj->removeResentGroups()
210           Removes all header lines which are member of a resent group, which
211           are explained in Mail::Message::Head::ResentGroup.  Returned is the
212           number of removed lines.
213
214           For removing single groups (for instance because you want to keep
215           the last), use Mail::Message::Head::FieldGroup::delete().
216
217       $obj->removeSpamGroups()
218           Removes all header lines which were produced by spam detection and
219           spam-fighting software.  Which fields that are is explained in
220           Mail::Message::Head::SpamGroup.  Returned is the number of removed
221           lines.
222
223       $obj->resentGroups()
224           Inherited, see "Access to the header" in
225           Mail::Message::Head::Complete
226
227       $obj->reset($name, @fields)
228           Inherited, see "Access to the header" in
229           Mail::Message::Head::Complete
230
231       $obj->set( $field | $line | <$name, $body, [$attrs]> )
232           Inherited, see "Access to the header" in
233           Mail::Message::Head::Complete
234
235       $obj->spamDetected()
236           Inherited, see "Access to the header" in
237           Mail::Message::Head::Complete
238
239       $obj->spamGroups( [$names] )
240           Inherited, see "Access to the header" in
241           Mail::Message::Head::Complete
242
243       $obj->string()
244           Inherited, see "Access to the header" in
245           Mail::Message::Head::Complete
246
247       $obj->study( $name, [$index] )
248           Inherited, see "Access to the header" in Mail::Message::Head
249
250   About the body
251       Extends "About the body" in Mail::Message::Head::Complete.
252
253       $obj->guessBodySize()
254           Inherited, see "About the body" in Mail::Message::Head
255
256       $obj->guessTimeStamp()
257           Inherited, see "About the body" in Mail::Message::Head::Complete
258
259       $obj->isMultipart()
260           Inherited, see "About the body" in Mail::Message::Head
261
262       $obj->recvstamp()
263           Inherited, see "About the body" in Mail::Message::Head::Complete
264
265       $obj->timestamp()
266           Inherited, see "About the body" in Mail::Message::Head::Complete
267
268   Internals
269       Extends "Internals" in Mail::Message::Head::Complete.
270
271       $obj->addNoRealize($field)
272           Inherited, see "Internals" in Mail::Message::Head
273
274       $obj->addOrderedFields($fields)
275           Inherited, see "Internals" in Mail::Message::Head
276
277       $obj->createFromLine()
278           Inherited, see "Internals" in Mail::Message::Head::Complete
279
280       $obj->createMessageId()
281           Inherited, see "Internals" in Mail::Message::Head::Complete
282
283       $obj->fileLocation()
284           Inherited, see "Internals" in Mail::Message::Head
285
286       $obj->load()
287           Inherited, see "Internals" in Mail::Message::Head
288
289       $obj->messageIdPrefix( [$prefix, [$hostname]|CODE] )
290       Mail::Message::Head::Partial->messageIdPrefix( [$prefix,
291       [$hostname]|CODE] )
292           Inherited, see "Internals" in Mail::Message::Head::Complete
293
294       $obj->moveLocation($distance)
295           Inherited, see "Internals" in Mail::Message::Head
296
297       $obj->read($parser)
298           Inherited, see "Internals" in Mail::Message::Head
299
300       $obj->setNoRealize($field)
301           Inherited, see "Internals" in Mail::Message::Head
302
303   Error handling
304       Extends "Error handling" in Mail::Message::Head::Complete.
305
306       $obj->AUTOLOAD()
307           Inherited, see "Error handling" in Mail::Reporter
308
309       $obj->addReport($object)
310           Inherited, see "Error handling" in Mail::Reporter
311
312       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
313       $callback] )
314       Mail::Message::Head::Partial->defaultTrace( [$level]|[$loglevel,
315       $tracelevel]|[$level, $callback] )
316           Inherited, see "Error handling" in Mail::Reporter
317
318       $obj->errors()
319           Inherited, see "Error handling" in Mail::Reporter
320
321       $obj->log( [$level, [$strings]] )
322       Mail::Message::Head::Partial->log( [$level, [$strings]] )
323           Inherited, see "Error handling" in Mail::Reporter
324
325       $obj->logPriority($level)
326       Mail::Message::Head::Partial->logPriority($level)
327           Inherited, see "Error handling" in Mail::Reporter
328
329       $obj->logSettings()
330           Inherited, see "Error handling" in Mail::Reporter
331
332       $obj->notImplemented()
333           Inherited, see "Error handling" in Mail::Reporter
334
335       $obj->report( [$level] )
336           Inherited, see "Error handling" in Mail::Reporter
337
338       $obj->reportAll( [$level] )
339           Inherited, see "Error handling" in Mail::Reporter
340
341       $obj->trace( [$level] )
342           Inherited, see "Error handling" in Mail::Reporter
343
344       $obj->warnings()
345           Inherited, see "Error handling" in Mail::Reporter
346
347   Cleanup
348       Extends "Cleanup" in Mail::Message::Head::Complete.
349
350       $obj->DESTROY()
351           Inherited, see "Cleanup" in Mail::Reporter
352

DETAILS

354       Extends "DETAILS" in Mail::Message::Head::Complete.
355
356   Ordered header fields
357       Extends "Ordered header fields" in Mail::Message::Head::Complete.
358
359   Head class implementation
360       Extends "Head class implementation" in Mail::Message::Head::Complete.
361
362   Subsets of header fields
363       Extends "Subsets of header fields" in Mail::Message::Head::Complete.
364
365   Reducing the header size
366       A message header is very large in memory and quite large on disk, and
367       therefore a good candidate for size reduction.  One way to reduce the
368       size is by simply eliminating superfluous header fields.  Each field
369       requires at least 100 bytes of run-time memory, so this may help!
370
371       Before you start playing around with removeFields() and
372       removeFieldsExcept(), you may take a look at two large groups of fields
373       which can be removes as sets: the resent headers and the mailinglist
374       headers.
375
376       Resent headers describe the intermediate steps in the transmission
377       process for the messages.  After successful delivery, they are rarely
378       useful.
379
380       When you are archiving a mailinglist, it is hardly ever useful to store
381       a the list administration lines for each message as well.
382
383       . see examples/reduce.pl in distribution
384
385        foreach my $msg ($folder->messages)
386        {  $msg->head->removeResentGroups;
387           $msg->head->removeResentList;
388        }
389

DIAGNOSTICS

391       Warning: Cannot remove field $name from header: not found.
392           You ask to remove a field which is not known in the header.  Using
393           delete(), reset(), or set() to do the job will not result in
394           warnings: those methods check the existence of the field first.
395
396       Warning: Field objects have an implied name ($name)
397       Error: Package $package does not implement $method.
398           Fatal error: the specific package (or one of its superclasses) does
399           not implement this method where it should. This message means that
400           some other related classes do implement this method however the
401           class at hand does not.  Probably you should investigate this and
402           probably inform the author of the package.
403

LICENSE

409       Copyrights 2001-2023 by [Mark Overmeer <markov@cpan.org>]. For other
410       contributors see ChangeLog.
411
412       This program is free software; you can redistribute it and/or modify it
413       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
414
415
416
417perl v5.38.0                      2023-07-20   Mail::Message::Head::Partial(3)