
=head1 NAME

Mail::Box::Dir::Message - one message in a directory-organized folder

=head1 CLASS INHERITANCE

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

 Mail::Box::Dir::Message is extended by
   Mail::Box::MH::Message
   Mail::Box::Maildir::Message

=head1 SYNOPSIS

 my $folder = new Mail::Box::MH ...
 my $message = $folder->message(10);

=head1 DESCRIPTION

A Mail::Box::Dir::Message is a base class for one message in a directory
organized folder; each message is stored in a separate file.  There are
no objects of type Mail::Box::Dir::Message, only extensions are allowed to
be created.

At the moment, two of these extended message types are implemented:

=over 4

=item * Mail::Box::MH::Message

which represents one message in a Mail::Box::MH folder.

=item * Mail::Box::Maildir::Message

which represents one message in a Mail::Box::Maildir folder.

=back

=head1 METHODS

=head2 Initiation

=over 4

=item B<new> OPTIONS

(Class method) 
Create a messages in a directory organized folder.

 OPTION               DEFAULT
 body                 undef
 body_type            <from folder>
 deleted              <false>
 field_type           undef
 filename             undef
 fix_header           C<false>
 folder               <required>
 head                 undef
 head_type            'Mail::Message::Head::Complete'
 log                  'WARNINGS'
 messageId            undef
 modified             <false>
 size                 undef
 trace                'WARNINGS'
 trusted              <false>

=over 4

=item B<body> =E<gt> OBJECT

See Mail::Message::new(body)

=item B<body_type> =E<gt> CODE|CLASS

See Mail::Box::Message::new(body_type)

=item B<deleted> =E<gt> BOOLEAN

See Mail::Box::Message::new(deleted)

=item B<field_type> =E<gt> CLASS

See Mail::Message::new(field_type)

=item B<filename> =E<gt> FILENAME

The file where the message is stored in.

=item B<fix_header> =E<gt> BOOLEAN

See Mail::Box::new(fix_headers).

=item B<folder> =E<gt> FOLDER

See Mail::Box::Message::new(folder)

=item B<head> =E<gt> OBJECT

See Mail::Message::new(head)

=item B<head_type> =E<gt> CLASS

See Mail::Message::new(head_type)

=item B<log> =E<gt> LEVEL

See Mail::Reporter::new(log)

=item B<messageId> =E<gt> STRING

See Mail::Message::new(messageId)

=item B<modified> =E<gt> BOOLEAN

See Mail::Message::new(modified)

=item B<size> =E<gt> INTEGER

See Mail::Box::Message::new(size)

=item B<trace> =E<gt> LEVEL

See Mail::Reporter::new(trace)

=item B<trusted> =E<gt> BOOLEAN

See Mail::Message::new(trusted)

=back

=back

=head2 Constructing a Message

=over 4

=item B<bounce> [RG-OBJECT|OPTIONS]

See Mail::Message::Construct::bounce()

=item B<build> [MESSAGE|BODY], CONTENT

See Mail::Message::Construct::build()

=item B<buildFromBody> BODY, [HEAD], HEADERS

See Mail::Message::Construct::buildFromBody()

=item B<coerce> MESSAGE

See Mail::Box::Message::coerce()

=item B<forward> OPTIONS

See Mail::Message::Construct::forward()

=item B<forwardPostlude> 

See Mail::Message::Construct::forwardPostlude()

=item B<forwardPrelude> 

See Mail::Message::Construct::forwardPrelude()

=item B<forwardSubject> STRING

See Mail::Message::Construct::forwardSubject()

=item B<read> FILEHANDLE|SCALAR|REF-SCALAR|ARRAY-OF-LINES, OPTIONS

See Mail::Message::Construct::read()

=item B<reply> OPTIONS

See Mail::Message::Construct::reply()

=item B<replyPrelude> [STRING|FIELD|ADDRESS]

See Mail::Message::Construct::replyPrelude()

=item B<replySubject> STRING

See Mail::Message::Construct::replySubject()

=back

=head2 The Message

=over 4

=item B<clone> 

See Mail::Message::clone()

=item B<container> 

See Mail::Message::container()

=item B<copyTo> FOLDER

See Mail::Box::Message::copyTo()

=item B<filename> [FILENAME]

Returns the name of the file in which this message is actually stored.  This
will return C<undef> when the message is not stored in a file.

=item B<folder> [FOLDER]

See Mail::Box::Message::folder()

=item B<isDummy> 

See Mail::Message::isDummy()

=item B<isModified> 

See Mail::Message::isModified()

=item B<isPart> 

See Mail::Message::isPart()

=item B<messageId> 

See Mail::Message::messageId()

=item B<modified> [BOOLEAN]

See Mail::Message::modified()

=item B<moveTo> FOLDER

See Mail::Box::Message::moveTo()

=item B<print> [FILEHANDLE]

See Mail::Message::print()

=item B<send> [MAILER], OPTIONS

See Mail::Message::send()

=item B<seqnr> [INTEGER]

See Mail::Box::Message::seqnr()

