1=encoding utf8
2
3=head1 NAME
4
5Mail::Box::MH::Message - one message in an MH-folder
6
7=head1 INHERITANCE
8
9 Mail::Box::MH::Message
10   is a Mail::Box::Dir::Message
11   is a Mail::Box::Message
12   is a Mail::Message
13   is a Mail::Reporter
14
15=head1 SYNOPSIS
16
17 my $folder = new Mail::Box::MH ...
18 my $message = $folder->message(10);
19
20=head1 DESCRIPTION
21
22A C<Mail::Box::MH::Message> represents one message in an
23L<Mail::Box::MH|Mail::Box::MH> folder . Each message is stored in a separate file,
24as for all L<Mail::Box::Dir|Mail::Box::Dir> folder types.
25
26Extends L<"DESCRIPTION" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"DESCRIPTION">.
27
28=head1 METHODS
29
30Extends L<"METHODS" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"METHODS">.
31
32=head2 Constructors
33
34Extends L<"Constructors" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"Constructors">.
35
36=over 4
37
38=item $obj-E<gt>B<clone>(%options)
39
40Inherited, see L<Mail::Message/"Constructors">
41
42=item Mail::Box::MH::Message-E<gt>B<new>(%options)
43
44Inherited, see L<Mail::Box::Dir::Message/"METHODS">
45
46=back
47
48=head2 Constructing a message
49
50Extends L<"Constructing a message" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"Constructing a message">.
51
52=over 4
53
54=item $obj-E<gt>B<bounce>( [<$rg_object|%options>] )
55
56Inherited, see L<Mail::Message::Construct::Bounce/"Constructing a message">
57
58=item Mail::Box::MH::Message-E<gt>B<build>( [$message|$part|$body], $content )
59
60Inherited, see L<Mail::Message::Construct::Build/"Constructing a message">
61
62=item Mail::Box::MH::Message-E<gt>B<buildFromBody>($body, [$head], $headers)
63
64Inherited, see L<Mail::Message::Construct::Build/"Constructing a message">
65
66=item $obj-E<gt>B<forward>(%options)
67
68Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
69
70=item $obj-E<gt>B<forwardAttach>(%options)
71
72Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
73
74=item $obj-E<gt>B<forwardEncapsulate>(%options)
75
76Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
77
78=item $obj-E<gt>B<forwardInline>(%options)
79
80Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
81
82=item $obj-E<gt>B<forwardNo>(%options)
83
84Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
85
86=item $obj-E<gt>B<forwardPostlude>()
87
88Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
89
90=item $obj-E<gt>B<forwardPrelude>()
91
92Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
93
94=item $obj-E<gt>B<forwardSubject>(STRING)
95
96Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
97
98=item Mail::Box::MH::Message-E<gt>B<read>($fh|STRING|SCALAR|ARRAY, %options)
99
100Inherited, see L<Mail::Message::Construct::Read/"Constructing a message">
101
102=item $obj-E<gt>B<rebuild>(%options)
103
104Inherited, see L<Mail::Message::Construct::Rebuild/"Constructing a message">
105
106=item $obj-E<gt>B<reply>(%options)
107
108Inherited, see L<Mail::Message::Construct::Reply/"Constructing a message">
109
110=item $obj-E<gt>B<replyPrelude>( [STRING|$field|$address|ARRAY-$of-$things] )
111
112Inherited, see L<Mail::Message::Construct::Reply/"Constructing a message">
113
114=item $obj-E<gt>B<replySubject>(STRING)
115
116=item Mail::Box::MH::Message-E<gt>B<replySubject>(STRING)
117
118Inherited, see L<Mail::Message::Construct::Reply/"Constructing a message">
119
120=back
121
122=head2 The message
123
124Extends L<"The message" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"The message">.
125
126=over 4
127
128=item $obj-E<gt>B<container>()
129
130Inherited, see L<Mail::Message/"The message">
131
132=item $obj-E<gt>B<copyTo>($folder, %options)
133
134Inherited, see L<Mail::Box::Message/"The message">
135
136=item $obj-E<gt>B<filename>( [$filename] )
137
138Inherited, see L<Mail::Box::Dir::Message/"The message">
139
140=item $obj-E<gt>B<folder>( [$folder] )
141
142Inherited, see L<Mail::Box::Message/"The message">
143
144=item $obj-E<gt>B<isDummy>()
145
146Inherited, see L<Mail::Message/"The message">
147
148=item $obj-E<gt>B<isPart>()
149
150Inherited, see L<Mail::Message/"The message">
151
152=item $obj-E<gt>B<messageId>()
153
154Inherited, see L<Mail::Message/"The message">
155
156=item $obj-E<gt>B<moveTo>($folder, %options)
157
158Inherited, see L<Mail::Box::Message/"The message">
159
160=item $obj-E<gt>B<partNumber>()
161
162Inherited, see L<Mail::Message/"The message">
163
164=item $obj-E<gt>B<print>( [$fh] )
165
166Inherited, see L<Mail::Message/"The message">
167
168=item $obj-E<gt>B<send>( [$mailer], %options )
169
170Inherited, see L<Mail::Message/"The message">
171
172=item $obj-E<gt>B<seqnr>( [$integer] )
173
174The order of this message in the folder, counted from zero.  Do not
175change the number (unless you understand the implications).
176
177WARNING:  This sequence number has nothing to do with the message's
178filename, which in case of MH folders are also numbers!  If you need
179that one, use the File::Basename subroutine basename of the filename.
180
181=item $obj-E<gt>B<size>()
182
183Inherited, see L<Mail::Message/"The message">
184
185=item $obj-E<gt>B<toplevel>()
186
187Inherited, see L<Mail::Message/"The message">
188
189=item $obj-E<gt>B<write>( [$fh] )
190
191Inherited, see L<Mail::Message/"The message">
192
193=back
194
195=head2 The header
196
197Extends L<"The header" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"The header">.
198
199=over 4
200
201=item $obj-E<gt>B<bcc>()
202
203Inherited, see L<Mail::Message/"The header">
204
205=item $obj-E<gt>B<cc>()
206
207Inherited, see L<Mail::Message/"The header">
208
209=item $obj-E<gt>B<date>()
210
211Inherited, see L<Mail::Message/"The header">
212
213=item $obj-E<gt>B<destinations>()
214
215Inherited, see L<Mail::Message/"The header">
216
217=item $obj-E<gt>B<from>()
218
219Inherited, see L<Mail::Message/"The header">
220
221=item $obj-E<gt>B<get>($fieldname)
222
223Inherited, see L<Mail::Message/"The header">
224
225=item $obj-E<gt>B<guessTimestamp>()
226
227Inherited, see L<Mail::Message/"The header">
228
229=item $obj-E<gt>B<head>( [$head] )
230
231Inherited, see L<Mail::Message/"The header">
232
233=item $obj-E<gt>B<nrLines>()
234
235Inherited, see L<Mail::Message/"The header">
236
237=item $obj-E<gt>B<sender>()
238
239Inherited, see L<Mail::Message/"The header">
240
241=item $obj-E<gt>B<study>($fieldname)
242
243Inherited, see L<Mail::Message/"The header">
244
245=item $obj-E<gt>B<subject>()
246
247Inherited, see L<Mail::Message/"The header">
248
249=item $obj-E<gt>B<timestamp>()
250
251Inherited, see L<Mail::Message/"The header">
252
253=item $obj-E<gt>B<to>()
254
255Inherited, see L<Mail::Message/"The header">
256
257=back
258
259=head2 The body
260
261Extends L<"The body" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"The body">.
262
263=over 4
264
265=item $obj-E<gt>B<body>( [$body] )
266
267Inherited, see L<Mail::Message/"The body">
268
269=item $obj-E<gt>B<contentType>()
270
271Inherited, see L<Mail::Message/"The body">
272
273=item $obj-E<gt>B<decoded>(%options)
274
275Inherited, see L<Mail::Message/"The body">
276
277=item $obj-E<gt>B<encode>(%options)
278
279Inherited, see L<Mail::Message/"The body">
280
281=item $obj-E<gt>B<isMultipart>()
282
283Inherited, see L<Mail::Message/"The body">
284
285=item $obj-E<gt>B<isNested>()
286
287Inherited, see L<Mail::Message/"The body">
288
289=item $obj-E<gt>B<parts>( [<'ALL'|'ACTIVE'|'DELETED'|'RECURSE'|$filter>] )
290
291Inherited, see L<Mail::Message/"The body">
292
293=back
294
295=head2 Flags
296
297Extends L<"Flags" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"Flags">.
298
299=over 4
300
301=item $obj-E<gt>B<delete>()
302
303Inherited, see L<Mail::Message/"Flags">
304
305=item $obj-E<gt>B<deleted>( [BOOLEAN] )
306
307Inherited, see L<Mail::Message/"Flags">
308
309=item $obj-E<gt>B<isDeleted>()
310
311Inherited, see L<Mail::Message/"Flags">
312
313=item $obj-E<gt>B<isModified>()
314
315Inherited, see L<Mail::Message/"Flags">
316
317=item $obj-E<gt>B<label>($label|PAIRS)
318
319Inherited, see L<Mail::Message/"Flags">
320
321=item $obj-E<gt>B<labels>()
322
323Inherited, see L<Mail::Message/"Flags">
324
325=item $obj-E<gt>B<labelsToStatus>()
326
327Inherited, see L<Mail::Message/"Flags">
328
329=item $obj-E<gt>B<modified>( [BOOLEAN] )
330
331Inherited, see L<Mail::Message/"Flags">
332
333=item $obj-E<gt>B<statusToLabels>()
334
335Inherited, see L<Mail::Message/"Flags">
336
337=back
338
339=head2 The whole message as text
340
341Extends L<"The whole message as text" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"The whole message as text">.
342
343=over 4
344
345=item $obj-E<gt>B<file>()
346
347Inherited, see L<Mail::Message::Construct::Text/"The whole message as text">
348
349=item $obj-E<gt>B<lines>()
350
351Inherited, see L<Mail::Message::Construct::Text/"The whole message as text">
352
353=item $obj-E<gt>B<printStructure>( [$fh|undef],[$indent] )
354
355Inherited, see L<Mail::Message::Construct::Text/"The whole message as text">
356
357=item $obj-E<gt>B<string>()
358
359Inherited, see L<Mail::Message::Construct::Text/"The whole message as text">
360
361=back
362
363=head2 Internals
364
365Extends L<"Internals" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"Internals">.
366
367=over 4
368
369=item $obj-E<gt>B<clonedFrom>()
370
371Inherited, see L<Mail::Message/"Internals">
372
373=item Mail::Box::MH::Message-E<gt>B<coerce>($message, %options)
374
375Inherited, see L<Mail::Message/"Internals">
376
377=item $obj-E<gt>B<create>($filename)
378
379Inherited, see L<Mail::Box::Dir::Message/"Internals">
380
381=item $obj-E<gt>B<diskDelete>()
382
383Inherited, see L<Mail::Box::Message/"Internals">
384
385=item $obj-E<gt>B<isDelayed>()
386
387Inherited, see L<Mail::Message/"Internals">
388
389=item $obj-E<gt>B<loadBody>()
390
391Inherited, see L<Mail::Box::Dir::Message/"Internals">
392
393=item $obj-E<gt>B<loadHead>()
394
395Inherited, see L<Mail::Box::Dir::Message/"Internals">
396
397=item $obj-E<gt>B<parser>()
398
399Inherited, see L<Mail::Box::Dir::Message/"Internals">
400
401=item $obj-E<gt>B<readBody>( $parser, $head, [$bodytype] )
402
403Inherited, see L<Mail::Box::Message/"Internals">
404
405=item $obj-E<gt>B<readFromParser>( $parser, [$bodytype] )
406
407Inherited, see L<Mail::Message/"Internals">
408
409=item $obj-E<gt>B<readHead>( $parser, [$class] )
410
411Inherited, see L<Mail::Message/"Internals">
412
413=item $obj-E<gt>B<recursiveRebuildPart>($part, %options)
414
415Inherited, see L<Mail::Message::Construct::Rebuild/"Internals">
416
417=item $obj-E<gt>B<storeBody>($body)
418
419Inherited, see L<Mail::Message/"Internals">
420
421=item $obj-E<gt>B<takeMessageId>( [STRING] )
422
423Inherited, see L<Mail::Message/"Internals">
424
425=back
426
427=head2 Error handling
428
429Extends L<"Error handling" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"Error handling">.
430
431=over 4
432
433=item $obj-E<gt>B<AUTOLOAD>()
434
435Inherited, see L<Mail::Message::Construct/"METHODS">
436
437=item $obj-E<gt>B<addReport>($object)
438
439Inherited, see L<Mail::Reporter/"Error handling">
440
441=item $obj-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
442
443=item Mail::Box::MH::Message-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
444
445Inherited, see L<Mail::Reporter/"Error handling">
446
447=item $obj-E<gt>B<errors>()
448
449Inherited, see L<Mail::Reporter/"Error handling">
450
451=item $obj-E<gt>B<log>( [$level, [$strings]] )
452
453=item Mail::Box::MH::Message-E<gt>B<log>( [$level, [$strings]] )
454
455Inherited, see L<Mail::Reporter/"Error handling">
456
457=item $obj-E<gt>B<logPriority>($level)
458
459=item Mail::Box::MH::Message-E<gt>B<logPriority>($level)
460
461Inherited, see L<Mail::Reporter/"Error handling">
462
463=item $obj-E<gt>B<logSettings>()
464
465Inherited, see L<Mail::Reporter/"Error handling">
466
467=item $obj-E<gt>B<notImplemented>()
468
469Inherited, see L<Mail::Reporter/"Error handling">
470
471=item $obj-E<gt>B<report>( [$level] )
472
473Inherited, see L<Mail::Reporter/"Error handling">
474
475=item $obj-E<gt>B<reportAll>( [$level] )
476
477Inherited, see L<Mail::Reporter/"Error handling">
478
479=item $obj-E<gt>B<shortSize>( [$value] )
480
481=item Mail::Box::MH::Message-E<gt>B<shortSize>( [$value] )
482
483Inherited, see L<Mail::Message/"Error handling">
484
485=item $obj-E<gt>B<shortString>()
486
487Inherited, see L<Mail::Message/"Error handling">
488
489=item $obj-E<gt>B<trace>( [$level] )
490
491Inherited, see L<Mail::Reporter/"Error handling">
492
493=item $obj-E<gt>B<warnings>()
494
495Inherited, see L<Mail::Reporter/"Error handling">
496
497=back
498
499=head2 Cleanup
500
501Extends L<"Cleanup" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"Cleanup">.
502
503=over 4
504
505=item $obj-E<gt>B<DESTROY>()
506
507Inherited, see L<Mail::Reporter/"Cleanup">
508
509=item $obj-E<gt>B<destruct>()
510
511Inherited, see L<Mail::Box::Message/"Cleanup">
512
513=back
514
515=head1 DETAILS
516
517Extends L<"DETAILS" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"DETAILS">.
518
519=head2 Structure of a Message
520
521Extends L<"Structure of a Message" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"Structure of a Message">.
522
523=head2 Message object implementation
524
525Extends L<"Message object implementation" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"Message object implementation">.
526
527=head2 Message class implementation
528
529Extends L<"Message class implementation" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"Message class implementation">.
530
531=head2 Labels
532
533Extends L<"Labels" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"Labels">.
534
535=head3 Predefined labels
536
537Extends L<"Predefined labels" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"Predefined labels">.
538
539=head3 Status and X-Status fields
540
541Extends L<"Status and X-Status fields" in Mail::Box::Dir::Message|Mail::Box::Dir::Message/"Status and X-Status fields">.
542
543=head3 The .mh_sequences file
544
545Typically, the file which contains the labels is called C<.mh_sequences>.
546The MH messages are numbered from C<1>.  As example content for
547C<.mh_sequences>:
548
549 cur: 93
550 unseen: 32 35-56 67-80
551
552To generalize labels on messages, two are treated specially:
553
554=over 4
555
556=item * cur
557
558The C<cur> specifies the number of the message where the user stopped
559reading mail from this folder at last access.  Internally in these
560modules referred to as label C<current>.
561
562=item * unseen
563
564With C<unseen> is listed which message was never read.
565This must be a mistake in the design of MH: it must be a source of
566confusion.  People should never use labels with a negation in the
567name:
568
569 if($seen)           if(!$unseen)    #yuk!
570 if(!$seen)          if($unseen)
571 unless($seen)       unless($unseen) #yuk!
572
573So: label C<unseen> is translated into C<seen> for internal use.
574
575=back
576
577=head1 DIAGNOSTICS
578
579=over 4
580
581=item Error: Cannot coerce a $class object into a $class object
582
583=item Error: Cannot create parser for $filename.
584
585For some reason (the previous message have told you already) it was not possible
586to create a message parser for the specified filename.
587
588=item Error: Cannot include forward source as $include.
589
590Unknown alternative for the L<forward(include)|Mail::Message::Construct::Forward/"Constructing a message">.  Valid choices are
591C<NO>, C<INLINE>, C<ATTACH>, and C<ENCAPSULATE>.
592
593=item Error: Cannot include reply source as $include.
594
595Unknown alternative for the C<include> option of L<reply()|Mail::Message::Construct::Reply/"Constructing a message">.  Valid
596choices are C<NO>, C<INLINE>, and C<ATTACH>.
597
598=item Error: Cannot write message to $filename: $!
599
600When a modified or new message is written to disk, it is first written
601to a temporary file in the folder directory.  For some reason, it is
602impossible to create this file.
603
604=item Error: Failed to move $new to $filename: $!
605
606When a modified or new message is written to disk, it is first written
607to a temporary file in the folder directory.  Then, the new file is
608moved to replace the existing file.  Apparently, the latter fails.
609
610=item Error: Method bounce requires To, Cc, or Bcc
611
612The message L<bounce()|Mail::Message::Construct::Bounce/"Constructing a message"> method forwards a received message off to someone
613else without modification; you must specified it's new destination.
614If you have the urge not to specify any destination, you probably
615are looking for L<reply()|Mail::Message::Construct::Reply/"Constructing a message">. When you wish to modify the content, use
616L<forward()|Mail::Message::Construct::Forward/"Constructing a message">.
617
618=item Error: Method forwardAttach requires a preamble
619
620=item Error: Method forwardEncapsulate requires a preamble
621
622=item Error: No address to create forwarded to.
623
624If a forward message is created, a destination address must be specified.
625
626=item Error: No default mailer found to send message.
627
628The message L<send()|Mail::Message/"The message"> mechanism had not enough information to automatically
629find a mail transfer agent to sent this message.  Specify a mailer
630explicitly using the C<via> options.
631
632=item Error: No rebuild rule $name defined.
633
634=item Error: Only build() Mail::Message's; they are not in a folder yet
635
636You may wish to construct a message to be stored in a some kind
637of folder, but you need to do that in two steps.  First, create a
638normal L<Mail::Message|Mail::Message>, and then add it to the folder.  During this
639L<Mail::Box::addMessage()|Mail::Box/"The folder"> process, the message will get L<coerce()|Mail::Message/"Internals">-d
640into the right message type, adding storage information and the like.
641
642=item Error: Package $package does not implement $method.
643
644Fatal error: the specific package (or one of its superclasses) does not
645implement this method where it should. This message means that some other
646related classes do implement this method however the class at hand does
647not.  Probably you should investigate this and probably inform the author
648of the package.
649
650=item Error: Unable to read delayed body.
651
652For some reason, the header of the message could be read, but the body
653cannot.  Probably the file has disappeared or the permissions were
654changed during the progress of the program.
655
656=item Error: Unable to read delayed head.
657
658Mail::Box tries to be I<lazy> with respect to parsing messages.  When a
659directory organized folder is opened, only the filenames of messages are
660collected.  At first use, the messages are read from their file.  Apperently,
661a message is used for the first time here, but has disappeared or is
662unreadible for some other reason.
663
664=item Error: coercion starts with some object
665
666=back
667
668=head1 SEE ALSO
669
670This module is part of Mail-Box distribution version 3.009,
671built on August 18, 2020. Website: F<http://perl.overmeer.net/CPAN/>
672
673=head1 LICENSE
674
675Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see ChangeLog.
676
677This program is free software; you can redistribute it and/or modify it
678under the same terms as Perl itself.
679See F<http://dev.perl.org/licenses/>
680
681