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),
118 as alternative for labels file reader as created by
119 "Mail::Box::MH".
120 labels_filename => FILENAME
122 In MH-folders, messages can be labeled, for instance based on the
123 sender or whether it is read or not. This status is kept in a
124 file which is usually called ".mh_sequences", but that name can
125 be overruled with this flag.
126 labels_type => CLASS
128 lock_file => FILENAME
129 lock_timeout => SECONDS
130 lock_type => CLASS|STRING|ARRAY
131 lock_wait => SECONDS
132 locker => OBJECT
133 log => LEVEL
134 manager => MANAGER
135 message_type => CLASS
136 multipart_type => CLASS
137 remove_when_empty => BOOLEAN
138 save_on_exit => BOOLEAN
139 trace => LEVEL
140 trusted => BOOLEAN
141 The folder
143 Extends "The folder" in Mail::Box::Dir.
144 $obj->addMessage($message, %options)
146 Inherited, see "The folder" in Mail::Box
147 $obj->addMessages(@messages)
149 Inherited, see "The folder" in Mail::Box
150 Mail::Box::MH->appendMessages(%options)
152 Append a message to a folder which is not open.
153 -Option --Defined in --Default
155 folder Mail::Box <required>
156 message Mail::Box undef
157 messages Mail::Box undef
158 share Mail::Box <false>
159 folder => FOLDERNAME
161 message => MESSAGE
162 messages => ARRAY-OF-MESSAGES
163 share => BOOLEAN
164 $obj->close(%options)
165 Inherited, see "The folder" in Mail::Box
166 $obj->copyTo($folder, %options)
168 Inherited, see "The folder" in Mail::Box
169 $obj->delete(%options)
171 Inherited, see "The folder" in Mail::Box
172 $obj->directory()
174 Inherited, see "The folder" in Mail::Box::Dir
175 $obj->folderdir( [$directory] )
177 Inherited, see "The folder" in Mail::Box
178 $obj->name()
180 Inherited, see "The folder" in Mail::Box
181 $obj->organization()
183 Inherited, see "The folder" in Mail::Box
184 $obj->size()
186 Inherited, see "The folder" in Mail::Box
187 $obj->type()
189 Inherited, see "The folder" in Mail::Box
190 $obj->update(%options)
192 Inherited, see "The folder" in Mail::Box
193 $obj->url()
195 Inherited, see "The folder" in Mail::Box
196 Folder flags
198 Extends "Folder flags" in Mail::Box::Dir.
199 $obj->access()
201 Inherited, see "Folder flags" in Mail::Box
202 $obj->isModified()
204 Inherited, see "Folder flags" in Mail::Box
205 $obj->modified( [BOOLEAN] )
207 Inherited, see "Folder flags" in Mail::Box
208 $obj->writable()
210 Inherited, see "Folder flags" in Mail::Box
211 The messages
213 Extends "The messages" in Mail::Box::Dir.
214 $obj->current( [$number|$message|$message_id] )
216 Inherited, see "The messages" in Mail::Box
217 $obj->find($message_id)
219 Inherited, see "The messages" in Mail::Box
220 $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
222 Inherited, see "The messages" in Mail::Box
223 $obj->message( $index, [$message] )
225 Inherited, see "The messages" in Mail::Box
226 $obj->messageId( $message_id, [$message] )
228 Inherited, see "The messages" in Mail::Box
229 $obj->messageIds()
231 Inherited, see "The messages" in Mail::Box
232 $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
234 !$label|$filter> )
235 Inherited, see "The messages" in Mail::Box
236 $obj->nrMessages(%options)
238 Inherited, see "The messages" in Mail::Box
239 $obj->scanForMessages($message, $message_ids, $timespan, $window)
241 Inherited, see "The messages" in Mail::Box
242 Sub-folders
244 Extends "Sub-folders" in Mail::Box::Dir.
245 $obj->listSubFolders(%options)
247 Mail::Box::MH->listSubFolders(%options)
248 Inherited, see "Sub-folders" in Mail::Box
249 $obj->nameOfSubFolder( $subname, [$parentname] )
251 Mail::Box::MH->nameOfSubFolder( $subname, [$parentname] )
252 Inherited, see "Sub-folders" in Mail::Box
253 $obj->openRelatedFolder(%options)
255 Inherited, see "Sub-folders" in Mail::Box
256 $obj->openSubFolder($subname, %options)
258 Inherited, see "Sub-folders" in Mail::Box
259 $obj->topFolderWithMessages()
261 Mail::Box::MH->topFolderWithMessages()
262 Inherited, see "Sub-folders" in Mail::Box
263 Internals
265 Extends "Internals" in Mail::Box::Dir.
266 $obj->coerce($message, %options)
268 Inherited, see "Internals" in Mail::Box
269 $obj->create($foldername, %options)
271 Mail::Box::MH->create($foldername, %options)
272 -Option --Defined in--Default
273 folderdir Mail::Box undef
274 folderdir => DIRECTORY
276 $obj->determineBodyType($message, $head)
277 Inherited, see "Internals" in Mail::Box
278 $obj->folderToDirectory($foldername, $folderdir)
280 Inherited, see "Internals" in Mail::Box::Dir
281 Mail::Box::MH->foundIn( [$foldername], %options )
283 Inherited, see "Internals" in Mail::Box
284 $obj->highestMessageNumber()
286 Returns the highest number which is used in the folder to store a
287 file. This method may be called when the folder is read (then this
288 number can be derived without file-system access), but also when
289 the folder is not read (yet).
290 $obj->index()
292 Create a index reader/writer object.
293 $obj->labels()
295 Create a label reader/writer object.
296 $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
298 Inherited, see "Internals" in Mail::Box
299 $obj->locker()
301 Inherited, see "Internals" in Mail::Box
302 $obj->messageInFile($filename)
304 Inherited, see "Internals" in Mail::Box::Dir
305 $obj->read(%options)
307 Inherited, see "Internals" in Mail::Box
308 $obj->readMessageFilenames($directory)
310 Inherited, see "Internals" in Mail::Box::Dir
311 $obj->readMessages(%options)
313 Inherited, see "Internals" in Mail::Box
314 $obj->storeMessage($message)
316 Inherited, see "Internals" in Mail::Box
317 $obj->toBeThreaded($messages)
319 Inherited, see "Internals" in Mail::Box
320 $obj->toBeUnthreaded($messages)
322 Inherited, see "Internals" in Mail::Box
323 $obj->updateMessages(%options)
325 Inherited, see "Internals" in Mail::Box
326 $obj->write(%options)
328 Inherited, see "Internals" in Mail::Box
329 $obj->writeMessages(%options)
331 -Option --Defined in --Default
332 messages Mail::Box <required>
333 renumber <true>
334 messages => ARRAY
336 renumber => BOOLEAN
337 Permit renumbering of message. By default this is true, but for
338 some unknown reason, you may be thinking that messages should not
339 be renumbered.
340 Other methods
342 Extends "Other methods" in Mail::Box::Dir.
343 $obj->timespan2seconds($time)
345 Mail::Box::MH->timespan2seconds($time)
346 Inherited, see "Other methods" in Mail::Box
347 Error handling
349 Extends "Error handling" in Mail::Box::Dir.
350 $obj->AUTOLOAD()
352 Inherited, see "Error handling" in Mail::Reporter
353 $obj->addReport($object)
355 Inherited, see "Error handling" in Mail::Reporter
356 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
358 $callback] )
359 Mail::Box::MH->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
360 $callback] )
361 Inherited, see "Error handling" in Mail::Reporter
362 $obj->errors()
364 Inherited, see "Error handling" in Mail::Reporter
365 $obj->log( [$level, [$strings]] )
367 Mail::Box::MH->log( [$level, [$strings]] )
368 Inherited, see "Error handling" in Mail::Reporter
369 $obj->logPriority($level)
371 Mail::Box::MH->logPriority($level)
372 Inherited, see "Error handling" in Mail::Reporter
373 $obj->logSettings()
375 Inherited, see "Error handling" in Mail::Reporter
376 $obj->notImplemented()
378 Inherited, see "Error handling" in Mail::Reporter
379 $obj->report( [$level] )
381 Inherited, see "Error handling" in Mail::Reporter
382 $obj->reportAll( [$level] )
384 Inherited, see "Error handling" in Mail::Reporter
385 $obj->trace( [$level] )
387 Inherited, see "Error handling" in Mail::Reporter
388 $obj->warnings()
390 Inherited, see "Error handling" in Mail::Reporter
391 Cleanup
393 Extends "Cleanup" in Mail::Box::Dir.
394 $obj->DESTROY()
396 Inherited, see "Cleanup" in Mail::Box
397
399 Extends "DETAILS" in Mail::Box::Dir.
400 Different kinds of folders
402 Extends "Different kinds of folders" in Mail::Box::Dir.
403 Available folder types
405 Extends "Available folder types" in Mail::Box::Dir.
406 Folder class implementation
408 Extends "Folder class implementation" in Mail::Box::Dir.
409 How MH folders work
411 MH-type folders use a directory to store the messages of one folder.
412 Each message is stored in a separate file. This seems useful, because
413 changes in a folder change only a few of these small files, in contrast
414 with file-based folders where changes in a folder cause rewrites of
415 huge folder files.
416 However, MH-based folders perform very bad if you need header
418 information of all messages. For instance, if you want to have full
419 knowledge about all message-threads (see Mail::Box::Thread::Manager) in
420 the folder, it requires to read all header lines in all message files.
421 And usually, reading your messages in threads is desired.
422 So, each message is written in a separate file. The filenames are
424 numbers, which count from 1. Next to these message files, a directory
425 may contain a file named ".mh_sequences", storing labels which relate
426 to the messages. Furthermore, a folder-directory may contain sub-
427 directories, which are seen as sub-folders.
428 This implementation
430 This implementation supports the ".mh-sequences" file and sub-folders.
431 Next to this, considerable effort it made to avoid reading each
432 message-file. This should boost performance of the MailBox
433 distribution over other Perl-modules which are able to read folders.
434 Folder types which store their messages each in one file, together in
436 one directory, are bad for performance. Consider that you want to know
437 the subjects of all messages, while browser through a folder with your
438 mail-reading client. This would cause all message-files to be read.
439 Mail::Box::MH has two ways to try improve performance. You can use an
441 index-file, and use on delay-loading. The combination performs even
442 better. Both are explained in the next sections.
443 An index-file
445 If you specify new(keep_index), then all header-lines of all messages
446 from the folder which have been read once, will also be written into
447 one dedicated index-file (one file per folder). The default filename
448 is ".index"
449 However, index-files are not supported by any other reader which
451 supports MH (as far as I know). If you read the folders with such I
452 client, it will not cause unrecoverable conflicts with this index-file,
453 but at most be bad for performance.
454 If you do not (want to) use an index-file, then delay-loading may save
456 your day.
457
459 Error: Cannot append message without lock on $folder.
460 It is impossible to append one or more messages to the folder which
461 is not opened, because locking it fails. The folder may be in use
462 by an other application, or you may need to specify some lock
463 related options (see new()).
464 Error: Cannot create MH folder $name: $!
466 For some reason, it is impossible to create the folder. Check the
467 permissions and the name of the folder. Does the path to the
468 directory to be created exist?
469 Error: Cannot write folder $name without lock.
471 It is impossible to get a lock on the folder, which means that the
472 changes can not be made. You may need to tune the lock related
473 options which are available at folder creation.
474 Warning: Changes not written to read-only folder $self.
476 You have opened the folder read-only --which is the default set by
477 new(access)--, made modifications, and now want to close it. Set
478 close(force) if you want to overrule the access mode, or close the
479 folder with close(write) set to "NEVER".
480 Error: Copying failed for one message.
482 For some reason, for instance disc full, removed by external
483 process, or read-protection, it is impossible to copy one of the
484 messages. Copying will proceed for the other messages.
485 Error: Destination folder $name is not writable.
487 The folder where the messages are copied to is not opened with
488 write access (see new(access)). This has no relation with write
489 permission to the folder which is controlled by your operating
490 system.
491 Warning: Different messages with id $msgid
493 The message id is discovered more than once within the same folder,
494 but the content of the message seems to be different. This should
495 not be possible: each message must be unique.
496 Error: Folder $name is opened read-only
498 You can not write to this folder unless you have opened the folder
499 to write or append with new(access), or the "force" option is set
500 true.
501 Error: Folder $name not deleted: not writable.
503 The folder must be opened with write access via new(access),
504 otherwise removing it will be refused. So, you may have write-
505 access according to the operating system, but that will not
506 automatically mean that this "delete" method permits you to. The
507 reverse remark is valid as well.
508 Error: Invalid timespan '$timespan' specified.
510 The string does not follow the strict rules of the time span syntax
511 which is permitted as parameter.
512 Warning: Message-id '$msgid' does not contain a domain.
514 According to the RFCs, message-ids need to contain a unique random
515 part, then an "@", and then a domain name. This is made to avoid
516 the creation of two messages with the same id. The warning emerges
517 when the "@" is missing from the string.
518 Error: Package $package does not implement $method.
520 Fatal error: the specific package (or one of its superclasses) does
521 not implement this method where it should. This message means that
522 some other related classes do implement this method however the
523 class at hand does not. Probably you should investigate this and
524 probably inform the author of the package.
525 Error: Unable to create subfolder $name of $folder.
527 The copy includes the subfolders, but for some reason it was not
528 possible to copy one of these. Copying will proceed for all other
529 sub-folders.
530 Error: Unable to write message for $folder to $filename: $!
532 The new message could not be written to its new file, for the
533 specific reason.
534 Error: Writing folder $name failed
536 For some reason (you probably got more error messages about this
537 problem) it is impossible to write the folder, although you should
538 because there were changes made.
539
541 This module is part of Mail-Box distribution version 3.009, built on
542 August 18, 2020. Website: http://perl.overmeer.net/CPAN/
543
545 Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
546 ChangeLog.
547 This program is free software; you can redistribute it and/or modify it
549 under the same terms as Perl itself. See http://dev.perl.org/licenses/
550perl v5.32.1 2021-01-27 Mail::Box::MH(3)