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->read(%options)
304 Inherited, see "Internals" in Mail::Box
305 $obj->readMessageFilenames($directory)
307 Inherited, see "Internals" in Mail::Box::Dir
308 $obj->readMessages(%options)
310 Inherited, see "Internals" in Mail::Box
311 $obj->storeMessage($message)
313 Inherited, see "Internals" in Mail::Box
314 $obj->toBeThreaded($messages)
316 Inherited, see "Internals" in Mail::Box
317 $obj->toBeUnthreaded($messages)
319 Inherited, see "Internals" in Mail::Box
320 $obj->updateMessages(%options)
322 Inherited, see "Internals" in Mail::Box
323 $obj->write(%options)
325 Inherited, see "Internals" in Mail::Box
326 $obj->writeMessages(%options)
328 -Option --Defined in --Default
329 messages Mail::Box <required>
330 renumber <true>
331 messages => ARRAY
333 renumber => BOOLEAN
334 Permit renumbering of message. By default this is true, but for
335 some unknown reason, you may be thinking that messages should not
336 be renumbered.
337 Other methods
339 Extends "Other methods" in Mail::Box::Dir.
340 $obj->timespan2seconds($time)
342 Mail::Box::MH->timespan2seconds($time)
343 Inherited, see "Other methods" in Mail::Box
344 Error handling
346 Extends "Error handling" in Mail::Box::Dir.
347 $obj->AUTOLOAD()
349 Inherited, see "Error handling" in Mail::Reporter
350 $obj->addReport($object)
352 Inherited, see "Error handling" in Mail::Reporter
353 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
355 $callback] )
356 Mail::Box::MH->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
357 $callback] )
358 Inherited, see "Error handling" in Mail::Reporter
359 $obj->errors()
361 Inherited, see "Error handling" in Mail::Reporter
362 $obj->log( [$level, [$strings]] )
364 Mail::Box::MH->log( [$level, [$strings]] )
365 Inherited, see "Error handling" in Mail::Reporter
366 $obj->logPriority($level)
368 Mail::Box::MH->logPriority($level)
369 Inherited, see "Error handling" in Mail::Reporter
370 $obj->logSettings()
372 Inherited, see "Error handling" in Mail::Reporter
373 $obj->notImplemented()
375 Inherited, see "Error handling" in Mail::Reporter
376 $obj->report( [$level] )
378 Inherited, see "Error handling" in Mail::Reporter
379 $obj->reportAll( [$level] )
381 Inherited, see "Error handling" in Mail::Reporter
382 $obj->trace( [$level] )
384 Inherited, see "Error handling" in Mail::Reporter
385 $obj->warnings()
387 Inherited, see "Error handling" in Mail::Reporter
388 Cleanup
390 Extends "Cleanup" in Mail::Box::Dir.
391 $obj->DESTROY()
393 Inherited, see "Cleanup" in Mail::Box
394
396 Extends "DETAILS" in Mail::Box::Dir.
397 Different kinds of folders
399 Extends "Different kinds of folders" in Mail::Box::Dir.
400 Available folder types
402 Extends "Available folder types" in Mail::Box::Dir.
403 Folder class implementation
405 Extends "Folder class implementation" in Mail::Box::Dir.
406 How MH folders work
408 MH-type folders use a directory to store the messages of one folder.
409 Each message is stored in a separate file. This seems useful, because
410 changes in a folder change only a few of these small files, in contrast
411 with file-based folders where changes in a folder cause rewrites of
412 huge folder files.
413 However, MH-based folders perform very bad if you need header
415 information of all messages. For instance, if you want to have full
416 knowledge about all message-threads (see Mail::Box::Thread::Manager) in
417 the folder, it requires to read all header lines in all message files.
418 And usually, reading your messages in threads is desired.
419 So, each message is written in a separate file. The filenames are
421 numbers, which count from 1. Next to these message files, a directory
422 may contain a file named ".mh_sequences", storing labels which relate
423 to the messages. Furthermore, a folder-directory may contain sub-
424 directories, which are seen as sub-folders.
425 This implementation
427 This implementation supports the ".mh-sequences" file and sub-folders.
428 Next to this, considerable effort it made to avoid reading each
429 message-file. This should boost performance of the MailBox
430 distribution over other Perl-modules which are able to read folders.
431 Folder types which store their messages each in one file, together in
433 one directory, are bad for performance. Consider that you want to know
434 the subjects of all messages, while browser through a folder with your
435 mail-reading client. This would cause all message-files to be read.
436 Mail::Box::MH has two ways to try improve performance. You can use an
438 index-file, and use on delay-loading. The combination performs even
439 better. Both are explained in the next sections.
440 An index-file
442 If you specify new(keep_index), then all header-lines of all messages
443 from the folder which have been read once, will also be written into
444 one dedicated index-file (one file per folder). The default filename
445 is ".index"
446 However, index-files are not supported by any other reader which
448 supports MH (as far as I know). If you read the folders with such I
449 client, it will not cause unrecoverable conflicts with this index-file,
450 but at most be bad for performance.
451 If you do not (want to) use an index-file, then delay-loading may save
453 your day.
454
456 Error: Cannot append message without lock on $folder.
457 It is impossible to append one or more messages to the folder which
458 is not opened, because locking it failes. The folder may be in use
459 by an other application, or you may need to specify some lock
460 related options (see new()).
461 Error: Cannot create MH folder $name: $!
463 For some reason, it is impossible to create the folder. Check the
464 permissions and the name of the folder. Does the path to the
465 directory to be created exist?
466 Error: Cannot write folder $name without lock.
468 It is impossible to get a lock on the folder, which means that the
469 changes can not be made. You may need to tune the lock related
470 options which are available at folder creation.
471 Warning: Changes not written to read-only folder $self.
473 You have opened the folder read-only --which is the default set by
474 new(access)--, made modifications, and now want to close it. Set
475 close(force) if you want to overrule the access mode, or close the
476 folder with close(write) set to "NEVER".
477 Error: Copying failed for one message.
479 For some reason, for instance disc full, removed by external
480 process, or read-protection, it is impossible to copy one of the
481 messages. Copying will proceed for the other messages.
482 Error: Destination folder $name is not writable.
484 The folder where the messages are copied to is not opened with
485 write access (see new(access)). This has no relation with write
486 permission to the folder which is controlled by your operating
487 system.
488 Warning: Different messages with id $msgid
490 The message id is discovered more than once within the same folder,
491 but the content of the message seems to be different. This should
492 not be possible: each message must be unique.
493 Error: Folder $name is opened read-only
495 You can not write to this folder unless you have opened the folder
496 to write or append with new(access), or the "force" option is set
497 true.
498 Error: Folder $name not deleted: not writable.
500 The folder must be opened with write access via new(access),
501 otherwise removing it will be refused. So, you may have write-
502 access according to the operating system, but that will not
503 automatically mean that this "delete" method permits you to. The
504 reverse remark is valid as well.
505 Error: Invalid timespan '$timespan' specified.
507 The string does not follow the strict rules of the time span syntax
508 which is permitted as parameter.
509 Warning: Message-id '$msgid' does not contain a domain.
511 According to the RFCs, message-ids need to contain a unique random
512 part, then an "@", and then a domain name. This is made to avoid
513 the creation of two messages with the same id. The warning emerges
514 when the "@" is missing from the string.
515 Error: Package $package does not implement $method.
517 Fatal error: the specific package (or one of its superclasses) does
518 not implement this method where it should. This message means that
519 some other related classes do implement this method however the
520 class at hand does not. Probably you should investigate this and
521 probably inform the author of the package.
522 Error: Unable to create subfolder $name of $folder.
524 The copy includes the subfolders, but for some reason it was not
525 possible to copy one of these. Copying will proceed for all other
526 sub-folders.
527 Error: Unable to write message for $folder to $filename: $!
529 The new message could not be written to its new file, for the
530 specific reason.
531 Error: Writing folder $name failed
533 For some reason (you probably got more error messages about this
534 problem) it is impossible to write the folder, although you should
535 because there were changes made.
536
538 This module is part of Mail-Box distribution version 3.005, built on
539 March 04, 2018. Website: http://perl.overmeer.net/CPAN/
540
542 Copyrights 2001-2018 by [Mark Overmeer]. For other contributors see
543 ChangeLog.
544 This program is free software; you can redistribute it and/or modify it
546 under the same terms as Perl itself. See http://dev.perl.org/licenses/
547perl v5.28.0 2018-03-04 Mail::Box::MH(3)