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
25 overload: @{}
27 See "OVERLOADED" in Mail::Box
28 overload: cmp
30 See "OVERLOADED" in Mail::Box
31
33 Constructors
34 Mail::Box::MH->new(OPTIONS)
35 -Option --Defined in --Default
36 access Mail::Box 'r'
37 body_delayed_type Mail::Box Mail::Message::Body::Delayed
38 body_type Mail::Box Mail::Message::Body::Lines
39 coerce_options Mail::Box []
40 create Mail::Box <false>
41 directory Mail::Box::Dir <derived from folder name>
42 extract Mail::Box 10240
43 field_type Mail::Box undef
44 fix_headers Mail::Box <false>
45 folder Mail::Box $ENV{MAIL}
46 folderdir Mail::Box $ENV{HOME}/.mh
47 head_delayed_type Mail::Box Mail::Message::Head::Delayed
48 head_type Mail::Box Mail::Message::Head::Complete
49 index undef
50 index_filename <foldername>/.index
51 index_type Mail::Box::MH::Index
52 keep_dups Mail::Box <false>
53 keep_index 0
54 labels undef
55 labels_filename <foldername>/.mh_sequence
56 labels_type Mail::Box::MH::Labels
57 lock_file Mail::Box <index_file>
58 lock_timeout Mail::Box 1 hour
59 lock_type Mail::Box Mail::Box::Locker::DotLock
60 lock_wait Mail::Box 10 seconds
61 locker Mail::Box undef
62 log Mail::Reporter 'WARNINGS'
63 manager Mail::Box undef
64 message_type Mail::Box Mail::Box::Message
65 multipart_type Mail::Box Mail::Message::Body::Multipart
66 remove_when_empty Mail::Box <true>
67 save_on_exit Mail::Box <true>
68 trace Mail::Reporter 'WARNINGS'
69 trusted Mail::Box <depends on folder location>
70 access => MODE
72 body_delayed_type => CLASS
73 body_type => CLASS|CODE
74 coerce_options => ARRAY
75 create => BOOLEAN
76 directory => DIRECTORY
77 extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
78 field_type => CLASS
79 fix_headers => BOOLEAN
80 folder => FOLDERNAME
81 folderdir => DIRECTORY
82 head_delayed_type => CLASS
83 head_type => CLASS
84 index => OBJECT
85 You may specify an OBJECT of a type which extends
86 Mail::Box::MH::Index (at least implements a "get()" method), as
87 alternative for an index file reader as created by
88 "Mail::Box::MH".
89 index_filename => FILENAME
91 The FILENAME which is used in each directory to store the headers
92 of all mails. The filename shall not contain a directory path.
93 (e.g. Do not use "/usr/people/jan/.index", nor "subdir/.index",
94 but say ".index".)
95 index_type => CLASS
97 keep_dups => BOOLEAN
98 keep_index => BOOLEAN
99 Keep an index file of the specified mailbox, one file per
100 directory. Using an index file will speed up things
101 considerably, because it avoids reading all the message files the
102 moment that you open the folder. When you open a folder, you can
103 use the index file to retrieve information such as the subject of
104 each message, instead of having to read possibly thousands of
105 messages.
106 labels => OBJECT
108 You may specify an OBJECT of a type which extends
109 Mail::Box::MH::Labels (at least implements the "get()" method),
110 as alternative for labels file reader as created by
111 "Mail::Box::MH".
112 labels_filename => FILENAME
114 In MH-folders, messages can be labeled, for instance based on the
115 sender or whether it is read or not. This status is kept in a
116 file which is usually called ".mh_sequences", but that name can
117 be overruled with this flag.
118 labels_type => CLASS
120 lock_file => FILENAME
121 lock_timeout => SECONDS
122 lock_type => CLASS|STRING|ARRAY
123 lock_wait => SECONDS
124 locker => OBJECT
125 log => LEVEL
126 manager => MANAGER
127 message_type => CLASS
128 multipart_type => CLASS
129 remove_when_empty => BOOLEAN
130 save_on_exit => BOOLEAN
131 trace => LEVEL
132 trusted => BOOLEAN
133 The folder
135 $obj->addMessage(MESSAGE, OPTIONS)
136 See "The folder" in Mail::Box
137 $obj->addMessages(MESSAGE [, MESSAGE, ...])
139 See "The folder" in Mail::Box
140 Mail::Box::MH->appendMessages(OPTIONS)
142 Append a message to a folder which is not open.
143 -Option --Defined in --Default
145 folder Mail::Box <required>
146 message Mail::Box undef
147 messages Mail::Box undef
148 share Mail::Box <false>
149 folder => FOLDERNAME
151 message => MESSAGE
152 messages => ARRAY-OF-MESSAGES
153 share => BOOLEAN
154 $obj->close(OPTIONS)
155 See "The folder" in Mail::Box
156 $obj->copyTo(FOLDER, OPTIONS)
158 See "The folder" in Mail::Box
159 $obj->delete(OPTIONS)
161 See "The folder" in Mail::Box
162 $obj->directory
164 See "The folder" in Mail::Box::Dir
165 $obj->folderdir([DIRECTORY])
167 See "The folder" in Mail::Box
168 $obj->name
170 See "The folder" in Mail::Box
171 $obj->organization
173 See "The folder" in Mail::Box
174 $obj->size
176 See "The folder" in Mail::Box
177 $obj->type
179 See "The folder" in Mail::Box
180 $obj->update(OPTIONS)
182 See "The folder" in Mail::Box
183 $obj->url
185 See "The folder" in Mail::Box
186 Folder flags
188 $obj->access
189 See "Folder flags" in Mail::Box
190 $obj->isModified
192 See "Folder flags" in Mail::Box
193 $obj->modified([BOOLEAN])
195 See "Folder flags" in Mail::Box
196 $obj->writable
198 See "Folder flags" in Mail::Box
199 The messages
201 $obj->current([NUMBER|MESSAGE|MESSAGE-ID])
202 See "The messages" in Mail::Box
203 $obj->find(MESSAGE-ID)
205 See "The messages" in Mail::Box
206 $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
208 See "The messages" in Mail::Box
209 $obj->message(INDEX [,MESSAGE])
211 See "The messages" in Mail::Box
212 $obj->messageId(MESSAGE-ID [,MESSAGE])
214 See "The messages" in Mail::Box
215 $obj->messageIds
217 See "The messages" in Mail::Box
218 $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
220 See "The messages" in Mail::Box
221 $obj->nrMessages(OPTIONS)
223 See "The messages" in Mail::Box
224 $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
226 See "The messages" in Mail::Box
227 Sub-folders
229 $obj->listSubFolders(OPTIONS)
230 Mail::Box::MH->listSubFolders(OPTIONS)
231 See "Sub-folders" in Mail::Box
233 $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
235 Mail::Box::MH->nameOfSubFolder(SUBNAME, [PARENTNAME])
236 See "Sub-folders" in Mail::Box
238 $obj->openRelatedFolder(OPTIONS)
240 See "Sub-folders" in Mail::Box
241 $obj->openSubFolder(SUBNAME, OPTIONS)
243 See "Sub-folders" in Mail::Box
244 $obj->topFolderWithMessages
246 Mail::Box::MH->topFolderWithMessages
247 See "Sub-folders" in Mail::Box
249 Internals
251 $obj->coerce(MESSAGE, OPTIONS)
252 See "Internals" in Mail::Box
253 $obj->create(FOLDERNAME, OPTIONS)
255 Mail::Box::MH->create(FOLDERNAME, OPTIONS)
256 -Option --Defined in--Default
258 folderdir Mail::Box undef
259 folderdir => DIRECTORY
261 $obj->determineBodyType(MESSAGE, HEAD)
262 See "Internals" in Mail::Box
263 $obj->folderToDirectory(FOLDERNAME, FOLDERDIR)
265 See "Internals" in Mail::Box::Dir
266 Mail::Box::MH->foundIn([FOLDERNAME], OPTIONS)
268 See "Internals" in Mail::Box
269 $obj->highestMessageNumber
271 Returns the highest number which is used in the folder to store a
272 file. This method may be called when the folder is read (then this
273 number can be derived without file-system access), but also when
274 the folder is not read (yet).
275 $obj->index
277 Create a index reader/writer object.
278 $obj->labels
280 Create a label reader/writer object.
281 $obj->lineSeparator([STRING|'CR'|'LF'|'CRLF'])
283 See "Internals" in Mail::Box
284 $obj->locker
286 See "Internals" in Mail::Box
287 $obj->read(OPTIONS)
289 See "Internals" in Mail::Box
290 $obj->readMessageFilenames(DIRECTORY)
292 See "Internals" in Mail::Box::Dir
293 $obj->readMessages(OPTIONS)
295 See "Internals" in Mail::Box
296 $obj->storeMessage(MESSAGE)
298 See "Internals" in Mail::Box
299 $obj->toBeThreaded(MESSAGES)
301 See "Internals" in Mail::Box
302 $obj->toBeUnthreaded(MESSAGES)
304 See "Internals" in Mail::Box
305 $obj->updateMessages(OPTIONS)
307 See "Internals" in Mail::Box
308 $obj->write(OPTIONS)
310 See "Internals" in Mail::Box
311 $obj->writeMessages(OPTIONS)
313 -Option --Defined in --Default
314 messages Mail::Box <required>
315 renumber <true>
316 messages => ARRAY
318 renumber => BOOLEAN
319 Permit renumbering of message. By default this is true, but for
320 some unknown reason, you may be thinking that messages should not
321 be renumbered.
322 Other methods
324 $obj->timespan2seconds(TIME)
325 Mail::Box::MH->timespan2seconds(TIME)
326 See "Other methods" in Mail::Box
328 Error handling
330 $obj->AUTOLOAD
331 See "Error handling" in Mail::Reporter
332 $obj->addReport(OBJECT)
334 See "Error handling" in Mail::Reporter
335 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
337 Mail::Box::MH->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL,
338 CALLBACK])
339 See "Error handling" in Mail::Reporter
341 $obj->errors
343 See "Error handling" in Mail::Reporter
344 $obj->log([LEVEL [,STRINGS]])
346 Mail::Box::MH->log([LEVEL [,STRINGS]])
347 See "Error handling" in Mail::Reporter
349 $obj->logPriority(LEVEL)
351 Mail::Box::MH->logPriority(LEVEL)
352 See "Error handling" in Mail::Reporter
354 $obj->logSettings
356 See "Error handling" in Mail::Reporter
357 $obj->notImplemented
359 See "Error handling" in Mail::Reporter
360 $obj->report([LEVEL])
362 See "Error handling" in Mail::Reporter
363 $obj->reportAll([LEVEL])
365 See "Error handling" in Mail::Reporter
366 $obj->trace([LEVEL])
368 See "Error handling" in Mail::Reporter
369 $obj->warnings
371 See "Error handling" in Mail::Reporter
372 Cleanup
374 $obj->DESTROY
375 See "Cleanup" in Mail::Box
376 $obj->inGlobalDestruction
378 See "Cleanup" in Mail::Reporter
379
381 Different kinds of folders
382 Available folder types
383 Folder class implementation
384 How MH folders work
385 MH-type folders use a directory to store the messages of one folder.
386 Each message is stored in a separate file. This seems useful, because
387 changes in a folder change only a few of these small files, in contrast
388 with file-based folders where changes in a folder cause rewrites of
389 huge folder files.
390 However, MH-based folders perform very bad if you need header
392 information of all messages. For instance, if you want to have full
393 knowledge about all message-threads (see Mail::Box::Thread::Manager) in
394 the folder, it requires to read all header lines in all message files.
395 And usually, reading your messages in threads is desired.
396 So, each message is written in a separate file. The filenames are
398 numbers, which count from 1. Next to these message files, a directory
399 may contain a file named ".mh_sequences", storing labels which relate
400 to the messages. Furthermore, a folder-directory may contain sub-
401 directories, which are seen as sub-folders.
402 This implementation
404 This implementation supports the ".mh-sequences" file and sub-folders.
405 Next to this, considerable effort it made to avoid reading each
406 message-file. This should boost performance of the MailBox
407 distribution over other Perl-modules which are able to read folders.
408 Folder types which store their messages each in one file, together in
410 one directory, are bad for performance. Consider that you want to know
411 the subjects of all messages, while browser through a folder with your
412 mail-reading client. This would cause all message-files to be read.
413 Mail::Box::MH has two ways to try improve performance. You can use an
415 index-file, and use on delay-loading. The combination performs even
416 better. Both are explained in the next sections.
417 An index-file
419 If you specify new(keep_index), then all header-lines of all messages
420 from the folder which have been read once, will also be written into
421 one dedicated index-file (one file per folder). The default filename
422 is ".index"
423 However, index-files are not supported by any other reader which
425 supports MH (as far as I know). If you read the folders with such I
426 client, it will not cause unrecoverable conflicts with this index-file,
427 but at most be bad for performance.
428 If you do not (want to) use an index-file, then delay-loading may save
430 your day.
431
433 Error: Cannot append message without lock on $folder.
434 It is impossible to append one or more messages to the folder which
435 is not opened, because locking it failes. The folder may be in use
436 by an other application, or you may need to specify some lock
437 related options (see new()).
438 Error: Cannot create MH folder $name: $!
440 For some reason, it is impossible to create the folder. Check the
441 permissions and the name of the folder. Does the path to the
442 directory to be created exist?
443 Error: Cannot write folder $name without lock.
445 It is impossible to get a lock on the folder, which means that the
446 changes can not be made. You may need to tune the lock related
447 options which are available at folder creation.
448 Warning: Changes not written to read-only folder $self.
450 You have opened the folder read-only --which is the default set by
451 new(access)--, made modifications, and now want to close it. Set
452 close(force) if you want to overrule the access mode, or close the
453 folder with close(write) set to "NEVER".
454 Error: Copying failed for one message.
456 For some reason, for instance disc full, removed by external
457 process, or read-protection, it is impossible to copy one of the
458 messages. Copying will proceed for the other messages.
459 Error: Destination folder $name is not writable.
461 The folder where the messages are copied to is not opened with
462 write access (see new(access)). This has no relation with write
463 permission to the folder which is controled by your operating
464 system.
465 Warning: Different messages with id $msgid
467 The message id is discovered more than once within the same folder,
468 but the content of the message seems to be different. This should
469 not be possible: each message must be unique.
470 Error: Folder $name is opened read-only
472 You can not write to this folder unless you have opened the folder
473 to write or append with new(access), or the "force" option is set
474 true.
475 Error: Folder $name not deleted: not writable.
477 The folder must be opened with write access via new(access),
478 otherwise removing it will be refused. So, you may have write-
479 access according to the operating system, but that will not
480 automatically mean that this "delete" method permits you to. The
481 reverse remark is valid as well.
482 Error: Invalid timespan '$timespan' specified.
484 The string does not follow the strict rules of the time span syntax
485 which is permitted as parameter.
486 Warning: Message-id '$msgid' does not contain a domain.
488 According to the RFCs, message-ids need to contain a unique random
489 part, then an "@", and then a domain name. This is made to avoid
490 the creation of two messages with the same id. The warning emerges
491 when the "@" is missing from the string.
492 Error: Package $package does not implement $method.
494 Fatal error: the specific package (or one of its superclasses) does
495 not implement this method where it should. This message means that
496 some other related classes do implement this method however the
497 class at hand does not. Probably you should investigate this and
498 probably inform the author of the package.
499 Error: Unable to create subfolder $name of $folder.
501 The copy includes the subfolders, but for some reason it was not
502 possible to copy one of these. Copying will proceed for all other
503 sub-folders.
504 Error: Unable to write message for $folder to $filename: $!
506 The new message could not be written to its new file, for the
507 specific reason.
508 Error: Writing folder $name failed
510 For some reason (you probably got more error messages about this
511 problem) it is impossible to write the folder, although you should
512 because there were changes made.
513
515 This module is part of Mail-Box distribution version 2.097, built on
516 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
517
519 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
520 ChangeLog.
521 This program is free software; you can redistribute it and/or modify it
523 under the same terms as Perl itself. See
524 http://www.perl.com/perl/misc/Artistic.html
525perl v5.12.3 2011-01-26 Mail::Box::MH(3)