1Mail::Message::Head::CoUmspelretCeo(n3t)ributed Perl DocMuamieln:t:aMteisosnage::Head::Complete(3)
2
6 Mail::Message::Head::Complete - the header of one message
7
9 Mail::Message::Head::Complete
10 is a Mail::Message::Head
11 is a Mail::Reporter
12 Mail::Message::Head::Complete is extended by
14 Mail::Message::Head::Partial
15 Mail::Message::Replace::MailHeader
16 Mail::Message::Head::Complete is realized by
18 Mail::Message::Head::Delayed
19 Mail::Message::Head::Subset
20
22 my $head = Mail::Message::Head::Complete->new;
23 See Mail::Message::Head
24
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 Extends "DESCRIPTION" in Mail::Message::Head.
31
33 Extends "OVERLOADED" in Mail::Message::Head.
34 overload: ""
36 Inherited, see "OVERLOADED" in Mail::Message::Head
37 overload: bool
39 Inherited, see "OVERLOADED" in Mail::Message::Head
40
42 Extends "METHODS" in Mail::Message::Head.
43 Constructors
45 Extends "Constructors" in Mail::Message::Head.
46 Mail::Message::Head::Complete->build( [PAIR|$field], ... )
48 Undefined values are interpreted as empty field values, and
49 therefore skipped.
50 $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 example:
57 my $newhead = $head->clone('Subject', 'Received');
59 Mail::Message::Head::Complete->new(%options)
61 Inherited, see "Constructors" in Mail::Message::Head
62 The header
64 Extends "The header" in Mail::Message::Head.
65 $obj->isDelayed()
67 Inherited, see "The header" in Mail::Message::Head
68 $obj->isEmpty()
70 Inherited, see "The header" in Mail::Message::Head
71 $obj->isModified()
73 Inherited, see "The header" in Mail::Message::Head
74 $obj->knownNames()
76 Inherited, see "The header" in Mail::Message::Head
77 $obj->message( [$message] )
79 Inherited, see "The header" in Mail::Message::Head
80 $obj->modified( [BOOLEAN] )
82 Inherited, see "The header" in Mail::Message::Head
83 $obj->nrLines()
85 Return the number of lines needed to display this header (including
86 the trailing newline)
87 $obj->orderedFields()
89 Inherited, see "The header" in Mail::Message::Head
90 $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 $obj->wrap($integer)
98 Re-fold all fields from the header to contain at most $integer
99 number of characters per line.
100 example: re-folding a header
102 $msg->head->wrap(78);
104 Access to the header
106 Extends "Access to the header" in Mail::Message::Head.
107 $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 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 $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 The return value of this method is the Mail::Message::Field object
124 which is created (or was specified).
125 example:
127 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 $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 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 example: of adding a list group to a header
147 my $lg = Mail::Message::Head::ListGroup->new(...);
149 my $own_lg = $msg->head->addListGroup($lg);
150 $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 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 example:
162 my $rg = Mail::Message::Head::ResentGroup->new(head => $head, ...);
164 $head->addResentGroup($rg);
165 my $rg = $head->addResentGroup(From => 'me');
167 $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 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 example: of adding a spam group to a header
179 my $sg = Mail::Message::Head::SpamGroup->new(...);
181 my $own_sg = $msg->head->addSpamGroup($sg);
182 $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 $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 $obj->get( $name, [$index] )
195 Inherited, see "Access to the header" in Mail::Message::Head
196 $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 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 example:
208 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 $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 example: use of listGroup()
219 if(my $lg = $msg->head->listGroup)
221 { $lg->print(\*STDERR);
222 $lg->delete;
223 }
224 $msg->head->removeListGroup;
226 $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 $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 example:
238 $head->print(\*OUT);
240 $head->print;
241 my $fh = IO::File->new(...);
243 $head->print($fh);
244 $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 example: printing only a subset of the fields
252 $head->printSelected(STDOUT, qw/Subject From To/, qr/^x\-(spam|xyz)\-/i)
254 $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 $obj->removeContentInfo()
261 Remove all body related fields from the header. The header will
262 become partial.
263 $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 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 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 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 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 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 $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 $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 $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 $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 $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 $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 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 $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 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 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 example:
371 # 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 # 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 $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 $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 example:
393 $message->delete if $message->spamDetected;
395 call_spamassassin($message)
397 unless defined $message->spamDetected;
398 $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 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 example: use of listGroup()
411 my @sg = $msg->head->spamGroups;
413 $sg[0]->print(\*STDERR);
414 $sg[-1]->delete;
415 my $sg = $msg->head->spamGroups('SpamAssassin');
417 $obj->string()
419 Returns the whole header as one scalar (in scalar context) or list
420 of lines (list context). Triggers completion.
421 $obj->study( $name, [$index] )
423 Inherited, see "Access to the header" in Mail::Message::Head
424 About the body
426 Extends "About the body" in Mail::Message::Head.
427 $obj->guessBodySize()
429 Inherited, see "About the body" in Mail::Message::Head
430 $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 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 $obj->isMultipart()
441 Inherited, see "About the body" in Mail::Message::Head
442 $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 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 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 example: of time-sorting folders with received messages
458 my $folder = $mgr->open('InBox');
460 my @messages = sort {$a->recvstamp <=> $b->recvstamp}
461 $folder->messages;
462 example: of time-sorting messages of mixed origin
464 my $folder = $mgr->open('MyFolder');
466 # Pre-calculate timestamps to be sorted (for speed)
468 my @stamps = map { [ ($_->timestamp || 0), $_ ] }
469 $folder->messages;
470 my @sorted
472 = map { $_->[1] } # get the message for the stamp
473 sort {$a->[0] <=> $b->[0]} # stamps are numerics
474 @stamps;
475 $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 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 Internals
487 Extends "Internals" in Mail::Message::Head.
488 $obj->addNoRealize($field)
490 Inherited, see "Internals" in Mail::Message::Head
491 $obj->addOrderedFields($fields)
493 Inherited, see "Internals" in Mail::Message::Head
494 $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 $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 $obj->fileLocation()
508 Inherited, see "Internals" in Mail::Message::Head
509 $obj->load()
511 Inherited, see "Internals" in Mail::Message::Head
512 $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 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 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 the
528 two, a nano-second time provided by Time::HiRes is used. If that
529 module is not available, "time" is called at the start of the
530 program, and incremented for each newly created id.
531 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 example: setting a message prefix
537 $head->messageIdPrefix('prefix');
539 Mail::Message::Head::Complete->messageIdPrefix('prefix');
540 my $code = $head->messageIdPrefix('mailbox', 'nohost');
541 sub new_msgid()
543 { my $head = shift;
544 "myid-$$-${(rand 10000)}@example.com";
545 }
546 $many_msg->messageIdPrefix(\&new_msgid);
548 Mail::Message::Head::Complete->messageIdPrefix(&new_msgid);
549 $obj->moveLocation($distance)
551 Inherited, see "Internals" in Mail::Message::Head
552 $obj->read($parser)
554 Inherited, see "Internals" in Mail::Message::Head
555 $obj->setNoRealize($field)
557 Inherited, see "Internals" in Mail::Message::Head
558 Error handling
560 Extends "Error handling" in Mail::Message::Head.
561 $obj->AUTOLOAD()
563 Inherited, see "Error handling" in Mail::Reporter
564 $obj->addReport($object)
566 Inherited, see "Error handling" in Mail::Reporter
567 $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 $obj->errors()
575 Inherited, see "Error handling" in Mail::Reporter
576 $obj->log( [$level, [$strings]] )
578 Mail::Message::Head::Complete->log( [$level, [$strings]] )
579 Inherited, see "Error handling" in Mail::Reporter
580 $obj->logPriority($level)
582 Mail::Message::Head::Complete->logPriority($level)
583 Inherited, see "Error handling" in Mail::Reporter
584 $obj->logSettings()
586 Inherited, see "Error handling" in Mail::Reporter
587 $obj->notImplemented()
589 Inherited, see "Error handling" in Mail::Reporter
590 $obj->report( [$level] )
592 Inherited, see "Error handling" in Mail::Reporter
593 $obj->reportAll( [$level] )
595 Inherited, see "Error handling" in Mail::Reporter
596 $obj->trace( [$level] )
598 Inherited, see "Error handling" in Mail::Reporter
599 $obj->warnings()
601 Inherited, see "Error handling" in Mail::Reporter
602 Cleanup
604 Extends "Cleanup" in Mail::Message::Head.
605 $obj->DESTROY()
607 Inherited, see "Cleanup" in Mail::Reporter
608
610 Extends "DETAILS" in Mail::Message::Head.
611
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 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
627 This module is part of Mail-Message distribution version 3.013, built
628 on June 24, 2023. Website: http://perl.overmeer.net/CPAN/
629
631 Copyrights 2001-2023 by [Mark Overmeer <markov@cpan.org>]. For other
632 contributors see ChangeLog.
633 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/
636perl v5.38.0 2023-07-20 Mail::Message::Head::Complete(3)