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

DETAILS

398       Extends "DETAILS" in Mail::Box::Dir.
399
400   Different kinds of folders
401       Extends "Different kinds of folders" in Mail::Box::Dir.
402
403   Available folder types
404       Extends "Available folder types" in Mail::Box::Dir.
405
406   Folder class implementation
407       Extends "Folder class implementation" in Mail::Box::Dir.
408
409   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
416       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
422       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
428   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
434       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
439       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
443   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
449       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
454       If you do not (want to) use an index-file, then delay-loading may save
455       your day.
456

DIAGNOSTICS

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
464       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
469       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
474       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
480       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
485       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
491       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
496       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
501       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
508       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
512       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
518       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
525       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
530       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
534       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

SEE ALSO

540       This module is part of Mail-Box distribution version 3.009, built on
541       August 18, 2020. Website: http://perl.overmeer.net/CPAN/
542

LICENSE

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