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 mes‐
7       sage
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 messsage) gets mutu‐
33       lated!
34

OVERLOADED

36       overload: ""
37
38           See "OVERLOADED" in Mail::Message::Head
39
40       overload: bool
41
42           See "OVERLOADED" in Mail::Message::Head
43

METHODS

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

DETAILS

398       Reducing the header size
399
400       A message header is very large in memory and quite large on disk, and
401       therefore a good candidate for size reduction.  One way to reduce the
402       size is by simply eliminating superfluous header fields.  Each field
403       requires at least 100 bytes of run-time memory, so this may help!
404
405       Before you start playing around with removeFields() and removeFieldsEx‐
406       cept(), you may take a look at two large groups of fields which can be
407       removes as sets: the resent headers and the mailinglist headers.
408
409       Resent headers describe the intermediate steps in the transmission
410       process for the messages.  After successful delivery, they are rarely
411       useful.
412
413       When you are archiving a mailinglist, it is hardly ever useful to store
414       a the list administration lines for each message as well.
415
416       Example: see examples/reduce.pl in distribution
417
418        foreach my $msg ($folder->messages)
419        {  $msg->head->removeResentGroups;
420           $msg->head->removeResentList;
421        }
422

DIAGNOSTICS

424       Warning: Cannot remove field $name from header: not found.
425
426       You ask to remove a field which is not known in the header.  Using
427       delete(), reset(), or set() to do the job will not result in warnings:
428       those methods check the existence of the field first.
429
430       Warning: Field objects have an implied name ($name)
431
432       Error: Package $package does not implement $method.
433
434       Fatal error: the specific package (or one of its superclasses) does not
435       implement this method where it should. This message means that some
436       other related classes do implement this method however the class at
437       hand does not.  Probably you should investigate this and probably
438       inform the author of the package.
439

LICENSE

445       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
446       ChangeLog.
447
448       This program is free software; you can redistribute it and/or modify it
449       under the same terms as Perl itself.  See
450       http://www.perl.com/perl/misc/Artistic.html
451
452
453
454perl v5.8.8                       2007-03-25   Mail::Message::Head::Partial(3)