1Mail::Message::Head(3)User Contributed Perl DocumentationMail::Message::Head(3)
2
6 Mail::Message::Head - the header of one message
7
9 Mail::Message::Head
10 is a Mail::Reporter
11 Mail::Message::Head is extended by
13 Mail::Box::IMAP4::Head
14 Mail::Message::Head::Complete
15 Mail::Message::Head::Delayed
16 Mail::Message::Head::Subset
17
19 my $head = Mail::Message::Head->new;
20 $head->add('From: me@localhost');
21 $head->add(From => 'me@localhost');
22 $head->add(Mail::Message::Field->new(From => 'me'));
23 my Mail::Message::Field $subject = $head->get('subject');
24 my Mail::Message::Field @rec = $head->get('received');
25 $head->delete('From');
26
28 "Mail::Message::Head" MIME headers are part of Mail::Message messages,
29 which are grouped in Mail::Box folders.
30 ATTENTION!!! most functionality about e-mail headers is described in
32 Mail::Message::Head::Complete, which is a matured header object. Other
33 kinds of headers will be translated to that type when time comes.
34 On this page, the general methods which are available on any header are
36 described. Read about differences in the sub-class specific pages.
37
39 overload: ""
40 (stringifaction) The header, when used as string, will format as if
42 Mail::Message::Head::Complete::string() was called, so return a
43 nicely folder full header. An exception is made for Carp, which
44 will get a simplified string to avoid unreadible messages from
45 "croak" and "confess".
46 Example: using a header object as string
48 print $head; # implicit stringification by print
50 $head->print; # the same
51 print "$head"; # explicit stringication
53 overload: bool
55 When the header does not contain any lines (which is illegal,
57 according to the RFCs), false is returned. In all other cases, a
58 true value is produced.
59
61 Constructors
62 $obj->build([PAIR⎪FIELD]-LIST)
64 A fast way to construct a header with many lines. The PAIRs are
66 "(name, content)" pairs of the header, but it is also possible to
67 pass Mail::Message::Field objects. A Mail::Message::Head::Com‐
68 plete header is created by simply calling Mail::Message::Head::Com‐
69 plete::build(), and then each field is added. Double field names
70 are permitted.
71 Example:
73 my $subject = Mail::Message::Full->new(Subject => 'xyz');
75 my $head = Mail::Message::Head->build
77 ( From => 'me@example.com'
78 , To => 'you@anywhere.aq'
79 , $subject
80 , Received => 'one'
81 , Received => 'two'
82 );
83 print ref $head;
85 # --> Mail::Message::Head::Complete
86 Mail::Message::Head->new(OPTIONS)
88 Create a new message header object. The object will store all the
90 fields of a header. When you get information from the header, it
91 will be returned to you as Mail::Message::Field objects, although
92 the fields may be stored differently internally.
93 If you try to instantiate a Mail::Message::Head, you will automati‐
95 cally be upgraded to a Mail::Message::Head::Complete --a full head.
96 Option --Defined in --Default
98 field_type Mail::Message::Field::Fast
99 log Mail::Reporter 'WARNINGS'
100 message undef
101 modified <false>
102 trace Mail::Reporter 'WARNINGS'
103 . field_type CLASS
105 The type of objects that all the fields will have. This must
107 be an extension of Mail::Message::Field.
108 . log LEVEL
110 . message MESSAGE
112 The MESSAGE where this header belongs to. Usually, this is not
114 known at creation of the header, but sometimes it is. If not,
115 call the message() method later to set it.
116 . modified BOOLEAN
118 . trace LEVEL
120 The header
122 $obj->isDelayed
124 Headers may only be partially read, in which case they are called
126 delayed. This method returns true if some header information still
127 needs to be read. Returns false if all header data has been read.
128 Will never trigger completion.
129 $obj->isEmpty
131 Are there any fields defined in the current header? Be warned that
133 the header will not be loaded for this: delayed headers will return
134 true in any case.
135 $obj->isModified
137 Returns whether the header has been modified after being read.
139 Example:
141 if($head->isModified) { ... }
143 $obj->knownNames
145 Like Mail::Message::Head::Complete::names(), but only returns the
147 known header fields, which may be less than "names" for header
148 types which are partial. "names()" will trigger completion, where
149 "knownNames()" does not.
150 $obj->message([MESSAGE])
152 Get (after setting) the message where this header belongs to. This
154 does not trigger completion.
155 $obj->modified([BOOLEAN])
157 Sets the modified flag to BOOLEAN. Without value, the current set‐
159 ting is returned, but in that case you can better use isModified().
160 Changing this flag will not trigger header completion.
161 Example:
163 $head->modified(1);
165 if($head->modified) { ... }
166 if($head->isModified) { ... }
167 $obj->orderedFields
169 Retuns the fields ordered the way they were read or added.
171 Access to the header
173 $obj->get(NAME [,INDEX])
175 Get the data which is related to the field with the NAME. The case
177 of the characters in NAME does not matter.
178 If there is only one data element defined for the NAME, or if there
180 is an INDEX specified as the second argument, only the specified
181 element will be returned. If the field NAME matches more than one
182 header the return value depends on the context. In LIST context,
183 all values will be returned in the order they are read. In SCALAR
184 context, only the last value will be returned.
185 Example:
187 my $head = Mail::Message::Head->new;
189 $head->add('Received: abc');
190 $head->add('Received: xyz');
191 $head->add('Subject: greetings');
192 my @rec_list = $head->get('Received');
194 my $rec_scalar = $head->get('Received');
195 print ",@rec_list,$rec_scalar," # ,abc xyz, xyz,
196 print $head->get('Received', 0); # abc
197 my @sub_list = $head->get('Subject');
198 my $sub_scalar = $head->get('Subject');
199 print ",@sub_list,$sub_scalar," # ,greetings, greetings,
200 $obj->study(NAME [,INDEX])
202 Like get(), but puts more effort in understanding the contents of
204 the field. Mail::Message::Field::study() will be called for the
205 field with the specified FIELDNAME, which returns Mail::Mes‐
206 sage::Field::Full objects. In scalar context only the last field
207 with that name is returned. When an INDEX is specified, that ele‐
208 ment is returned.
209 About the body
211 $obj->guessBodySize
213 Try to estimate the size of the body of this message, but without
215 parsing the header or body. The result might be "undef" or a few
216 percent of the real size. It may even be very far of the real
217 value, that's why this is a guess.
218 $obj->isMultipart
220 Returns whether the body of the related message is a multipart
222 body. May trigger completion, when the "Content-Type" field is not
223 defined.
224 Internals
226 $obj->addNoRealize(FIELD)
228 Add a field, like Mail::Message::Head::Complete::add() does, but
230 avoid the loading of a possibly partial header. This method does
231 not test the validity of the argument, nor flag the header as
232 changed. This does not trigger completion.
233 $obj->addOrderedFields(FIELDS)
235 $obj->fileLocation
237 Returns the location of the header in the file, as a pair begin and
239 end. The begin is the first byte of the header. The end is the
240 first byte after the header.
241 $obj->load
243 Be sure that the header is loaded. This returns the loaded header
245 object.
246 $obj->moveLocation(DISTANCE)
248 Move the registration of the header in the file.
250 $obj->read(PARSER)
252 Read the header information of one message into this header struc‐
254 ture. This method is called by the folder object (some Mail::Box
255 sub-class), which passes the PARSER as an argument.
256 $obj->setNoRealize(FIELD)
258 Set a field, but avoid the loading of a possibly partial header as
260 set() does. This method does not test the validity of the argu‐
261 ment, nor flag the header as changed. This does not trigger com‐
262 pletion.
263 Error handling
265 $obj->AUTOLOAD
267 See "Error handling" in Mail::Reporter
269 $obj->addReport(OBJECT)
271 See "Error handling" in Mail::Reporter
273 $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
275 Mail::Message::Head->defaultTrace([LEVEL]⎪[LOGLEVEL,
277 TRACELEVEL]⎪[LEVEL, CALLBACK])
278 See "Error handling" in Mail::Reporter
280 $obj->errors
282 See "Error handling" in Mail::Reporter
284 $obj->log([LEVEL [,STRINGS]])
286 Mail::Message::Head->log([LEVEL [,STRINGS]])
288 See "Error handling" in Mail::Reporter
290 $obj->logPriority(LEVEL)
292 Mail::Message::Head->logPriority(LEVEL)
294 See "Error handling" in Mail::Reporter
296 $obj->logSettings
298 See "Error handling" in Mail::Reporter
300 $obj->notImplemented
302 See "Error handling" in Mail::Reporter
304 $obj->report([LEVEL])
306 See "Error handling" in Mail::Reporter
308 $obj->reportAll([LEVEL])
310 See "Error handling" in Mail::Reporter
312 $obj->trace([LEVEL])
314 See "Error handling" in Mail::Reporter
316 $obj->warnings
318 See "Error handling" in Mail::Reporter
320 Cleanup
322 $obj->DESTROY
324 See "Cleanup" in Mail::Reporter
326 $obj->inGlobalDestruction
328 See "Cleanup" in Mail::Reporter
330
332 Ordered header fields
333 Many Perl implementations make a big mistake by disturbing the order of
335 header fields. For some fields (especially the resent groups, see
336 Mail::Message::Head::ResentGroup) the order shall be maintained.
337 MailBox will keep the order of the fields as they were found in the
339 source. When your add a new field, it will be added at the end. If
340 your replace a field with a new value, it will stay in the original
341 order.
342 Head class implementation
344 The header of a MIME message object contains a set of lines, which are
346 called fields (by default represented by Mail::Message::Field objects).
347 Dependent on the situation, the knowledge about the fields can be in
348 one of three situations, each represented by a sub-class of this mod‐
349 ule:
350 * Mail::Message::Head::Complete
352 In this case, it is sure that all knowledge about the header is
353 available. When you get() information from the header and it is
354 not there, it will never be there.
355 * Mail::Message::Head::Subset
357 There is no certainty whether all header lines are known (probably
358 not). This may be caused as result of reading a fast index file,
359 as described in Mail::Box::MH::Index. The object is automatically
360 transformed into a Mail::Message::Head::Complete when all header
361 lines must be known.
362 * Mail::Message::Head::Partial
364 A partial header is like a subset header: probably the header is
365 incomplete. The means that you are not sure whether a get() for a
366 field fails because the field is not a part of the message or that
367 it fails because it is not yet known to the program. Where the
368 subset header knows where to get the other fields, the partial
369 header does not know it. It cannot hide its imperfection.
370 * Mail::Message::Head::Delayed
372 In this case, there is no single field known. Access to this
373 header will always trigger the loading of the full header.
374 Subsets of header fields
376 Message headers can be quite large, and therefore MailBox provides sim‐
378 plified access to some subsets of information. You can grab these sets
379 of fields together, create and delete them as group.
380 On the moment, the following sets are defined:
382 * Mail::Message::Head::ResentGroup
384 A resent group is a set of fields which is used to log one step in
385 the transmission of the message from the original sender to the
386 destination.
387 Each step adds a set of headers to indicate when the message was
389 received and how it was forwarded (without modification). These
390 fields are best created using Mail::Message::bounce().
391 * Mail::Message::Head::ListGroup
393 Fields which are used to administer and log mailing list activity.
394 Mailing list software has to play trics with the original message
395 to be able to get the reply on that message back to the mailing
396 list. Usually a large number of lines are added.
397 * Mail::Message::Head::SpamGroup
399 A set of fields which contains header fields which are produced by
400 spam detection software. You may want to remove these fields when
401 you store a message for a longer period of time.
402
404 Error: Package $package does not implement $method.
405 Fatal error: the specific package (or one of its superclasses) does not
407 implement this method where it should. This message means that some
408 other related classes do implement this method however the class at
409 hand does not. Probably you should investigate this and probably
410 inform the author of the package.
411
413 This module is part of Mail-Box distribution version 2.070, built on
414 March 25, 2007. Website: http://perl.overmeer.net/mailbox/
415
417 Copyrights 2001-2007 by Mark Overmeer.For other contributors see
418 ChangeLog.
419 This program is free software; you can redistribute it and/or modify it
421 under the same terms as Perl itself. See
422 http://www.perl.com/perl/misc/Artistic.html
423perl v5.8.8 2007-03-25 Mail::Message::Head(3)