Mail::...:Index(3pm)

💖 NAME 💖

Mail::Box::MH::Index — bestie, this one keeps index files for messages 💅

This page lives in the User Contributed Perl Documentation neighborhood (section 3pm), so you already know it's a Perl module and not some dusty old command you type at a prompt ✨

---

🌸 INHERITANCE 🌸

Mail::Box::MH::Index
  is a Mail::Reporter

So like, it's a Mail::Reporter at heart, and it inherits all that reporter energy 💜

---

🦋 SYNOPSIS 🦋

my $index = Mail::Box::MH::Index->new;
$index->read(...)
$index->write(...)

That's the whole vibe check. Make one, read it, write it. Periodt. 🎀

---

✨ DESCRIPTION ✨

Okay so picture this: message folders that store every single message in one file per message. Cute in theory, right? But literally the worst for building subject overviews and for figuring out message threads 😭 It's giving "why are we like this."

Enter Mail::Box::MH::Index — it's the object that can store and read the headers of a whole set of Mail::Box::MH::Message messages that all belong to a single Mail::Box::MH folder, and it does it all in one file 👑

When the Mail::Box::MH::Index functionality is enabled — which you do by specifying Mail::Box::MH::new(keep_index) when you open a folder — the index file gets read automatically, no cap. And when the folder is closed, a brand new index file is created. Slay.

Special care is taken (yes, actual care, we're thoughtful like that 🫶) to dodge the problems that pop up when the user changes or removes message files without updating the index. And if the index is not trustworthy? It simply will not be used — which costs some performance for whoever's reading the folder. Trade-offs, bestie, it's called boundaries. 🙈

Extends "DESCRIPTION" in Mail::Reporter.

---

💅 METHODS 💅

Extends "METHODS" in Mail::Reporter.

🧚 Constructors

Extends "Constructors" in Mail::Reporter.

• $class->new(%options) — Inherited, see "Constructors" in Mail::Reporter

The options it takes, with their defaults:

 -Option   --Default
  filename   <required>
  head_type  Mail::Message::Head::Subset
  head_wrap  72

• filename => $file — This is the $file used to store the headers of all the e-mails for one folder. Heads up: this must be an absolute pathname ⭐
• head_type => $class — The type of headers that will be used to store header info when it's read from the index file. You can not be sure the index contains every header line (because the mailbox may have been updated without updating the index), so this will usually be — an sub-class of — Mail::Message::Head::Subset 💖
• head_wrap => $nrchars — The preferred maximum number of characters in each header line.

🌈 Attributes

Extends "Attributes" in Mail::Reporter.

• $obj->filename() — Returns the name of the index file. That's it, that's the whole method 🎀

🔥 Error handling

Extends "Error handling" in Mail::Reporter.

• $obj->AUTOLOAD() — Inherited, see "Error handling" in Mail::Reporter
• $obj->notImplemented() — Inherited, see "Error handling" in Mail::Reporter

🧼 Cleanup

Extends "Cleanup" in Mail::Reporter.

• $obj->DESTROY() — Inherited, see "Cleanup" in Mail::Reporter

👑 The Index

• $obj->append(@messages) — Append @messages to the index file. Simple. Iconic. 💅
• $obj->get($msgfile) — Look if there is header info for the specified $msgfile. That filename represents one message in a folder type which is organized as a directory. This method returns an object of the new(head_type) as specified when you created the index object — or it returns "undef" if the information is not known or not trustworthy, i.e. the file size changed. 🙈
• $obj->read() — Read the index file. After this, the header objects can be requested with the get() method. Main character energy 🦋
• $obj->write(@messages) — Write an index file containing the headers specified in @messages (Mail::Message objects). 💖

---

😭 DIAGNOSTICS 😭

• Error: MH index requires a filename. — Cast by new()
• Error: class $package does not implement method $method. — Fatal error: the specific $package (or one of its superclasses) does not implement this method where it should. This message means that some other related classes do implement this method however the class at hand does not. Probably you should investigate this and probably inform the author of the package. Cast by notImplemented()

Not me getting a fatal error at 2am 💀 Investigate, then go tell the author, bestie. Politely.

---

🌟 SEE ALSO 🌟

This module is part of Mail-Box version 4.02, built on April 10, 2026.

Website: http://perl.overmeer.net/CPAN/ — go peek, it's giving very much iykyk 🌸

---

🎀 LICENSE 🎀

For contributors see file ChangeLog.

This software is copyright (c) 2001-2026 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 💜

---

okay that's a wrap, bestie 🫶 this was perl v5.40.1, dated 2026-05-09, and honestly? iconic. mwah 💅✨