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->read(%options)
304           Inherited, see "Internals" in Mail::Box
305
306       $obj->readMessageFilenames($directory)
307           Inherited, see "Internals" in Mail::Box::Dir
308
309       $obj->readMessages(%options)
310           Inherited, see "Internals" in Mail::Box
311
312       $obj->storeMessage($message)
313           Inherited, see "Internals" in Mail::Box
314
315       $obj->toBeThreaded($messages)
316           Inherited, see "Internals" in Mail::Box
317
318       $obj->toBeUnthreaded($messages)
319           Inherited, see "Internals" in Mail::Box
320
321       $obj->updateMessages(%options)
322           Inherited, see "Internals" in Mail::Box
323
324       $obj->write(%options)
325           Inherited, see "Internals" in Mail::Box
326
327       $obj->writeMessages(%options)
328            -Option  --Defined in     --Default
329             messages  Mail::Box        <required>
330             renumber                   <true>
331
332           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
338   Other methods
339       Extends "Other methods" in Mail::Box::Dir.
340
341       $obj->timespan2seconds($time)
342       Mail::Box::MH->timespan2seconds($time)
343           Inherited, see "Other methods" in Mail::Box
344
345   Error handling
346       Extends "Error handling" in Mail::Box::Dir.
347
348       $obj->AUTOLOAD()
349           Inherited, see "Error handling" in Mail::Reporter
350
351       $obj->addReport($object)
352           Inherited, see "Error handling" in Mail::Reporter
353
354       $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
360       $obj->errors()
361           Inherited, see "Error handling" in Mail::Reporter
362
363       $obj->log( [$level, [$strings]] )
364       Mail::Box::MH->log( [$level, [$strings]] )
365           Inherited, see "Error handling" in Mail::Reporter
366
367       $obj->logPriority($level)
368       Mail::Box::MH->logPriority($level)
369           Inherited, see "Error handling" in Mail::Reporter
370
371       $obj->logSettings()
372           Inherited, see "Error handling" in Mail::Reporter
373
374       $obj->notImplemented()
375           Inherited, see "Error handling" in Mail::Reporter
376
377       $obj->report( [$level] )
378           Inherited, see "Error handling" in Mail::Reporter
379
380       $obj->reportAll( [$level] )
381           Inherited, see "Error handling" in Mail::Reporter
382
383       $obj->trace( [$level] )
384           Inherited, see "Error handling" in Mail::Reporter
385
386       $obj->warnings()
387           Inherited, see "Error handling" in Mail::Reporter
388
389   Cleanup
390       Extends "Cleanup" in Mail::Box::Dir.
391
392       $obj->DESTROY()
393           Inherited, see "Cleanup" in Mail::Box
394

DETAILS

396       Extends "DETAILS" in Mail::Box::Dir.
397
398   Different kinds of folders
399       Extends "Different kinds of folders" in Mail::Box::Dir.
400
401   Available folder types
402       Extends "Available folder types" in Mail::Box::Dir.
403
404   Folder class implementation
405       Extends "Folder class implementation" in Mail::Box::Dir.
406
407   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
414       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
420       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
426   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
432       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
437       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
441   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
447       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
452       If you do not (want to) use an index-file, then delay-loading may save
453       your day.
454

DIAGNOSTICS

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
462       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
467       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
472       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
478       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
483       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
489       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
494       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
499       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
506       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
510       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
516       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
523       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
528       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
532       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

SEE ALSO

538       This module is part of Mail-Box distribution version 3.006, built on
539       February 15, 2019. Website: http://perl.overmeer.net/CPAN/
540

LICENSE

542       Copyrights 2001-2019 by [Mark Overmeer]. For other contributors see
543       ChangeLog.
544
545       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/
547
548
549
550perl v5.28.1                      2019-02-15                  Mail::Box::MH(3)
Impressum