NAME

Mail::Box::Maildir - handle Maildir folders

CLASS HIERARCHY

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

SYNOPSIS

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

DESCRIPTION

This documentation describes how Maildir mailboxes work, and what you can do with the Maildir folder object Mail::Box::Maildir. Please read Mail::Box-Overview and Mail::Box::Dir first.

The internal organization and details are found at the bottom of this manual-page.

METHOD INDEX

Methods prefixed with an abbreviation are described in Mail::Box (MB), Mail::Reporter (MR), Mail::Box::Dir (MBD).

The general methods for Mail::Box::Maildir objects:

   MB addMessage  MESSAGE               MB locker
   MB addMessages MESSAGE [, MESS...    MR log [LEVEL [,STRINGS]]
   MB allMessageIds                     MB message INDEX [,MESSAGE]
   MB close OPTIONS                     MB messageId MESSAGE-ID [,MESS...
   MB create FOLDERNAME [, OPTIONS]     MB messages
      createDirs FOLDERDIR              MB modified [BOOLEAN]
   MB current [NUMBER|MESSAGE|MES...    MB name
   MB delete                               new OPTIONS
  MBD directory                         MB openSubFolder NAME [,OPTIONS]
   MR errors                            MR report [LEVEL]
   MB find MESSAGE-ID                   MR reportAll [LEVEL]
      folderIsEmpty FOLDERDIR           MR trace [LEVEL]
   MB listSubFolders OPTIONS            MR warnings

The extra methods for extension writers:

   MR AUTOLOAD                          MB organization
   MB DESTROY                           MB read OPTIONS
   MB appendMessages OPTIONS           MBD readAllHeaders
   MB clone OPTIONS                    MBD readMessageFilenames DIRECTORY
   MB coerce MESSAGE                    MB readMessages OPTIONS
   MB determineBodyType MESSAGE, ...    MB scanForMessages MESSAGE, ME...
  MBD folderToDirectory FOLDERNAM...    MB sort PREPARE, COMPARE, LIST
   MB folderdir [DIR]                   MB storeMessage MESSAGE
   MB foundIn [FOLDERNAME], OPTIONS     MB timespan2seconds TIME
   MR inGlobalDestruction               MB toBeThreaded MESSAGES
   MB lineSeparator [STRING|'CR'|...    MB toBeUnthreaded MESSAGES
   MR logPriority LEVEL                 MB update OPTIONS
   MR logSettings                       MB updateMessages OPTIONS
   MR notImplemented                    MB write OPTIONS

METHODS

new OPTIONS

Create a new folder. The are many options which are taken from other objects. For some, different options are set. For MH-specific options see below, but first the full list.

 OPTION            DEFINED BY         DEFAULT
 access            Mail::Box          'r'
 create            Mail::Box          0
 folder            Mail::Box          $ENV{MAIL}
 folderdir         Mail::Box          <no default>
 head_wrap         Mail::Box          72
 keep_dups         Mail::Box          0
 extract           Mail::Box          10kB
 lock_type         Mail::Box          'NONE'  # constant
 lock_file         Mail::Box          <not used>
 lock_timeout      Mail::Box          <not used>
 lock_wait         Mail::Box          <not used>
 log               Mail::Reporter     'WARNINGS'
 remove_when_empty Mail::Box          1
 save_on_exit      Mail::Box          1
 trace             Mail::Reporter     'WARNINGS'
 trusted           Mail::Box          <depends on folder location>

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

 OPTION            DEFINED BY         DEFAULT
 body_type         Mail::Box::Dir     <see Mail::Box::Dir>
 body_delayed_type Mail::Box          'Mail::Message::Body::Delayed'
 coerce_options    Mail::Box          []
 field_type        Mail::Box          undef
 head_type         Mail::Box          'Mail::Message::Head::Complete'
 head_delayed_type Mail::Box          'Mail::Message::Head::Delayed'
 locker            Mail::Box          <not used>
 multipart_type    Mail::Box          'Mail::Message::Body::Multipart'
 manager           Mail::Box          undef
 message_type      Mail::Box          'Mail::Box::MH::Message'
 realhead_type     Mail::Box          'Mail::Message::Head'

MH specific options:

createDirs FOLDERDIR

(Instance or class method) The FOLDERDIR contains the absolute path of the location where the messages are kept. Maildir folders contain a tmp, new, and cur sub-directory within that folder directory as well. This method will ensure that all directories exist. Returns false on failure.

folderIsEmpty FOLDERDIR

(Instance or class method) Checks whether the folder whose directory is specified as absolute FOLDERDIR is empty or not. A folder is empty when the tmp, new, and cur subdirectories are empty and some files which are left there by application programs. The maildir spec explicitly states: .qmail, bulletintime, bulletinlock and seriallock. If any other files are found, the directory is considered not-empty.

METHODS for extension writers

writeMessages [OPTIONS]

Write all messages to the folder-file.

 OPTION            DEFINED BY         DEFAULT
 force             Mail::Box          <true>
 head_wrap         Mail::Box          72
 keep_deleted      Mail::Box          <false>
 save_deleted      Mail::Box          <false>

IMPLEMENTATION

The explanation is complicated, but for normal use you should bother yourself with all details.

How Maildir-folders work

Maildir-type folders use a directory to store the messages of one folder. Each message is stored in a seperate 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, Maildir 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 as threads is desired. Maildir maintains a tiny amount of info visible in the filename, which may make it perform just a little bit faster than MH.

The following information was found at http://cr.yp.to/proto/maildir.html. Each message is written in a seperate file. The filename is constructed from the time-of-arrival, a unique component, hostname, a syntax marker, and flags. For example 1014220791.meteor.42:2,DF. The filename must match:

 my ($time, $unique, $hostname, $info)
    = $filename =~ m!^(\d+)\.(.*)\.(\w+)(\:.*)?$!;
 my ($semantics, $flags)
    = $info =~ m!([12])\,([RSTDF]+)$!;
 my @flags = split //, $flags;

The @flags are sorted alphabetically, with the following meanings:

 D = draft, to be sent later
 F = flagged for user-defined purpose
 R = has been replied
 S = seen / (partially) read by the user
 T = trashed, flagged to be deleted later

Labels

The filename contains flags, and those flags are translated into labels when the folder is opened. Labels can be changed by the application using the labels method.

Changes will directly reflect in a filename change. The Status and X-Status lines in the header, which are used by Mbox kind of folders, are ignored except when a new message is received in the new directory. In case a message has to be written to file for some reason, the status header lines are updated as well.

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.015.

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.

cpanm Mail::Box

perl -MCPAN -e shell
install Mail::Box