Box::MH::Index(3)

NAME
Mail::Box::MH::Index - keep index files for messages.

CLASS HIERARCHY
 Mail::Box::MH::Index
 is a Mail::Reporter

SYNOPSIS
 my $index = Mail::Box::MH::Index->new;
 $index->read(...)
 $index->write(...)

DESCRIPTION
Message folders which store their data in one single file per message are very inefficient for producing subject overviews and for computing message threads. The "Mail::Box::MH::Index" module is able to store and read a the headers of all messages in one file.

When "Mail::Box::MH::Index" functionality is enabled by specifying "keep_index" when opening a folder, the index file is automatically read. When the folder is closed, a new index file is created.

Special care is taken to avoid problems which occur when the user changes or removes message files without updating the index. If the index is not trustworthy it will not be used (costing some performance for the reader of the folder).

METHOD INDEX
Methods prefixed with an abbreviation are described in Mail::Reporter (MR).

The general methods for "Mail::Box::MH::Index" objects:

   MR errors                            MR report [LEVEL]
      get MSGFILE                       MR reportAll [LEVEL]
   MR log [LEVEL [,STRINGS]]            MR trace [LEVEL]
      new OPTIONS                       MR warnings
      read                                 write MESSAGES

The extra methods for extension writers:

   MR AUTOLOAD                          MR logPriority LEVEL
   MR DESTROY                           MR logSettings
      filename                          MR notImplemented
   MR inGlobalDestruction

METHODS

new OPTIONS
    This method is called by folder classes, and should not be called by client programs, unless you really know what you are doing.

     OPTION      DEFINED BY             DEFAULT
     filename    Mail::Box::MH::Index   <obligatory>
     log         Mail::Reporter         'WARNINGS'
     trace       Mail::Reporter         'WARNINGS'
     head_wrap   Mail::Box::MH::Index   72
     head_type   Mail::Box::MH::Index   'Mail::Message::Head::Subset'

    * filename => FILENAME
        The FILENAME which is used to store the headers of all the e-mails for one folder. This must be an absolute pathname.

    * head_type => CLASS
        The type of headers which will be used to store header information when it is read from the index file. You can not be sure the index contains all header line (the mailbox may have been updated without updating the index) so this will usually be (an sub-class of) "Mail::Message::Head::Subset".

    * head_wrap => INTEGER
        The preferred number of character in each header line.

write MESSAGES
    Write an index file containing the headers specified MESSAGES ("Mail::Message" objects).

read
    Read the index file. The header objects can after this be requested with the "get()" method.

get MSGFILE
    Look if there is header info for the specified MSGFILE. The filename represents one message in folder type which are organized as directory. This method will return an object of the "head_type" as specified during creation of the index object, or "undef" if the information is not known or not trustworthy -i.e. the filesize changed.

METHODS for extension writers

filename
    Returns the name of the index file.

SEE ALSO
Mail::Box-Overview

For support and additional documentation, see http://perl.overmeer.net/mailbox/

AUTHOR
Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION
This code is beta, version 2.018.

Copyright (c) 2001-2002 Mark Overmeer. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.