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 Extends "DESCRIPTION" in Mail::Box::Dir.
23
25 Extends "OVERLOADED" in Mail::Box::Dir.
26 overload: ""
28 Inherited, see "OVERLOADED" in Mail::Box
29 overload: @{}
31 Inherited, see "OVERLOADED" in Mail::Box
32 overload: cmp
34 Inherited, see "OVERLOADED" in Mail::Box
35
37 Extends "METHODS" in Mail::Box::Dir.
38 Constructors
40 Extends "Constructors" in Mail::Box::Dir.
41 Mail::Box::MH->new(%options)
43 -Option --Defined in --Default
44 access Mail::Box 'r'
45 body_delayed_type Mail::Box Mail::Message::Body::Delayed
46 body_type Mail::Box Mail::Message::Body::Lines
47 coerce_options Mail::Box []
48 create Mail::Box <false>
49 directory Mail::Box::Dir <derived from folder name>
50 extract Mail::Box 10240
51 field_type Mail::Box undef
52 fix_headers Mail::Box <false>
53 folder Mail::Box $ENV{MAIL}
54 folderdir Mail::Box $ENV{HOME}/.mh
55 head_delayed_type Mail::Box Mail::Message::Head::Delayed
56 head_type Mail::Box Mail::Message::Head::Complete
57 index undef
58 index_filename <foldername>/.index
59 index_type Mail::Box::MH::Index
60 keep_dups Mail::Box <false>
61 keep_index 0
62 labels undef
63 labels_filename <foldername>/.mh_sequence
64 labels_type Mail::Box::MH::Labels
65 lock_file Mail::Box <index_file>
66 lock_timeout Mail::Box 1 hour
67 lock_type Mail::Box Mail::Box::Locker::DotLock
68 lock_wait Mail::Box 10 seconds
69 locker Mail::Box undef
70 log Mail::Reporter 'WARNINGS'
71 manager Mail::Box undef
72 message_type Mail::Box <folder-class>::Message
73 multipart_type Mail::Box Mail::Message::Body::Multipart
74 remove_when_empty Mail::Box <true>
75 save_on_exit Mail::Box <true>
76 trace Mail::Reporter 'WARNINGS'
77 trusted Mail::Box <depends on folder location>
78 access => MODE
80 body_delayed_type => CLASS
81 body_type => CLASS|CODE
82 coerce_options => ARRAY
83 create => BOOLEAN
84 directory => DIRECTORY
85 extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
86 field_type => CLASS
87 fix_headers => BOOLEAN
88 folder => FOLDERNAME
89 folderdir => DIRECTORY
90 head_delayed_type => CLASS
91 head_type => CLASS
92 index => OBJECT
93 You may specify an OBJECT of a type which extends
94 Mail::Box::MH::Index (at least implements a get() method), as
95 alternative for an index file reader as created by
96 "Mail::Box::MH".
97 index_filename => FILENAME
99 The FILENAME which is used in each directory to store the headers
100 of all mails. The filename shall not contain a directory path.
101 (e.g. Do not use "/usr/people/jan/.index", nor "subdir/.index",
102 but say ".index".)
103 index_type => CLASS
105 keep_dups => BOOLEAN
106 keep_index => BOOLEAN
107 Keep an index file of the specified mailbox, one file per
108 directory. Using an index file will speed up things
109 considerably, because it avoids reading all the message files the
110 moment that you open the folder. When you open a folder, you can
111 use the index file to retrieve information such as the subject of
112 each message, instead of having to read possibly thousands of
113 messages.
114 labels => OBJECT
116 You may specify an OBJECT of a type which extends
117 Mail::Box::MH::Labels (at least implements the get() method), as
118 alternative for labels file reader as created by "Mail::Box::MH".
119 labels_filename => FILENAME
121 In MH-folders, messages can be labeled, for instance based on the
122 sender or whether it is read or not. This status is kept in a
123 file which is usually called ".mh_sequences", but that name can
124 be overruled with this flag.
125 labels_type => CLASS
127 lock_file => FILENAME
128 lock_timeout => SECONDS
129 lock_type => CLASS|STRING|ARRAY
130 lock_wait => SECONDS
131 locker => OBJECT
132 log => LEVEL
133 manager => MANAGER
134 message_type => CLASS
135 multipart_type => CLASS
136 remove_when_empty => BOOLEAN
137 save_on_exit => BOOLEAN
138 trace => LEVEL
139 trusted => BOOLEAN
140 The folder
142 Extends "The folder" in Mail::Box::Dir.
143 $obj->addMessage($message, %options)
145 Inherited, see "The folder" in Mail::Box
146 $obj->addMessages(@messages)
148 Inherited, see "The folder" in Mail::Box
149 Mail::Box::MH->appendMessages(%options)
151 Append a message to a folder which is not open.
152 -Option --Defined in --Default
154 folder Mail::Box <required>
155 message Mail::Box undef
156 messages Mail::Box undef
157 share Mail::Box <false>
158 folder => FOLDERNAME
160 message => MESSAGE
161 messages => ARRAY-OF-MESSAGES
162 share => BOOLEAN
163 $obj->close(%options)
164 Inherited, see "The folder" in Mail::Box
165 $obj->copyTo($folder, %options)
167 Inherited, see "The folder" in Mail::Box
168 $obj->delete(%options)
170 Inherited, see "The folder" in Mail::Box
171 $obj->directory()
173 Inherited, see "The folder" in Mail::Box::Dir
174 $obj->folderdir( [$directory] )
176 Inherited, see "The folder" in Mail::Box
177 $obj->name()
179 Inherited, see "The folder" in Mail::Box
180 $obj->organization()
182 Inherited, see "The folder" in Mail::Box
183 $obj->size()
185 Inherited, see "The folder" in Mail::Box
186 $obj->type()
188 Inherited, see "The folder" in Mail::Box
189 $obj->update(%options)
191 Inherited, see "The folder" in Mail::Box
192 $obj->url()
194 Inherited, see "The folder" in Mail::Box
195 Folder flags
197 Extends "Folder flags" in Mail::Box::Dir.
198 $obj->access()
200 Inherited, see "Folder flags" in Mail::Box
201 $obj->isModified()
203 Inherited, see "Folder flags" in Mail::Box
204 $obj->modified( [BOOLEAN] )
206 Inherited, see "Folder flags" in Mail::Box
207 $obj->writable()
209 Inherited, see "Folder flags" in Mail::Box
210 The messages
212 Extends "The messages" in Mail::Box::Dir.
213 $obj->current( [$number|$message|$message_id] )
215 Inherited, see "The messages" in Mail::Box
216 $obj->find($message_id)
218 Inherited, see "The messages" in Mail::Box
219 $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
221 Inherited, see "The messages" in Mail::Box
222 $obj->message( $index, [$message] )
224 Inherited, see "The messages" in Mail::Box
225 $obj->messageId( $message_id, [$message] )
227 Inherited, see "The messages" in Mail::Box
228 $obj->messageIds()
230 Inherited, see "The messages" in Mail::Box
231 $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
233 !$label|$filter> )
234 Inherited, see "The messages" in Mail::Box
235 $obj->nrMessages(%options)
237 Inherited, see "The messages" in Mail::Box
238 $obj->scanForMessages($message, $message_ids, $timespan, $window)
240 Inherited, see "The messages" in Mail::Box
241 Sub-folders
243 Extends "Sub-folders" in Mail::Box::Dir.
244 $obj->listSubFolders(%options)
246 Mail::Box::MH->listSubFolders(%options)
247 Inherited, see "Sub-folders" in Mail::Box
248 $obj->nameOfSubFolder( $subname, [$parentname] )
250 Mail::Box::MH->nameOfSubFolder( $subname, [$parentname] )
251 Inherited, see "Sub-folders" in Mail::Box
252 $obj->openRelatedFolder(%options)
254 Inherited, see "Sub-folders" in Mail::Box
255 $obj->openSubFolder($subname, %options)
257 Inherited, see "Sub-folders" in Mail::Box
258 $obj->topFolderWithMessages()
260 Mail::Box::MH->topFolderWithMessages()
261 Inherited, see "Sub-folders" in Mail::Box
262 Internals
264 Extends "Internals" in Mail::Box::Dir.
265 $obj->coerce($message, %options)
267 Inherited, see "Internals" in Mail::Box
268 $obj->create($foldername, %options)
270 Mail::Box::MH->create($foldername, %options)
271 -Option --Defined in--Default
272 folderdir Mail::Box undef
273 folderdir => DIRECTORY
275 $obj->determineBodyType($message, $head)
276 Inherited, see "Internals" in Mail::Box
277 $obj->folderToDirectory($foldername, $folderdir)
279 Inherited, see "Internals" in Mail::Box::Dir
280 Mail::Box::MH->foundIn( [$foldername], %options )
282 Inherited, see "Internals" in Mail::Box
283 $obj->highestMessageNumber()
285 Returns the highest number which is used in the folder to store a
286 file. This method may be called when the folder is read (then this
287 number can be derived without file-system access), but also when
288 the folder is not read (yet).
289 $obj->index()
291 Create a index reader/writer object.
292 $obj->labels()
294 Create a label reader/writer object.
295 $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
297 Inherited, see "Internals" in Mail::Box
298 $obj->locker()
300 Inherited, see "Internals" in Mail::Box
301 $obj->messageInFile($filename)
303 Inherited, see "Internals" in Mail::Box::Dir
304 $obj->read(%options)
306 Inherited, see "Internals" in Mail::Box
307 $obj->readMessageFilenames($directory)
309 Inherited, see "Internals" in Mail::Box::Dir
310 $obj->readMessages(%options)
312 Inherited, see "Internals" in Mail::Box
313 $obj->storeMessage($message)
315 Inherited, see "Internals" in Mail::Box
316 $obj->toBeThreaded($messages)
318 Inherited, see "Internals" in Mail::Box
319 $obj->toBeUnthreaded($messages)
321 Inherited, see "Internals" in Mail::Box
322 $obj->updateMessages(%options)
324 Inherited, see "Internals" in Mail::Box
325 $obj->write(%options)
327 Inherited, see "Internals" in Mail::Box
328 $obj->writeMessages(%options)
330 -Option --Defined in --Default
331 messages Mail::Box <required>
332 renumber <true>
333 messages => ARRAY
335 renumber => BOOLEAN
336 Permit renumbering of message. By default this is true, but for
337 some unknown reason, you may be thinking that messages should not
338 be renumbered.
339 Other methods
341 Extends "Other methods" in Mail::Box::Dir.
342 $obj->timespan2seconds($time)
344 Mail::Box::MH->timespan2seconds($time)
345 Inherited, see "Other methods" in Mail::Box
346 Error handling
348 Extends "Error handling" in Mail::Box::Dir.
349 $obj->AUTOLOAD()
351 Inherited, see "Error handling" in Mail::Reporter
352 $obj->addReport($object)
354 Inherited, see "Error handling" in Mail::Reporter
355 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
357 $callback] )
358 Mail::Box::MH->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
359 $callback] )
360 Inherited, see "Error handling" in Mail::Reporter
361 $obj->errors()
363 Inherited, see "Error handling" in Mail::Reporter
364 $obj->log( [$level, [$strings]] )
366 Mail::Box::MH->log( [$level, [$strings]] )
367 Inherited, see "Error handling" in Mail::Reporter
368 $obj->logPriority($level)
370 Mail::Box::MH->logPriority($level)
371 Inherited, see "Error handling" in Mail::Reporter
372 $obj->logSettings()
374 Inherited, see "Error handling" in Mail::Reporter
375 $obj->notImplemented()
377 Inherited, see "Error handling" in Mail::Reporter
378 $obj->report( [$level] )
380 Inherited, see "Error handling" in Mail::Reporter
381 $obj->reportAll( [$level] )
383 Inherited, see "Error handling" in Mail::Reporter
384 $obj->trace( [$level] )
386 Inherited, see "Error handling" in Mail::Reporter
387 $obj->warnings()
389 Inherited, see "Error handling" in Mail::Reporter
390 Cleanup
392 Extends "Cleanup" in Mail::Box::Dir.
393 $obj->DESTROY()
395 Inherited, see "Cleanup" in Mail::Box
396
398 Extends "DETAILS" in Mail::Box::Dir.
399 Different kinds of folders
401 Extends "Different kinds of folders" in Mail::Box::Dir.
402 Available folder types
404 Extends "Available folder types" in Mail::Box::Dir.
405 Folder class implementation
407 Extends "Folder class implementation" in Mail::Box::Dir.
408 How MH folders work
410 MH-type folders use a directory to store the messages of one folder.
411 Each message is stored in a separate file. This seems useful, because
412 changes in a folder change only a few of these small files, in contrast
413 with file-based folders where changes in a folder cause rewrites of
414 huge folder files.
415 However, MH-based folders perform very bad if you need header
417 information of all messages. For instance, if you want to have full
418 knowledge about all message-threads (see Mail::Box::Thread::Manager) in
419 the folder, it requires to read all header lines in all message files.
420 And usually, reading your messages in threads is desired.
421 So, each message is written in a separate file. The filenames are
423 numbers, which count from 1. Next to these message files, a directory
424 may contain a file named ".mh_sequences", storing labels which relate
425 to the messages. Furthermore, a folder-directory may contain sub-
426 directories, which are seen as sub-folders.
427 This implementation
429 This implementation supports the ".mh-sequences" file and sub-folders.
430 Next to this, considerable effort it made to avoid reading each
431 message-file. This should boost performance of the MailBox
432 distribution over other Perl-modules which are able to read folders.
433 Folder types which store their messages each in one file, together in
435 one directory, are bad for performance. Consider that you want to know
436 the subjects of all messages, while browser through a folder with your
437 mail-reading client. This would cause all message-files to be read.
438 Mail::Box::MH has two ways to try improve performance. You can use an
440 index-file, and use on delay-loading. The combination performs even
441 better. Both are explained in the next sections.
442 An index-file
444 If you specify new(keep_index), then all header-lines of all messages
445 from the folder which have been read once, will also be written into
446 one dedicated index-file (one file per folder). The default filename
447 is ".index"
448 However, index-files are not supported by any other reader which
450 supports MH (as far as I know). If you read the folders with such I
451 client, it will not cause unrecoverable conflicts with this index-file,
452 but at most be bad for performance.
453 If you do not (want to) use an index-file, then delay-loading may save
455 your day.
456
458 Error: Cannot append message without lock on $folder.
459 It is impossible to append one or more messages to the folder which
460 is not opened, because locking it fails. The folder may be in use
461 by an other application, or you may need to specify some lock
462 related options (see new()).
463 Error: Cannot create MH folder $name: $!
465 For some reason, it is impossible to create the folder. Check the
466 permissions and the name of the folder. Does the path to the
467 directory to be created exist?
468 Error: Cannot write folder $name without lock.
470 It is impossible to get a lock on the folder, which means that the
471 changes can not be made. You may need to tune the lock related
472 options which are available at folder creation.
473 Warning: Changes not written to read-only folder $self.
475 You have opened the folder read-only --which is the default set by
476 new(access)--, made modifications, and now want to close it. Set
477 close(force) if you want to overrule the access mode, or close the
478 folder with close(write) set to "NEVER".
479 Error: Copying failed for one message.
481 For some reason, for instance disc full, removed by external
482 process, or read-protection, it is impossible to copy one of the
483 messages. Copying will proceed for the other messages.
484 Error: Destination folder $name is not writable.
486 The folder where the messages are copied to is not opened with
487 write access (see new(access)). This has no relation with write
488 permission to the folder which is controlled by your operating
489 system.
490 Warning: Different messages with id $msgid
492 The message id is discovered more than once within the same folder,
493 but the content of the message seems to be different. This should
494 not be possible: each message must be unique.
495 Error: Folder $name is opened read-only
497 You can not write to this folder unless you have opened the folder
498 to write or append with new(access), or the "force" option is set
499 true.
500 Error: Folder $name not deleted: not writable.
502 The folder must be opened with write access via new(access),
503 otherwise removing it will be refused. So, you may have write-
504 access according to the operating system, but that will not
505 automatically mean that this "delete" method permits you to. The
506 reverse remark is valid as well.
507 Error: Invalid timespan '$timespan' specified.
509 The string does not follow the strict rules of the time span syntax
510 which is permitted as parameter.
511 Warning: Message-id '$msgid' does not contain a domain.
513 According to the RFCs, message-ids need to contain a unique random
514 part, then an "@", and then a domain name. This is made to avoid
515 the creation of two messages with the same id. The warning emerges
516 when the "@" is missing from the string.
517 Error: Package $package does not implement $method.
519 Fatal error: the specific package (or one of its superclasses) does
520 not implement this method where it should. This message means that
521 some other related classes do implement this method however the
522 class at hand does not. Probably you should investigate this and
523 probably inform the author of the package.
524 Error: Unable to create subfolder $name of $folder.
526 The copy includes the subfolders, but for some reason it was not
527 possible to copy one of these. Copying will proceed for all other
528 sub-folders.
529 Error: Unable to write message for $folder to $filename: $!
531 The new message could not be written to its new file, for the
532 specific reason.
533 Error: Writing folder $name failed
535 For some reason (you probably got more error messages about this
536 problem) it is impossible to write the folder, although you should
537 because there were changes made.
538
540 This module is part of Mail-Box distribution version 3.010, built on
541 July 18, 2023. Website: http://perl.overmeer.net/CPAN/
542
544 Copyrights 2001-2023 by [Mark Overmeer]. For other contributors see
545 ChangeLog.
546 This program is free software; you can redistribute it and/or modify it
548 under the same terms as Perl itself. See http://dev.perl.org/licenses/
549perl v5.38.0 2023-07-24 Mail::Box::MH(3)