
=head1 NAME

Mail::Box::Parser::Perl - reading messages from file using Perl

=head1 CLASS INHERITANCE

 Mail::Box::Parser::Perl
   is a Mail::Box::Parser
   is a Mail::Reporter

=head1 SYNOPSIS


=head1 DESCRIPTION

The Mail::Box::Parser::Perl implements parsing of messages in Perl.
This may be a little slower than the C<C> based parser, but will also
work on platforms where no C compiler is available.

=head1 METHODS

=head2 Initiation

=over 4

=item B<new> OPTIONS

(Class method)

 OPTION               DEFAULT
 file                 undef
 filename             <required>
 fix_header_errors    <false>
 log                  'WARNINGS'
 mode                 'r'
 trace                'WARNINGS'
 trusted              <false>

=over 4

=item B<file> =E<gt> FILE-HANDLE

See Mail::Box::Parser::new(file)

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

See Mail::Box::Parser::new(filename)

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

When header errors are detected, the parsing of the header will
be stopped.  Other header lines will become part of the body of
the message.  Set this flag to have the erroneous line added to
the previous header line.

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

See Mail::Reporter::new(log)

=item B<mode> =E<gt> OPENMODE

See Mail::Box::Parser::new(mode)

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

See Mail::Reporter::new(trace)

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

Is the input from the file to be trusted, or does it require extra
tests.  Related to Mail::Box::new(trusted).

=back

=back

=head2 The Parser

=over 4

=item B<defaultParserType> [CLASS]

See Mail::Box::Parser::defaultParserType()

=item B<fileChanged> 

See Mail::Box::Parser::fileChanged()

=item B<filename> 

See Mail::Box::Parser::filename()

=item B<restart> 

See Mail::Box::Parser::restart()

=item B<start> OPTIONS

See Mail::Box::Parser::start()

=item B<stop> 

See Mail::Box::Parser::stop()

=item B<takeFileInfo> 

See Mail::Box::Parser::takeFileInfo()

=back

=head2 Parsing

=over 4

=item B<bodyAsFile> FILEHANDLE [,CHARS [,LINES]]

See Mail::Box::Parser::bodyAsFile()

=item B<bodyAsList> [,CHARS [,LINES]]

See Mail::Box::Parser::bodyAsList()

=item B<bodyAsString> [,CHARS [,LINES]]

See Mail::Box::Parser::bodyAsString()

=item B<bodyDelayed> [,CHARS [,LINES]]

See Mail::Box::Parser::bodyDelayed()

=item B<filePosition> [POSITION]

See Mail::Box::Parser::filePosition()

=item B<fixHeaderErrors> [BOOLEAN]

If set to C<true>, parsing of a header will not stop on an error, but
attempt to add the erroneous this line to previous field.  Without BOOLEAN,
the current setting is returned.

Examples:

 $folder->parser->fixHeaderErrors(1);
 my $folder = $mgr->open('folder', fix_header_errors => 1);

=item B<lineSeparator> 

See Mail::Box::Parser::lineSeparator()

=item B<popSeparator> 

See Mail::Box::Parser::popSeparator()

=item B<pushSeparator> STRING|REGEXP

See Mail::Box::Parser::pushSeparator()

=item B<readHeader> 

=item B<readSeparator> OPTIONS

See Mail::Box::Parser::readSeparator()

=back

=head2 Reading and Writing [internals]

=over 4

=item B<closeFile> 

See Mail::Box::Parser::closeFile()

=item B<openFile> ARGS

See Mail::Box::Parser::openFile()

=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<report> [LEVEL]

See Mail::Reporter::report()

=item B<reportAll> [LEVEL]

See Mail::Reporter::reportAll()

=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<DESTROY> 

See Mail::Reporter::DESTROY()

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