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
31 overload: ""
32 See "OVERLOADED" in Mail::Message::Head
33 overload: bool
35 See "OVERLOADED" in Mail::Message::Head
36
38 Constructors
39 $obj->build([PAIR|FIELD]-LIST)
40 Undefined values are interpreted as empty field values, and
41 therefore skipped.
42 $obj->clone([NAMES|ARRAY-OF-NAMES|REGEXS])
44 Make a copy of the header, optionally limited only to the header
45 lines specified by NAMES. See grepNames() on the way these fields
46 can be used.
47 example:
49 my $newhead = $head->clone('Subject', 'Received');
51 Mail::Message::Head::Complete->new(OPTIONS)
53 See "Constructors" in Mail::Message::Head
54 The header
56 $obj->isDelayed
57 See "The header" in Mail::Message::Head
58 $obj->isEmpty
60 See "The header" in Mail::Message::Head
61 $obj->isModified
63 See "The header" in Mail::Message::Head
64 $obj->knownNames
66 See "The header" in Mail::Message::Head
67 $obj->message([MESSAGE])
69 See "The header" in Mail::Message::Head
70 $obj->modified([BOOLEAN])
72 See "The header" in Mail::Message::Head
73 $obj->nrLines
75 Return the number of lines needed to display this header (including
76 the trailing newline)
77 $obj->orderedFields
79 See "The header" in Mail::Message::Head
80 $obj->size
82 Return the number of bytes needed to display this header (including
83 the trailing newline). On systems which use CRLF as line
84 separator, the number of lines in the header (see nrLines()) must
85 be added to find the actual size in the file.
86 $obj->wrap(INTEGER)
88 Re-fold all fields from the header to contain at most INTEGER
89 number of characters per line.
90 example: re-folding a header
92 $msg->head->wrap(78);
94 Access to the header
96 $obj->add(FIELD | LINE | (NAME,BODY[,ATTRS]))
97 Add a field to the header. If a field is added more than once, all
98 values are stored in the header, in the order they are added.
99 When a FIELD object is specified (some Mail::Message::Field
101 instance), that will be added. Another possibility is to specify a
102 raw header LINE, or a header line nicely split-up in NAME and BODY,
103 in which case the field constructor is called for you.
104 LINE or BODY specifications which are terminated by a new-line are
106 considered to be correctly folded. Lines which are not terminated
107 by a new-line will be folded when needed: new-lines will be added
108 where required. It is strongly advised to let MailBox do the
109 folding for you.
110 The return value of this method is the Mail::Message::Field object
112 which is created (or was specified).
113 example:
115 my $head = Mail::Message::Head->new;
117 $head->add('Subject: hi!');
118 $head->add(From => 'me@home');
119 my $field = Mail::Message::Field->new('To: you@there');
120 $head->add($field);
121 my Mail::Message::Field $s = $head->add(Sender => 'I');
122 $obj->addListGroup(OBJECT)
124 A list group is a set of header fields which contain data about a
125 mailing list which was used to transmit the message. See
126 Mail::Message::Head::ListGroup for details about the implementation
127 of the OBJECT.
128 When you have a list group prepared, you can add it later using
130 this method. You will get your private copy of the list group data
131 in return, because the same group can be used for multiple
132 messages.
133 example: of adding a list group to a header
135 my $lg = Mail::Message::Head::ListGroup->new(...);
137 my $own_lg = $msg->head->addListGroup($lg);
138 $obj->addResentGroup(RESENT-GROUP|DATA)
140 Add a RESENT-GROUP (a Mail::Message::Head::ResentGroup object) to
141 the header. If you specify DATA, that is used to create such group
142 first. If no "Received" line is specified, it will be created for
143 you.
144 These header lines have nothing to do with the user's sense of
146 "reply" or "forward" actions: these lines trace the e-mail
147 transport mechanism.
148 example:
150 my $rg = Mail::Message::Head::ResentGroup->new(head => $head, ...);
152 $head->addResentGroup($rg);
153 my $rg = $head->addResentGroup(From => 'me');
155 $obj->addSpamGroup(OBJECT)
157 A spam fighting group is a set of header fields which contains data
158 which is used to fight spam. See Mail::Message::Head::SpamGroup
159 for details about the implementation of the OBJECT.
160 When you have a spam group prepared, you can add it later using
162 this method. You will get your private copy of the spam group data
163 in return, because the same group can be used for multiple
164 messages.
165 example: of adding a spam group to a header
167 my $sg = Mail::Message::Head::SpamGroup->new(...);
169 my $own_sg = $msg->head->addSpamGroup($sg);
170 $obj->count(NAME)
172 Count the number of fields with this NAME. Most fields will return
173 1: only one occurance in the header. As example, the "Received"
174 fields are usually present more than once.
175 $obj->delete(NAME)
177 Remove the field with the specified name. If the header contained
178 multiple lines with the same name, they will be replaced all
179 together. This method simply calls reset() without replacement
180 fields. READ THE IMPORTANT WARNING IN removeField()
181 $obj->get(NAME [,INDEX])
183 See "Access to the header" in Mail::Message::Head
184 $obj->grepNames([NAMES|ARRAY-OF-NAMES|REGEXS])
186 Filter from all header fields those with names which start will any
187 of the specified list. When no names are specified, all fields
188 will be returned. The list is ordered as they where read from
189 file, or added later.
190 The NAMES are considered regular expressions, and will all be
192 matched case insensitive and attached to the front of the string
193 only. You may also specify one or more prepared regexes.
194 example:
196 my @f = $head->grepNames(); # same as $head->orderedFields
198 my @f = $head->grepNames('X-', 'Subject', ');
199 my @to = $head->grepNames('To\b'); # will only select To
200 $obj->listGroup
202 Returns a list group description: the set of headers which form the
203 information about mailing list software used to transport the
204 message. See also addListGroup() and removeListGroup().
205 example: use of listGroup()
207 if(my $lg = $msg->head->listGroup)
209 { $lg->print(\*STDERR);
210 $lg->delete;
211 }
212 $msg->head->removeListGroup;
214 $obj->names
216 Returns a full ordered list of known field names, as defined in the
217 header. Fields which were reset() to be empty will still be listed
218 here.
219 $obj->print([FILEHANDLE])
221 Print all headers to the specified FILEHANDLE, by default the
222 selected filehandle. See printUndisclosed() to limit the headers
223 to include only the public headers.
224 example:
226 $head->print(\*OUT);
228 $head->print;
229 my $fh = IO::File->new(...);
231 $head->print($fh);
232 $obj->printSelected(FILEHANDLE, (STRING|REGEXP)s)
234 Like the usual print(), the header lines are printed to the
235 specified FILEHANDLE. In this case, however, only the fields with
236 names as specified by STRING (case insensative) or REGEXP are
237 printed. They will stay the in-order of the source header.
238 example: printing only a subset of the fields
240 $head->printSelected(STDOUT, qw/Subject From To/, qr/^x\-(spam|xyz)\-/i)
242 $obj->printUndisclosed([FILEHANDLE])
244 Like the usual print(), the header lines are printed to the
245 specified FILEHANDLE, by default the selected filehandle. In this
246 case, however, "Bcc" and "Resent-Bcc" lines are included.
247 $obj->removeContentInfo
249 Remove all body related fields from the header. The header will
250 become partial.
251 $obj->removeField(FIELD)
253 Remove the specified FIELD object from the header. This is useful
254 when there are possible more than one fields with the same name,
255 and you need to remove exactly one of them. Also have a look at
256 delete(), reset(), and set().
257 See also Mail::Message::Head::Partial::removeFields() (mind the 's'
259 at the end of the name), which accepts a string or regular
260 expression as argument to select the fields to be removed.
261 WARNING WARNING WARNING: for performance reasons, the header
263 administration uses weak references (see Scalar::Util method
264 weaken()> to figure-out which fields have been removed. A header
265 is a hash of field for fast search and an array of weak references
266 to remember the order of the fields, required for printing. If the
267 field is removed from the hash, the weak-ref is set to undef and
268 the field not printed.
269 However... it is easy to disturb this process. Example:
271 my $msg = ....; # subject ref-count = 1 + 0 = 1
272 $msg->head->delete('Subject'); # subject ref-count = 0 = 0:
273 clean-up
274 $msg->print; # subject doesn't show: ok
275 But
277 my $msg = ....; # subject ref-count = 1 + 0 = 1
278 my $s = $msg->head->get('subject'); # ref-count = 1 + 1 + 0 = 2
279 $msg->head->delete('Subject'); # subject ref-count = 1 + 0 = 1:
280 no clean-up
281 $msg->print; # subject DOES show: not ok
282 undef $s; # ref-count becomes 0: clean-up
283 $msg->print; # subject doesn't show: ok
284 To avoid the latter situation, do not catch the field object, but
286 only the field content. SAVE are all methods which return the
287 text:
288 my $s = $msg->head->get('subject')->body;
289 my $s = $msg->head->get('subject')->unfoldedBody;
290 my $s = $msg->head->get('subject')->foldedBody;
291 my $s = $msg->head->get('subject')->foldedBody;
292 my $s = $msg->get('subject');
293 my $s = $msg->subject;
294 my $s = $msg->string;
295 $obj->removeFields(STRING|REGEXP, [STRING|REGEXP, ...])
297 The header object is turned into a Mail::Message::Head::Partial
298 object which has a set of fields removed. Read about the
299 implications and the possibilities in
300 Mail::Message::Head::Partial::removeFields().
301 $obj->removeFieldsExcept(STRING|REGEXP, [STRING|REGEXP, ...])
303 The header object is turned into a Mail::Message::Head::Partial
304 object which has a set of fields removed. Read about the
305 implications and the possibilities in
306 Mail::Message::Head::Partial::removeFieldsExcept().
307 $obj->removeListGroup
309 Removes all fields related to mailing list administration at once.
310 The header object is turned into a Mail::Message::Head::Partial
311 object. Read about the implications and the possibilities in
312 Mail::Message::Head::Partial::removeListGroup().
313 $obj->removeResentGroups
315 Removes all resent groups at once. The header object is turned
316 into a Mail::Message::Head::Partial object. Read about the
317 implications and the possibilities in
318 Mail::Message::Head::Partial::removeResentGroups().
319 $obj->removeSpamGroups
321 Removes all fields which were added by various spam detection
322 software at once. The header object is turned into a
323 Mail::Message::Head::Partial object. Read about the implications
324 and the possibilities in
325 Mail::Message::Head::Partial::removeSpamGroups().
326 $obj->resentGroups
328 Returns a list of Mail::Message::Head::ResentGroup objects which
329 each represent one intermediate point in the message's transmission
330 in the order as they appear in the header: the most recent one
331 first. See also addResentGroup() and removeResentGroups().
332 A resent group contains a set of header fields whose names start
334 with "Resent-*". Before the first "Resent" line is trace
335 information, which is composed of an optional "Return-Path" field
336 and an required "Received" field.
337 $obj->reset(NAME, FIELDS)
339 Replace the values in the header fields named by NAME with the
340 values specified in the list of FIELDS. A single name can
341 correspond to multiple repeated fields. READ THE IMPORTANT WARNING
342 IN removeField()
343 Removing fields which are part of one of the predefined field
345 groups is not a smart idea. You can better remove these fields as
346 group, all together. For instance, the 'Received' lines are part
347 of resent groups, 'X-Spam' is past of a spam group, and "List-Post"
348 belongs to a list group. You can delete a whole group with
349 Mail::Message::Head::FieldGroup::delete(), or with methods which
350 are provided by Mail::Message::Head::Partial.
351 If FIELDS is empty, the corresponding NAME fields will be removed.
353 The location of removed fields in the header order will be
354 remembered. Fields with the same name which are added later will
355 appear at the remembered position. This is equivalent to the
356 delete() method.
357 example:
359 # reduce number of 'Keywords' lines to last 5)
361 my @keywords = $head->get('Keywords');
362 $head->reset('Keywords', @keywords[-5..-1]) if @keywords > 5;
363 # Reduce the number of Received lines to only the last added one.
365 my @rgs = $head->resentGroups;
366 shift @rgs; # keep this one (later is added in front)
367 $_->delete foreach @rgs;
368 $obj->set(FIELD | LINE | (NAME, BODY [,ATTRS]))
370 The "set" method is similar to the add() method, and takes the same
371 options. However, existing values for fields will be removed before
372 a new value is added. READ THE IMPORTANT WARNING IN removeField()
373 $obj->spamDetected
375 Returns whether one of the spam groups defines a report about spam.
376 If there are not header fields in the message which relate to spam-
377 detection software, "undef" is returned. The spamgroups which
378 report spam are returned.
379 example:
381 $message->delete if $message->spamDetected;
383 call_spamassassin($message)
385 unless defined $message->spamDetected;
386 $obj->spamGroups([NAMES])
388 Returns a list of Mail::Message::Head::SpamGroup objects, each
389 collecting some lines which contain spam fighting information.
390 When any NAMES are given, then only these groups are returned. See
391 also addSpamGroup() and removeSpamGroups().
392 In scalar context, with exactly one NAME specified, that group will
394 be returned. With more NAMES or without NAMES, a list will be
395 returned (which defaults to the length of the list in scalar
396 context).
397 example: use of listGroup()
399 my @sg = $msg->head->spamGroups;
401 $sg[0]->print(\*STDERR);
402 $sg[-1]->delete;
403 my $sg = $msg->head->spamGroups('SpamAssassin');
405 $obj->string
407 Returns the whole header as one scalar (in scalar context) or list
408 of lines (list context). Triggers completion.
409 $obj->study(NAME [,INDEX])
411 See "Access to the header" in Mail::Message::Head
412 About the body
414 $obj->guessBodySize
415 See "About the body" in Mail::Message::Head
416 $obj->guessTimeStamp
418 Make a guess about when the message was origanally posted, based on
419 the information found in the header's "Date" field.
420 For some kinds of folders, Mail::Message::guessTimestamp() may
422 produce a better result, for instance by looking at the
423 modification time of the file in which the message is stored. Also
424 some protocols, like POP can supply that information.
425 $obj->isMultipart
427 See "About the body" in Mail::Message::Head
428 $obj->recvstamp
430 Returns an indication about when the message was sent, but only
431 using the "Date" field in the header as last resort: we do not
432 trust the sender of the message to specify the correct date. See
433 timestamp() when you do trust the sender.
434 Many spam producers fake a date, which mess up the order of
436 receiving things. The timestamp which is produced is derived from
437 the Received headers, if they are present, and "undef" otherwise.
438 The timestamp is encoded as "time" is on your system (see perldoc
440 -f time), and as such usable for the "gmtime" and "localtime"
441 methods.
442 example: of time-sorting folders with received messages
444 my $folder = $mgr->open('InBox');
446 my @messages = sort {$a->recvstamp <=> $b->recvstamp}
447 $folder->messages;
448 example: of time-sorting messages of mixed origin
450 my $folder = $mgr->open('MyFolder');
452 # Pre-calculate timestamps to be sorted (for speed)
454 my @stamps = map { [ ($_->timestamp || 0), $_ ] }
455 $folder->messages;
456 my @sorted
458 = map { $_->[1] } # get the message for the stamp
459 sort {$a->[0] <=> $b->[0]} # stamps are numerics
460 @stamps;
461 $obj->timestamp
463 Returns an indication about when the message was sent, with as
464 little guessing as possible. In this case, the date as specified
465 by the sender is trusted. See recvstamp() when you do not want to
466 trust the sender.
467 The timestamp is encoded as "time" is on your system (see perldoc
469 -f time), and as such usable for the "gmtime" and "localtime"
470 methods.
471 Internals
473 $obj->addNoRealize(FIELD)
474 See "Internals" in Mail::Message::Head
475 $obj->addOrderedFields(FIELDS)
477 See "Internals" in Mail::Message::Head
478 $obj->createFromLine
480 For some mail-folder types separate messages by a line starting
481 with '"From "'. If a message is moved to such folder from a
482 folder-type which does not support these separators, this method is
483 called to produce one.
484 $obj->createMessageId
486 Creates a message-id for this message. This method will be run
487 when a new message is created, or a message is discovered without
488 the message-id header field. Message-ids are required for
489 detection of message-threads. See messageIdPrefix().
490 $obj->fileLocation
492 See "Internals" in Mail::Message::Head
493 $obj->load
495 See "Internals" in Mail::Message::Head
496 $obj->messageIdPrefix([PREFIX, [HOSTNAME]|CODE])
498 Mail::Message::Head::Complete->messageIdPrefix([PREFIX,
499 [HOSTNAME]|CODE])
500 When options are provided, it sets a new way to create message-ids,
502 as used by createMessageId(). You have two choices: either by
503 providing a PREFIX and optionally a HOSTNAME, or a CODE reference.
504 The CODE reference will be called with the header as first
506 argument. You must ensure yourself that the returned value is RFC
507 compliant.
508 The PREFIX defaults to "mailbox-$$", the HOSTNAME defaults to the
510 return of Sys::Hostname's method "hostname()". Inbetween the two,
511 a nano-second time provided by Time::Hires is used. If that module
512 is not available, "time" is called at the start of the program, and
513 incremented for each newly created id.
514 In any case, a subroutine will be created to be used. A reference
516 to that will be returned. When the method is called without
517 arguments, but no subroutine is defined yet, one will be created.
518 example: setting a message prefix
520 $head->messageIdPrefix('prefix');
522 Mail::Message::Head::Complete->messageIdPrefix('prefix');
523 my $code = $head->messageIdPrefix('mailbox', 'nohost');
524 sub new_msgid()
526 { my $head = shift;
527 "myid-$$-${(rand 10000)}@example.com";
528 }
529 $many_msg->messageIdPrefix(\&new_msgid);
531 Mail::Message::Head::Complete->messageIdPrefix(&new_msgid);
532 $obj->moveLocation(DISTANCE)
534 See "Internals" in Mail::Message::Head
535 $obj->read(PARSER)
537 See "Internals" in Mail::Message::Head
538 $obj->setNoRealize(FIELD)
540 See "Internals" in Mail::Message::Head
541 Error handling
543 $obj->AUTOLOAD
544 See "Error handling" in Mail::Reporter
545 $obj->addReport(OBJECT)
547 See "Error handling" in Mail::Reporter
548 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
550 Mail::Message::Head::Complete->defaultTrace([LEVEL]|[LOGLEVEL,
551 TRACELEVEL]|[LEVEL, CALLBACK])
552 See "Error handling" in Mail::Reporter
554 $obj->errors
556 See "Error handling" in Mail::Reporter
557 $obj->log([LEVEL [,STRINGS]])
559 Mail::Message::Head::Complete->log([LEVEL [,STRINGS]])
560 See "Error handling" in Mail::Reporter
562 $obj->logPriority(LEVEL)
564 Mail::Message::Head::Complete->logPriority(LEVEL)
565 See "Error handling" in Mail::Reporter
567 $obj->logSettings
569 See "Error handling" in Mail::Reporter
570 $obj->notImplemented
572 See "Error handling" in Mail::Reporter
573 $obj->report([LEVEL])
575 See "Error handling" in Mail::Reporter
576 $obj->reportAll([LEVEL])
578 See "Error handling" in Mail::Reporter
579 $obj->trace([LEVEL])
581 See "Error handling" in Mail::Reporter
582 $obj->warnings
584 See "Error handling" in Mail::Reporter
585 Cleanup
587 $obj->DESTROY
588 See "Cleanup" in Mail::Reporter
589 $obj->inGlobalDestruction
591 See "Cleanup" in Mail::Reporter
592
594 Warning: Cannot remove field $name from header: not found.
595 You ask to remove a field which is not known in the header. Using
596 delete(), reset(), or set() to do the job will not result in
597 warnings: those methods check the existence of the field first.
598 Warning: Field objects have an implied name ($name)
600 Error: Package $package does not implement $method.
601 Fatal error: the specific package (or one of its superclasses) does
602 not implement this method where it should. This message means that
603 some other related classes do implement this method however the
604 class at hand does not. Probably you should investigate this and
605 probably inform the author of the package.
606
608 This module is part of Mail-Box distribution version 2.097, built on
609 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
610
612 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
613 ChangeLog.
614 This program is free software; you can redistribute it and/or modify it
616 under the same terms as Perl itself. See
617 http://www.perl.com/perl/misc/Artistic.html
618perl v5.12.3 2011-01-26 Mail::Message::Head::Complete(3)