
=head1 NAME

Mail::Message::Construct::Read - read a Mail::Message from a file handle


=head1 INHERITANCE


=head1 SYNOPSIS

 my $msg1 = Mail::Message->read(\*STDIN);
 my $msg2 = Mail::Message->read(\@lines);


=head1 DESCRIPTION

When complex methods are called on a C<Mail::Message> object, this package
is autoloaded to support the reading of messages directly from any file
handle.



=head1 METHODS


=head2 Constructing a message


Mail::Message-E<gt>B<read>(FILEHANDLE|SCALAR|REF-SCALAR|ARRAY-OF-LINES, OPTIONS)

=over 4

Read a message from a FILEHANDLE, SCALAR, a reference to a SCALAR, or
a reference to an array of LINES.  The OPTIONS are passed to the L<new()|"Constructors">
of the message which is created.

Please have a look at L<build()|"Constructing a message"> and L<buildFromBody()|"Constructing a message"> before thinking about
this C<read> method.  Use this C<read> only when you have a file-handle
like STDIN to parse from, or some external source of message lines.
When you already have a separate set of head and body lines, then C<read>
is certainly B<not> your best choice.

Some people use this method in a procmail script: the message arrives
at stdin, so we only have a filehandle.  In this case, you are stuck
with this method.  The message is preceeded by a line which can be used
as message separator in mbox folders.  See the example how to handle
that one.

I<Example:> 

 my $msg1 = Mail::Message->read(\*STDIN);
 my $msg2 = Mail::Message->read(\@lines, log => 'PROGRESS');
 $folder->addMessages($msg1, $msg2);

 my $msg3 = Mail::Message->read(<<MSG);
 Subject: hello world
 To: you@example.com
                      # warning: empty line required !!!
 Hi, greetings!
 MSG

 # promail example
 my $fromline = <STDIN>;
 my $msg      = Mail::Message->read(\*STDIN);
 my $coerced  = $mboxfolder->addMessage($msg);
 $coerced->fromLines($fromline);

=back








=head1 REFERENCES

See the Mail::Box website at L<http://perl.overmeer.net/mailbox/> for more details.

=head1 COPYRIGHTS

Module version 2.042.
Written by Mark Overmeer (mark@overmeer.net).  See the ChangeLog for
other contributors.

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


