Mail::...eParser(3pm)

💖 NAME 💖

Mail::Mbox::MessageParser — a fast and simple mbox folder reader, bestie. That's the whole vibe: it reads your mbox folders, and it does it fast.

---

✨ SYNOPSIS ✨

Okay so here's the whole thing in action, copy-paste energy:

#!/usr/bin/perl

use Mail::Mbox::MessageParser;

# Compression support
my $file_name = 'mail/saved-mail.xz';
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 🦋

So this module is a fast-but-simple mbox folder reader, no cap. It's got three whole implementations (Cache, Grep, Perl) and it picks one based on what you want plus whatever your system's got going on. Periodt.

The first one is cache-based: it stores email info about mailboxes right there on the file system, so later accesses are way faster because it doesn't have to re-analyze the mailbox at all. The second one is built on GNU grep, and it's significantly faster than the Perl version for mailboxes holding absolutely enormous (10MB) emails. And the final one is a fast Perl-based implementation that should always, always work. 🫶

Numbers time, because we love data:

• The Cache implementation is about 6 times faster than the standard Perl implementation.
• The Grep implementation is about 4 times faster than the standard Perl implementation.
• Got GNU grep? Bestie, enable both the Cache and Grep implementations. If the cache info is there, you get very fast speeds. If it isn't, you take about a 1/3 performance hit when the Grep version steps in instead.

The overriding requirement for this module is speed. That's the whole personality. If you want fancier parsing, go use Mail::MboxParser (which is literally based on this module) or Mail::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 you create any parsers, okay? You <u>must</u> provide the location of the cache file. There is no default value — none, zero, nada. 🙈

⭐ 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 a file name, or a file handle, or both — dealer's choice. If the file handle isn't defined, Mail::Mbox::MessageParser will try to open the file using the file name. And listen: you should always pass the file name if you have it, so the parser can cache the mailbox info. Trust. 💖

This module will automatically decompress the mailbox as needed. If a filename is available but the file handle is undef, the module will call bzip, bzip2, gzip, lzip, xz to decompress the file in memory — but only if the filename ends with the appropriate suffix. If the file handle is defined, it'll sniff out the type of compression and apply the correct decompression program. 🧚

Whichever of the Cache, Grep, or Perl implementations is most appropriate gets loaded. For example: first time you use caching there's no cache yet, so the grep implementation can step in instead. The cache gets updated in memory while the grep implementation parses the mailbox, and the cache gets written after the program exits. The file name is optional — but if you skip it, then enable_cache and enable_grep must both be false. 😤

force_processing makes the module process folders that look binary, or whose text data doesn't look like a mailbox at all.

Returns a reference to a Mail::Mbox::MessageParser object on success, and a scalar describing an error on failure. The error strings you might catch are: "Not a mailbox", "Can't open <filename>: <system error>", "Can't execute <uncompress command> for file <filename>".

⭐ reset()

Resets the filehandle and all internal state. Heads up though — this will not work with filehandles which are streams. If there's enough demand, the author may add the ability to store the previously read stream data internally so that reset() works correctly. iykyk. 💀

⭐ endline()

Returns "\n" or "\r\n", depending on the file format. Whichever one your file's giving. ✨

⭐ prologue()

Returns any newlines or other content at the start of the mailbox, before the first email. The little pre-show. 🎀

⭐ end_of_file()

Returns true if the end of the file has been encountered. That's it, that's the function.

⭐ line_number()

Returns the line number for the start of the last email read.

⭐ number()

Returns the number of the last email read. (So like, the first email will have a number of 1. Counting starts at one, bestie, not zero.)

⭐ 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 the mailbox, or undef at the end of the file. 👑

---

💀 BUGS 💀

No known bugs. Not a single one. Flawless, we love to see it. ✨

Contact david@coppit.org for bug reports and suggestions. 📧

---

👑 AUTHOR 👑

David Coppit <david@coppit.org>. The icon, the legend. 💜

---

📜 LICENSE 📜

This code is distributed under the GNU General Public License (GPL) Version 2. See the file LICENSE in the distribution for the details, bestie.

---

🌈 HISTORY 🌈

This code was originally part of the grepmail distribution. See http://grepmail.sf.net/ for previous versions of grepmail which included early versions of this code. Glow-up story fr fr. 🦋

---

🍓 SEE ALSO 🍓

• Mail::MboxParser
• Mail::Box

---

And that's the whole page, bestie!! This lil masterpiece is perl v5.36.0, dated 2023-08-06, and it lives in the User Contributed Perl Documentation. Now go read some mailboxes, you absolute main character. 💅✨🎀🫶