Mail::...:Cache(3pm)

💾 Mail::Mbox::MessageParser::Cache — the perl manual, bestie edition ✨

okay so real talk, this is the User Contributed Perl Documentation page for Mail::Mbox::MessageParser::Cache, and if you're here it's because you're doing mbox folder reading and you want it to go ✨fast✨. Sit down, grab a boba, we're doing this together 💖

---

🌸 NAME 🌸

Mail::Mbox::MessageParser::Cache — literally just a cache-based mbox folder reader. that's it, that's the name 🎀

---

🦋 SYNOPSIS 🦋

here's the whole vibe, verbatim, no cap:

#!/usr/bin/perl

use Mail::Mbox::MessageParser;

my $filename = 'mail/saved-mail';
my $filehandle = new FileHandle($filename);

# Set up cache
Mail::Mbox::MessageParser::SETUP_CACHE(
  { 'file_name' => '/tmp/cache' } );

my $folder_reader =
  new Mail::Mbox::MessageParser( {
    'file_name' => $filename,
    'file_handle' => $filehandle,
    'enable_cache' => 1,
  } );

die $folder_reader unless ref $folder_reader;

warn "No cached information"
  if $Mail::Mbox::MessageParser::Cache::UPDATING_CACHE;

# 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;
}

like… it's giving "set up the cache, make a reader, print the prologue, loop through every email." main character energy fr fr 👑

---

💅 DESCRIPTION 💅

so this module is the cached-based mbox folder reader. important caveat bestie: it can only be used when cache information already exists. like, the cache has to be there first. no cache, no service 🙈

and here's the thing — users must not instantiate this class directly. nope. don't do it. use Mail::Mbox::MessageParser instead. the base MessageParser module handles all the cache/non-cache juggling automatically so you literally do not have to think about it. she's got it 💁‍♀️

✨ METHODS AND FUNCTIONS ✨

these are the ones that are specific to the Mail::Mbox::MessageParser::Cache package. for the ones it inherits, go look at the Mail::Mbox::MessageParser docs, bestie 🫶

• $ref = new( { 'file_name' => <mailbox file name>, 'file_handle' => <mailbox file handle>, });
  • <file_name> — the full filename of the mailbox
  • <file_handle> — an opened file handle for the mailbox

okay so the constructor takes two parameters, no more no less. file_name is the filename of the mailbox, and heads up — this gets used as the cache key, so it's super important that it fully defines the path to the mailbox. like, fully fully. don't be vague about it 💀

file_handle is the opened file handle to the mailbox. both arguments are required — you cannot skip one, that's not a thing.

what you get back: a reference to a Mail::Mbox::MessageParser object 🌟 … or a string describing the error 😭 (yes, she returns a string on failure, so please check the ref, like the synopsis does).

• reset()
• read_next_email()

these two methods are overridden in this subclass of Mail::Mbox::MessageParser. that's the whole note. iconic behaviour honestly 💖

---

🍓 BUGS 🍓

No known bugs. she's flawless, your honour 💅✨

but if you do find something, contact david@coppit.org for bug reports and suggestions. be nice, be specific 🫶

---

👑 AUTHOR 👑

David Coppit <david@coppit.org>.

---

📜 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. read the license, love the license 🌈

---

🧚 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::Mbox::MessageParser

---

⚠️ quick reminder bestie: don't instantiate this class directly, and don't run it without cache info already chilling on disk. that's not a vibe check you want to fail 💀

okay that's the whole page!! 💖 this was perl v5.36.0, dated 2023-08-06, and it's the Mail::...:Cache(3pm) page — mwah, slay, bye bestie 🎀🦋💅