Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Apropos / Subsearch:
optional field

Mail::Box::MH(3pm)    User Contributed Perl Documentation   Mail::Box::MH(3pm)

       Mail::Box::MH - handle MH folders

          is a Mail::Box::Dir
          is a Mail::Box
          is a Mail::Reporter

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

       This documentation describes how MH mailboxes work, and what you can do
       with the MH folder object "Mail::Box::MH".

       overload: ""

           See "OVERLOADED" in Mail::Box

       overload: @{}

           See "OVERLOADED" in Mail::Box

       overload: cmp

           See "OVERLOADED" in Mail::Box



        Option           --Defined in     --Default
        access             Mail::Box        'r'
        body_delayed_type  Mail::Box        Mail::Message::Body::Delayed
        body_type          Mail::Box        Mail::Message::Body::Lines
        coerce_options     Mail::Box        []
        create             Mail::Box        <false>
        directory          Mail::Box::Dir   <derived from folder name>
        extract            Mail::Box        10240
        field_type         Mail::Box        undef
        fix_headers        Mail::Box        <false>
        folder             Mail::Box        $ENV{MAIL}
        folderdir          Mail::Box        $ENV{HOME}/.mh
        head_delayed_type  Mail::Box        Mail::Message::Head::Delayed
        head_type          Mail::Box        Mail::Message::Head::Complete
        index                               undef
        index_filename                      <foldername>/.index
        index_type                          Mail::Box::MH::Index
        keep_dups          Mail::Box        <false>
        keep_index                          0
        labels                              undef
        labels_filename                     <foldername>/.mh_sequence
        labels_type                         Mail::Box::MH::Labels
        lock_file          Mail::Box        <index_file>
        lock_timeout       Mail::Box        1 hour
        lock_type          Mail::Box        Mail::Box::Locker::DotLock
        lock_wait          Mail::Box        10 seconds
        locker             Mail::Box        undef
        log                Mail::Reporter   'WARNINGS'
        manager            Mail::Box        undef
        message_type       Mail::Box        Mail::Box::Message
        multipart_type     Mail::Box        Mail::Message::Body::Multipart
        remove_when_empty  Mail::Box        <true>
        save_on_exit       Mail::Box        <true>
        trace              Mail::Reporter   'WARNINGS'
        trusted            Mail::Box        <depends on folder location>

           . access => MODE

           . body_delayed_type => CLASS

           . body_type => CLASS|CODE

           . coerce_options => ARRAY

           . create => BOOLEAN

           . directory => DIRECTORY

           . extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'

           . field_type => CLASS

           . fix_headers => BOOLEAN

           . folder => FOLDERNAME

           . folderdir => DIRECTORY

           . head_delayed_type => CLASS

           . head_type => CLASS

           . index => OBJECT

               You may specify an OBJECT of a type which extends
               Mail::Box::MH::Index (at least implements a "get()" method), as
               alternative for an index file reader as created by

           . index_filename => FILENAME

               The FILENAME which is used in each directory to store the
               headers of all mails. The filename shall not contain a
               directory path. (e.g. Do not use "/usr/people/jan/.index", nor
               "subdir/.index", but say ".index".)

           . index_type => CLASS

           . keep_dups => BOOLEAN

           . keep_index => BOOLEAN

               Keep an index file of the specified mailbox, one file per
               directory.  Using an index file will speed up things
               considerably, because it avoids reading all the message files
               the moment that you open the folder.  When you open a folder,
               you can use the index file to retrieve information such as the
               subject of each message, instead of having to read possibly
               thousands of messages.

           . labels => OBJECT

               You may specify an OBJECT of a type which extends
               Mail::Box::MH::Labels (at least implements the "get()" method),
               as alternative for labels file reader as created by

           . labels_filename => FILENAME

               In MH-folders, messages can be labeled, for instance based on
               the sender or whether it is read or not.  This status is kept
               in a file which is usually called ".mh_sequences", but that
               name can be overruled with this flag.

           . labels_type => CLASS

           . lock_file => FILENAME

           . lock_timeout => SECONDS

           . lock_type => CLASS|STRING|ARRAY

           . lock_wait => SECONDS

           . locker => OBJECT

           . log => LEVEL

           . manager => MANAGER

           . message_type => CLASS

           . multipart_type => CLASS

           . remove_when_empty => BOOLEAN

           . save_on_exit => BOOLEAN

           . trace => LEVEL

           . trusted => BOOLEAN

       The folder

       $obj->addMessage(MESSAGE, OPTIONS)

           See "The folder" in Mail::Box

       $obj->addMessages(MESSAGE [, MESSAGE, ...])

           See "The folder" in Mail::Box


           Append a message to a folder which is not open.

            Option  --Defined in     --Default
            folder    Mail::Box        <required>
            message   Mail::Box        undef
            messages  Mail::Box        undef
            share     Mail::Box        <false>

           . folder => FOLDERNAME

           . message => MESSAGE

           . messages => ARRAY-OF-MESSAGES

           . share => BOOLEAN


           See "The folder" in Mail::Box

       $obj->copyTo(FOLDER, OPTIONS)

           See "The folder" in Mail::Box


           See "The folder" in Mail::Box


           See "The folder" in Mail::Box::Dir


           See "The folder" in Mail::Box


           See "The folder" in Mail::Box


           See "The folder" in Mail::Box


           See "The folder" in Mail::Box


           See "The folder" in Mail::Box


           See "The folder" in Mail::Box


           See "The folder" in Mail::Box

       Folder flags


           See "Folder flags" in Mail::Box


           See "Folder flags" in Mail::Box


           See "Folder flags" in Mail::Box


           See "Folder flags" in Mail::Box

       The messages


           See "The messages" in Mail::Box


           See "The messages" in Mail::Box

       $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])

           See "The messages" in Mail::Box

       $obj->message(INDEX [,MESSAGE])

           See "The messages" in Mail::Box

       $obj->messageId(MESSAGE-ID [,MESSAGE])

           See "The messages" in Mail::Box


           See "The messages" in Mail::Box


           See "The messages" in Mail::Box


           See "The messages" in Mail::Box

       $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)

           See "The messages" in Mail::Box




           See "Sub-folders" in Mail::Box

       $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])

       Mail::Box::MH->nameOfSubFolder(SUBNAME, [PARENTNAME])

           See "Sub-folders" in Mail::Box


           See "Sub-folders" in Mail::Box

       $obj->openSubFolder(SUBNAME, OPTIONS)

           See "Sub-folders" in Mail::Box



           See "Sub-folders" in Mail::Box


       $obj->coerce(MESSAGE, OPTIONS)

           See "Internals" in Mail::Box

       $obj->create(FOLDERNAME, OPTIONS)

       Mail::Box::MH->create(FOLDERNAME, OPTIONS)

        Option   --Defined in--Default
        folderdir  Mail::Box   undef

           . folderdir => DIRECTORY

       $obj->determineBodyType(MESSAGE, HEAD)

           See "Internals" in Mail::Box

       $obj->folderToDirectory(FOLDERNAME, FOLDERDIR)

           See "Internals" in Mail::Box::Dir

       Mail::Box::MH->foundIn([FOLDERNAME], OPTIONS)

           See "Internals" in Mail::Box


           Returns the highest number which is used in the folder to store a
           file.  This method may be called when the folder is read (then this
           number can be derived without file-system access), but also when
           the folder is not read (yet).


           Create a index reader/writer object.


           Create a label reader/writer object.


           See "Internals" in Mail::Box


           See "Internals" in Mail::Box


           See "Internals" in Mail::Box


           See "Internals" in Mail::Box::Dir


           See "Internals" in Mail::Box


           See "Internals" in Mail::Box


           See "Internals" in Mail::Box


           See "Internals" in Mail::Box


           See "Internals" in Mail::Box


           See "Internals" in Mail::Box


        Option  --Defined in     --Default
        messages  Mail::Box        <required>
        renumber                   <true>

           . messages => ARRAY

           . renumber => BOOLEAN

               Permit renumbering of message.  By default this is true, but
               for some unknown reason, you may be thinking that messages
               should not be renumbered.

       Other methods



           See "Other methods" in Mail::Box

       Error handling


           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter

       $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])

       Mail::Box::MH->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL,

           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter

       $obj->log([LEVEL [,STRINGS]])

       Mail::Box::MH->log([LEVEL [,STRINGS]])

           See "Error handling" in Mail::Reporter



           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter



           See "Cleanup" in Mail::Box


           See "Cleanup" in Mail::Reporter

       How MH folders work

       MH-type folders use a directory to store the messages of one folder.
       Each message is stored in a separate file.  This seems useful, because
       changes in a folder change only a few of these small files, in contrast
       with file-based folders where changes in a folder cause rewrites of
       huge folder files.

       However, MH-based folders perform very bad if you need header
       information of all messages.  For instance, if you want to have full
       knowledge about all message-threads (see Mail::Box::Thread::Manager) in
       the folder, it requires to read all header lines in all message files.
       And usually, reading your messages in threads is desired.

       So, each message is written in a separate file.  The filenames are
       numbers, which count from 1.  Next to these message files, a directory
       may contain a file named ".mh_sequences", storing labels which relate
       to the messages.  Furthermore, a folder-directory may contain sub-
       directories, which are seen as sub-folders.

       This implementation

       This implementation supports the ".mh-sequences" file and sub-folders.
       Next to this, considerable effort it made to avoid reading each
       message-file.  This should boost performance of the MailBox
       distribution over other Perl-modules which are able to read folders.

       Folder types which store their messages each in one file, together in
       one directory, are bad for performance.  Consider that you want to know
       the subjects of all messages, while browser through a folder with your
       mail-reading client.  This would cause all message-files to be read.

       Mail::Box::MH has two ways to try improve performance.  You can use an
       index-file, and use on delay-loading.  The combination performs even
       better.  Both are explained in the next sections.

       An index-file

       If you specify new(keep_index), then all header-lines of all messages
       from the folder which have been read once, will also be written into
       one dedicated index-file (one file per folder).  The default filename
       is ".index"

       However, index-files are not supported by any other reader which
       supports MH (as far as I know).  If you read the folders with such I
       client, it will not cause unrecoverable conflicts with this index-file,
       but at most be bad for performance.

       If you do not (want to) use an index-file, then delay-loading may save
       your day.

       Error: Cannot append message without lock on $folder.

           It is impossible to append one or more messages to the folder which
           is not opened, because locking it failes.  The folder may be in use
           by an other application, or you may need to specify some lock
           related options (see new()).

       Error: Cannot create MH folder $name: $!

           For some reason, it is impossible to create the folder.  Check the
           permissions and the name of the folder.  Does the path to the
           directory to be created exist?

       Error: Cannot write folder $name without lock.

           It is impossible to get a lock on the folder, which means that the
           changes can not be made.  You may need to tune the lock related
           options which are available at folder creation.

       Warning: Changes not written to read-only folder $self.

           You have opened the folder read-only --which is the default set by
           new(access)--, made modifications, and now want to close it.  Set
           close(force) if you want to overrule the access mode, or close the
           folder with close(write) set to "NEVER".

       Error: Copying failed for one message.

           For some reason, for instance disc full, removed by external
           process, or read-protection, it is impossible to copy one of the
           messages.  Copying will proceed for the other messages.

       Error: Destination folder $name is not writable.

           The folder where the messages are copied to is not opened with
           write access (see new(access)).  This has no relation with write
           permission to the folder which is controled by your operating

       Warning: Different messages with id $msgid

           The message id is discovered more than once within the same folder,
           but the content of the message seems to be different.  This should
           not be possible: each message must be unique.

       Error: Folder $name is opened read-only

           You can not write to this folder unless you have opened the folder
           to write or append with new(access), or the "force" option is set

       Error: Folder $name not deleted: not writable.

           The folder must be opened with write access via new(access),
           otherwise removing it will be refused.  So, you may have write-
           access according to the operating system, but that will not
           automatically mean that this "delete" method permits you to.  The
           reverse remark is valid as well.

       Error: Invalid timespan '$timespan' specified.

           The string does not follow the strict rules of the time span syntax
           which is permitted as parameter.

       Warning: Message-id '$msgid' does not contain a domain.

           According to the RFCs, message-ids need to contain a unique random
           part, then an "@", and then a domain name.  This is made to avoid
           the creation of two messages with the same id.  The warning emerges
           when the "@" is missing from the string.

       Error: Package $package does not implement $method.

           Fatal error: the specific package (or one of its superclasses) does
           not implement this method where it should. This message means that
           some other related classes do implement this method however the
           class at hand does not.  Probably you should investigate this and
           probably inform the author of the package.

       Error: Unable to create subfolder $name of $folder.

           The copy includes the subfolders, but for some reason it was not
           possible to copy one of these.  Copying will proceed for all other

       Error: Unable to write message for $folder to $filename: $!

           The new message could not be written to its new file, for the
           specific reason.

       Error: Writing folder $name failed

           For some reason (you probably got more error messages about this
           problem) it is impossible to write the folder, although you should
           because there were changes made.

       This module is part of Mail-Box distribution version 2.082, built on
       April 28, 2008. Website: http://perl.overmeer.net/mailbox/

       Copyrights 2001-2008 by Mark Overmeer. For other contributors see

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See

perl v5.10.0                      2008-04-28                Mail::Box::MH(3pm)