SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE




YUM REPOSITORY

 
 

MAN page from Mandriva 2010 perl-Mail-Mbox-MessageParser-1.500.200-1mdv2010.1.noarch.rpm

Mail::Mbox::MessageParser

Section: User Contributed Perl Documentation (3)
Updated: 2009-08-09
Index 

NAME

Mail::Mbox::MessageParser - A fast and simple mbox folder reader 

SYNOPSIS

  #!/usr/bin/perl  use Mail::Mbox::MessageParser;  my $file_name = 'mail/saved-mail';  my $file_handle = new FileHandle($file_name);  # Set up cache. (Not necessary if enable_cache is false.)  Mail::Mbox::MessageParser::SETUP_CACHE(    { 'file_name' => '/tmp/cache' } );  my $folder_reader =    new Mail::Mbox::MessageParser( {      'file_name' => $file_name,      'file_handle' => $file_handle,      'enable_cache' => 1,      'enable_grep' => 1,    } );  die $folder_reader unless ref $folder_reader;  # Any newlines or such before the start of the first email  my $prologue = $folder_reader->prologue;  print $prologue;  # This is the main loop. It's executed once for each email  while(!$folder_reader->end_of_file())  {    my $email = $folder_reader->read_next_email();    print $$email;  }
 

DESCRIPTION

This module implements a fast but simple mbox folder reader. One of threeimplementations (Cache, Grep, Perl) will be used depending on the wishes of theuser and the system configuration. The first implementation is a cached-basedone which stores email information about mailboxes on the file system.Subsequent accesses will be faster because no analysis of the mailbox will beneeded. The second implementation is one based on GNU grep, and issignificantly faster than the Perl version for mailboxes which contain verylarge (10MB) emails. The final implementation is a fast Perl-based one whichshould always be applicable.

The Cache implementation is about 6 times faster than the standard Perlimplementation. The Grep implementation is about 4 times faster than thestandard Perl implementation. If you have GNU grep, it's best to enable boththe Cache and Grep implementations. If the cache information is available,you'll get very fast speeds. Otherwise, you'll take about a 1/3 performancehit when the Grep version is used instead.

The overriding requirement for this module is speed. If you wish moresophisticated parsing, use Mail::MboxParser (which is based on this module) orMail::Box. 

METHODS AND FUNCTIONS

SETUP_CACHE(...)
  SETUP_CACHE( { 'file_name' => <cache file name> } );  <cache file name> - the file name of the cache

Call this function once to set up the cache before creating any parsers. Youmust provide the location to the cache file. There is no default value.

new(...)
  new( { 'file_name' => <mailbox file name>,    'file_handle' => <mailbox file handle>,    'enable_cache' => <1 or 0>,    'enable_grep' => <1 or 0>,    'force_processing' => <1 or 0>,    'debug' => <1 or 0>,  } );  <mailbox file name> - the file name of the mailbox  <mailbox file handle> - the already opened file handle for the mailbox  <enable_cache> - true to attempt to use the cache implementation  <enable_grep> - true to attempt to use the grep implementation  <force_processing> - true to force processing of files that look invalid  <debug> - true to print some debugging information to STDERR

The constructor takes either a file name or a file handle, or both. If thefile handle is not defined, Mail::Mbox::MessageParser will attempt to open thefile using the file name. You should always pass the file name if you have it,so that the parser can cache the mailbox information.

This module will automatically decompress the mailbox as necessary. If afilename is available but the file handle is undef, the module will calleither bzip2, or gzip to decompress the file in memory if the filenameends with .tz, .bz2, or .gz, respectively. If the file handle is defined, itwill detect the type of compression and apply the correct decompressionprogram.

The Cache, Grep, or Perl implementation of the parser will be loaded,whichever is most appropriate. For example, the first time you use caching,there will be no cache. In this case, the grep implementation can be usedinstead. The cache will be updated in memory as the grep implementation parsesthe mailbox, and the cache will be written after the program exits. The filename is optional, in which case enable_cache and enable_grep must bothbe false.

force_processing will cause the module to process folders that look to bebinary, or whose text data doesn't look like a mailbox.

Returns a reference to a Mail::Mbox::MessageParser object on success, and ascalar desribing an error on failure. (``Not a mailbox'', ``Can't open <filename>: <system error>'', ``Can't execute <uncompress command> for file <filename>''

reset()
Reset the filehandle and all internal state. Note that this will not work withfilehandles which are streams. If there is enough demand, I may add theability to store the previously read stream data internally so that reset()will work correctly.
endline()
Returns ``\n'' or ``\r\n'', depending on the file format.
prologue()
Returns any newlines or other content at the start of the mailbox prior to thefirst email.
end_of_file()
Returns true if the end of the file has been encountered.
line_number()
Returns the line number for the start of the last email read.
number()
Returns the number of the last email read. (i.e. The first email will have anumber of 1.)
length()
Returns the length of the last email read.
offset()
Returns the byte offset of the last email read.
read_next_email()
Returns a reference to a scalar holding the text of the next email in themailbox, or undef at the end of the file.
 

BUGS

No known bugs.

Contact davidAATTcoppit.org for bug reports and suggestions. 

AUTHOR

David Coppit <davidAATTcoppit.org>. 

LICENSE

This software is distributed under the terms of the GPL. See the file``LICENSE'' for more information. 

HISTORY

This code was originally part of the grepmail distribution. Seehttp://grepmail.sf.net/ for previous versions of grepmail which included earlyversions of this code. 

SEE ALSO

Mail::MboxParser, Mail::Box


 

Index

NAME
SYNOPSIS
DESCRIPTION
METHODS AND FUNCTIONS
BUGS
AUTHOR
LICENSE
HISTORY
SEE ALSO

This document was created byman2html,using the manual pages.