MediaW...isions(3pm)

💖 NAME 💖

Parse::MediaWikiDump::Revisions — bestie, this is an object that's literally built to chew through dump files that have multiple revisions per article ✨

(Also, hi, this is a page from the User Contributed Perl Documentation manual, section 3pm, so you know it's the real deal 💅)

---

🌸 ABOUT 🌸

Okay so here's the vibe: this object gives you access to all the metadata hanging out with a MediaWiki instance, and it hands you an iterative interface so you can pull out the individual article revisions from that same dump file one at a time. So cozy, so convenient 🫶

But listen — if what you actually want is a guarantee that there's only one revision per article, you do not use this one. Use the Parse::MediaWikiDump::Pages object instead. Different tool, different job, no cap 💀

---

✨ SYNOPSIS ✨

  use MediaWiki::DumpFile::Compat;

  $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";
  }

Look at that little loop go, she's eating fr fr 🔥

---

🎀 METHODS 🎀

• $revisions->new — opens up the MediaWiki dump file you point at. If the one argument you hand it is a string, it gets used as the path to the file it should open. If instead you pass it a reference to a filehandle, then the contents get read from that filehandle exactly as specified. Pick your fighter 💅
• $revisions->next — hands you back an instance of the next available Parse::MediaWikiDump::page object, or returns undef if there are no more articles left. When it goes undef that's your sign to pack it up, 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 holding '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 that's 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 is a string that's the name of the namespace 🗂️
• $revisions->namespaces_names — returns an array reference, and that array holds strings of all the namespaces, each one as its own element 📝
• $revisions->current_byte — returns the number of bytes that have 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 MediaWiki::DumpFile::Compat;

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

Periodt. Copy it, run it, thank yourself later 💖

---

🙈 LIMITATIONS 🙈

Version 0.4

This class got an upgrade so it can support version 0.4 dump files coming out of a MediaWiki instance — slay — but heads up: it does not currently support any of the new information that's available in those files. So it'll read them, it just won't spill the new tea 🫖😭

---

That's the whole page, bestie — written up by the lovely folks behind the User Contributed Perl Documentation, built for perl v5.34.0, dated 2022-06-15. Go forth and parse responsibly 🎀✨💅