1Mail::Box::MH(3)      User Contributed Perl Documentation     Mail::Box::MH(3)
2
3
4

NAME

6       Mail::Box::MH - handle MH folders
7

INHERITANCE

9        Mail::Box::MH
10          is a Mail::Box::Dir
11          is a Mail::Box
12          is a Mail::Reporter
13

SYNOPSIS

15        use Mail::Box::MH;
16        my $folder = new Mail::Box::MH folder => $ENV{MAIL}, ...;
17

DESCRIPTION

19       This documentation describes how MH mailboxes work, and what you can do
20       with the MH folder object "Mail::Box::MH".
21
22       Extends "DESCRIPTION" in Mail::Box::Dir.
23

OVERLOADED

25       Extends "OVERLOADED" in Mail::Box::Dir.
26
27       overload: ""
28           Inherited, see "OVERLOADED" in Mail::Box
29
30       overload: @{}
31           Inherited, see "OVERLOADED" in Mail::Box
32
33       overload: cmp
34           Inherited, see "OVERLOADED" in Mail::Box
35

METHODS

37       Extends "METHODS" in Mail::Box::Dir.
38
39   Constructors
40       Extends "Constructors" in Mail::Box::Dir.
41
42       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
79           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
98           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
104           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
115           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
121           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
127           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
142   The folder
143       Extends "The folder" in Mail::Box::Dir.
144
145       $obj->addMessage($message, %options)
146           Inherited, see "The folder" in Mail::Box
147
148       $obj->addMessages(@messages)
149           Inherited, see "The folder" in Mail::Box
150
151       Mail::Box::MH->appendMessages(%options)
152           Append a message to a folder which is not open.
153
154            -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
160           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
167       $obj->copyTo($folder, %options)
168           Inherited, see "The folder" in Mail::Box
169
170       $obj->delete(%options)
171           Inherited, see "The folder" in Mail::Box
172
173       $obj->directory()
174           Inherited, see "The folder" in Mail::Box::Dir
175
176       $obj->folderdir( [$directory] )
177           Inherited, see "The folder" in Mail::Box
178
179       $obj->name()
180           Inherited, see "The folder" in Mail::Box
181
182       $obj->organization()
183           Inherited, see "The folder" in Mail::Box
184
185       $obj->size()
186           Inherited, see "The folder" in Mail::Box
187
188       $obj->type()
189           Inherited, see "The folder" in Mail::Box
190
191       $obj->update(%options)
192           Inherited, see "The folder" in Mail::Box
193
194       $obj->url()
195           Inherited, see "The folder" in Mail::Box
196
197   Folder flags
198       Extends "Folder flags" in Mail::Box::Dir.
199
200       $obj->access()
201           Inherited, see "Folder flags" in Mail::Box
202
203       $obj->isModified()
204           Inherited, see "Folder flags" in Mail::Box
205
206       $obj->modified( [BOOLEAN] )
207           Inherited, see "Folder flags" in Mail::Box
208
209       $obj->writable()
210           Inherited, see "Folder flags" in Mail::Box
211
212   The messages
213       Extends "The messages" in Mail::Box::Dir.
214
215       $obj->current( [$number|$message|$message_id] )
216           Inherited, see "The messages" in Mail::Box
217
218       $obj->find($message_id)
219           Inherited, see "The messages" in Mail::Box
220
221       $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
222           Inherited, see "The messages" in Mail::Box
223
224       $obj->message( $index, [$message] )
225           Inherited, see "The messages" in Mail::Box
226
227       $obj->messageId( $message_id, [$message] )
228           Inherited, see "The messages" in Mail::Box
229
230       $obj->messageIds()
231           Inherited, see "The messages" in Mail::Box
232
233       $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
234       !$label|$filter> )
235           Inherited, see "The messages" in Mail::Box
236
237       $obj->nrMessages(%options)
238           Inherited, see "The messages" in Mail::Box
239
240       $obj->scanForMessages($message, $message_ids, $timespan, $window)
241           Inherited, see "The messages" in Mail::Box
242
243   Sub-folders
244       Extends "Sub-folders" in Mail::Box::Dir.
245
246       $obj->listSubFolders(%options)
247       Mail::Box::MH->listSubFolders(%options)
248           Inherited, see "Sub-folders" in Mail::Box
249
250       $obj->nameOfSubFolder( $subname, [$parentname] )
251       Mail::Box::MH->nameOfSubFolder( $subname, [$parentname] )
252           Inherited, see "Sub-folders" in Mail::Box
253
254       $obj->openRelatedFolder(%options)
255           Inherited, see "Sub-folders" in Mail::Box
256
257       $obj->openSubFolder($subname, %options)
258           Inherited, see "Sub-folders" in Mail::Box
259
260       $obj->topFolderWithMessages()
261       Mail::Box::MH->topFolderWithMessages()
262           Inherited, see "Sub-folders" in Mail::Box
263
264   Internals
265       Extends "Internals" in Mail::Box::Dir.
266
267       $obj->coerce($message, %options)
268           Inherited, see "Internals" in Mail::Box
269
270       $obj->create($foldername, %options)
271       Mail::Box::MH->create($foldername, %options)
272            -Option   --Defined in--Default
273             folderdir  Mail::Box   undef
274
275           folderdir => DIRECTORY
276       $obj->determineBodyType($message, $head)
277           Inherited, see "Internals" in Mail::Box
278
279       $obj->folderToDirectory($foldername, $folderdir)
280           Inherited, see "Internals" in Mail::Box::Dir
281
282       Mail::Box::MH->foundIn( [$foldername], %options )
283           Inherited, see "Internals" in Mail::Box
284
285       $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
291       $obj->index()
292           Create a index reader/writer object.
293
294       $obj->labels()
295           Create a label reader/writer object.
296
297       $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
298           Inherited, see "Internals" in Mail::Box
299
300       $obj->locker()
301           Inherited, see "Internals" in Mail::Box
302
303       $obj->messageInFile($filename)
304           Inherited, see "Internals" in Mail::Box::Dir
305
306       $obj->read(%options)
307           Inherited, see "Internals" in Mail::Box
308
309       $obj->readMessageFilenames($directory)
310           Inherited, see "Internals" in Mail::Box::Dir
311
312       $obj->readMessages(%options)
313           Inherited, see "Internals" in Mail::Box
314
315       $obj->storeMessage($message)
316           Inherited, see "Internals" in Mail::Box
317
318       $obj->toBeThreaded($messages)
319           Inherited, see "Internals" in Mail::Box
320
321       $obj->toBeUnthreaded($messages)
322           Inherited, see "Internals" in Mail::Box
323
324       $obj->updateMessages(%options)
325           Inherited, see "Internals" in Mail::Box
326
327       $obj->write(%options)
328           Inherited, see "Internals" in Mail::Box
329
330       $obj->writeMessages(%options)
331            -Option  --Defined in     --Default
332             messages  Mail::Box        <required>
333             renumber                   <true>
334
335           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
341   Other methods
342       Extends "Other methods" in Mail::Box::Dir.
343
344       $obj->timespan2seconds($time)
345       Mail::Box::MH->timespan2seconds($time)
346           Inherited, see "Other methods" in Mail::Box
347
348   Error handling
349       Extends "Error handling" in Mail::Box::Dir.
350
351       $obj->AUTOLOAD()
352           Inherited, see "Error handling" in Mail::Reporter
353
354       $obj->addReport($object)
355           Inherited, see "Error handling" in Mail::Reporter
356
357       $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
363       $obj->errors()
364           Inherited, see "Error handling" in Mail::Reporter
365
366       $obj->log( [$level, [$strings]] )
367       Mail::Box::MH->log( [$level, [$strings]] )
368           Inherited, see "Error handling" in Mail::Reporter
369
370       $obj->logPriority($level)
371       Mail::Box::MH->logPriority($level)
372           Inherited, see "Error handling" in Mail::Reporter
373
374       $obj->logSettings()
375           Inherited, see "Error handling" in Mail::Reporter
376
377       $obj->notImplemented()
378           Inherited, see "Error handling" in Mail::Reporter
379
380       $obj->report( [$level] )
381           Inherited, see "Error handling" in Mail::Reporter
382
383       $obj->reportAll( [$level] )
384           Inherited, see "Error handling" in Mail::Reporter
385
386       $obj->trace( [$level] )
387           Inherited, see "Error handling" in Mail::Reporter
388
389       $obj->warnings()
390           Inherited, see "Error handling" in Mail::Reporter
391
392   Cleanup
393       Extends "Cleanup" in Mail::Box::Dir.
394
395       $obj->DESTROY()
396           Inherited, see "Cleanup" in Mail::Box
397

DETAILS

399       Extends "DETAILS" in Mail::Box::Dir.
400
401   Different kinds of folders
402       Extends "Different kinds of folders" in Mail::Box::Dir.
403
404   Available folder types
405       Extends "Available folder types" in Mail::Box::Dir.
406
407   Folder class implementation
408       Extends "Folder class implementation" in Mail::Box::Dir.
409
410   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
417       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
423       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
429   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
435       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
440       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
444   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
450       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
455       If you do not (want to) use an index-file, then delay-loading may save
456       your day.
457

DIAGNOSTICS

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
465       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
470       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
475       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
481       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
486       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
492       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
497       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
502       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
509       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
513       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
519       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
526       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
531       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
535       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

SEE ALSO

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

LICENSE

545       Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
546       ChangeLog.
547
548       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/
550
551
552
553perl v5.36.0                      2022-07-22                  Mail::Box::MH(3)
Impressum