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::Message::Head::Complete
14 Mail::Message::Head::Delayed
15 Mail::Message::Head::Subset
16
18 my $head = Mail::Message::Head->new;
19 $head->add('From: me@localhost');
20 $head->add(From => 'me@localhost');
21 $head->add(Mail::Message::Field->new(From => 'me'));
22 my $subject = $head->get('subject');
23 my @rec = $head->get('received');
24 $head->delete('From');
25
27 "Mail::Message::Head" MIME headers are part of Mail::Message messages,
28 which are grouped in Mail::Box folders.
29 ATTENTION!!! most functionality about e-mail headers is described in
31 Mail::Message::Head::Complete, which is a matured header object. Other
32 kinds of headers will be translated to that type when time comes.
33 On this page, the general methods which are available on any header are
35 described. Read about differences in the sub-class specific pages.
36 Extends "DESCRIPTION" in Mail::Reporter.
38
40 overload: ""
41 (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,
56 according to the RFCs), false is returned. In all other cases, a
57 true value is produced.
58
60 Extends "METHODS" in Mail::Reporter.
61 Constructors
63 Extends "Constructors" in Mail::Reporter.
64 Mail::Message::Head->build( [PAIR|$field]-LIST )
66 A fast way to construct a header with many lines. The PAIRs are
67 "(name, content)" pairs of the header, but it is also possible to
68 pass Mail::Message::Field objects. A
69 Mail::Message::Head::Complete header is created by simply calling
70 Mail::Message::Head::Complete::build(), and then each field is
71 added. Double field names are permitted.
72 example:
74 my $subject = Mail::Message::Field->new(Subject => 'xyz');
76 my $head = Mail::Message::Head->build
78 ( From => 'me@example.com'
79 , To => 'you@anywhere.aq'
80 , $subject
81 , Received => 'one'
82 , Received => 'two'
83 );
84 print ref $head;
86 # --> Mail::Message::Head::Complete
87 Mail::Message::Head->new(%options)
89 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
95 automatically be upgraded to a Mail::Message::Head::Complete --a
96 full head.
97 -Option --Defined in --Default
99 field_type Mail::Message::Field::Fast
100 log Mail::Reporter 'WARNINGS'
101 message undef
102 modified <false>
103 trace Mail::Reporter 'WARNINGS'
104 field_type => CLASS
106 The type of objects that all the fields will have. This must be
107 an extension of Mail::Message::Field.
108 log => LEVEL
110 message => MESSAGE
111 The MESSAGE where this header belongs to. Usually, this is not
112 known at creation of the header, but sometimes it is. If not,
113 call the message() method later to set it.
114 modified => BOOLEAN
116 trace => LEVEL
117 The header
119 $obj->isDelayed()
120 Headers may only be partially read, in which case they are called
121 delayed. This method returns true if some header information still
122 needs to be read. Returns false if all header data has been read.
123 Will never trigger completion.
124 $obj->isEmpty()
126 Are there any fields defined in the current header? Be warned that
127 the header will not be loaded for this: delayed headers will return
128 true in any case.
129 $obj->isModified()
131 Returns whether the header has been modified after being read.
132 example:
134 if($head->isModified) { ... }
136 $obj->knownNames()
138 Like Mail::Message::Head::Complete::names(), but only returns the
139 known header fields, which may be less than "names" for header
140 types which are partial. "names()" will trigger completion, where
141 "knownNames()" does not.
142 $obj->message( [$message] )
144 Get (after setting) the message where this header belongs to. This
145 does not trigger completion.
146 $obj->modified( [BOOLEAN] )
148 Sets the modified flag to BOOLEAN. Without value, the current
149 setting is returned, but in that case you can better use
150 isModified(). Changing this flag will not trigger header
151 completion.
152 example:
154 $head->modified(1);
156 if($head->modified) { ... }
157 if($head->isModified) { ... }
158 $obj->orderedFields()
160 Returns the fields ordered the way they were read or added.
161 Access to the header
163 $obj->get( $name, [$index] )
164 Get the data which is related to the field with the $name. The
165 case of the characters in $name does not matter.
166 If there is only one data element defined for the $name, or if
168 there is an $index specified as the second argument, only the
169 specified element will be returned. If the field $name matches more
170 than one header the return value depends on the context. In LIST
171 context, all values will be returned in the order they are read. In
172 SCALAR context, only the last value will be returned.
173 example:
175 my $head = Mail::Message::Head->new;
177 $head->add('Received: abc');
178 $head->add('Received: xyz');
179 $head->add('Subject: greetings');
180 my @rec_list = $head->get('Received');
182 my $rec_scalar = $head->get('Received');
183 print ",@rec_list,$rec_scalar," # ,abc xyz, xyz,
184 print $head->get('Received', 0); # abc
185 my @sub_list = $head->get('Subject');
186 my $sub_scalar = $head->get('Subject');
187 print ",@sub_list,$sub_scalar," # ,greetings, greetings,
188 $obj->study( $name, [$index] )
190 Like get(), but puts more effort in understanding the contents of
191 the field. Mail::Message::Field::study() will be called for the
192 field with the specified FIELDNAME, which returns
193 Mail::Message::Field::Full objects. In scalar context only the last
194 field with that name is returned. When an $index is specified,
195 that element is returned.
196 About the body
198 $obj->guessBodySize()
199 Try to estimate the size of the body of this message, but without
200 parsing the header or body. The result might be "undef" or a few
201 percent of the real size. It may even be very far of the real
202 value, that's why this is a guess.
203 $obj->isMultipart()
205 Returns whether the body of the related message is a multipart
206 body. May trigger completion, when the "Content-Type" field is not
207 defined.
208 Internals
210 $obj->addNoRealize($field)
211 Add a field, like Mail::Message::Head::Complete::add() does, but
212 avoid the loading of a possibly partial header. This method does
213 not test the validity of the argument, nor flag the header as
214 changed. This does not trigger completion.
215 $obj->addOrderedFields($fields)
217 $obj->fileLocation()
218 Returns the location of the header in the file, as a pair begin and
219 end. The begin is the first byte of the header. The end is the
220 first byte after the header.
221 $obj->load()
223 Be sure that the header is loaded. This returns the loaded header
224 object.
225 $obj->moveLocation($distance)
227 Move the registration of the header in the file.
228 $obj->read($parser)
230 Read the header information of one message into this header
231 structure. This method is called by the folder object (some
232 Mail::Box sub-class), which passes the $parser as an argument.
233 $obj->setNoRealize($field)
235 Set a field, but avoid the loading of a possibly partial header as
236 set() does. This method does not test the validity of the
237 argument, nor flag the header as changed. This does not trigger
238 completion.
239 Error handling
241 Extends "Error handling" in Mail::Reporter.
242 $obj->AUTOLOAD()
244 Inherited, see "Error handling" in Mail::Reporter
245 $obj->addReport($object)
247 Inherited, see "Error handling" in Mail::Reporter
248 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
250 $callback] )
251 Mail::Message::Head->defaultTrace( [$level]|[$loglevel,
252 $tracelevel]|[$level, $callback] )
253 Inherited, see "Error handling" in Mail::Reporter
254 $obj->errors()
256 Inherited, see "Error handling" in Mail::Reporter
257 $obj->log( [$level, [$strings]] )
259 Mail::Message::Head->log( [$level, [$strings]] )
260 Inherited, see "Error handling" in Mail::Reporter
261 $obj->logPriority($level)
263 Mail::Message::Head->logPriority($level)
264 Inherited, see "Error handling" in Mail::Reporter
265 $obj->logSettings()
267 Inherited, see "Error handling" in Mail::Reporter
268 $obj->notImplemented()
270 Inherited, see "Error handling" in Mail::Reporter
271 $obj->report( [$level] )
273 Inherited, see "Error handling" in Mail::Reporter
274 $obj->reportAll( [$level] )
276 Inherited, see "Error handling" in Mail::Reporter
277 $obj->trace( [$level] )
279 Inherited, see "Error handling" in Mail::Reporter
280 $obj->warnings()
282 Inherited, see "Error handling" in Mail::Reporter
283 Cleanup
285 Extends "Cleanup" in Mail::Reporter.
286 $obj->DESTROY()
288 Inherited, see "Cleanup" in Mail::Reporter
289
291 Ordered header fields
292 Many Perl implementations make a big mistake by disturbing the order of
293 header fields. For some fields (especially the resent groups, see
294 Mail::Message::Head::ResentGroup) the order shall be maintained.
295 MailBox will keep the order of the fields as they were found in the
297 source. When your add a new field, it will be added at the end. If
298 your replace a field with a new value, it will stay in the original
299 order.
300 Head class implementation
302 The header of a MIME message object contains a set of lines, which are
303 called fields (by default represented by Mail::Message::Field objects).
304 Dependent on the situation, the knowledge about the fields can be in
305 one of three situations, each represented by a sub-class of this
306 module:
307 · Mail::Message::Head::Complete
309 In this case, it is sure that all knowledge about the header is
311 available. When you get() information from the header and it is
312 not there, it will never be there.
313 · Mail::Message::Head::Subset
315 There is no certainty whether all header lines are known (probably
317 not). This may be caused as result of reading a fast index file,
318 as described in Mail::Box::MH::Index. The object is automatically
319 transformed into a Mail::Message::Head::Complete when all header
320 lines must be known.
321 · Mail::Message::Head::Partial
323 A partial header is like a subset header: probably the header is
325 incomplete. The means that you are not sure whether a get() for a
326 field fails because the field is not a part of the message or that
327 it fails because it is not yet known to the program. Where the
328 subset header knows where to get the other fields, the partial
329 header does not know it. It cannot hide its imperfection.
330 · Mail::Message::Head::Delayed
332 In this case, there is no single field known. Access to this
334 header will always trigger the loading of the full header.
335 Subsets of header fields
337 Message headers can be quite large, and therefore MailBox provides
338 simplified access to some subsets of information. You can grab these
339 sets of fields together, create and delete them as group.
340 On the moment, the following sets are defined:
342 · Mail::Message::Head::ResentGroup
344 A resent group is a set of fields which is used to log one step in
346 the transmission of the message from the original sender to the
347 destination.
348 Each step adds a set of headers to indicate when the message was
350 received and how it was forwarded (without modification). These
351 fields are best created using Mail::Message::bounce().
352 · Mail::Message::Head::ListGroup
354 Fields which are used to administer and log mailing list activity.
356 Mailing list software has to play trics with the original message
357 to be able to get the reply on that message back to the mailing
358 list. Usually a large number of lines are added.
359 · Mail::Message::Head::SpamGroup
361 A set of fields which contains header fields which are produced by
363 spam detection software. You may want to remove these fields when
364 you store a message for a longer period of time.
365
367 Error: Package $package does not implement $method.
368 Fatal error: the specific package (or one of its superclasses) does
369 not implement this method where it should. This message means that
370 some other related classes do implement this method however the
371 class at hand does not. Probably you should investigate this and
372 probably inform the author of the package.
373
375 This module is part of Mail-Message distribution version 3.009, built
376 on February 07, 2020. Website: http://perl.overmeer.net/CPAN/
377
379 Copyrights 2001-2020 by [Mark Overmeer <markov@cpan.org>]. For other
380 contributors see ChangeLog.
381 This program is free software; you can redistribute it and/or modify it
383 under the same terms as Perl itself. See http://dev.perl.org/licenses/
384perl v5.32.0 2020-07-28 Mail::Message::Head(3)