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