=item B<size> 

See Mail::Message::size()

=item B<toplevel> 

See Mail::Message::toplevel()

=item B<write> [FILEHANDLE]

See Mail::Message::write()

=back

=head2 The Header

=over 4

=item B<head> [HEAD]

See Mail::Message::head()

=back

=head2 Header Shortcuts

=over 4

=item B<bcc> 

See Mail::Message::bcc()

=item B<cc> 

See Mail::Message::cc()

=item B<date> 

See Mail::Message::date()

=item B<destinations> 

See Mail::Message::destinations()

=item B<from> 

See Mail::Message::from()

=item B<get> FIELD

See Mail::Message::get()

=item B<guessTimestamp> 

See Mail::Message::guessTimestamp()

=item B<nrLines> 

See Mail::Message::nrLines()

=item B<sender> 

See Mail::Message::sender()

=item B<subject> 

See Mail::Message::subject()

=item B<timestamp> 

See Mail::Message::timestamp()

=item B<to> 

See Mail::Message::to()

=back

=head2 The Body

=over 4

=item B<body> [BODY]

See Mail::Message::body()

=item B<decoded> OPTIONS

See Mail::Message::decoded()

=item B<encode> OPTIONS

See Mail::Message::encode()

=item B<isMultipart> 

See Mail::Message::isMultipart()

=item B<parts> ['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER]

See Mail::Message::parts()

=back

=head2 Access to the Message

=over 4

=item B<file> 

See Mail::Message::Construct::file()

=item B<lines> 

See Mail::Message::Construct::lines()

=item B<string> 

See Mail::Message::Construct::string()

=back

=head2 Labels

=over 4

=item B<delete> 

See Mail::Box::Message::delete()

=item B<deleted> [BOOLEAN]

See Mail::Box::Message::deleted()

=item B<isDeleted> 

See Mail::Box::Message::isDeleted()

=item B<label> LABEL [,VALUE [LABEL, VALUE] ]

See Mail::Message::label()

=item B<labels> 

See Mail::Message::labels()

=item B<labelsToStatus> 

See Mail::Message::labelsToStatus()

=item B<statusToLabels> 

See Mail::Message::statusToLabels()

=back

=head2 Reading and Writing [internals]

=over 4

=item B<DESTROY> 

See Mail::Message::DESTROY()

=item B<create> FILENAME

Create the message in the specified file.  If the message already has
a filename and is not modified, then a move is tried.  Otherwise the
message is printed to the file.  If the FILENAME already exists for
this message, nothing is done.  In any case, the new FILENAME is set
as well.

=item B<diskDelete> 

See Mail::Box::Message::diskDelete()

=item B<isDelayed> 

See Mail::Message::isDelayed()

=item B<loadBody> 

This method is called by the autoloader when the body of the message
is needed.

=item B<loadHead> 

This method is called by the autoloader when the header of the message
is needed.

=item B<parser> 

Create and return a parser for this message (-file).

=item B<readBody> PARSER, HEAD [, BODYTYPE]

See Mail::Box::Message::readBody()

=item B<readFromParser> PARSER, [BODYTYPE]

See Mail::Message::readFromParser()

=item B<readHead> PARSER [,CLASS]

See Mail::Message::readHead()

=item B<storeBody> BODY

See Mail::Message::storeBody()

=item B<takeMessageId> [STRING]

See Mail::Message::takeMessageId()

=back

=head2 Logging and Tracing

=over 4

=item B<defaultTrace> [LEVEL, [LEVEL]

See Mail::Reporter::defaultTrace()

=item B<errors> 

See Mail::Reporter::errors()

=item B<log> [LEVEL [,STRINGS]]

See Mail::Reporter::log()

=item B<printStructure> [FILEHANDLE][, INDENT]

See Mail::Message::Construct::printStructure()

=item B<report> [LEVEL]

See Mail::Reporter::report()

=item B<reportAll> [LEVEL]

See Mail::Reporter::reportAll()

=item B<shortString> 

See Mail::Box::Message::shortString()

=item B<trace> [LEVEL]

See Mail::Reporter::trace()

=item B<warnings> 

See Mail::Reporter::warnings()

=back

=head2 Other Methods

=over 4

=item B<AUTOLOAD> 

See Mail::Reporter::AUTOLOAD()

=item B<inGlobalDestruction> 

See Mail::Reporter::inGlobalDestruction()

=item B<logPriority> LEVEL

See Mail::Reporter::logPriority()

=item B<logSettings> 

See Mail::Reporter::logSettings()

=item B<notImplemented> 

See Mail::Reporter::notImplemented()

=back

=head1 SEE ALSO

A good start to read is Mail::Box-Overview.
More documentation and a mailinglist are available from the project's
website at L<http://perl.overmeer.net/mailbox/>.

=head1 AUTHOR

Written by Mark Overmeer (L<mark@overmeer.net|mailto:mark@overmeer.net>)
with the help of many.  See the ChangeLog for details.

=head1 VERSION

This code is beta, version 2.037.

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