1Mail::Box::MH(3) User Contributed Perl Documentation Mail::Box::MH(3)
2
6 Mail::Box::MH - handle MH folders
7
9 Mail::Box::MH
10 is a Mail::Box::Dir
11 is a Mail::Box
12 is a Mail::Reporter
13
15 use Mail::Box::MH;
16 my $folder = new Mail::Box::MH folder => $ENV{MAIL}, ...;
17
19 This documentation describes how MH mailboxes work, and what you can do
20 with the MH folder object "Mail::Box::MH".
21
23 overload: ""
24 See "OVERLOADED" in Mail::Box
26 overload: @{}
28 See "OVERLOADED" in Mail::Box
30 overload: cmp
32 See "OVERLOADED" in Mail::Box
34
36 Constructors
37 Mail::Box::MH->new(OPTIONS)
39 Option --Defined in --Default
41 access Mail::Box 'r'
42 body_delayed_type Mail::Box Mail::Message::Body::Delayed
43 body_type Mail::Box Mail::Message::Body::Lines
44 coerce_options Mail::Box []
45 create Mail::Box <false>
46 directory Mail::Box::Dir <derived from folder name>
47 extract Mail::Box 10240
48 field_type Mail::Box undef
49 fix_headers Mail::Box <false>
50 folder Mail::Box $ENV{MAIL}
51 folderdir Mail::Box $ENV{HOME}/.mh
52 head_delayed_type Mail::Box Mail::Message::Head::Delayed
53 head_type Mail::Box Mail::Message::Head::Complete
54 index undef
55 index_filename <foldername>/.index
56 index_type Mail::Box::MH::Index
57 keep_dups Mail::Box <false>
58 keep_index 0
59 labels undef
60 labels_filename <foldername>/.mh_sequence
61 labels_type Mail::Box::MH::Labels
62 lock_file Mail::Box <index_file>
63 lock_timeout Mail::Box 1 hour
64 lock_type Mail::Box Mail::Box::Locker::DotLock
65 lock_wait Mail::Box 10 seconds
66 locker Mail::Box undef
67 log Mail::Reporter 'WARNINGS'
68 manager Mail::Box undef
69 message_type Mail::Box Mail::Box::Message
70 multipart_type Mail::Box Mail::Message::Body::Multipart
71 remove_when_empty Mail::Box <true>
72 save_on_exit Mail::Box <true>
73 trace Mail::Reporter 'WARNINGS'
74 trusted Mail::Box <depends on folder location>
75 . access MODE
77 . body_delayed_type CLASS
79 . body_type CLASS⎪CODE
81 . coerce_options ARRAY
83 . create BOOLEAN
85 . directory DIRECTORY
87 . extract INTEGER ⎪ CODE ⎪ METHOD ⎪ 'LAZY'⎪'ALWAYS'
89 . field_type CLASS
91 . fix_headers BOOLEAN
93 . folder FOLDERNAME
95 . folderdir DIRECTORY
97 . head_delayed_type CLASS
99 . head_type CLASS
101 . index OBJECT
103 You may specify an OBJECT of a type which extends
105 Mail::Box::MH::Index (at least implements a "get()" method), as
106 alternative for an index file reader as created by
107 "Mail::Box::MH".
108 . index_filename FILENAME
110 The FILENAME which is used in each directory to store the head‐
112 ers of all mails. The filename shall not contain a directory
113 path. (e.g. Do not use "/usr/people/jan/.index", nor "sub‐
114 dir/.index", but say ".index".)
115 . index_type CLASS
117 . keep_dups BOOLEAN
119 . keep_index BOOLEAN
121 Keep an index file of the specified mailbox, one file per
123 directory. Using an index file will speed up things consider‐
124 ably, because it avoids reading all the message files the
125 moment that you open the folder. When you open a folder, you
126 can use the index file to retrieve information such as the sub‐
127 ject of each message, instead of having to read possibly thou‐
128 sands of messages.
129 . labels OBJECT
131 You may specify an OBJECT of a type which extends
133 Mail::Box::MH::Labels (at least implements the "get()" method),
134 as alternative for labels file reader as created by
135 "Mail::Box::MH".
136 . labels_filename FILENAME
138 In MH-folders, messages can be labeled, for instance based on
140 the sender or whether it is read or not. This status is kept
141 in a file which is usually called ".mh_sequences", but that
142 name can be overruled with this flag.
143 . labels_type CLASS
145 . lock_file FILENAME
147 . lock_timeout SECONDS
149 . lock_type CLASS⎪STRING⎪ARRAY
151 . lock_wait SECONDS
153 . locker OBJECT
155 . log LEVEL
157 . manager MANAGER
159 . message_type CLASS
161 . multipart_type CLASS
163 . remove_when_empty BOOLEAN
165 . save_on_exit BOOLEAN
167 . trace LEVEL
169 . trusted BOOLEAN
171 The folder
173 $obj->addMessage(MESSAGE, OPTIONS)
175 See "The folder" in Mail::Box
177 $obj->addMessages(MESSAGE [, MESSAGE, ...])
179 See "The folder" in Mail::Box
181 Mail::Box::MH->appendMessages(OPTIONS)
183 Append a message to a folder which is not open.
185 Option --Defined in --Default
187 folder Mail::Box <required>
188 message Mail::Box undef
189 messages Mail::Box undef
190 share Mail::Box <false>
191 . folder FOLDERNAME
193 . message MESSAGE
195 . messages ARRAY-OF-MESSAGES
197 . share BOOLEAN
199 $obj->close(OPTIONS)
201 See "The folder" in Mail::Box
203 $obj->copyTo(FOLDER, OPTIONS)
205 See "The folder" in Mail::Box
207 $obj->delete(OPTIONS)
209 See "The folder" in Mail::Box
211 $obj->directory
213 See "The folder" in Mail::Box::Dir
215 $obj->folderdir([DIRECTORY])
217 See "The folder" in Mail::Box
219 $obj->name
221 See "The folder" in Mail::Box
223 $obj->organization
225 See "The folder" in Mail::Box
227 $obj->size
229 See "The folder" in Mail::Box
231 $obj->type
233 See "The folder" in Mail::Box
235 $obj->update(OPTIONS)
237 See "The folder" in Mail::Box
239 $obj->url
241 See "The folder" in Mail::Box
243 Folder flags
245 $obj->access
247 See "Folder flags" in Mail::Box
249 $obj->isModified
251 See "Folder flags" in Mail::Box
253 $obj->modified([BOOLEAN])
255 See "Folder flags" in Mail::Box
257 $obj->writable
259 See "Folder flags" in Mail::Box
261 The messages
263 $obj->current([NUMBER⎪MESSAGE⎪MESSAGE-ID])
265 See "The messages" in Mail::Box
267 $obj->find(MESSAGE-ID)
269 See "The messages" in Mail::Box
271 $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
273 See "The messages" in Mail::Box
275 $obj->message(INDEX [,MESSAGE])
277 See "The messages" in Mail::Box
279 $obj->messageId(MESSAGE-ID [,MESSAGE])
281 See "The messages" in Mail::Box
283 $obj->messageIds
285 See "The messages" in Mail::Box
287 $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
289 See "The messages" in Mail::Box
291 $obj->nrMessages(OPTIONS)
293 See "The messages" in Mail::Box
295 $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
297 See "The messages" in Mail::Box
299 Sub-folders
301 $obj->listSubFolders(OPTIONS)
303 Mail::Box::MH->listSubFolders(OPTIONS)
305 See "Sub-folders" in Mail::Box
307 $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
309 Mail::Box::MH->nameOfSubFolder(SUBNAME, [PARENTNAME])
311 See "Sub-folders" in Mail::Box
313 $obj->openRelatedFolder(OPTIONS)
315 See "Sub-folders" in Mail::Box
317 $obj->openSubFolder(SUBNAME, OPTIONS)
319 See "Sub-folders" in Mail::Box
321 $obj->topFolderWithMessages
323 Mail::Box::MH->topFolderWithMessages
325 See "Sub-folders" in Mail::Box
327 Internals
329 $obj->coerce(MESSAGE, OPTIONS)
331 See "Internals" in Mail::Box
333 $obj->create(FOLDERNAME, OPTIONS)
335 Mail::Box::MH->create(FOLDERNAME, OPTIONS)
337 Option --Defined in--Default
339 folderdir Mail::Box undef
340 . folderdir DIRECTORY
342 $obj->determineBodyType(MESSAGE, HEAD)
344 See "Internals" in Mail::Box
346 $obj->folderToDirectory(FOLDERNAME, FOLDERDIR)
348 See "Internals" in Mail::Box::Dir
350 Mail::Box::MH->foundIn([FOLDERNAME], OPTIONS)
352 See "Internals" in Mail::Box
354 $obj->highestMessageNumber
356 Returns the highest number which is used in the folder to store a
358 file. This method may be called when the folder is read (then this
359 number can be derived without file-system access), but also when
360 the folder is not read (yet).
361 $obj->index
363 Create a index reader/writer object.
365 $obj->labels
367 Create a label reader/writer object.
369 $obj->lineSeparator([STRING⎪'CR'⎪'LF'⎪'CRLF'])
371 See "Internals" in Mail::Box
373 $obj->locker
375 See "Internals" in Mail::Box
377 $obj->read(OPTIONS)
379 See "Internals" in Mail::Box
381 $obj->readMessageFilenames(DIRECTORY)
383 See "Internals" in Mail::Box::Dir
385 $obj->readMessages(OPTIONS)
387 See "Internals" in Mail::Box
389 $obj->storeMessage(MESSAGE)
391 See "Internals" in Mail::Box
393 $obj->toBeThreaded(MESSAGES)
395 See "Internals" in Mail::Box
397 $obj->toBeUnthreaded(MESSAGES)
399 See "Internals" in Mail::Box
401 $obj->updateMessages(OPTIONS)
403 See "Internals" in Mail::Box
405 $obj->write(OPTIONS)
407 See "Internals" in Mail::Box
409 $obj->writeMessages(OPTIONS)
411 Option --Defined in --Default
413 messages Mail::Box <required>
414 renumber <true>
415 . messages ARRAY
417 . renumber BOOLEAN
419 Permit renumbering of message. By default this is true, but
421 for some unknown reason, you may be thinking that messages
422 should not be renumbered.
423 Other methods
425 $obj->timespan2seconds(TIME)
427 Mail::Box::MH->timespan2seconds(TIME)
429 See "Other methods" in Mail::Box
431 Error handling
433 $obj->AUTOLOAD
435 See "Error handling" in Mail::Reporter
437 $obj->addReport(OBJECT)
439 See "Error handling" in Mail::Reporter
441 $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
443 Mail::Box::MH->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL,
445 CALLBACK])
446 See "Error handling" in Mail::Reporter
448 $obj->errors
450 See "Error handling" in Mail::Reporter
452 $obj->log([LEVEL [,STRINGS]])
454 Mail::Box::MH->log([LEVEL [,STRINGS]])
456 See "Error handling" in Mail::Reporter
458 $obj->logPriority(LEVEL)
460 Mail::Box::MH->logPriority(LEVEL)
462 See "Error handling" in Mail::Reporter
464 $obj->logSettings
466 See "Error handling" in Mail::Reporter
468 $obj->notImplemented
470 See "Error handling" in Mail::Reporter
472 $obj->report([LEVEL])
474 See "Error handling" in Mail::Reporter
476 $obj->reportAll([LEVEL])
478 See "Error handling" in Mail::Reporter
480 $obj->trace([LEVEL])
482 See "Error handling" in Mail::Reporter
484 $obj->warnings
486 See "Error handling" in Mail::Reporter
488 Cleanup
490 $obj->DESTROY
492 See "Cleanup" in Mail::Box
494 $obj->inGlobalDestruction
496 See "Cleanup" in Mail::Reporter
498
500 How MH folders work
501 MH-type folders use a directory to store the messages of one folder.
503 Each message is stored in a separate file. This seems useful, because
504 changes in a folder change only a few of these small files, in contrast
505 with file-based folders where changes in a folder cause rewrites of
506 huge folder files.
507 However, MH-based folders perform very bad if you need header informa‐
509 tion of all messages. For instance, if you want to have full knowledge
510 about all message-threads (see Mail::Box::Thread::Manager) in the
511 folder, it requires to read all header lines in all message files. And
512 usually, reading your messages in threads is desired.
513 So, each message is written in a separate file. The filenames are num‐
515 bers, which count from 1. Next to these message files, a directory may
516 contain a file named ".mh_sequences", storing labels which relate to
517 the messages. Furthermore, a folder-directory may contain sub-directo‐
518 ries, which are seen as sub-folders.
519 This implementation
521 This implementation supports the ".mh-sequences" file and sub-folders.
523 Next to this, considerable effort it made to avoid reading each mes‐
524 sage-file. This should boost performance of the MailBox distribution
525 over other Perl-modules which are able to read folders.
526 Folder types which store their messages each in one file, together in
528 one directory, are bad for performance. Consider that you want to know
529 the subjects of all messages, while browser through a folder with your
530 mail-reading client. This would cause all message-files to be read.
531 Mail::Box::MH has two ways to try improve performance. You can use an
533 index-file, and use on delay-loading. The combination performs even
534 better. Both are explained in the next sections.
535 An index-file
537 If you specify new(keep_index), then all header-lines of all messages
539 from the folder which have been read once, will also be written into
540 one dedicated index-file (one file per folder). The default filename
541 is ".index"
542 However, index-files are not supported by any other reader which sup‐
544 ports MH (as far as I know). If you read the folders with such I
545 client, it will not cause unrecoverable conflicts with this index-file,
546 but at most be bad for performance.
547 If you do not (want to) use an index-file, then delay-loading may save
549 your day.
550
552 Error: Cannot append message without lock on $folder.
553 It is impossible to append one or more messages to the folder which is
555 not opened, because locking it failes. The folder may be in use by an
556 other application, or you may need to specify some lock related options
557 (see new()).
558 Error: Cannot create MH folder $name: $!
560 For some reason, it is impossible to create the folder. Check the per‐
562 missions and the name of the folder. Does the path to the directory to
563 be created exist?
564 Error: Cannot write folder $name without lock.
566 It is impossible to get a lock on the folder, which means that the
568 changes can not be made. You may need to tune the lock related options
569 which are available at folder creation.
570 Warning: Changes not written to read-only folder $self.
572 You have opened the folder read-only --which is the default set by
574 new(access)--, made modifications, and now want to close it. Set
575 close(force) if you want to overrule the access mode, or close the
576 folder with close(write) set to "NEVER".
577 Error: Copying failed for one message.
579 For some reason, for instance disc full, removed by external process,
581 or read-protection, it is impossible to copy one of the messages.
582 Copying will proceed for the other messages.
583 Error: Destination folder $name is not writable.
585 The folder where the messages are copied to is not opened with write
587 access (see new(access)). This has no relation with write permission
588 to the folder which is controled by your operating system.
589 Warning: Different messages with id $msgid
591 The message id is discovered more than once within the same folder, but
593 the content of the message seems to be different. This should not be
594 possible: each message must be unique.
595 Error: Folder $name is opened read-only
597 You can not write to this folder unless you have opened the folder to
599 write or append with new(access), or the "force" option is set true.
600 Error: Folder $name not deleted: not writable.
602 The folder must be opened with write access via new(access), otherwise
604 removing it will be refused. So, you may have write-access according
605 to the operating system, but that will not automatically mean that this
606 "delete" method permits you to. The reverse remark is valid as well.
607 Error: Invalid timespan '$timespan' specified.
609 The string does not follow the strict rules of the time span syntax
611 which is permitted as parameter.
612 Warning: Message-id '$msgid' does not contain a domain.
614 According to the RFCs, message-ids need to contain a unique random
616 part, then an "@", and then a domain name. This is made to avoid the
617 creation of two messages with the same id. The warning emerges when
618 the "@" is missing from the string.
619 Error: Package $package does not implement $method.
621 Fatal error: the specific package (or one of its superclasses) does not
623 implement this method where it should. This message means that some
624 other related classes do implement this method however the class at
625 hand does not. Probably you should investigate this and probably
626 inform the author of the package.
627 Error: Unable to create subfolder $name of $folder.
629 The copy includes the subfolders, but for some reason it was not possi‐
631 ble to copy one of these. Copying will proceed for all other sub-fold‐
632 ers.
633 Error: Unable to write message for $folder to $filename: $!
635 The new message could not be written to its new file, for the specific
637 reason.
638 Error: Writing folder $name failed
640 For some reason (you probably got more error messages about this prob‐
642 lem) it is impossible to write the folder, although you should because
643 there were changes made.
644
646 This module is part of Mail-Box distribution version 2.070, built on
647 March 25, 2007. Website: http://perl.overmeer.net/mailbox/
648
650 Copyrights 2001-2007 by Mark Overmeer.For other contributors see
651 ChangeLog.
652 This program is free software; you can redistribute it and/or modify it
654 under the same terms as Perl itself. See
655 http://www.perl.com/perl/misc/Artistic.html
656perl v5.8.8 2007-03-25 Mail::Box::MH(3)