bin::do...ntities(3)

💖 bin::do...ntities(3) — like, the manual page, but make it make sense ✨

okay bestie, welcome to the bin::do...ntities(3) page (yes the title is literally truncated like that in the real man page, it's giving drama 💅). Perldoc, user-contributed, all that. Let's get into it 🫶

---

🌸 NAME 🌸

download-entities — download and parse XML Entity definitions. that's the whole vibe. ✨

---

🎀 SYNOPSIS 🎀

$ perl download-entities.pl -i # interactive
$ perl download-entities.pl > output-file.pm
$ perl download-entities.pl output-file.pm

# instead of http://www.w3.org/2003/entities/iso9573-2003/
$ perl download-entities.pl http://my.server.com/entities.html

like, four ways to do it, pick your fighter 💖

---

🦋 DESCRIPTION 🦋

So this script downloads the definitions of XML entities from http://www.w3.org/2003/entities/iso9573-2003/ — or honestly from whatever address you hand it as an argument. no cap. 🌈

That argument should be an URL (one that LWP::UserAgent::get can access) pointing to a document containing absolute or relative references to files that end with the .ent suffix. And those files? They're expected to be DTD's with lines that look exactly like this:

<!ENTITY amp "&#38;" >

Then the script parses those files and prints the perl module to standard output. cute, right? and if you want, you can pass file as another argument and it'll print to file instead. you can also set the output file via the environment variable OUTPUT_FILE. flexible queen 👑

Here's the little detail you need to know: the index and the output file are told apart by whether the string :// shows up. that's the whole check. So if you want to use a locally stored index file (the one with the .ent references), you get to it by saying:

perl download.pl file:///path/to/index.html

ok so heads up, this is the part where you go 😭: the script currently distinguishes between relative and absolute paths by looking at whether the href contains a :// substring. that means it can legitimately crash when your links look like href="/path/file.ent". not a vibe, but it's the truth, so plan accordingly.

Also — and this is important — the script assumes the links have exactly the format href="...", with double quotes. single quotes? no. no quotes? also no. double quotes only, periodt. 💅

---

🌟 Interactive download 🌟

If you run into problems downloading the documents (it happens, the internet is a mess 😭), you can try running the script with the -i or --interactive option. that lets you skip downloads, or enter alternative URLs for individual documents. main character energy: you take control 🫶

Oh and — interactive mode is also triggered when the INTERACTIVE environment variable is set to a true value (true in the Perl sense, iykyk). ⭐

---

✨ Options ✨

• --interactive, -i — as described above, lets you skip downloads or enter alternative URLs for individual documents. also auto-triggered by the INTERACTIVE env var being true (Perl sense).
• --timeout — sets the timeout for LWP::UserAgent, in seconds, when downloading. the same thing is controlled by the DOWNLOAD_TIMEOUT environment variable. the default is 180 seconds (that's 180s) and it's used when you don't specify anything.

and here are the examples, verbatim, because they're iconic:

# 10 seconds timeout - croak on failure
perl download-entities.pl --timeout 10 > XML/Entities/Data.pm
# 5 seconds timeout - croak on failure
DOWNLOAD_TIMEOUT=5 perl download-entities.pl > XML/Entities/Data.pm
# 1 second timeout - ask on failure
perl download-entities.pl --interactive --timeout 1 > XML/Entities/Data.pm

---

🧚 Dependencies 🧚

Real talk: this script has dependencies that the XML::Entities module doesn't have, which is exactly why they're not mentioned in the META.yml file. sneaky, but documented 📝

They are: LWP::UserAgent, File::Basename, and Fatal. go install them bestie 🍓

---

👑 COPYRIGHT 👑

Copyright 2010 Jan Oldrich Kruza <sixtease@cpan.org>. All rights reserved.

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

---

and that's the whole page!! 🎀 cute sign-off time: this was perl v5.32.1, dated 2022-01-21, bin::do...ntities(3), and yeah — that truncated title is still sending me 💀 slay, go download your entities 🌸