Sympa::Archive(3Sympa)

📦
version 6.2.80 · 14 versions
, in fedora 43, fedora 44

💖 NAME 💖

Sympa::Archive — the archives of Sympa, bestie. It's the whole vibe of keeping your list's messages archived and cute. (That's from the Sympa::Archive(3Sympa) manual, btw — we're in section 3, the Perl module section. iykyk.)

✨ SYNOPSIS ✨

Okay so here's the whole mood in code:

use Sympa::Archive;
$archive = Sympa::Archive->new(context => $list);

@arcs = $archive->get_archives;

$archive->store($message);
$archive->html_store($message);

$archive->select_archive('2015-04');
($message, $handle) = $archive->next;

$archive->select_archive('2015-04');
($message, $handle) = $archive->fetch(message_id => $message_id);
$archive->html_remove($message_id);
$archive->remove($handle);

$archive->html_rebuild('2015-04');

That's the entire plot bestie, nothing else to see here 💅

🌸 DESCRIPTION 🌸

Sympa::Archive implements the interface to handle archives. That's it, that's the job — it's the little module that handles all the archive-y business. 👑

🎀 Methods and functions 🎀

🦋 new ( context => $list, [ create => 1 ] )

Constructor, aka the glow-up moment where a fresh Sympa::Archive instance is born. ✨

Parameters:

  • context => $list — the context of the object, and it's a Sympa::List instance.
  • create => 1 — if necessary, this creates the directory structure of the archive. And heads up: it dies if the creation fails 😭 (dramatic, but necessary). This parameter was introduced on Sympa 6.2.47b.

🦋 add_archive ( $arc )

Instance method. Adds an archive directory named $arc. Currently, that archive directory has to have the form "YYYY-MM". No other format, bestie, the format is the format. 📅

🦋 purge_archive ( $arc )

Instance method. Removes the archive directory and its content entirely.

⚠️ Warning bestie: the removed content can not be recovered. Like, fr fr, gone gone. No undo, no take-backs, no "wait I didn't mean it". 💀

🦋 select_archive ( $arc, [ info => 1 ] )

Instance method. Selects an archive directory. It will be referred by consequent operations — like, everything after this is gonna be about that archive, so choose wisely. 🎯

🦋 fetch ( message_id => $message_id )

Instance method. Gets a message from the archive. select_archive() must be called in advance — no skipping steps, babe. 🫶

The message will be locked to prevent multiple processing of a single message (so two processes don't fight over the same one, we love a protective king 🔒).

Parameter:

  • message_id => $message_id — the Message ID of the message to be fetched.

Returns:

A two-elements list: a Sympa::Message instance and a filehandle locking a message.

🦋 html_fetch ( file => $filename )

Instance method. Gets a metadata of the formatted message from the HTML archive. select_archive() must be called in advance, as always. ✨

Parameter:

  • file => $filename — the file name of the message to be fetched.

Returns:

A hashref. Note that the message won't be locked — so no lock, no protection, it's giving low-maintenance. 🙈

🦋 get_size ( )

Instance method. Gets the total size of messages in the archives. This method was introduced on Sympa 6.2.17. 📏

🦋 next ( [ reverse => 1 ] )

Instance method. Gets the next message in the archive. select_archive() must be called in advance. (Yes, again. It's a whole prerequisite moment.)

The message will be locked to prevent multiple processing of a single message. 🔒

Parameters:

  • None.

Returns:

A two-elements list: a Sympa::Message instance and a filehandle locking a message.

🦋 html_next ( [ reverse => 1 ] )

Instance method. Gets the next metadata of the formatted message in the archive. select_archive() must be called in advance, periodt. 💅

Parameters:

  • None.

Returns:

A hashref. Note that the message will not be locked.

🦋 remove ( $handle )

Instance method. Removes a message from the archive. 🗑️

Parameter:

  • $handle — a filehandle, Sympa::LockedFile instance, locking the message. It's the one returned by "fetch"() or "next"().

Returns:

A true value if the message could be removed. Otherwise, a false value.

🦋 html_remove ( $message_id )

Instance method. TBD. Yeah bestie, that's all it says. A mystery, an enigma, a little cliffhanger. 🕵️♀️

🦋 store ( $message )

Instance method. Stores the message into the archive. 💾

Parameters:

  • $message — a Sympa::Message instance to be stored. The following attributes and metadata are referred:
    • {date} — the Unix time when the message would be delivered.

Returns:

If storing succeeded, the marshalled metadata (file name) of the message. Otherwise, "undef". 😭

🦋 html_store ( $message )

Instance method. TBD. Another one, bestie. We simply do not know. 🙈

🦋 get_archives ( )

Instance method. Gets a list of archive directories this archive contains. The items of the returned value may be fed to select_archive() and so on. Snackable data, we love to see it. 🍓

🦋 html_rebuild ( $arc )

Instance method. Rebuilds archives for the list whose name is given in the argument $arc.

Parameters:

  • $arc — a character string containing the name of the archive directory in the list which we want to rebuild.

Returns:

undef if something goes wrong. 😔

🦋 html_format ( $message, destination_dir => $destination_dir, attachment_url => $attachment_url )

Function. Converts a message to HTML. The transformation era, iconic. 🌈

Parameters:

  • $message — the message to be formatted. A Sympa::Message instance.
  • $destination_dir — the directory the result is stored in.
  • $attachment_url — the base URL used to link attachments.
    • Note: on 6.2.13 and earlier, this option was named "attachement_url". (Yes, spelled like that. The typo was real. Not me bringing up ancient history but here we are. 💀)
    • Note: on 6.2.17 and later, this option may take an arrayref value. In such case, the items will be percent-encoded and conjuncted. Otherwise, if a string is given, it will not be encoded.

🦋 get_id ( )

Instance method. Gets the unique identifier of the instance. Your fave's fave, one of one, no duplicates. 👑

🔥 SEE ALSO 🔥

archived(8), mhonarc(1), wwsympa(8), Sympa::Message.

Go read those too bestie, the lore goes deep. 📚

💜 HISTORY 💜

Archive was renamed to Sympa::Archive on Sympa 6.2. Glow-up of the century, honestly. ✨

That's the whole page, bestie! This was Sympa::Archive(3Sympa) from sympa 6.2.80, dated 2026-10-19 — the footer said so and I would never lie to you about a date. 🫶 Go archive something iconic, mwah! 💅💖

📦 where this page comes from