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 $subject = $head->get('subject');
24 my @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
41 Mail::Message::Head::Complete::string() was called, so return a
42 nicely folder full header. An exception is made for Carp, which
43 will get a simplified string to avoid unreadible messages from
44 "croak" and "confess".
45 example: using a header object as string
47 print $head; # implicit stringification by print
49 $head->print; # the same
50 print "$head"; # explicit stringication
52 overload: bool
54 When the header does not contain any lines (which is illegal,
55 according to the RFCs), false is returned. In all other cases, a
56 true value is produced.
57
59 Constructors
60 Mail::Message::Head->build([PAIR|FIELD]-LIST)
61 A fast way to construct a header with many lines. The PAIRs are
62 "(name, content)" pairs of the header, but it is also possible to
63 pass Mail::Message::Field objects. A
64 Mail::Message::Head::Complete header is created by simply calling
65 Mail::Message::Head::Complete::build(), and then each field is
66 added. Double field names are permitted.
67 example:
69 my $subject = Mail::Message::Field->new(Subject => 'xyz');
71 my $head = Mail::Message::Head->build
73 ( From => 'me@example.com'
74 , To => 'you@anywhere.aq'
75 , $subject
76 , Received => 'one'
77 , Received => 'two'
78 );
79 print ref $head;
81 # --> Mail::Message::Head::Complete
82 Mail::Message::Head->new(OPTIONS)
84 Create a new message header object. The object will store all the
85 fields of a header. When you get information from the header, it
86 will be returned to you as Mail::Message::Field objects, although
87 the fields may be stored differently internally.
88 If you try to instantiate a Mail::Message::Head, you will
90 automatically be upgraded to a Mail::Message::Head::Complete --a
91 full head.
92 -Option --Defined in --Default
94 field_type Mail::Message::Field::Fast
95 log Mail::Reporter 'WARNINGS'
96 message undef
97 modified <false>
98 trace Mail::Reporter 'WARNINGS'
99 field_type => CLASS
101 The type of objects that all the fields will have. This must be
102 an extension of Mail::Message::Field.
103 log => LEVEL
105 message => MESSAGE
106 The MESSAGE where this header belongs to. Usually, this is not
107 known at creation of the header, but sometimes it is. If not,
108 call the message() method later to set it.
109 modified => BOOLEAN
111 trace => LEVEL
112 The header
114 $obj->isDelayed
115 Headers may only be partially read, in which case they are called
116 delayed. This method returns true if some header information still
117 needs to be read. Returns false if all header data has been read.
118 Will never trigger completion.
119 $obj->isEmpty
121 Are there any fields defined in the current header? Be warned that
122 the header will not be loaded for this: delayed headers will return
123 true in any case.
124 $obj->isModified
126 Returns whether the header has been modified after being read.
127 example:
129 if($head->isModified) { ... }
131 $obj->knownNames
133 Like Mail::Message::Head::Complete::names(), but only returns the
134 known header fields, which may be less than "names" for header
135 types which are partial. "names()" will trigger completion, where
136 "knownNames()" does not.
137 $obj->message([MESSAGE])
139 Get (after setting) the message where this header belongs to. This
140 does not trigger completion.
141 $obj->modified([BOOLEAN])
143 Sets the modified flag to BOOLEAN. Without value, the current
144 setting is returned, but in that case you can better use
145 isModified(). Changing this flag will not trigger header
146 completion.
147 example:
149 $head->modified(1);
151 if($head->modified) { ... }
152 if($head->isModified) { ... }
153 $obj->orderedFields
155 Retuns the fields ordered the way they were read or added.
156 Access to the header
158 $obj->get(NAME [,INDEX])
159 Get the data which is related to the field with the NAME. The case
160 of the characters in NAME does not matter.
161 If there is only one data element defined for the NAME, or if there
163 is an INDEX specified as the second argument, only the specified
164 element will be returned. If the field NAME matches more than one
165 header the return value depends on the context. In LIST context,
166 all values will be returned in the order they are read. In SCALAR
167 context, only the last value will be returned.
168 example:
170 my $head = Mail::Message::Head->new;
172 $head->add('Received: abc');
173 $head->add('Received: xyz');
174 $head->add('Subject: greetings');
175 my @rec_list = $head->get('Received');
177 my $rec_scalar = $head->get('Received');
178 print ",@rec_list,$rec_scalar," # ,abc xyz, xyz,
179 print $head->get('Received', 0); # abc
180 my @sub_list = $head->get('Subject');
181 my $sub_scalar = $head->get('Subject');
182 print ",@sub_list,$sub_scalar," # ,greetings, greetings,
183 $obj->study(NAME [,INDEX])
185 Like get(), but puts more effort in understanding the contents of
186 the field. Mail::Message::Field::study() will be called for the
187 field with the specified FIELDNAME, which returns
188 Mail::Message::Field::Full objects. In scalar context only the last
189 field with that name is returned. When an INDEX is specified, that
190 element is returned.
191 About the body
193 $obj->guessBodySize
194 Try to estimate the size of the body of this message, but without
195 parsing the header or body. The result might be "undef" or a few
196 percent of the real size. It may even be very far of the real
197 value, that's why this is a guess.
198 $obj->isMultipart
200 Returns whether the body of the related message is a multipart
201 body. May trigger completion, when the "Content-Type" field is not
202 defined.
203 Internals
205 $obj->addNoRealize(FIELD)
206 Add a field, like Mail::Message::Head::Complete::add() does, but
207 avoid the loading of a possibly partial header. This method does
208 not test the validity of the argument, nor flag the header as
209 changed. This does not trigger completion.
210 $obj->addOrderedFields(FIELDS)
212 $obj->fileLocation
213 Returns the location of the header in the file, as a pair begin and
214 end. The begin is the first byte of the header. The end is the
215 first byte after the header.
216 $obj->load
218 Be sure that the header is loaded. This returns the loaded header
219 object.
220 $obj->moveLocation(DISTANCE)
222 Move the registration of the header in the file.
223 $obj->read(PARSER)
225 Read the header information of one message into this header
226 structure. This method is called by the folder object (some
227 Mail::Box sub-class), which passes the PARSER as an argument.
228 $obj->setNoRealize(FIELD)
230 Set a field, but avoid the loading of a possibly partial header as
231 set() does. This method does not test the validity of the
232 argument, nor flag the header as changed. This does not trigger
233 completion.
234 Error handling
236 $obj->AUTOLOAD
237 See "Error handling" in Mail::Reporter
238 $obj->addReport(OBJECT)
240 See "Error handling" in Mail::Reporter
241 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
243 Mail::Message::Head->defaultTrace([LEVEL]|[LOGLEVEL,
244 TRACELEVEL]|[LEVEL, CALLBACK])
245 See "Error handling" in Mail::Reporter
247 $obj->errors
249 See "Error handling" in Mail::Reporter
250 $obj->log([LEVEL [,STRINGS]])
252 Mail::Message::Head->log([LEVEL [,STRINGS]])
253 See "Error handling" in Mail::Reporter
255 $obj->logPriority(LEVEL)
257 Mail::Message::Head->logPriority(LEVEL)
258 See "Error handling" in Mail::Reporter
260 $obj->logSettings
262 See "Error handling" in Mail::Reporter
263 $obj->notImplemented
265 See "Error handling" in Mail::Reporter
266 $obj->report([LEVEL])
268 See "Error handling" in Mail::Reporter
269 $obj->reportAll([LEVEL])
271 See "Error handling" in Mail::Reporter
272 $obj->trace([LEVEL])
274 See "Error handling" in Mail::Reporter
275 $obj->warnings
277 See "Error handling" in Mail::Reporter
278 Cleanup
280 $obj->DESTROY
281 See "Cleanup" in Mail::Reporter
282 $obj->inGlobalDestruction
284 See "Cleanup" in Mail::Reporter
285
287 Ordered header fields
288 Many Perl implementations make a big mistake by disturbing the order of
289 header fields. For some fields (especially the resent groups, see
290 Mail::Message::Head::ResentGroup) the order shall be maintained.
291 MailBox will keep the order of the fields as they were found in the
293 source. When your add a new field, it will be added at the end. If
294 your replace a field with a new value, it will stay in the original
295 order.
296 Head class implementation
298 The header of a MIME message object contains a set of lines, which are
299 called fields (by default represented by Mail::Message::Field objects).
300 Dependent on the situation, the knowledge about the fields can be in
301 one of three situations, each represented by a sub-class of this
302 module:
303 · Mail::Message::Head::Complete
305 In this case, it is sure that all knowledge about the header is
307 available. When you get() information from the header and it is
308 not there, it will never be there.
309 · Mail::Message::Head::Subset
311 There is no certainty whether all header lines are known (probably
313 not). This may be caused as result of reading a fast index file,
314 as described in Mail::Box::MH::Index. The object is automatically
315 transformed into a Mail::Message::Head::Complete when all header
316 lines must be known.
317 · Mail::Message::Head::Partial
319 A partial header is like a subset header: probably the header is
321 incomplete. The means that you are not sure whether a get() for a
322 field fails because the field is not a part of the message or that
323 it fails because it is not yet known to the program. Where the
324 subset header knows where to get the other fields, the partial
325 header does not know it. It cannot hide its imperfection.
326 · Mail::Message::Head::Delayed
328 In this case, there is no single field known. Access to this
330 header will always trigger the loading of the full header.
331 Subsets of header fields
333 Message headers can be quite large, and therefore MailBox provides
334 simplified access to some subsets of information. You can grab these
335 sets of fields together, create and delete them as group.
336 On the moment, the following sets are defined:
338 · Mail::Message::Head::ResentGroup
340 A resent group is a set of fields which is used to log one step in
342 the transmission of the message from the original sender to the
343 destination.
344 Each step adds a set of headers to indicate when the message was
346 received and how it was forwarded (without modification). These
347 fields are best created using Mail::Message::bounce().
348 · Mail::Message::Head::ListGroup
350 Fields which are used to administer and log mailing list activity.
352 Mailing list software has to play trics with the original message
353 to be able to get the reply on that message back to the mailing
354 list. Usually a large number of lines are added.
355 · Mail::Message::Head::SpamGroup
357 A set of fields which contains header fields which are produced by
359 spam detection software. You may want to remove these fields when
360 you store a message for a longer period of time.
361
363 Error: Package $package does not implement $method.
364 Fatal error: the specific package (or one of its superclasses) does
365 not implement this method where it should. This message means that
366 some other related classes do implement this method however the
367 class at hand does not. Probably you should investigate this and
368 probably inform the author of the package.
369
371 This module is part of Mail-Box distribution version 2.097, built on
372 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
373
375 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
376 ChangeLog.
377 This program is free software; you can redistribute it and/or modify it
379 under the same terms as Perl itself. See
380 http://www.perl.com/perl/misc/Artistic.html
381perl v5.12.3 2011-01-26 Mail::Message::Head(3)