/ 
Mail-Box-1.310
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Box::Mbox::Message

NAME

Mail::Box::Mbox::Message - a message in a Mbox folder

SYNOPSIS

my $folder  = new Mail::Box::Mbox folder => $ENV{MAIL}, ...;
my $message = $folder->message(0);

DESCRIPTION

This manual-page describes the classes Mail::Box::Mbox::Message, Mail::Box::Mbox::Parsed, and Mail::Box::Mbox::NotParsed. These objects are used to store messages which are not totally read, fully read, or to be written to a Mail::Box::Mbox type of folder.

During its life, a message will pass through certain stages. These stages were introduced to reduce the access-time to the folder. Changing from stage, the message changes from object-class (try to do this in any other language than Perl!).

All information which is required during the full life-span of the message is stored in a Mail::Box::Mbox::Message, which is extended by the Mail::Box::Mbox::NotParsed and the Mail::Box::Mbox::Message::Parsed. The last object (Mail::Box::Mbox::NotReadHead) maintains some header-lines of the message.

The bottom of this page provides more details about the implementation, but first the use.

CLASS Mail::Box::Mbox::Message

This object contains methods which are part of as well delay-loaded (not-parsed) as loaded messages, but not general for all folders.

METHODS

new ARGS

Messages in file-based folders use the following extra options for creation:

  • from LINE

    The line which precedes each message in the file. Some people detest this line, but this is just how things were invented...

fromLine [LINE]

Many people detest file-style folders because they store messages all in one file, where a line starting with From leads the header. If we receive a message from a file-based folder, we store that line. If we write to such a file, but there is no such line stored, then we try to produce one.

When you pass a LINE, that this is stored.

Write one message to a file-handle. Unmodified messages are taken from the folder-file where they were stored in. Modified messages are written as in memory. Specify a FILEHANDLE to write to (defaults to STDOUT).

migrate FILEHANDLE

Move the message from the current folder, to a new folder-file. The old location should be not used after this.

CLASS Mail::Box::Mbox::Parsed

This object extends a Mail::Box::Message::Parsed with extra tools and facts on what is special to messages in file-based folders, with respect to messages in other types of folders.

METHODS

coerce FOLDER, MESSAGE [,OPTIONS]

(Class method) Coerce a MESSAGE into a Mail::Box::Mbox::Parsed. When any message is offered to be stored in a mbox FOLDER, it first should have all fields which are specific for Mbox-folders.

The coerced message is returned on success, else undef.

Example:

my $inbox = Mail::Box::Mbox->new(...);
my $mh    = Mail::Box::MH::Message->new(...);
Mail::Box::Mbox::Parsed->coerce($inbox, $mh);
# Now, the $mh is ready to be included in $inbox.

However, you can better use

$inbox->coerce($mh);

which will call the right coerce() for sure.

CLASS Mail::Box::Mbox::NotParsed

Not parsed messages stay in the file until the message is used. Because this folder structure uses many messages in the same file, the byte-locations are remembered.

METHODS

load

This method is called by the autoloader then the data of the message is required. If you specified REAL for the take_headers option for new(), you did have a MIME::Head in your hands, however this will be destroyed when the whole message is loaded.

IMPLEMENTATION

The user of a folder gets his hand on a message-object, and is not bothered with the actual data which is stored in the object at that moment. As implementor of a mail-package, you might be.

A message is simple to use, but has a quite complex class structure. A message is not a real message from the start, but only when you access the body of it. Before that, a hollow placeholder is used. Below is depicted how the internal structure of a message-object changes based on actions on the object and parameters.

The inheritance relation is like this:

  read()
  =====#
       V              load()
  ::Mbox::NotParsed ========> ::Mbox::Parsed
        |       \               /    |
        ^        \             /     ^
        |        ::Mbox::Message     |
        |                            |
::Message::NotParsed        ::Message::Parsed
              \                  /   |
               ::Message::Message    ^
                        |            |
                        ^       MIME::Entity
                        |            |
                    ::Thread         ^
                                     |
                                 Mail::Internet

The Mail::Box::Mbox::Parsed stage, means that the whole message is in memory. It then is a full decendent of a MIME::Entity. But at the same time, it consumes a considerable amount of memory, and the program has spent quite some processor time on. All the intermediate stati are created to avoid full loading, so to be cheap in memory and time. Folder access will be much faster under normal circumstances.

For trained eyes only the status-transition diagram:

read()     !lazy
-------> +----------------------------------> Mail::Box::
         |                                  Mbox::Parsed
         |                                         ^
         |                                         |
         |                    NotParsed    load    |
         |        ALL ,-----> NotReadHead ------>-'|
         | lazy      /                             |
         `--------->+                              |
                     \        NotParsed    load    |
                 REAL `-----> MIME::Head ------->-'


      ,-------------------------+---.
     |                      ALL |   | regexps && taken
     v                          |   |
NotParsed    head()    get()   /   /
NotReadHead --------> ------->+---'
          \          \         \
           \ other()  \ other() \regexps && !taken
            \          \         \
             \          \         \    load    Mail::Box::
              `----->----+---------+---------> MBox::Parsed

      ,---------------.
     |                |
     v                |
NotParsed     head()  |
MIME::Head -------->--'
         \                           Mail::Box::
          `------------------------> MBox::Parsed

Terms: lazy refers to the evaluation of the lazy_extract() option. The load and load_head are triggers to the AUTOLOAD mothods. All terms like head() refer to method-calls. Finally, ALL, REAL, and regexps (default) refer to values of the take_headers option of new().

Hm... not that easy... but relatively simple compared to MH-folder messages.

AUTHOR

Mark Overmeer (Mark@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 1.310