grab::Grab_XML(3pm)

💖 grab::Grab_XML — the perl manual page, bestie edition 💖

okay so you found the grab::Grab_XML(3pm) page and honestly? iconic. it's part of the User Contributed Perl Documentation situation, and we're gonna walk through it together like it's a group chat. grab a strawberry 🍓 and let's go.

---

✨ NAME ✨

XMLTV::Grab_XML — a Perl extension to fetch raw XMLTV data from a site. that's the whole vibe. it grabs. it's XML. periodt. 💅

---

🌸 SYNOPSIS 🌸

here's the shape of it, bestie, copy it exactly:

package Grab_XML_rur;
use base 'XMLTV::Grab_XML';
sub urls_by_date( $ ) { my $pkg = shift; ... }
sub country( $ ) { my $pkg = shift; return 'Ruritania' }
# Maybe override a couple of other methods as described below...
Grab_XML_rur->go();

so you make your own little subclass, you inherit from the base, you override a couple of things, and then you hit it with ->go(). that's it. that's the whole ritual. 🦋

---

🎀 DESCRIPTION 🎀

This module helps to write grabbers which fetch pages in XMLTV format from some website and output the data. lowkey the whole point.

but — and this is important — it is not used for grabbers which scrape human-readable sites. if the site is meant for human eyeballs and you're scraping it, that's a different girl. this one is strictly for sites already serving XMLTV format. ✨

It consists of several class methods (package methods). The way to use it is to subclass it and override some of these. like, you don't use it directly, you become it. main character energy fr fr. 👑

---

💅 METHODS 💅

XMLTV::Grab_XML->date_init()

Called at the start of the program to set up Date::Manip. You might want to override this with a method that sets the timezone. so if your grabber lives in a different timezone than the machine, this is your moment. 🌈

XMLTV::Grab_XML->urls_by_date()

Returns a hash mapping YYYYMMDD dates to a URL where listings for that date can be downloaded.

🚨 this method is abstract, you must override it. like, there is no default. if you don't write it, nothing happens. no cap.

Arguments: the command line options for --config-file and --quiet.

XMLTV::Grab_XML->xml_from_data(data)

Given page data for a particular day, turn it into XML. The default implementation just returns the data unchanged, but you might override it if you need to decompress the data or patch it up. so like, if the site sends you a .gz or the XML needs a lil glow-up, this is where you do it. 🧚

XMLTV::Grab_XML->configure()

Configure the grabber if needed. Arguments are --config-file option (or undef) and --quiet flag (or undef).

This method is not provided in the base class; if you don't provide it then attempts to --configure will give a message that configuration is not necessary. so the base class is basically like "we're good bestie, nothing to set up" 🙈

XMLTV::Grab_XML->nextday(day)

Bump a YYYYMMDD date by one. You probably shouldn't override this. it just... adds a day. let it cook. 🍓

XMLTV::Grab_XML->country()

Return the name of the country you're grabbing for, used in usage messages. Abstract. yeah, abstract again — you gotta write it yourself. 💜

XMLTV::Grab_XML->usage_msg()

Return a command-line usage message. This calls country(), so you probably need to override only that method. see how it all connects? it's giving teamwork. 🫶

XMLTV::Grab_XML->get()

Given a URL, fetch the content at that URL. The default implementation calls XMLTV::Get_nice::get_nice() but you might want to override it if you need to do wacky things with http requests, like cookies. 🍪 yes, literally cookies, the http kind, not the snack kind (though also valid).

Note that while this method fetches a page, xml_from_data() does any further processing of the result to turn it into XML. two different jobs, two different methods, don't mix them up. ⭐

XMLTV::Grab_XML->go()

The main program. Parse command line options, fetch and write data. this is the one you call at the end of your subclass. the closer. 💅

Most of the options are fairly self-explanatory but this routine also calls the XMLTV::Memoize module to look for a --cache argument. The functions memoized are those given by the cachables() method. so it's not just vibes — there's a cache system involved. 🔥

XMLTV::Grab_XML->cachables()

Returns a list of names of functions which could reasonably be memoized between runs. This will normally be whatever function fetches the web pages — you memoize that to save on repeated downloads. A subclass might want to add things to this list if it has its own way of fetching web pages. so if you wrote your own fancy fetcher, add it to the list, bestie. 😭

XMLTV::Grab_XML->remove_early_stop_times()

Checks each stop time and removes it if it's before the start time. no early stopping allowed, we're not about that life. ✋

Argument: the XML to correct Returns: the corrected XML

---

👑 AUTHOR 👑

Ed Avis, ed@membled.com

---

🌈 SEE ALSO 🌈

perl(1), XMLTV(3).

---

and that's the whole page, bestie!! you ate. 💖 this was grab::Grab_XML(3pm), and the lil footer said perl v5.40.1 dated 2025-04-19 — so shoutout to that version and that date, mwah. 🎀✨ slay, go write ur grabber. 🦋