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

1Mail::Message::Head::CoUmspelretCeo(n3t)ributed Perl DocMuamieln:t:aMteisosnage::Head::Complete(3)
2
3
4

NAME

6       Mail::Message::Head::Complete - the header of one message
7

INHERITANCE

9        Mail::Message::Head::Complete
10          is a Mail::Message::Head
11          is a Mail::Reporter
12
13        Mail::Message::Head::Complete is extended by
14          Mail::Message::Head::Partial
15          Mail::Message::Replace::MailHeader
16
17        Mail::Message::Head::Complete is realized by
18          Mail::Message::Head::Delayed
19          Mail::Message::Head::Subset
20

SYNOPSIS

22        my $head = Mail::Message::Head::Complete->new;
23        See Mail::Message::Head
24

DESCRIPTION

26       E-mail's message can be in various states: unread, partially read, and
27       fully read.  The class stores a message of which all header lines are
28       known for sure.
29

OVERLOADED

31       overload: ""
32
33           See "OVERLOADED" in Mail::Message::Head
34
35       overload: bool
36
37           See "OVERLOADED" in Mail::Message::Head
38

METHODS

40       Constructors
41
42       $obj->build([PAIR⎪FIELD]-LIST)
43
44           Undefined values are interpreted as empty field values, and there‐
45           fore skipped.
46
47       $obj->clone([NAMES⎪ARRAY-OF-NAMES⎪REGEXS])
48
49           Make a copy of the header, optionally limited only to the header
50           lines specified by NAMES.  See grepNames() on the way these fields
51           can be used.
52
53           Example:
54
55            my $newhead = $head->clone('Subject', 'Received');
56
57       Mail::Message::Head::Complete->new(OPTIONS)
58
59           See "Constructors" in Mail::Message::Head
60
61       The header
62
63       $obj->isDelayed
64
65           See "The header" in Mail::Message::Head
66
67       $obj->isEmpty
68
69           See "The header" in Mail::Message::Head
70
71       $obj->isModified
72
73           See "The header" in Mail::Message::Head
74
75       $obj->knownNames
76
77           See "The header" in Mail::Message::Head
78
79       $obj->message([MESSAGE])
80
81           See "The header" in Mail::Message::Head
82
83       $obj->modified([BOOLEAN])
84
85           See "The header" in Mail::Message::Head
86
87       $obj->nrLines
88
89           Return the number of lines needed to display this header (including
90           the trailing newline)
91
92       $obj->orderedFields
93
94           See "The header" in Mail::Message::Head
95
96       $obj->size
97
98           Return the number of bytes needed to display this header (including
99           the trailing newline).  On systems which use CRLF as line separa‐
100           tor, the number of lines in the header (see nrLines()) must be
101           added to find the actual size in the file.
102
103       $obj->wrap(INTEGER)
104
105           Re-fold all fields from the header to contain at most INTEGER num‐
106           ber of characters per line.
107
108           Example: re-folding a header
109
110            $msg->head->wrap(78);
111
112       Access to the header
113
114       $obj->add(FIELD ⎪ LINE ⎪ (NAME,BODY[,ATTRS]))
115
116           Add a field to the header.  If a field is added more than once, all
117           values are stored in the header, in the order they are added.
118
119           When a FIELD object is specified (some Mail::Message::Field
120           instance), that will be added.  Another possibility is to specify a
121           raw header LINE, or a header line nicely split-up in NAME and BODY,
122           in which case the field constructor is called for you.
123
124           LINE or BODY specifications which are terminated by a new-line are
125           considered to be correctly folded.  Lines which are not terminated
126           by a new-line will be folded when needed: new-lines will be added
127           where required.  It is strongly adviced to let MailBox do the fold‐
128           ing for you.
129
130           The return value of this method is the Mail::Message::Field object
131           which is created (or was specified).
132
133           Example:
134
135            my $head  = Mail::Message::Head->new;
136            $head->add('Subject: hi!');
137            $head->add(From => 'me@home');
138            my $field = Mail::Message::Field->new('To: you@there');
139            $head->add($field);
140            my Mail::Message::Field $s = $head->add(Sender => 'I');
141
142       $obj->addListGroup(OBJECT)
143
144           A list group is a set of header fields which contain data about a
145           mailing list which was used to transmit the message.  See
146           Mail::Message::Head::ListGroup for details about the implementation
147           of the OBJECT.
148
149           When you have a list group prepared, you can add it later using
150           this method.  You will get your private copy of the list group data
151           in return, because the same group can be used for multiple mes‐
152           sages.
153
154           Example: of adding a list group to a header
155
156            my $lg = Mail::Message::Head::ListGroup->new(...);
157            my $own_lg = $msg->head->addListGroup($lg);
158
159       $obj->addResentGroup(RESENT-GROUP⎪DATA)
160
161           Add a RESENT-GROUP (a Mail::Message::Head::ResentGroup object) to
162           the header.  If you specify DATA, that is used to create such group
163           first.  If no "Received" line is specified, it will be created for
164           you.
165
166           These header lines have nothing to do with the user's sense of
167           "reply" or "forward" actions: these lines trace the e-mail trans‐
168           port mechanism.
169
170           Example:
171
172            my $rg = Mail::Message::Head::ResentGroup->new(head => $head, ...);
173            $head->addResentGroup($rg);
174
175            my $rg = $head->addResentGroup(From => 'me');
176
177       $obj->addSpamGroup(OBJECT)
178
179           A spam fighting group is a set of header fields which contains data
180           which is used to fight spam.  See Mail::Message::Head::SpamGroup
181           for details about the implementation of the OBJECT.
182
183           When you have a spam group prepared, you can add it later using
184           this method.  You will get your private copy of the spam group data
185           in return, because the same group can be used for multiple mes‐
186           sages.
187
188           Example: of adding a spam group to a header
189
190            my $sg = Mail::Message::Head::SpamGroup->new(...);
191            my $own_sg = $msg->head->addSpamGroup($sg);
192
193       $obj->count(NAME)
194
195           Count the number of fields with this NAME.  Most fields will return
196           1: only one occurance in the header.  As example, the "Received"
197           fields are usually present more than once.
198
199       $obj->delete(NAME)
200
201           Remove the field with the specified name.  If the header contained
202           multiple lines with the same name, they will be replaced all
203           together.  This method simply calls reset() without replacement
204           fields.  READ THE IMPORTANT WARNING IN removeField()
205
206       $obj->get(NAME [,INDEX])
207
208           See "Access to the header" in Mail::Message::Head
209
210       $obj->grepNames([NAMES⎪ARRAY-OF-NAMES⎪REGEXS])
211
212           Filter from all header fields those with names which start will any
213           of the specified list.  When no names are specified, all fields
214           will be returned.  The list is ordered as they where read from
215           file, or added later.
216
217           The NAMES are considered regular expressions, and will all be
218           matched case insensitive and attached to the front of the string
219           only.  You may also specify one or more prepared regexes.
220
221           Example:
222
223            my @f  = $head->grepNames();       # same as $head->orderedFields
224            my @f  = $head->grepNames('X-', 'Subject', ');
225            my @to = $head->grepNames('To\b'); # will only select To
226
227       $obj->listGroup
228
229           Returns a list group description: the set of headers which form the
230           information about mailing list software used to transport the mes‐
231           sage.  See also addListGroup() and removeListGroup().
232
233           Example: use of listGroup()
234
235            if(my $lg = $msg->head->listGroup)
236            {  $lg->print(\*STDERR);
237               $lg->delete;
238            }
239
240            $msg->head->removeListGroup;
241
242       $obj->names
243
244           Returns a full ordered list of known field names, as defined in the
245           header.  Fields which were reset() to be empty will still be listed
246           here.
247
248       $obj->print([FILEHANDLE])
249
250           Print all headers to the specified FILEHANDLE, by default the
251           selected filehandle.  See printUndisclosed() to limit the headers
252           to include only the public headers.
253
254           Example:
255
256            $head->print(\*OUT);
257            $head->print;
258
259            my $fh = IO::File->new(...);
260            $head->print($fh);
261
262       $obj->printSelected(FILEHANDLE, (STRING⎪REGEXP)s)
263
264           Like the usual print(), the header lines are printed to the speci‐
265           fied FILEHANDLE.  In this case, however, only the fields with names
266           as specified by STRING (case insensative) or REGEXP are printed.
267           They will stay the in-order of the source header.
268
269           Example: printing only a subset of the fields
270
271            $head->printSelected(STDOUT, qw/Subject From To/, qr/^x\-(spam⎪xyz)\-/i)
272
273       $obj->printUndisclosed([FILEHANDLE])
274
275           Like the usual print(), the header lines are printed to the speci‐
276           fied FILEHANDLE, by default the selected filehandle.  In this case,
277           however, "Bcc" and "Resent-Bcc" lines are included.
278
279       $obj->removeContentInfo
280
281           Remove all body related fields from the header.  The header will
282           become partial.
283
284       $obj->removeField(FIELD)
285
286           Remove the specified FIELD object from the header.  This is useful
287           when there are possible more than one fields with the same name,
288           and you need to remove exactly one of them.  Also have a look at
289           delete(), reset(), and set().
290
291           See also Mail::Message::Head::Partial::removeFields() (mind the 's'
292           at the end of the name), which accepts a string or regular expres‐
293           sion as argument to select the fields to be removed.
294
295           WARNING WARNING WARNING: for performance reasons, the header admin‐
296           istration uses weak references (see Scalar::Util method weaken()>
297           to figure-out which fields have been removed.  A header is a hash
298           of field for fast search and an array of weak references to remem‐
299           ber the order of the fields, required for printing.  If the field
300           is removed from the hash, the weak-ref is set to undef and the
301           field not printed.
302
303           However... it is easy to disturb this process.  Example:
304            my $msg = ....;                 # subject ref-count = 1 + 0 = 1
305            $msg->head->delete('Subject');  # subject ref-count =     0 = 0:
306           clean-up
307            $msg->print;                    # subject doesn't show: ok
308
309           But
310            my $msg = ....;                 # subject ref-count = 1 + 0 = 1
311            my $s = $msg->head->get('subject'); # ref-count = 1 + 1 + 0 = 2
312            $msg->head->delete('Subject');  # subject ref-count = 1 + 0 = 1:
313           no clean-up
314            $msg->print;                    # subject DOES show: not ok
315            undef $s;                       # ref-count becomes 0: clean-up
316            $msg->print;                    # subject doesn't show: ok
317
318           To avoid the latter situation, do not catch the field object, but
319           only the field content.  SAVE are all methods which return the
320           text:
321            my $s = $msg->head->get('subject')->body;
322            my $s = $msg->head->get('subject')->unfoldedBody;
323            my $s = $msg->head->get('subject')->foldedBody;
324            my $s = $msg->head->get('subject')->foldedBody;
325            my $s = $msg->get('subject');
326            my $s = $msg->subject;
327            my $s = $msg->string;
328
329       $obj->removeFields(STRING⎪REGEXP, [STRING⎪REGEXP, ...])
330
331           The header object is turned into a Mail::Message::Head::Partial
332           object which has a set of fields removed.  Read about the implica‐
333           tions and the possibilities in Mail::Message::Head::Par‐
334           tial::removeFields().
335
336       $obj->removeFieldsExcept(STRING⎪REGEXP, [STRING⎪REGEXP, ...])
337
338           The header object is turned into a Mail::Message::Head::Partial
339           object which has a set of fields removed.  Read about the implica‐
340           tions and the possibilities in Mail::Message::Head::Par‐
341           tial::removeFieldsExcept().
342
343       $obj->removeListGroup
344
345           Removes all fields related to mailing list administration at once.
346           The header object is turned into a Mail::Message::Head::Partial
347           object.  Read about the implications and the possibilities in
348           Mail::Message::Head::Partial::removeListGroup().
349
350       $obj->removeResentGroups
351
352           Removes all resent groups at once.  The header object is turned
353           into a Mail::Message::Head::Partial object.  Read about the impli‐
354           cations and the possibilities in Mail::Message::Head::Par‐
355           tial::removeResentGroups().
356
357       $obj->removeSpamGroups
358
359           Removes all fields which were added by various spam detection soft‐
360           ware at once.  The header object is turned into a Mail::Mes‐
361           sage::Head::Partial object.  Read about the implications and the
362           possibilities in Mail::Message::Head::Partial::removeSpamGroups().
363
364       $obj->resentGroups
365
366           Returns a list of Mail::Message::Head::ResentGroup objects which
367           each represent one intermediate point in the message's transmission
368           in the order as they appear in the header: the most recent one
369           first.  See also addResentGroup() and removeResentGroups().
370
371           A resent group contains a set of header fields whose names start
372           with "Resent-".  Before the first "Resent" line is trace informa‐
373           tion, which is composed of an optional "Return-Path" field and an
374           required "Received" field.
375
376       $obj->reset(NAME, FIELDS)
377
378           Replace the values in the header fields named by NAME with the val‐
379           ues specified in the list of FIELDS. A single name can correspond
380           to multiple repeated fields.  READ THE IMPORTANT WARNING IN remove‐
381           Field()
382
383           Removing fields which are part of one of the predefined field
384           groups is not a smart idea.  You can better remove these fields as
385           group, all together.  For instance, the 'Received' lines are part
386           of resent groups, 'X-Spam' is past of a spam group, and "List-Post"
387           belongs to a list group.  You can delete a whole group with
388           Mail::Message::Head::FieldGroup::delete(), or with methods which
389           are provided by Mail::Message::Head::Partial.
390
391           If FIELDS is empty, the corresponding NAME fields will be removed.
392           The location of removed fields in the header order will be remem‐
393           bered. Fields with the same name which are added later will appear
394           at the remembered position.  This is equivalent to the delete()
395           method.
396
397           Example:
398
399            # reduce number of 'Keywords' lines to last 5)
400            my @keywords = $head->get('Keywords');
401            $head->reset('Keywords', @keywords[-5..-1]) if @keywords > 5;
402
403            # Reduce the number of Received lines to only the last added one.
404            my @rgs = $head->resentGroups;
405            shift @rgs;     # keep this one (later is added in front)
406            $_->delete foreach @rgs;
407
408       $obj->set(FIELD ⎪ LINE ⎪ (NAME, BODY [,ATTRS]))
409
410           The "set" method is similar to the add() method, and takes the same
411           options. However, existing values for fields will be removed before
412           a new value is added.  READ THE IMPORTANT WARNING IN removeField()
413
414       $obj->spamDetected
415
416           Returns whether one of the spam groups defines a report about spam.
417           If there are not header fields in the message which relate to spam-
418           detection software, "undef" is returned.  The spamgroups which
419           report spam are returned.
420
421           Example:
422
423            $message->delete if $message->spamDetected;
424
425            call_spamassassin($message)
426               unless defined $message->spamDetected;
427
428       $obj->spamGroups([NAMES])
429
430           Returns a list of Mail::Message::Head::SpamGroup objects, each col‐
431           lecting some lines which contain spam fighting information.  When
432           any NAMES are given, then only these groups are returned.  See also
433           addSpamGroup() and removeSpamGroups().
434
435           In scalar context, with exactly one NAME specified, that group will
436           be returned.  With more NAMES or without NAMES, a list will be
437           returned (which defaults to the length of the list in scalar con‐
438           text).
439
440           Example: use of listGroup()
441
442            my @sg = $msg->head->spamGroups;
443            $sg[0]->print(\*STDERR);
444            $sg[-1]->delete;
445
446            my $sg = $msg->head->spamGroups('SpamAssassin');
447
448       $obj->string
449
450           Returns the whole header as one scalar (in scalar context) or list
451           of lines (list context).  Triggers completion.
452
453       $obj->study(NAME [,INDEX])
454
455           See "Access to the header" in Mail::Message::Head
456
457       About the body
458
459       $obj->guessBodySize
460
461           See "About the body" in Mail::Message::Head
462
463       $obj->guessTimeStamp
464
465           Make a guess about when the message was origanally posted, based on
466           the information found in the header's "Date" field.
467
468           For some kinds of folders, Mail::Message::guessTimestamp() may pro‐
469           duce a better result, for instance by looking at the modification
470           time of the file in which the message is stored.  Also some proto‐
471           cols, like POP can supply that information.
472
473       $obj->isMultipart
474
475           See "About the body" in Mail::Message::Head
476
477       $obj->recvstamp
478
479           Returns an indication about when the message was sent, but only
480           using the "Date" field in the header as last resort: we do not
481           trust the sender of the message to specify the correct date.  See
482           timestamp() when you do trust the sender.
483
484           Many spam producers fake a date, which mess up the order of receiv‐
485           ing things.  The timestamp which is produced is derived from the
486           Received headers, if they are present, and "undef" otherwise.
487
488           The timestamp is encoded as "time" is on your system (see perldoc
489           -f time), and as such usable for the "gmtime" and "localtime" meth‐
490           ods.
491
492           Example: of time-sorting folders with received messages
493
494            my $folder = $mgr->open('InBox');
495            my @messages = sort {$a->recvstamp <=> $b->recvstamp}
496                              $folder->messages;
497
498           Example: of time-sorting messages of mixed origin
499
500            my $folder = $mgr->open('MyFolder');
501
502            # Pre-calculate timestamps to be sorted (for speed)
503            my @stamps = map { [ ($_->timestamp ⎪⎪ 0), $_ ] }
504                                $folder->messages;
505
506            my @sorted
507              = map { $_->[1] }      # get the message for the stamp
508                  sort {$a->[0] <=> $b->[0]}   # stamps are numerics
509                     @stamps;
510
511       $obj->timestamp
512
513           Returns an indication about when the message was sent, with as lit‐
514           tle guessing as possible.  In this case, the date as specified by
515           the sender is trusted.  See recvstamp() when you do not want to
516           trust the sender.
517
518           The timestamp is encoded as "time" is on your system (see perldoc
519           -f time), and as such usable for the "gmtime" and "localtime" meth‐
520           ods.
521
522       Internals
523
524       $obj->addNoRealize(FIELD)
525
526           See "Internals" in Mail::Message::Head
527
528       $obj->addOrderedFields(FIELDS)
529
530           See "Internals" in Mail::Message::Head
531
532       $obj->createFromLine
533
534           For some mail-folder types separate messages by a line starting
535           with '"From "'.  If a message is moved to such folder from a
536           folder-type which does not support these separators, this method is
537           called to produce one.
538
539       $obj->createMessageId
540
541           Creates a message-id for this message.  This method will be run
542           when a new message is created, or a message is discovered without
543           the message-id header field.  Message-ids are required for detec‐
544           tion of message-threads.  See messageIdPrefix().
545
546       $obj->fileLocation
547
548           See "Internals" in Mail::Message::Head
549
550       $obj->load
551
552           See "Internals" in Mail::Message::Head
553
554       $obj->messageIdPrefix([PREFIX, [HOSTNAME]⎪CODE])
555
556       Mail::Message::Head::Complete->messageIdPrefix([PREFIX, [HOST‐
557       NAME]⎪CODE])
558
559           When options are provided, it sets a new way to create message-ids,
560           as used by createMessageId().  You have two choices: either by pro‐
561           viding a PREFIX and optionally a HOSTNAME, or a CODE reference.
562
563           The CODE reference will be called with the header as first argu‐
564           ment.  You must ensure yourself that the returned value is RFC com‐
565           pliant.
566
567           The PREFIX defaults to "mailbox-$$", the HOSTNAME defaults to the
568           return of Sys::Hostname's method "hostname()".  Inbetween the two,
569           a nano-second time provided by Time::Hires is used.  If that module
570           is not available, "time" is called at the start of the program, and
571           incremented for each newly created id.
572
573           In any case, a subroutine will be created to be used.  A reference
574           to that will be returned.  When the method is called without argu‐
575           ments, but no subroutine is defined yet, one will be created.
576
577           Example: setting a message prefix
578
579             $head->messageIdPrefix('prefix');
580             Mail::Message::Head::Complete->messageIdPrefix('prefix');
581             my $code = $head->messageIdPrefix('mailbox', 'nohost');
582
583             sub new_msgid()
584             {   my $head = shift;
585                 "myid-$$-${(rand 10000)}@example.com";
586             }
587
588             $many_msg->messageIdPrefix(\&new_msgid);
589             Mail::Message::Head::Complete->messageIdPrefix(&new_msgid);
590
591       $obj->moveLocation(DISTANCE)
592
593           See "Internals" in Mail::Message::Head
594
595       $obj->read(PARSER)
596
597           See "Internals" in Mail::Message::Head
598
599       $obj->setNoRealize(FIELD)
600
601           See "Internals" in Mail::Message::Head
602
603       Error handling
604
605       $obj->AUTOLOAD
606
607           See "Error handling" in Mail::Reporter
608
609       $obj->addReport(OBJECT)
610
611           See "Error handling" in Mail::Reporter
612
613       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
614
615       Mail::Message::Head::Complete->defaultTrace([LEVEL]⎪[LOGLEVEL,
616       TRACELEVEL]⎪[LEVEL, CALLBACK])
617
618           See "Error handling" in Mail::Reporter
619
620       $obj->errors
621
622           See "Error handling" in Mail::Reporter
623
624       $obj->log([LEVEL [,STRINGS]])
625
626       Mail::Message::Head::Complete->log([LEVEL [,STRINGS]])
627
628           See "Error handling" in Mail::Reporter
629
630       $obj->logPriority(LEVEL)
631
632       Mail::Message::Head::Complete->logPriority(LEVEL)
633
634           See "Error handling" in Mail::Reporter
635
636       $obj->logSettings
637
638           See "Error handling" in Mail::Reporter
639
640       $obj->notImplemented
641
642           See "Error handling" in Mail::Reporter
643
644       $obj->report([LEVEL])
645
646           See "Error handling" in Mail::Reporter
647
648       $obj->reportAll([LEVEL])
649
650           See "Error handling" in Mail::Reporter
651
652       $obj->trace([LEVEL])
653
654           See "Error handling" in Mail::Reporter
655
656       $obj->warnings
657
658           See "Error handling" in Mail::Reporter
659
660       Cleanup
661
662       $obj->DESTROY
663
664           See "Cleanup" in Mail::Reporter
665
666       $obj->inGlobalDestruction
667
668           See "Cleanup" in Mail::Reporter
669

DETAILS

DIAGNOSTICS

672       Warning: Cannot remove field $name from header: not found.
673
674       You ask to remove a field which is not known in the header.  Using
675       delete(), reset(), or set() to do the job will not result in warnings:
676       those methods check the existence of the field first.
677
678       Warning: Field objects have an implied name ($name)
679
680       Error: Package $package does not implement $method.
681
682       Fatal error: the specific package (or one of its superclasses) does not
683       implement this method where it should. This message means that some
684       other related classes do implement this method however the class at
685       hand does not.  Probably you should investigate this and probably
686       inform the author of the package.
687

LICENSE

693       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
694       ChangeLog.
695
696       This program is free software; you can redistribute it and/or modify it
697       under the same terms as Perl itself.  See
698       http://www.perl.com/perl/misc/Artistic.html
699
700
701
702perl v5.8.8                       2007-03-25  Mail::Message::Head::Complete(3)