1Mail::Message::Head(3)User Contributed Perl DocumentationMail::Message::Head(3)
2
3
4

NAME

6       Mail::Message::Head - the header of one message
7

INHERITANCE

9        Mail::Message::Head
10          is a Mail::Reporter
11
12        Mail::Message::Head is extended by
13          Mail::Message::Head::Complete
14          Mail::Message::Head::Delayed
15          Mail::Message::Head::Subset
16

SYNOPSIS

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

DESCRIPTION

27       "Mail::Message::Head" MIME headers are part of Mail::Message messages,
28       which are grouped in Mail::Box folders.
29
30       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
34       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
37       Extends "DESCRIPTION" in Mail::Reporter.
38

OVERLOADED

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
47           example: using a header object as string
48
49            print $head;     # implicit stringification by print
50            $head->print;    # the same
51
52            print "$head";   # explicit stringication
53
54       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

METHODS

60       Extends "METHODS" in Mail::Reporter.
61
62   Constructors
63       Extends "Constructors" in Mail::Reporter.
64
65       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
73           example:
74
75            my $subject = Mail::Message::Field->new(Subject => 'xyz');
76
77            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
85            print ref $head;
86             # -->  Mail::Message::Head::Complete
87
88       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
94           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
98            -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
105           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
109           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
115           modified => BOOLEAN
116           trace => LEVEL
117
118   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
125       $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
130       $obj->isModified()
131           Returns whether the header has been modified after being read.
132
133           example:
134
135            if($head->isModified) { ... }
136
137       $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
143       $obj->message( [$message] )
144           Get (after setting) the message where this header belongs to.  This
145           does not trigger completion.
146
147       $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
153           example:
154
155            $head->modified(1);
156            if($head->modified) { ... }
157            if($head->isModified) { ... }
158
159       $obj->orderedFields()
160           Returns the fields ordered the way they were read or added.
161
162   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
167           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
174           example:
175
176            my $head = Mail::Message::Head->new;
177            $head->add('Received: abc');
178            $head->add('Received: xyz');
179            $head->add('Subject: greetings');
180
181            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
189       $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
197   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
204       $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
209   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
216       $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
222       $obj->load()
223           Be sure that the header is loaded.  This returns the loaded header
224           object.
225
226       $obj->moveLocation($distance)
227           Move the registration of the header in the file.
228
229       $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
234       $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
240   Error handling
241       Extends "Error handling" in Mail::Reporter.
242
243       $obj->AUTOLOAD()
244           Inherited, see "Error handling" in Mail::Reporter
245
246       $obj->addReport($object)
247           Inherited, see "Error handling" in Mail::Reporter
248
249       $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
255       $obj->errors()
256           Inherited, see "Error handling" in Mail::Reporter
257
258       $obj->log( [$level, [$strings]] )
259       Mail::Message::Head->log( [$level, [$strings]] )
260           Inherited, see "Error handling" in Mail::Reporter
261
262       $obj->logPriority($level)
263       Mail::Message::Head->logPriority($level)
264           Inherited, see "Error handling" in Mail::Reporter
265
266       $obj->logSettings()
267           Inherited, see "Error handling" in Mail::Reporter
268
269       $obj->notImplemented()
270           Inherited, see "Error handling" in Mail::Reporter
271
272       $obj->report( [$level] )
273           Inherited, see "Error handling" in Mail::Reporter
274
275       $obj->reportAll( [$level] )
276           Inherited, see "Error handling" in Mail::Reporter
277
278       $obj->trace( [$level] )
279           Inherited, see "Error handling" in Mail::Reporter
280
281       $obj->warnings()
282           Inherited, see "Error handling" in Mail::Reporter
283
284   Cleanup
285       Extends "Cleanup" in Mail::Reporter.
286
287       $obj->DESTROY()
288           Inherited, see "Cleanup" in Mail::Reporter
289

DETAILS

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
296       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
301   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
308       •   Mail::Message::Head::Complete
309
310           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
314       •   Mail::Message::Head::Subset
315
316           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
322       •   Mail::Message::Head::Partial
323
324           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
331       •   Mail::Message::Head::Delayed
332
333           In this case, there is no single field known.  Access to this
334           header will always trigger the loading of the full header.
335
336   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
341       On the moment, the following sets are defined:
342
343       •   Mail::Message::Head::ResentGroup
344
345           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
349           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
353       •   Mail::Message::Head::ListGroup
354
355           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
360       •   Mail::Message::Head::SpamGroup
361
362           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

DIAGNOSTICS

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

SEE ALSO

375       This module is part of Mail-Message distribution version 3.011, built
376       on July 27, 2021. Website: http://perl.overmeer.net/CPAN/
377

LICENSE

379       Copyrights 2001-2021 by [Mark Overmeer <markov@cpan.org>]. For other
380       contributors see ChangeLog.
381
382       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/
384
385
386
387perl v5.34.0                      2021-07-27            Mail::Message::Head(3)
Impressum