XML::Catalog(3pm)

💖 XML::Catalog 💖

okay bestie, so this is XML::Catalog — a Perl module (it lives in the User Contributed Perl Documentation section, section 3pm, if you were wondering 🫶) and it does two absolutely iconic things: it resolves public identifiers and it remaps system identifiers. that's the whole vibe. slay.

---

✨ NAME ✨

XML::Catalog — Resolve public identifiers and remap system identifiers

no cap, that's literally what it does 💅

---

🌸 SYNOPSIS 🌸

here's the little demo, look how cute and short it is:

use XML::Catalog;
my $catalog=XML::Catalog->new('/xml/catalog.cat');
$catalog->add('http://www.w3.org/xcatalog/mastercat.xml');
my $sysid=$catalog->resolve_public('-//John Cowan//LOC Diacritics');
my $newsysid=$catalog->remap_system('http://www.w3.org');
$parser->setHandlers(ExternEnt=>$catalog->get_handler($parser));

like. we make a catalog, we chain another catalog onto it, we resolve a public id, we remap a system id, and then we hand the whole thing to XML::Parser as its ExternEnt handler. main character behavior fr fr ✨

🦋 Oasis Example 🦋

and here's the OASIS one, running straight from the command line:

$ perl -e 'use XML::Catalog; \
$pubid = q|-//OASIS//DTD DocBook XML V4.5//EN|; \
my $catalog=XML::Catalog->new("/etc/xml/catalog"); \
print $catalog->resolve_public($pubid), "\n";'

and it prints out:

file:///usr/share/sgml/docbook/xml-dtd-4.5-1.0-51.el6/docbookx.dtd

ate. 💖

---

🌈 DESCRIPTION 🌈

so this module implements draft 0.4 of John Cowan's XML Catalog proposal — which used to be called XCatalog, iconic name change tbh — and you can find the proposal at http://www.ccil.org/~cowan/XML/XCatalog.html.

the tea ☕ is that catalogs can be written in either SOCAT or XML syntax (go read the proposal if you want the syntax deets, bestie, that's not our job here). and XML::Catalog will just assume SOCAT syntax if the catalog is not in well-formed XML syntax. it's giving "i'll figure it out, don't worry."

and as of 1.0.0, this module also supports Oasis XML catalogs. glow up 💅

---

👑 CONSTRUCTOR 👑

new(URL [,URL]*)

Read the catalog identified by URL and return a catalog object implementing it. If more than one URL is given, chain the additional catalogs as extensions to the catalog — and heads up, those extras get searched before catalogs specified by EXTEND entries.

⚠️ All URLs must be absolute. A URL with no protocol is treated as a filename. so don't be out here passing relative nonsense, ok? 😭

---

🧚 METHODS 🧚

add(URL [,URL]*)

Chain the catalogs identified by the URL(s) to the current catalog. more friends for your catalog, we love a social butterfly 🦋

resolve_public(PUBID)

Translate the public identifier PUBID to a system identifier. Returns undef if the identifier could not be translated. (it tried its best, okay? 🙈)

remap_system(SYSID)

Remap the system identifier SYSID as specified by the catalog. Returns SYSID unchanged if no remapping was found. so if nothing happened, that's not a bug, that's just the vibe check failing 🫶

get_handler(PARSER)

Returns a coderef to a resolver suitable for use as the ExternEnt handler for an XML::Parser object. The resolver will first attempt to resolve a public identifier if supplied, and then attempt to remap the resulting system identifier (or the original system identifier if no public identifier was supplied). It will then call the original ExternEnt handler associated with the parser object. PARSER is the parser object — it's needed as an argument in order to obtain the original handler. iykyk 💅

add_delegate($pubid, $href)

TBD

add_extend($href)

TBD

add_extend_object($cat, $group )

TBD

add_map($pubid, $href)

TBD

add_remap($sysid, $href)

TBD

build($url)

create new catalog object

fix_base($url)

TBD

parse

TBD

parse_SOCAT($ct)

TBD

parse_XML($ct)

TBD

set_base($href)

TBD

bestie, yes, that's a lot of TBD and we're not gonna pretend otherwise. some of these are still cooking in the oven 🍓

---

💀 BUGS / TODO 💀

• Searching of chained catalogs is not purely depth-first (EXTEND items in a chained catalog will be searched before EXTEND items in the original catalog.
• Error checking leaves much to be desired.

so yeah, the depth-first thing is a little chaotic 😭 and the error checking? "leaves much to be desired" is the manpage being polite. not me reading that and going 💀

---

🎀 AUTHOR 🎀

Current Author:

        Jeff Fearn E<lt>jfearn@cpan.orgE<gt>.

Former Authors:

        Eric Bohlman E<lt>ebohlman@netcom.comE<gt>.

shoutout to the OGs 🫶

---

⭐ COPYRIGHT ⭐

Copyright (c) 1999-2000 Eric Bohlman. All rights reserved. Copyright (c) 2013 Jeff Fearn. All rights reserved.

This program is free software; you can use/modify/redistribute it under the same terms as Perl itself.

(that's the same terms as Perl itself, so go wild, but respectfully 💖)

---

and that's the whole page, bestie!! 🎀 this one's from perl v5.34.0, dated 2022-06-28 — so like, it's been around, it knows what it's doing, and it's still serving looks in the XML::Catalog(3pm) section. mwah 💅✨🌸