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