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