Parse:...visions(3pm)

💅 NAME 💅

Parse::MediaWikiDump::Revisions — an object that's literally built to handle dump files that have multiple revisions per article. She's the multi-revision girlie of the Parse::MediaWikiDump family, and she's serving.

---

🦋 ABOUT 🦋

Okay so bestie, here's the deal. This object is how you get at the metadata hanging off a MediaWiki instance, and it also hands you an iterative interface so you can pull the individual article revisions out of that same dump, one at a time.

Tiny little plot twist though: if you want to be absolutely guaranteed that there's only a single revision per article, you use the Parse::MediaWikiDump::Revisions object. Like, that's the one. That's the vibe check.

---

✨ SYNOPSIS ✨

$pmwd = Parse::MediaWikiDump->new;
$revisions = $pmwd->revisions('pages-articles.xml');
$revisions = $pmwd->revisions(\*FILEHANDLE);

#print the title and id of each article inside the dump file
while(defined($page = $revisions->next)) {
  print "title '", $page->title, "' id ", $page->id, "\n";
}

---

💀 STATUS 💀

Not me having to tell you this: this software is being RETIRED. 🫶

MediaWiki::DumpFile is the official successor to Parse::MediaWikiDump, and it ships with a compatibility library called MediaWiki::DumpFile::Compat that is 100% API compatible and is a near-perfect stand-in for this module. It's faster in all the instances where it actually counts, and it's actively maintained. Periodt.

And like, for real for real: any undocumented deviation of MediaWiki::DumpFile::Compat from Parse::MediaWikiDump is considered a bug and will be fixed. No cap. 🌈

---

🎀 METHODS 🎀

• $revisions->new — opens up the MediaWiki dump file you picked. If the single argument you hand it is a string, that string is the path to the file it opens. If instead the argument is a reference to a filehandle, then it reads the contents straight from that filehandle, exactly as specified. 💖
• $revisions->next — returns an instance of the next available Parse::MediaWikiDump::page object, or returns undef when there are no more articles left. That's your stop signal, bestie.
• $revisions->version — returns a plain text string of the dump file format revision number. 📄
• $revisions->sitename — returns a plain text string that is the name of the MediaWiki instance.
• $revisions->base — returns the URL to the instance's main article, as a string. 🔗
• $revisions->generator — returns a string containing 'MediaWiki' plus a version number of the instance that dumped this file. Example: 'MediaWiki 1.14alpha' 🌸
• $revisions->case — returns a string describing the case sensitivity configured in the instance.
• $revisions->namespaces — returns a reference to an array of references. Each one of those references points at another array, where the first item is the unique identifier of the namespace and the second element holds a string that is the name of the namespace. Nested arrays, iconic behavior. 🧚
• $revisions->namespaces_names — returns an array reference; that array contains strings of all the namespaces, each one as an element.
• $revisions->current_byte — returns the number of bytes that has been processed so far. ⭐
• $revisions->size — returns the total size of the dump file in bytes.

---

🔥 EXAMPLE 🔥

Extract the article text of each revision of an article using a given title

#!/usr/bin/perl

use strict;
use warnings;
use Parse::MediaWikiDump;

my $file = shift(@ARGV) or die "must specify a MediaWiki dump of the current pages";
my $title = shift(@ARGV) or die "must specify an article title";
my $pmwd = Parse::MediaWikiDump->new;
my $dump = $pmwd->revisions($file);
my $found = 0;

binmode(STDOUT, ':utf8');
binmode(STDERR, ':utf8');

#this is the only currently known value but there could be more in the future
if ($dump->case ne 'first-letter') {
  die "unable to handle any case setting besides 'first-letter'";
}

$title = case_fixer($title);

while(my $revision = $dump->next) {
  if ($revision->title eq $title) {
    print STDERR "Located text for $title revision ", $revision->revision_id, "\n";
    my $text = $revision->text;
    print $$text;

    $found = 1;
  }
}

print STDERR "Unable to find article text for $title\n" unless $found;
exit 1;

#removes any case sensativity from the very first letter of the title
#but not from the optional namespace name
sub case_fixer {
  my $title = shift;

  #check for namespace
  if ($title =~ /^(.+?):(.+)/) {
    $title = $1 . ':' . ucfirst($2);
  } else {
    $title = ucfirst($title);
  }

  return $title;
}

---

🙈 LIMITATIONS 🙈

Version 0.4

So this class got updated to support version 0.4 dump files coming out of a MediaWiki instance — slay — but it does not currently support any of the new information available in those files. So like, the upgrade happened, but the new lore did not. 💀

---

Okay bestie that's the whole page, no notes, you're gonna do great. 💜

This cutie was brought to you by perl v5.36.0, dated 2022-10-14, living her best life as Parse:...visions(3pm). Mwah. 💅✨🎀