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

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 inGlobalDestruction
   MR DESTROY                           MR logPriority LEVEL
      filename                          MR logSettings

Prefixed methods are described in MR = Mail::Reporter.

METHODS

new OPTIONS

This method is called by folder classes, and should not be called by client programs. If you wish to control how indexing occurs, use the following options when creating a folder.

 OPTION      DEFINED BY             DEFAULT
 filename    Mail::Box::MH::Index   '.index'
 log         Mail::Reporter         'WARNINGS'
 trace       Mail::Reporter         'WARNINGS'
 head_wrap   Mail::Box::MH::Index   72

Only useful to write extension to Mail::Box::MH::Index. Common users of folders you will not specify these:

 OPTION      DEFINED BY             DEFAULT
 head_type   Mail::Box::MH::Index   'Mail::Message::Head::Subset'

• 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.)

• 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

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.00_17.

Copyright (c) 2001 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.