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

OVERLOADED

33       Extends "OVERLOADED" in Mail::Message::Head.
34
35       overload: ""
36           Inherited, see "OVERLOADED" in Mail::Message::Head
37
38       overload: bool
39           Inherited, see "OVERLOADED" in Mail::Message::Head
40

METHODS

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

DETAILS

610       Extends "DETAILS" in Mail::Message::Head.
611

DIAGNOSTICS

613       Warning: Cannot remove field $name from header: not found.
614           You ask to remove a field which is not known in the header.  Using
615           delete(), reset(), or set() to do the job will not result in
616           warnings: those methods check the existence of the field first.
617
618       Warning: Field objects have an implied name ($name)
619       Error: Package $package does not implement $method.
620           Fatal error: the specific package (or one of its superclasses) does
621           not implement this method where it should. This message means that
622           some other related classes do implement this method however the
623           class at hand does not.  Probably you should investigate this and
624           probably inform the author of the package.
625

SEE ALSO

627       This module is part of Mail-Message distribution version 3.010, built
628       on October 14, 2020. Website: http://perl.overmeer.net/CPAN/
629

LICENSE

631       Copyrights 2001-2020 by [Mark Overmeer <markov@cpan.org>]. For other
632       contributors see ChangeLog.
633
634       This program is free software; you can redistribute it and/or modify it
635       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
636
637
638
639perl v5.32.1                      2021-01-27  Mail::Message::Head::Complete(3)
Impressum